Basic concepts
| Chapter 1. Introduction |

## Basic concepts

### Configuration

Configuration holds all configuration information in order to generate builds. These information includes what to build, how to build, and when to build, etc. Configurations are organized in a tree structure. To refer to a configuration, name of all its ancestor configurations should be put together and connected with period, plus its own name, for example: root.department1.project1.nightly. Child configurations can inherit build settings from parent, and can selectively override some of them. This behavior is referred as inherit and override rule, which makes build management of many projects very easy.

### Build

Build always associates with a version, and is generated by running of configuration. When a particular configuration is triggered (either by user or by scheduling system), the build necessary condition of configuration will be evaluated. If the result is true, the configuration will run, and a new build will be generated. Lately information about this build can be accessed online, including published artifacts, build logs, revision logs, etc.

### Repository

Repository stands for a place stores files needed for generating builds. It provides "what to build" information for a configuration. It includes but not limited to version control systems, such as CVS, ClearCase, Subversion, etc. Also ordinary directories can also be treated as a repository ( in case you store your source codes in a plain file system folder, instead of some version control system). Generally any place be able to store build artifacts (either source codes, or intermediate build artifacts such as libraries which may be used for further build process) can be treated as a repository. The repository object obeys the inherit and override rule, which means repositories defined in descendent configurations with the same name will override those defined in ancestor configuration.

### Builder

Builder defines how to perform a build. After necessary files have been checked out from configured repositories, QuickBuild will call related builders to actually run the build. Currently, Ant builder, NAnt builder, Maven Builder and a command line builder are supported. However, any builder facilities with a command line interface should be able to work with QuickBuild. The builder object obeys inherit and override rule.

### Notifier

Notifier defines how to notify users about information of recent build. Notification message can be customized through using of Velocity templates. Currently QuickBuild supports Email notifier, Jabber notifier, MSN messenger Notifier, and Google Talk notifier. Thanks for the inherit and override rule, you can define notifiers in high level configuration, and reuse them in descendents to minimize your configuration work.

### Step

In order to make the build process more flexible, the step concept is introduced in QuickBuild. It defines the build process for a particular configuration, and you can control which parts of the build process can be executed simultaneously, and which parts should e executed serially. The step object obeys inherit and override rule. Currently, the following steps can be used:

- checkout

  This step helps to check out codes from specified repository.

- build

  This step helps to perform build with specified builder.

- label

  This step helps to create a label in related repositories in order to make a snapshot of files used for this build.

- publish

  This step helps to publish files so that they can be accessed online from QuickBuild web interface.

  | Note
  This step is only needed for files that are not under control of QuickBuild. For example, in your build script, you do not copy generated artifacts to the directory denoted by artifactsDir property. In this case, this publish step will make them visible through the web interface by creating soft links to these files.

- label

  This step helps to create a label in related repositories in order to remember correct version of files used for this build.

- notify

  This step helps to notify proper persons about status of current build.

- serial composition

  This is a composition step that helps to create a step comprised of other steps. Included child steps will be executed serially.

- parallel composition

  This is a composition step that helps to create a step comprised of other steps. Included child steps will be executed simultaneously.

### Login mappings

Login mapping is used to map repository logins to QuickBuild users in order to do certain things, such as sending out failure build notifications to users who has checked in codes into repository recently, etc. You can define multiple login mappings, and associate different login mappings with different repositories. This is very useful when you have multiple repositories and login name for a particular user is not consistent through out these repositories. The login mapping object obeys override and inherit rule.

### Schedule

Schedule defines "When to build" aspect of the configuration. By defining a schedule, builds can be triggered at specified time, or can be triggered periodically.

### Triggering instance

Triggering of a configuration is called a triggering instance, which will be put into build queue when all working threads for that queue have been used up. Execution of a triggering instance does not necessarily generate a new build. This is determined by build necessary condition. However, if you set value of build necessary condition as true (by choosing force build from the build necessary condition drop down menu), new build will always be generated when this triggering instance get the chance to be executed.

### Build queue

Every configuration associates with a build queue (if not set explicitly, parent configuration's build queue will be used), which is used to control maximum concurrent builds in this configuration (and its descendents if choose to inherit). When a configuration is triggered, some of the triggering will be queued if all configured working threads in the queue have been used up.

### Configuration's working directory

Every configuration has an working directory which is used to hold configuration logs, checkouts directory, and child configuration working directories. Let's assume that you've installed QuickBuild under `/opt/quickbuild`, the default working directory for configuration root.department1.project1.nightly will be `/opt/quickbuild/working/root/department1/project1/nightly`. If you've changed working directory setting for a particular parent , working directories of child configurations will be derived in the same way starting from that directory.

### Configuration's checkouts directory

Configuration's checkouts directory is located in a sub directory named by `checkouts` under configuration's working directory. It is used to hold checked out stuffs from various repositories.

### Configuration's publish directory

Every configuration has an publish directory which is used to hold produced builds, and child configuration publish directories. Let's assume that you've installed QuickBuild under `/opt/quickbuild`, the default publish directory for configuration root.department1.project1.nightly will be `/opt/quickbuild/publish/root/department1/project1/nightly`. If you've changed publish directory setting for a particular parent , publish directories of child configurations will be derived in the same way starting from that directory.

### Build's publish directory

Build publish directory is used to hold artifacts directory, various logs and reports generated by a build. It is named by version number of the build, and is located under `builds` sub directory under configuration's publish directory. Continue with the example in last section, if build project1-3.0.0 is produced by configuration root.department1.project1.nightly, its publish directory will be `/opt/quickbuild/publish/root/department1/project1/nightly/builds/project1-3.0.0`.

### Build's artifacts directory

Build artifacts directory is used to hold published artifacts for a particular build, and is located under a sub directory named by `artifacts` of build's publish directory.

### Build's JUNIT html report directory

Build JUNIT html report directory is used to hold JUNIT html reports generated by a particular build, and is located under a sub directory named by `junitHtmlReports` of build's publish directory.

### Build's Clover html report directory

Build Clover html report directory is used to hold Clover html reports generated by a particular build, and is located under a sub directory named by `cloverHtmlReports` of build's publish directory.

Chapter 1. Introduction |  | Chapter 2. User interfaces