Overview

Dependencies are used to establish relationships between projects that are related. When one project depends upon another it may be triggered by that project and/or use artifacts produced by that project in its own builds.

A simple example consists of two projects:

1. A "utilities" project, builds of which produce a library artifact. This artifact is a library that exposes some API useful to other projects.
2. A "product" project, builds of which require the "utilities" library.

In this case the "product" project should be configured to depend on the "utilities" project. This enables "product" builds to use the library artifacts produced by "utilities" builds. It further allows you to configure the "product" project to be triggered by changes to the "utilities" library.

Terminology

For the sake of clarity, some dependency-related terms are defined below:

In particular, the terms upstream and downstream are used as a simple way to establish a dependency relationship.

Artifact Transfers

The primary purpose of the dependencies functionality is to allow you to deliver files between builds of different projects. To enable this, you need to configure three things:

1. The version and status of the upstream project.
2. Publication of the desired artifacts in the upstream project.
3. A dependency in the downstream project.

In some advanced cases, you may also need to tune the artifact publication and retrieval to suit your project.

Version and Status

The first step is to configure a version numbering strategy and status for the upstream project. These values can be configured in the project dependencies section of your project configuration. By default, a project's version is set to "$(build.number)". That is, each build is assigned an integer version that is one more than the preceding build. You could alternatively configure the version to be a fixed string, e.g. "SNAPSHOT", or perhaps to include higher-level version numbers, e.g. "1.2.$(build.number)". No restriction is placed on the form of the version.

The status of the project indicates how stable or mature it is. Three status levels are defined by pulse™:

Again, the exact interpretation of these statuses is not fixed. The important distinction is their increasing order of maturity.

Per-Build Versioning

In some cases you may want to designate a specific build of your project as having a different version and/or status. Rather than editing the project configuration, you can achieve this by turning on prompting for manually-triggered builds. This is achieved by checking the prompt option in your project's build options. When this option is on, a manual trigger will present you with a prompt which allows you to set the version and status to use for that build (amongst other things).

Publishing

To publish files from your build, you first need to configure appropriate artifacts. This configuration tells pulse™ to capture the files at the end of a command and store them as part of a build result. To actually have the files published to the internal artifact repository (and therefore available to downstream builds), you must explicitly check the "publish" option (or set publish="true" in your pulse™ file). This explicit step is required as it is not desirable to publish all captured files (e.g. command output).

Note that artifacts are only published by successful builds. Artifacts from unsuccessful builds are not considered to be publication-quality.

Artifact Pattern

When publishing files to the repository, pulse™ needs to extract the name and extension of the artifact (although the latter is optional). By default, the name is everything that comes before the last period (.), and the extension is everything that comes after it (i.e. the file extension). So, for example, if you published a file named "mylibrary.lib", pulse™ would extract "mylibrary" as the artifact name, and "lib" as the artifact extension.

You can customise this behaviour by changing the artifact pattern. This setting is a regular expression which is matched against the file name to extract the artifact name and extension. The extraction is done using regular expression groups: the first group in the expression is the name and the second group the extension. For example, the default expression is:

(.*?)(?:\.([^.]*))?

The complexity of this expression allows for extensions to be optional. Notice the capturing groups, which are delimited by parentheses (a third, non-capturing group, indicated with ?:, surrounds the optional extension). Now suppose that your file names include a version number that you wish to exclude from the artifact name. You could achieve this by matching the version outside of the groups, i.e.:

(.*?)-[0-9]+(?:\.([^.]*))?

Using this expression, a file named "versioned-123.jar" would have an artifact name of "versioned" and an extension of "jar".

Retrieval

To retrieve files published by another project, you must configure a dependency on that project. Dependencies are configured in the project dependencies section of your project configuration. When adding a dependency, you need to decide which revision of that project to depend on. There are two main types of revision:

1. The latest build of a given status. In this case downstream builds will retrieve artifacts from the latest upstream build of the given or more mature status. So if the revision is set to latest.milestone, for example, the downstream project will retrieve artifacts from the latest milestone or release build. Upstream integration builds will be ignored, as they have a lower than required maturity.
2. A custom version. For example, you might want to depend on a specific version of the upstream project, e.g. "1.2".

Transitive Retrieval

If the upstream project itself depends on other projects, your downstream build may require the artifacts from these indirect dependencies. In this case you can check the transitive option when configuring the dependency. When this option is enabled, artifacts are retrieved from all upstream projects recursively. When this option is disabled, only artifacts published by the upstream project itself are retrieved.

Stage-Specific Retrieval

By default, the downstream project will retrieve all artifacts published by the upstream build, regardless of the build stage they were published by. When the upstream project has multiple stages, you may want to restrict which stages artifacts are retrieved from. This is controlled by the retrieve stages option, which provides three alternatives:

Retrieval Location

Artifacts are retrieved by the downstream builds just after the bootstrap step. The location to which artifacts are retrieve is controlled by the retrieval pattern setting in the project dependencies section of your project configuration. By default, this pattern is set to:

lib/[artifact](.[ext])

meaning that the artifacts are placed in a "lib" directory within the base directory of the build, and named with the artifact name and extension (if present). By changing this pattern, you can move the artifacts to another location in your build tree and/or control how they are named. For example, to move them to a directory named "deps" and include the version in the file name, you could use the pattern:

deps/[artifact]-[revision](.[ext])

Triggering

The second main purpose of configuring dependencies is to allow downstream projects to be triggered when builds of upstream projects complete. This is controlled by the presence or absence of a dependency trigger. By default, all projects have such a trigger, enabling builds to be triggered when upstream builds complete. To disable this behaviour you can pause or delete the dependency trigger.

Dependency triggers are similar to build completed triggers, but are aware of dependency configuration. In particular, these triggers take transitive dependencies and build statuses into account. This avoids downstream builds being triggered inappropriately:

• If a project build fails, no project downstream of it will be built (as no new artifacts will have been published).
• If the downstream project can be reached by multiple paths from some upstream dependency, it will not be built multiple times due to an upstream build.
• If the downstream project requires the upstream project to have a particular revision, it will not be triggered by upstream builds of the wrong version or a less mature status.

For this reason dependency triggers are preferable when your dependencies are configured in pulse™.

Version and Status Propagation

Dependency triggers may be configured to propagate the version and/or status from upstream builds to downstream builds that they trigger. This means the version and status from the upstream build will be applied to the triggered downstream build. This overrides the configured version/status of the downstream project for that build.

Manual Triggering with Dependencies

In some cases you may wish to manually force a build of a project and all of its dependencies. One scenario where this is useful is performing a release build of a whole dependency graph. This can be achieved by enabling the prompt setting in the downstream project's build options, and using the trigger with dependencies link to trigger a downstream build. When prompted, you can set the desired version string and release status, and pulse™ will rebuild the whole dependency graph with this version and status.

SCM Change spanning multiple Dependent Projects

If you have a project that has multiple components (each represented as a project within pulse™), you can make a change to multiple components at the same time and pulse™ will create a single build from these changes. That is, each of the changed components will be built only once and in the order defined by there dependencies.