13. Configuring Building

Availability in Polarion REQUIREMENTS & REVIEWER

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 in Polarion REVIEWER.

Scope(s): Project

This chapter 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 Administrator's Guide: Advance Build Management .

Basic Build Management

The following sections describe the standard or basic type of builds you can set up in Polarion.

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 auto-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 (i.e. <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 the Finish button in the Create Build wizard, the build will start.

To launch a build for a simple Maven 2 project:

  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 the Create Build button to launch the Create Build wizard dialog.

    As mentioned above, you should be able to accept the defaults. If you want build reports to be updated after the build, check 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 ALM.

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> (i.e., 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 (unless resources are used) is downloaded from repository to local disk before the build.

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 that 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 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 execute 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 named build.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 is executed, trunk is downloaded to local disk (the location parameter) and make all is executed (by invoking "executable" with correct "arguments") from the build directory (the workdir parameter).

Quick Start: External Exe, Batch/Shell Script

This is essentially the same as previous section about Makefile builds. Executables, batch files and shell scripts which are not stored in the repository must be called by some special script which is stored in the repository.

Quick Start: Continuous Integration

Polarion has 2 key features for continuous integration:

  • Scheduled builds

  • 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 Configuring 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>
				

Configuring Work Item Reports

You can include some information about Work Items in build results by configuring Work Item Reports for builds. The <workitem-report> 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 section "Build Results").

The Work Item reports configuration for builds is available for both repository and for each project.

To access the Work Item reports configuration for builds:

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

  2. If your login does not already take you into Administration from a previous session, enter Administration by clicking the link in the tool view of Navigation.

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

Editing the Configuration File

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 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.