OpenDOF Build Process

The Build Process Explained

The OpenDOF build process is based on using Apache Ant (v1.9.1 or later) as a cross-platform build tool, and Apache Ivy (v2.3.0 or later) as a generic dependency resolution tool. Each module’s build defines the following targets:

1. dist-src: This target generates the source artifacts for the module. This is required to produce a source distribution file of the form organization-module-version.src.tar.gz, and may produce other source distribution formats (e.g., a module-version-sources.jar for Java modules). Source artifacts should be as close to the original source (from source control) as possible, but should also include information about their version and where the source was obtained. This does not expect any previous target to be executed, and may in fact clean the working folder (destroying/removing the work of other tasks) as a side-effect of building the source artifacts.
2. publish-src: This target publishes the source artifacts to a local Ivy repository, so other builds can depend on them. This expects only that the previous target (dist-src) to already have been executed.
3. dist: This target is the main build of the module, and is also expected to be the default target. This generates all other artifacts of the build, including any binary distribution of the form organization-module-version.noarch.tar.gz (for platform-independent modules), or organization-module-platform-version.tar.gz (for platform-specific modules). It may also optionally produce a documentation distribution, named similar to the source distribution, with an extention of .doc.tar.gz instead of .src.tar.gz. Documentation artifacts are assumed to be platform-independent. This does not expect any previous target to be executed.
4. publish: This target publishes the binary artifacts to a local Ivy repository, so other builds can depend on them. This expects only that the previous target (dist) to already have been executed.
5. clean: This target cleans the local directory of all build artifacts (source and binary). It is often set as a pre-requisite for the dist-src target to ensure the source is clean before producing the source artifacts. This does not expect any previous target to be executed.

On the OpenDOF build system, the first two targets are always executed in a Linux environment, and no extra tools are expected to be utilized to generate or publish the source artifacts. Typically the third target, dist, will execute on a target platform and use additional tools necessary for completing the specific build tasks for the individual module, such as a JDK (for Java) or CMake/gcc (for C). The fourth target will also execute on the target platform (where dist was executed), but should refrain from using extra tools as only the artifacts already generated need to be published. The first four targets are always required. The final target is optional, although strongly recommended, and typically used by developers.

For modules that are platform-specific, you should define the “platform” variable in Ant (must be set identically for all targets listed above). This should be defined using the canonical platform naming compatible with autoconf. However, the specific naming must simply be sufficient for fully identify the platform-specific artifacts and be unique among all platforms supported in your repository. For example:

ant -Dplatform=i686-pc-linux-gnu dist

Additional Ant variables that can be configured are as follows. These can be especially useful when trying to completely replicate an official build.

1. org.opendof.local.root: The local path that will be used for publishing artifacts and ivy files.
2. scm.branch: The branch of source control from which the source was obtained (from source control).
3. scm.path: The path (within the branch) from which the source was obtained (from source control).
4. scm.revision: The revision of the source that was obtained (as defined by source control).
5. version.official: The complete 4-part version for the release, e.g., 1.2.3.4.