dir-artifact - Pulse v1.2

Directory Artifacts

The dir-artifact element allows entire directories to be captured as artifacts. All nested files and directories may be captured recursively, or they may be filtered using Apache Ant style inclusion and exclusion patterns. It can be used to capture a group of related files from a directory, or even entire HTML reports consisting of multiple files and directories.

Escaping

Note that to use backslash (\) as a path separator when specifying directories, you must preceed it with another backslash. For this reason, it is usually more convenient to use forward slash (/) as a separator, even on Windows.

HTML Reports

HTML report capturing allows reports produced by various build/testing tools to be easily linked to build results in the pulse™ web interface. Examples include test reports, static code analysis reports and code coverage reports. By simply capturing the directory containing the report, it should appear in the pulse™ web interface as a linked HTML report. HTML reports are identified by searching for an index file (e.g. index.html in the captured directory. To force a specific index file (when multiple exist or the file is not found), use the index attribute.

Filtering Captured Files

The files captured from the specified directory may be filtered using Apache Ant style inclusion and exclusion patterns. These patterns allow the following wildcards:

Wildcard	Description
?	Matches any single character.
*	Matches any string of characters (including the empty string) within a single directory or filename, but does not match multiple path elements.
**	Matches any string of characters, possibly including multiple path elements.

To illustrate:

Pattern	Description	Matches	Does Not Match
*.java	Matches all files in the base directory ending in ".java".	Foo.java Bar.java	src/Foo.java
MyFile.?	Matches any file named "MyFile" with a single character extension.	MyFile.c MyFile.h	MyFile.txt
.	Matches any file with a "." somewhere in the name.	Foo.java Foo. .txt	Foo
src/Source.?*	Matches any file in the directory "src/" name named "Source" with an extension of at least one character.	src/Source.txt src/Source.java	Source.java src/Source.
*/.java	Matches any file ending in ".java", nested anywhere in the base directory.	Foo.java src/Foo.java src/com/zutubi/Foo.java	Bar.c Bar.javax
src/*/.java	Matches any file ending in ".java" nested under the "src/" directory.	src/Foo.java src/com/zutubi/Foo.java	Foo.java test/src/Foo.java

Attributes

Attribute	Description	Required?	Default
base	The base directory for the files and directories to be captured, relative to the base directory for the recipe.	No	The abse directory for the recipe.
fail-if-not-present	If true, if the directory to be captured is not found the corresponding command (and thus the build) will fail.	No	true
follow-symlinks	If true, symbolic links to directories found when scanning for included files will be followed.	No	false
ignore-stale	If true, files with modified times before the start of the recipe execution will be ignored.	No	false
name	The name of this artifact (used in the web interface).	Yes
index	For HTML reports, the name of the file to use as the index (default file when the artifact is viewed).	No	The first of `index.html`, `index.htm`, `default.html` or `default.htm` that is found to exist.
type	The MIME type for the files captured, passed to the browser when the files are downloaded.	No	Guessed based on file name and content.

Child Elements

Element	Description	Number
exclude	Specifies a pattern to match files that should not be captured.	0 or more
include	Specifies a pattern to match files that should be captured (if no patterns are specified, all files are captured).	0 or more
process	Specifies a post-processor to apply to all captured files.	0 or more

Examples

Capture a JUnit HTML report:

<command name="test">
    <ant targets="test"/>
    <dir-artifact name="junit report" base="reports/junit"/>
</command>

Capture a directory of RPM packages:

<command name="package">
    <make targets="package"/>
    <dir-artifact name="rpms" base="packages">
        <include pattern="*.rpm"/>
    </dir-artifact>
</command>

Capture all log files nested anywhere in the base directory, except those with "boring" in their name, and post-process them all for errors:

<regex.pp name="log.pp">
    <pattern category="error" expression="^Error:"/>
</regex.pp>

<recipe name="default">
    <command name="build">
        <make targets="all"/>
        <dir-artifact name="logs">
            <include pattern="**/*.log"/>
            <exclude pattern="**/*boring*.log/>
            <process processor="${log.pp}"/>
        </dir-artifact>
    </command>
</recipe>