This feature is also available in Polarion REQUIREMENTS, but it is hidden in the default configuration. The topic can be shown in Navigation by changing the Navigation topics configuration. For more information, see Administrator's Guide: Configuring Interface Views.
This feature is read-only for users of Polarion REVIEWER.
This chapter covers Polarion build management configuration and customization in more depth for those who have more complex building setups than those described in Getting Started with Build Management.
Build artifacts are the smallest buildable entity. They are comprised of resources (usually source code and support files). Multiple build artifacts may share the same resources.
One project may contain zero, one, or more build artifacts. Their definition is
stored in the
artifacts.xml configuration file.
To access the
Log in with administrative rights for the scope you want to configure (repository or project).
Open the scope you want to configure (global/repository, project group, or project. (See User Guide: Accessing Projects).
In the Navigation panes, select the topic.
Use the appropriate link in the Configuration section to download the configuration file to your local system.
After editing the file, use the controls in the Upload New [Global][Project] Configuration section to upload the modified file back to the Polarion repository.
The basic format of the configuration file can be found in the Administration reference topic: Building configuration file format. Please refer to it as necessary when reading this section.
Local deployment space is a place where a build artifact is downloaded before building. Let's consider an example with the following source repository structure:
pom.xml is written as if sources were in a
src in its directory. This definition can be
<artifact> <type>maven2</type> <location>trunk</location> <resources> <resource source="sources" target="build/src" recurse="true"/> <resource source="build/pom.xml" target="build"/> </resources> </artifact>
Each artifact is identified by its
group id (the same
convention used with Java package names - e.g.
a hyphen-delimited name, e.g.
sample-demo ). These IDs are usually
based on the artifact itself, or are specified in the above configuration.
Artifacts also have their label, version and list of source directories (for
This section describes the types of build artifacts supported in Polarion build management. Currently supported types are:
Shell (batch/executable invocation)
<!-- default is =pom.xml= --> <pom>PROJECT_MODEL_FILE_LOCATION_RELATIVE_TO_BASE_LOCATION</pom>
Label and source directories are determined from POM file. Note that if POM
file is of type
pom and it defines modules, then those
modules must be build artifacts themselves.
Note that instead of embedded Maven, you can use external Maven, either the
one bundled with Polarion distributions, or any other installation you have. This is not
enabled by default during upgrades (only for new installations), but is strongly
encouraged to do by placing following into the global
<!-- default is =build.xml= --> <antFile>PROJECT_FILE_LOCATION_RELATIVE_TO_BASE_LOCATION</antFile> <!-- default is derived from project's location --> <groupId>GROUP_ID</groupId> <!-- default is "ant" --> <artifactId>ARTIFACT_ID</artifactId> <!-- may be omitted --> <sourceDirectories> <sourceDirectory> SOURCE_DIRECTORY_LOCATION_RELATIVE_TO_BASE_LOCATION </sourceDirectory> ... <sourceDirectory> ... <sourceDirectories> <!-- default is based on artifact id --> <label>LABEL</label> <!-- default is 1.0.0 --> <version>VERSION</version>
If file pointed to by
antFile has project name
(attribute name of top-level element), then it is taken as a label (regardless
of settings in
<executable>EXECUTABLE_LOCATION_RELATIVE_TO_BASE_LOCATION</executable> <!-- may be omitted -> <arguments>ARGUMENT1 ARGUMENT2 ...</arguments> <!-- default is executable's directory --> <workdir>WORKING_DIRECTORY_RELATIVE_TO_BASE_LOCATION</workdir> <!-- default is derived from project's location --> <groupId>GROUP_ID</groupId> <!-- default is "ant" --> <artifactId>ARTIFACT_ID</artifactId> <!-- may be omitted --> <sourceDirectories> <sourceDirectory> SOURCE_DIRECTORY_LOCATION_RELATIVE_TO_BASE_LOCATION </sourceDirectory> ... <sourceDirectory> ... <sourceDirectories> <!-- default is based on artifact id --> <label>LABEL</label> <!-- default is 1.0.0 --> <version>VERSION</version>
The term "build definition" may appear in the portal user interface. It refers to "build descriptor" as described in this topic.
Descriptors are configured in the file
.polarion/builder/descriptors.xml. You can configure build
descriptors in both the global scope, and per project. These are merged if necessary. Here is an example of a build
<?xml version="1.0" encoding="UTF-8"?> <descriptors xmlns="http://polarion.com/schema/Builder/Descriptors" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> xsi:schemaLocation="http://polarion.com/schema/Builder/Descriptors"> <!-- no name and "_default" are equal --> <descriptor name="NAME"> <!-- may be omitted --> <artifacts> <artifact> <!-- if id ends with "*" then the given prefix is searched for; default value is "*" --> <groupId>GROUP_ID</groupId> <!-- if id ends with "*" then the given prefix is searched for; default value is "*" --> <artifactId>ARTIFACT_ID</artifactId> </artifact> ... <artifact> ... </artifacts> <!-- may be omitted --> <build> <properties> <PROPERTY_NAME>PROPERTY_VALUE</PROPERTY_NAME> ... </properties> </build> <!-- may be omitted --> <deploy> <!-- includes and excludes may be omitted, default value for defaultexcludes is true --> <copy|move todir="TARGET_DIRECTORY" label="LABEL_FOR_BUILD_REPORT" dir="SOURCE_DIRECTORY" includes="INCLUDES_PATTERN" excludes="EXCLUDES_PATTERN" defaultexcludes="USE_DEFAULT_EXCLUDES_TRUE_OR_FALSE"> ... <copy|move> ... <item todir="TARGET_DIRECTORY" label="LABEL_FOR_BUILD_REPORT" name="ITEM_NAME" /> ... <item> ... </deploy> </descriptor> ... <descriptor> ... </descriptors>
<deploy> should be used with caution. It can fail depending on operating system,
file system and whether BIR is on the same file system/volume/disk as the data folder. It is also not possible to combine more deployments whose sources are on
the same path. Generally, the "move" feature should be used with care and only if necessary due to storage space or performance reasons.
Descriptors are attached to all build artifacts which match a given group and
artifact IDs (or all if
omitted). There could be two different descriptors with same name attached to
There is always one default build descriptor named
_default which simply runs a build and deploys it to BIR
(linked from the build report) data produced by Maven 2. This default descriptor can
be overridden by a descriptor with the same name (or nameless).
<deploy> tags includes, excludes and
defaultexcludes are the same as in Ant (see http://ant.apache.org/manual/CoreTypes/fileset.html for more
There is only one deploy item supported for build artifacts of type
maven2: default which will deploy all files produced by a
Maven 2 build (stored in
It could be said that a build artifact describes what is built, and build descriptor (definition) describes how it is built. Reality is a bit more complicated than this, because build artifacts also define how the build should go. So the more correct view is that a build artifact says what is built (type, identification, repository resources), and what tools are used and their basic configuration (both defined by type-dependent files), while a build descriptor says how these tools are configured (by build properties) and what are the build results (i.e. BIR deployment).
Build properties can be defined in (latter overrides former):
system configuration (in
polarion.properties configuration file)
global repository file
project-level repository file
properties defined by build descriptor
properties defined in Scheduler configuration
The following properties are set by the system before a build and cannot be changed:
polarion.files.repository: BIR location top level
polarion.build.id: the build ID (e.g.
polarion.build.shared.config.dir: name of a
repository folder relative to the project's location or global root,
which will be locally deployed alongside each artifact. Defaults to
.polarion/maven. Global is used only if a
project scope configuration is missing.
name of repository folder (relative to build artifact's local deployment
directory; defaults to
polarion.build.single.artifact.deployment: use if
there is a problem with paths being too long for Windows. Setting it to
true will deploy to shorter path. However this
can be used only with build artifacts which do not contain other
artifacts - not for Maven multiprojects, for example. Do not use it for calculations under any
build has its own local Maven repository located inside the associated
job's working directory, but by setting this property to
true builds can use one shared one.
Please note that setting this property to
may cause failed builds or calculations, because local Maven
repository is not safe for concurrent modifications, and
calculations use it by default.
polarion.build.maven.executor: specifies which underlying Maven is executed: embedded or external
installation (default is the Maven installation bundled with Polarion distributions, called
location of an external Maven installation (Maven home)
space-separated JVM options (like
-Xmx) passed to
underlying Maven. (Ignored by embedded Maven.)
space-separated Maven options passed to underlying Maven. (Ignored by
polarion.build.maven.non.recursive: Maven option
--non-recursive (for true), default is nothing.
polarion.build.maven.offline: Maven option
--offline (for true), default is nothing.
--no-plugin-registry (for true), default is nothing.
--update-snapshots (for true), default is nothing.
polarion.build.maven.reactor: Maven option
--reactor (for true), default is nothing.
--strict-checksums (for fail) and
--lax-checksums (for warn), default is nothing.
--check-plugin-updates (for true) and
--no-plugin-updates (for false), default is nothing.
--activate-profiles. Comma-separated list of
profiles to activate.
comma-separated list of profiles to deactivate (ignored by external
--fail-at-end (for fail-at-end),
--fail-fast (for fail-fast), and
--fail-never (for fail-never), default is nothing.
location of the used Maven plugin registry (path and name).
of the used Maven plugin registry (without path). Default is
of the used Maven settings (path and name).
polarion.build.maven.settings.name: name of the
used Maven settings (without path). Default is
polarion.build.goals: space-separated list of
Maven goals/phases to run (defaults to
default deployment repository ID (usually set in system configuration).
default deployment repository URL (usually set in system configuration).
The default deployment repository is used if the POM file does not define the
All build properties are reflected as properties accessible by standard ways in Maven (including properties controlling behavior of various plugins like compiler, etc.)
polarion.build.ant.targets: space-separated or
comma-separated list of Ant targets to run. Defaults to the default
specified in the project configuration file.
of Ant <taskdef>'s attribute with a given name.
NAME is just an arbitrary name used for pairing
attributes of one <taskdef>.
All build properties are reflected as properties accessible by standard ways in Ant.
There are several important directories:
working directory of the job related to the build (its location is visible in build's log)
base location (in local deployment space = after the download from repository)
base directory of Maven 2 (accessible by Maven property
current working directory (called "current user directory" or "cwd" by various platforms)
Base location is either somewhere under the job's working directory or inside the shared local deployment space (if it is an integration build).
Base directory of Maven 2 is always the directory where
pom.xml was downloaded (or the build file for Ant builds, or
executable for shell builds - Maven is used internally for execution of those). It
is under the base location.
If embedded Maven is used, then the current working directory is always the same as the working directory of Polarion (usually directory from which Polarion was run). Otherwise, if external Maven is used (which is the default), then the current working directory is the same as the base directory of Maven 2.
For shell builds, the current working directory can be changed, regardless of which Maven is used, to any directory relative to base location by specifying the <workdir> element in the build artifacts definition.
Polarion will automatically recognize build artifacts if one of these conditions is satisfied:
clean start (or recognition requested from UI) and there is no
artifacts.xml present in the configuration.
clean start (or recognition requested from UI) and
artifacts.xml is present in the configuration with
auto-recognition set to
Polarion can also auto-recognize artifacts of types maven2 (searches for
pom.xml) and ant (searches for
build.xml). Files are searched to a maximum of three folders
depth, starting from project's location or folder trunk within project's location
(if there is one, then it is taken as base location for all artifacts found).
Source directories are automatically determined for maven2, and heuristics is used for ant (heuristics is name-based, not content-based).
If no artifact is auto-recognized, but source directories are found, then special
artifact of type
auto is used. This type is not intended for
building. Rather, it allows source-based reports to work on unknown data.
Because auto-recognition (and detection of changes to build artifacts and related
configuration) is a potentially resource intensive operation, there are two
configuration options which affect it:
polarion.startup.disable.artifacts.change.detection. Refer to
Administrator's Guide, System Tuning for Advanced
Administrators for more information.
This section explains how to build Eclipse and Maven 1 projects.
Eclipse projects can be built using the Eclipse PDE Maven Plugin (see http://mojo.codehaus.org/pde-maven-plugin/) which wraps the Eclipse PDE headless build process automation. For details on usage see http://mojo.codehaus.org/pde-maven-plugin/usage.html. In short, one Maven project is created for one Eclipse project (which may contain multiple features and plugins) which must be rigorously structured (all the features in one folder and all the plugins in second folder).
If your repository structure is different than the one required by the Eclipse PDE Maven Plugin, you can adjust build artifact's resources to make the structure upon the build execution. For example consider this repository structure (all under the trunk folder):
folderA |--- plugin1 |--- plugin2 |--- feature1 folderB |--- plugin3 |--- feature2 pom.xml
However Eclipse PDE Maven Plugin requires this:
features |--- feature1 |--- feature2 plugins |--- plugin1 |--- plugin2 |--- plugin3 pom.xml
That is achievable by changing
artifacts.xml to contain:
<artifact> <type>maven2</type> <location>trunk</location> <resources> <resource source="folderA/plugin1" target="plugins/plugin1" recurse="true"/> <resource source="folderA/plugin2" target="plugins/plugin2" recurse="true"/> <resource source="folderB/plugin3" target="plugins/plugin3" recurse="true"/> <resource source="folderA/feature1" target="features/feature1" recurse="true"/> <resource source="folderB/feature2" target="features/feature2" recurse="true"/> <resource source="pom.xml" target=""/> </resources> </artifact>
Polarion is able to automatically recognize source code from simple Maven
1 projects whose layout adheres to recommended conventions (with source code in
src/main/java. Such build artifacts have their artifact
ID (visible in Create New Build wizard) set to
system should be able to compute source code metrics for this artifact, but
please note that source code detection is entirely heuristic and may not
properly detect source code. It is highly recommended to migrate Maven 1
projects to Maven 2 and not to rely on this source code detection feature.
There is no direct support for building of Maven 1 projects. However it is possible to call Maven 1 from the command-line as any other tool (see information on build artifacts of type Shell).
Migration from Maven 1 to Maven 2 is usually very straightforward. Most
projects can be converted simply by copying
pom.xml with a few changes (all these changes apply
to elements directly under top-level
change <pomVersion>3</pomVersion> to <modelVersion>4.0.0</modelVersion>
change <id>...</id> to <artifactId>...</artifactId>
change <currentVersion>...</currentVersion> to <version>...</version>
change <package>...</package> to <groupId>...</groupId>
For more information see the official Guide to Moving from Maven 1.x to Maven 2.x on Maven's site.
There is also a possibility to convert a Maven 1 project to a Maven 2
project by using the Maven 2 One
Plugin. Issue command
mvn one:convert in
the same directory as
project.xml. This will not only
convert project definition files, but the plugin also tries to convert any
Maven 1 reports to their Maven 2 counterparts. Please note that the
conversion is not 100%, but mostly it works. Be sure to update
artifacts.xml or issue build artifacts
auto-recognition after checking the converted project back in to
There is explicit support for branched artifacts. Artifacts from a branch are handled the same as trunk artifacts. Because Polarion identifies artifacts (from one project) by their group and artifact IDs, and it is fairly common to have branched artifacts with same group and artifact ID but different version, some work-around must be done in order to be able to build trunk and branched artifacts. There are two possibilities:
Have separate projects for trunk and for every branch.
Have different group or artifact IDs of trunk and branched artifacts.
This section provides some advanced topics related to building with Maven 2.
It is sometimes required to distinguish between running the builds on a
developer's machine and running them inside Polarion. For this, Maven's concept
of profiles can be used (more information is available at http://maven.apache.org/guides/introduction/introduction-to-profiles.html
). There are several ways to define profiles, but here is the use of global
profiles defined in
add new profiles to the ones already there):
<profile> <id>development</id> <properties> <somePathProperty>FOLDER_ON_DEVELOPERS_MACHINE</somePathProperty> </properties> <id>polarion</id> <properties> <somePathProperty>FOLDER_ON_POLARION_MACHINE</somePathProperty> </properties> </profile>
If developer runs this in standalone Maven with argument
development then the build will have a property
somePathProperty pointing to a folder on developer's
machine. If it is run inside Polarion, and build property
polarion.build.maven.active.profiles is set to
polarion, then the
somePathProperty property will point to a folder on the
To minimize connections to the central Maven repository (by other means than
by using potentially dangerous
polarion.build.shared.local.repository), it is recommended to
use Maven proxy (see http://maven-proxy.codehaus.org/). If you have trouble installing
the proxy, check http://codeforfun.wordpress.com/2006/05/24/maven-proxy/ and http://codeforfun.wordpress.com/2006/09/11/maven-proxy-details/ for
information. Once you have the proxy installed, just edit
C:/Polarion/maven/settings.xml and add a new
<mirror> section. For example:
<settings> <localRepository>C:/Polarion/data/maven-repo</localRepository> <mirrors> <mirror> <mirrorOf>central</mirrorOf> <id>central-mirror</id> <name>Mirror of Central Repo</name> <url>http://PROXY_HOST:PROXY_PORT/PROXY_PREFIX/repository</url> </mirror> </mirrors> <profiles> <profile> <id>polarion-bundled</id> <repositories> <repository> <id>polarion-bundled</id> <url>file:///C:/Polarion/maven/repository</url> </repository> </repositories> <pluginRepositories> <pluginRepository> <id>polarion-bundled</id> <url>file:///C:/Polarion/maven/repository</url> </pluginRepository> </pluginRepositories> </profile> <profile> <id>polarion-shared</id> <repositories> <repository> <id>polarion-shared</id> <url>file:///C:/Polarion/data/shared-maven-repo</url> </repository> </repositories> <pluginRepositories> <pluginRepository> <id>polarion-shared</id> <url>file:///C:/Polarion/data/shared-maven-repo</url> </pluginRepository> </pluginRepositories> </profile> </profiles> <activeProfiles> <activeProfile>polarion-bundled</activeProfile> <activeProfile>polarion-shared</activeProfile> </activeProfiles> </settings>
For more information about mirrors see http://maven.apache.org/guides/mini/guide-mirror-settings.html.
One local and two remote repositories are configured:
Local repository at
is used by calculations and can be emptied at will. (Builds each have
their own located in their job's working directory. Build property
polarion.build.shared.local.repository can be set
true to have this for builds as well, but be
warned that it may have undesirable side effects.)
C:/Polarion/maven/repository) contains some
bundled third party plugins and projects (as well as plugins and
projects required for Polarion to work) to minimize connections to
Maven's central repository.
C:/Polarion/data/shared-maven-repo) is fully
under user's control and is intended for deployment of projects (this is
configured by default to be the default deployment repository - see
is also accessible via
There is no difference (except for additional configuration which can change the behavior) between running stand-alone Maven 2 tool and running a build with external Maven.
Embedded Maven is significantly different because it is a development version in a frozen state, and is carefully balanced to work with bundled plugins. Using it for builds is discouraged.
Maven 2 is a core piece of the Polarion build management system. All builds
and calculations are routed through it. Embedded Maven is version 2.1, bundled
external Maven is version 2.0 (installed at
If something fails and it is not clear why, then it is recommended to go to
the working directory of the build's job, find
(even if the build was not a Maven build) and see what is inside that could
cause something to go wrong.
Plugin registry is at
C:/Polarion/maven/plugin-registry.xml, settings are at
C:/Polarion/maven/settings.xml. Both files can be
freely changed, or other files can be used (see build properties
When tests are executed during a standard Maven build, they can be automatically imported as a Test Run when properties in
.polarion\builder\build.properties are set. It is possible to fill some Test Run fields from an xUnit file name using
regular expressions (regex).
For information, see User Reference: Test Management Reference
Builds are scheduled like this (in global
<job name="ARBITRARY_NAME" id="master.build" cronExpression="CRON_EXPRESSION" scope="project:PROJECT_NAME"> <buildArtifact>GROUP_ID:ARTIFACT_ID</buildArtifact> <!-- use "_default" for default build --> <buildDescriptorName>BUILD_DESCRIPTOR_NAME</buildDescriptorName> <!-- use for integration build, omit for standalone build --> <localDeploymentSpaceName>_default</localDeploymentSpaceName> <!-- may be omitted; specifies additional build properties --> <properties> <PROPERTY_NAME>PROPERTY_VALUE</PROPERTY_NAME> ... </properties> </job>
Build is executed with access rights of the system user (defined in
polarion.properties in the
property). So make sure that this user has repository access to all sources.
Integration builds are builds which are deployed to one shared local deployment
space. This results in a faster deployment phase, because only changes are
downloaded from the repository, and the build phase is faster because results of
previous build are still in place. Please note that calculations share the same
shared local deployment space. Integration builds which must wait for others have
Integration builds are usually stored in data directory in path