It is quite common that a product is comprised of different components, and a component is used by different products. We suggest to set up builds for these components and products separately in this case, and utilize QuickBuild's dependency mechanism to use result of component builds in product builds.
h1. Dependency mechanism
QuickBuild implements build dependency through a special repository type - [QuickBuild repository]. Assume we have two configurations: _root/product_ and _root/component_. Configuration _root/product_ is created to build the product, and configuration _root/component_ is created to build component. To use component artifacts, you will need to:
# Switch to _repositories_ tab of _root/product_, and define a QuickBuild repository there retrieving desired files from desired build of _root/component_.
# Switch to _steps_ tab of _root/product_, and add a checkout step into step execution graph to check out from the repository defined above.
If the product depends on multiple components, you will just need to define multiple QuickBuild repositories corresponding to these components, and add multiple checkout steps to check out from these repositories in the product configuration. You can even arrange these checkout steps in a parallel composition step to resolve and retrieve multiple dependencies simultaneously.
h1. Dependency resolution and change detection
Taking the example used in the above section, before retrieving artifacts from configuration _root/component_, QuickBuild needs to determine which build in _root/componentA_ to be used. The process of resolving dependency build is called dependency resolution in QuickBuild, and is controlled by the property _build_ when define the QuickBuild repository as shown below:
!dependency.png!
Currently this property can take one of below value:
* latest finished build (generate new if necessary)
If this value is selected, QuickBuild will check if a new build is necessary in the dependency configuration (_root/component_ in this case) when resolve the dependency build. If the build is necessary, the newly generated build will be used as the actual dependency build; otherwise, the current latest finished build will be resolved.
Variables can be specified to control the dependency build process in this case.
* latest finished build
If this value is selected, QuickBuild will directly resolve the dependency build as the latest finished build without attempting to generate a new build in the dependency configuration even if build condition is satisfied.
* latest recommended build
If this value is selected, QuickBuild will resolve the dependency build as the latest recommended build. This is very useful to make sure that the product builds always use good and approved builds from component configurations. Newly introduced features in component builds will not affect product builds unless they are approved.
* latest successful build
If this value is selected, QuickBuild will resolve the dependency build as latest successful build.
* specify a build version
If this option is choosed, you will need to specify a particular build version to be used as dependency build.
The dependency resolution process is recursive if the dependency configuration itself uses other dependencies. In this case, other dependency resolution processes will be triggered before current resolution finishes.
Like other repository types, changes will be detected in the QuickBuild repository when configuration _root/product_ is triggered. When detecting changes, the dependency resolution process will run to get the actual dependency build. If the resulted dependency build is different from the dependency build used in previous build, QuickBuild will think that the dependency has changed and new build will be generated if the configuration is triggered by scheduler or by a recursive dependency resolution process.
h1. Dependency types
Different dependency types are defined based on different resolution processes introduced above:
* {anchor: active dependency} *Active dependency*
This dependency refers to the dependency setup with resolution process set to "latest finished build (generate new if necessary)". It is called active since the resolution process can trigger new build in dependency configuration. We call configuration _project1_ actively depends on configuration _project2_ if _project1_ has an active dependency on _project2_.
* {anchor: passive dependency} *Passive dependency*
This dependency refers to the dependency setup with resolution process set to "latest finished build", "latest recommended build", and "latest successful build". It is called passive since the resolution process itself will never trigger a build actively. However, if there is a new build generated matching the criteria, it will be used as the new dependency. We call configuration _project1_ passively depends on configuration _project2_ if _project1_ has a passive dependency on _project2_.
* {anchor: static dependency} *Static dependency*
This dependency refers to the dependency setup with resolution process set to "specify a build version". It is called static since the dependency build will remain unchanged unless another build is specified by the user.
Having explained dependency types, let is assume that configuration _project1_ actively depends on _project2_, and _project2_ actively depends on _project3_. If _project3_ has new source commits since last build, triggering of _project1_ will generate new build in _project3_, _project2_ and _project1_ in turn.
h1. Check dependent builds
In a continuous integration environment, when build/test a configuration, it is sometimes desirable to check if configurations depending on current build are successful or not. If dependent builds are failed, the dependency build will be marked as failed to indicate that it breaks the dependents. To achieve this, you will need to:
# Make sure the dependent configurations you want to check have an active dependency on the current configuration.
# Add an additional step _Trigger Other Builds_ into step execution graph of the dependency configuration, and configure it to trigger desired dependent configurations. Dependent configurations specified here will be triggered parallely.
Future versions will add a dependent trigger step to find out configurations actively depending on current configuration automatically, and trigger them parallely.
h1. Track build dependencies
Used dependencies in a particular build can be examined from the build overview page as explained [here|dependent and dependency builds].
h1. Dependency mechanism
QuickBuild implements build dependency through a special repository type - [QuickBuild repository]. Assume we have two configurations: _root/product_ and _root/component_. Configuration _root/product_ is created to build the product, and configuration _root/component_ is created to build component. To use component artifacts, you will need to:
# Switch to _repositories_ tab of _root/product_, and define a QuickBuild repository there retrieving desired files from desired build of _root/component_.
# Switch to _steps_ tab of _root/product_, and add a checkout step into step execution graph to check out from the repository defined above.
If the product depends on multiple components, you will just need to define multiple QuickBuild repositories corresponding to these components, and add multiple checkout steps to check out from these repositories in the product configuration. You can even arrange these checkout steps in a parallel composition step to resolve and retrieve multiple dependencies simultaneously.
h1. Dependency resolution and change detection
Taking the example used in the above section, before retrieving artifacts from configuration _root/component_, QuickBuild needs to determine which build in _root/componentA_ to be used. The process of resolving dependency build is called dependency resolution in QuickBuild, and is controlled by the property _build_ when define the QuickBuild repository as shown below:
!dependency.png!
Currently this property can take one of below value:
* latest finished build (generate new if necessary)
If this value is selected, QuickBuild will check if a new build is necessary in the dependency configuration (_root/component_ in this case) when resolve the dependency build. If the build is necessary, the newly generated build will be used as the actual dependency build; otherwise, the current latest finished build will be resolved.
Variables can be specified to control the dependency build process in this case.
* latest finished build
If this value is selected, QuickBuild will directly resolve the dependency build as the latest finished build without attempting to generate a new build in the dependency configuration even if build condition is satisfied.
* latest recommended build
If this value is selected, QuickBuild will resolve the dependency build as the latest recommended build. This is very useful to make sure that the product builds always use good and approved builds from component configurations. Newly introduced features in component builds will not affect product builds unless they are approved.
* latest successful build
If this value is selected, QuickBuild will resolve the dependency build as latest successful build.
* specify a build version
If this option is choosed, you will need to specify a particular build version to be used as dependency build.
The dependency resolution process is recursive if the dependency configuration itself uses other dependencies. In this case, other dependency resolution processes will be triggered before current resolution finishes.
Like other repository types, changes will be detected in the QuickBuild repository when configuration _root/product_ is triggered. When detecting changes, the dependency resolution process will run to get the actual dependency build. If the resulted dependency build is different from the dependency build used in previous build, QuickBuild will think that the dependency has changed and new build will be generated if the configuration is triggered by scheduler or by a recursive dependency resolution process.
h1. Dependency types
Different dependency types are defined based on different resolution processes introduced above:
* {anchor: active dependency} *Active dependency*
This dependency refers to the dependency setup with resolution process set to "latest finished build (generate new if necessary)". It is called active since the resolution process can trigger new build in dependency configuration. We call configuration _project1_ actively depends on configuration _project2_ if _project1_ has an active dependency on _project2_.
* {anchor: passive dependency} *Passive dependency*
This dependency refers to the dependency setup with resolution process set to "latest finished build", "latest recommended build", and "latest successful build". It is called passive since the resolution process itself will never trigger a build actively. However, if there is a new build generated matching the criteria, it will be used as the new dependency. We call configuration _project1_ passively depends on configuration _project2_ if _project1_ has a passive dependency on _project2_.
* {anchor: static dependency} *Static dependency*
This dependency refers to the dependency setup with resolution process set to "specify a build version". It is called static since the dependency build will remain unchanged unless another build is specified by the user.
Having explained dependency types, let is assume that configuration _project1_ actively depends on _project2_, and _project2_ actively depends on _project3_. If _project3_ has new source commits since last build, triggering of _project1_ will generate new build in _project3_, _project2_ and _project1_ in turn.
h1. Check dependent builds
In a continuous integration environment, when build/test a configuration, it is sometimes desirable to check if configurations depending on current build are successful or not. If dependent builds are failed, the dependency build will be marked as failed to indicate that it breaks the dependents. To achieve this, you will need to:
# Make sure the dependent configurations you want to check have an active dependency on the current configuration.
# Add an additional step _Trigger Other Builds_ into step execution graph of the dependency configuration, and configure it to trigger desired dependent configurations. Dependent configurations specified here will be triggered parallely.
Future versions will add a dependent trigger step to find out configurations actively depending on current configuration automatically, and trigger them parallely.
h1. Track build dependencies
Used dependencies in a particular build can be examined from the build overview page as explained [here|dependent and dependency builds].