Basic build management

Note:

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 Configure Interface Views.

This feature is read-only in Polarion Reviewer.

Scope(s): Project

This topic discusses configuration and usage of Polarion ALM's basic build management features. It explains how to quickly get started with several common project build types:

Additional information for more complex and custom building with Polarion are covered in: Advanced build management .

Tip:

Administrators can Disable builds or Calculation Jobs for security reasons by adding the following properties to the polarion.properties file:

  • To disable builds - com.siemens.polarion.security.executingBuilds.enabled=false

  • To disable Calculation Jobs - com.siemens.polarion.security.executingCalculations.enabled=false

Quick start: Simple Maven 2 project

Building of a simple Maven 2 project that is structured according to http://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html is quite simple. Polarion will automatically recognize the Maven 2 project and show it in the Create Build wizard in the Builds topic (in project information scope) either under its name (specifically <name> from pom.xml) or artifact ID (<artifactId>) if no name is set. No configuration is necessary.

A default build definition called _default is sufficient for most builds. When you click Finish in the Create Build wizard, the build will start.

  1. Open the project you want to build.

  2. Select the Builds topic in the Navigation pane.

  3. In the Builds panel of the Content Pane, click Create Build to launch the Create Build wizard dialog box.

    As mentioned above, you should be able to accept the defaults. If you want build reports to be updated after the build, select Update reports together with the build.

Quick start: Maven 2 multiproject

There is essentially no difference between a simple Maven 2 project and multiproject when it comes to building with Polarion. The only thing which must be assured is that every module in a Maven 2 multiproject is recognized by Polarion.

Quick start: Ant build

As with Maven projects, Ant builds are also auto-recognized by Polarion - it looks for the file build.xml. The Polarion build artifact's name is either the value of the name attribute of the Ant project, or the simple string ant.

If there are multiple Ant builds in one project, additional steps must be performed to distinguish between them (because Polarion will assign each build artifact the same artifact ID). Suppose the project's structure looks like this:

trunk
|--- build.xml
|--- sources
|--- scripts
     |--- release_build.xml

You can make Polarion recognize the different builds by modifying the file.polarion/builder/artifacts.xml (for the project, not the global scope):

<artifacts auto-recognition="false"> <!-- value "false" is important -->
    <artifact>
        <type>ant</type>
        <location>trunk</location>
        <groupId>com.example.project</groupId>
        <artifactId>normal-build</artifactId>
        <label>Normal Build of Example Project</label>
    </artifact>
    <artifact>
        <type>ant</type>
        <location>trunk</location>
        <antFile>scripts/release_build.xml</antFile>
        <groupId>com.example.project</groupId>
        <artifactId>release-build</artifactId>
        <label>Release Build of Example Project</label>
    </artifact>
</artifacts>

Setting the auto-recognition attribute to false disables auto-recognition for the entire project (since it is not needed in this case). Because the second Ant build file is not named build.xml and is not located directly under the place specified in <location> (the called artifact's base location) it is necessary to specify the path to the second Ant build file in <antFile>. Base location serves two purposes:

  1. All locations are relative to it, and...

  2. Everything under it is downloaded from repository to local disk before the build, unless build resources are used.

If base location is not explicitly specified, then it is the project's location (or trunk folder if the build artifact was auto-recognized and such a folder exists).

Unless Maven builds, Ant builds (and all other types) do not deploy anything by default to anywhere. Only basic information is deployed to BIR. To be able to deploy more things, a build descriptor must be used. The default build descriptor can be extended with this (contents of the project-level repository file .polarion/builder/descriptors.xml):

<descriptors>
    <descriptor>
        <deploy>
            <copy dir="dist" includes="*.jar" todir="results" label="jar files"/>
        </deploy>
    </descriptor>
</descriptors>

This will deploy all jars which appear in the dist folder to BIR folder results with label jar files. The name, and a link to this deployment, will be visible in the build's detail.

Note:

The <descriptor> element could have a name attribute with the name of the descriptor. There could be descriptors with different names for different types of builds. See the advanced topic on build descriptors for more information.

Quick start: build with makefile

Suppose that the project structure is like this:

trunk
|--- build
     |--- build.sh
|--- src

Let's also suppose that developers run builds by going into the build directory and executing make all.

Since it is not possible to call external scripts directly, a simple shell script must be created in the build folder namedbuild.sh:

#!/bin/sh

make "$@"

Next, the following snippet needs to be added to the project-scope

.polarion/builder/artifacts.xml file:

<artifact>
    <type>shell</type>
    <location>trunk</location>
    <workdir>build</workdir>
    <executable>build/build.sh</executable>
    <arguments>all</arguments>
</artifact>

Now when a build runs, trunk is downloaded to local disk (the location parameter) and make all is run (by invoking executable with correct arguments) from the build directory (the workdir parameter).

Quick start: External exe, batch or shell script

This is essentially the same as makefile builds. The main difference is that executable files, batch files, and shell scripts not stored in the repository must be called by some special script that is stored in the repository.

Quick start: Continuous integration

Polarion has two key features for continuous integration:

  1. Scheduled builds

  2. Integration builds

Scheduled builds are those builds which run at regular intervals without manual intervention. Integration builds are builds in which only updates of source code committed since the last build are downloaded from repository, and intermediate results of the last build (like compiled classes) are still available.

The following is an example of an integration build that runs every hour. You would define such a build in the jobs configuration file /.polarion/jobs/schedule.xml. (See Configure the Scheduler for more information on this configuration file and working with scheduled jobs.)

<job name="Integration Build of Example Project" id="master.build" cronExpression="0 0 0/1 ? * * 
scope="project:ExampleProject">
    <buildArtifact>com.example.project:normal-build</buildArtifact>
    <buildDescriptorName>_default</buildDescriptorName>
    <localDeploymentSpaceName>_default</localDeploymentSpaceName>
</job>

Work Item reports in builds

You can include some information about Work Items in build results by configuring Work Item Reports for builds. The Work Item reports configuration for builds is available for both repository and for each project. Use the following procedure to access the configuration.

  1. Log on with administrator permissions for the scope you want to configure (Repository or project).

  2. Open the repository or project you want to configure.

  3. If necessary, enter Administration by clicking the Administration link in the tool view of Navigation.

  4. In Navigation, expand Building and select Work Item Reports. The Work Item Reports administration page loads in your browser.

This configuration is performed by editing the workitem_reports.xml configuration file. You can either edit the file in the text editor provided on the administration page, or download it, edit locally, and upload the edited file back to the portal using the controls provided on the administration page.

The <workitem-report> element in the configuration file enables listing of some Work Items in the build preview and notification. A typical usage is to list the Work Items resolved since the previous build. You can configure several Work Item reports, each corresponding to one <workitem-report> element in the configuration. Each report will show as a section in the build preview and notification, below the Build Results section.

The configuration file contains extensive comments and an example of a typical configuration in comments. Please refer to the embedded comments for documentation about the available elements and attributes.