Build Configuration and Integration Policy

Latest approved version of this policy
23.01.2012: EMI_SA2_ConfigIntegration_v_3_0.pdf

1. Introduction

This document describes the EMI policy to be followed when building EMI middleware. The following topics are covered by this policy:

  • The Build Integration policy defines how the 4 Middleware distributions will manage to have a successful shared single build using standard external and internal dependencies.
  • The Build Configuration policy defines how to configure the selected build/integration tool to properly build each software component.

This document was agreed by the EMI SA2 Configuration and Integration Task Force [R1].

2. Build Integration Policy

2.1 Unified Build, Single Tool

  • All the EMI software is built together in a single unit. This build produces QA metrics, source and binary packages. Binary packages can be used for testing or release. Source packages are used to build binary packages in pristine environments as specified in OS distributions.
  • A single tool is used to perform integration builds from source. The system of choice is ETICS. All build tools will be supported and integrated via this unified integration system.
  • EMI is to use a common build, test and QA system as much as practically possible. All components to be released as part of EMI must have configurations in ETICS.

2.2. Build Environment

  • EMI is released on two sets of platforms, mandatory and optional.
  • Mandatory platforms must be supported by all components in EMI, optional platforms can be supported by individual PTs depending on needs of technical capabilities.
  • Currently EMI 1 is supported on the RHEL5 platform on 64bit architecture.
  • EMI 2 will support also RHEL6 and Debian6 platforms.
  • The build and integration reference platforms are Scientific Linux 5 x86_64, Scientific Linux 6 x86_64 and Debian 6 amd64. The SLx machines with the following enabled YUM repositories: SLX.Y X86_64, EPEL X x86_64, EMI. The Debian machines are using the official Debian repository.
  • All components in EMI must be provided in the standard packaging formats typical of the supported mandatory platforms. Currently this means rpms for RHEL5 and RHEL 6; debs for Debian 6.

2.3. Dependencies

  • All external dependencies needed at build and runtime must be specified in the ETICS configuration for a component.
  • Globus packages for EMI shall be taken from existing standard repository such as EPEL whenever available. All components in EMI shall adopt this strategy.
  • Exceptions to be discussed at the EMT:
    • If a package not available in OS or EPEL/DEBIAN is required and right package is available from a third party, then it is added to a EMI repository which is used as source of external dependencies as well.
    • If a package is not available in the right package format and it is required as dependency, the requester PT becomes responsible of creating the proper package, building the package from source and making it available first as an ETICS external and then in the EMI YUM/APT repository.

2.4. ETICS project organization

  • A new EMI project is available where all the EMI software is built. All the EMI configurations required to build are part of this project.
  • Configurations already existing in other parts of the system must be cloned and moved in the EMI project.
  • Product Teams which are interested in re-organizing subsystems or components are given the opportunity to change their software structure in ETICS. Please contact the ETICS Support for this.

2.5. EMI WNs and testing repository

  • The ETICS Worker Nodes are configured to use a minimal VM images with only the set of packages required to bootstrap the build. (See for instance: Fedora BuildRequires Exceptions [R3])
  • The ETICS client additionally checks for the availability of CVS, SVN and Autotools packages before the build. These packages are installed if not available.
  • External dependencies must be specified in ETICS and they are installed using YUM/APT as SUDO before starting the build which will happen instead in user space.
  • The external configurations are not required anymore since the new feature of the ETICS client 1.5.0 is available: OS.DEFAULT (which will resolve the ETICS dependencies according what is currently installed in the VM)
  • No .DEFAULT properties are edited anymore since all of them are resolved according to OS.DEFAULT
  • EMI YUM/APT repositories available for installation testing and certification. These repositories are updated with new packages after every nightly build.

3. Build Configuration Policy

Here are the configuration conventions adopted in using ETICS.

3.1. Project structure

  • In ETICS the software is organized in projects, subsystems and components
  • A module is a generic term to define a project, a subsystem or a component
  • Components are the smallest independently buildable piece of software (Usually corresponds to a CVS module or to a SVN buildable subtree)
  • Subsystem are ways of grouping components, Projects group subsystems

3.2. Module naming

  • Names are case sensitive
  • A module name must be unique in the whole system
  • In order to ensure uniqueness, EMI must use the convention:
    • emi
    • emi.subsystem1
      • emi.subsystem1.component1
      • emi.subsystem1.component2
    • emi.subsystem2
      • emi.subsystem2.component3
      • emi.subsystem2.component4
      • emi.subsystem2.component5
    • emi.subsystem3
      • emi.subsystem3.component6

  • The ETICS Configuration and Repository web-applications do not show the prefixes in the browsing trees to be more concise but the modules names are usually prefixed with project and subsystem.

3.3. Module fields

  • field contents are inherited from the parent module upon creation but can be changed when needed
  • common fields of each module are:

ETICS name
unique name of the module, see module naming conventions
display name
name displayed in the applications, usually kept empty so that the name is displayed
short description of the module, unless the property ${package.description} is set, the component description text is introduced in the Description field of the packages by the ETICS packager. For RPM please refer to Fedora Guidelines - Summary and Description [R4], for Debian please refer to Debian Policy Manual - Description [R5]
must be set to EMI
root of your anonymous CVS or SVN or WGET account. This value will be used in checkout commands with the property ${vcsroot}. Examples are for CVS, for SVN or for WGET
ETICS repository instance to be used. By default Do not change unless you know what you are doing!
website of the project or package for more information
read only, creation date
read only, last modification date
read only, internal identifier

  • Additional fields available only on components:
    software license of the software
    package name
    used by the ETICS packager as name of the package. If not specified the component name is used by default.
    location from which packages can be downloaded, used mainly for external components which are taken from other location and added in ETICS

  • Required Fields are: name, description, vendor=EMI, vcsroot, repository=, license, package name
  • display name must be empty
  • The "package name" must be specified and it must be unique for the whole project:
    • for components already in production the package name should not be changed.
      • Ex: package name: glite-ce-blahp
    • for components released for the first time in EMI, there's no rule on choosing "glite-", "nordugrid-", "unicore-", "dcache-" or "emi-" prefix
      • Ex: package name: glite-data-catalog-interface

3.4. Configuration structure

* A configuration is an ETICS object which contains all the information to checkout, build, test and package a specific version of a component

  • To better understand, ETICS modules are similar to CVS modules as software containers while ETICS configurations are similar to CVS tags as versions over time of a component
  • Configurations can be created inside projects, subsystem and components
  • Project and subsystem configurations do not contain any checkout/build/test instructions. They are used instead to group children configurations in subsystem and in turn project releases
  • Component configurations are used to define the checkout/build/test instructions
  • An example can be the following configuration tree. A new project release (version 2.0.0) is composed of version 2.5.0 of the servers and of version 6.0.0 of the clients. The server subsystem is in turn composed of three versions of server components and the client subsystem is composed of three versions of client components. In this example only the component configurations define instructions for checkout/build/test while the other configurations are used to group configurations in releases:
    • P: my-project_R_2_0_0_1
      • S: servers_R_2_5_0_1
        • C: web_server_R_2_5_1_1
          • component checkout/build/test instructions
        • C: database_server_R_2_0_1_1
          • components checkout/build/test instructions
        • C: database_schemas_R_3_0_0_1
          • components checkout/build/test instructions
      • S: clients_R_6_0_0_1
        • C: java_api_R_5_2_2_1
          • components checkout/build/test instructions
        • C: python_api_R_5_0_0_1
          • components checkout/build/test instructions
        • C: cli_client_R_5_6_1_1
          • components checkout/build/test instructions

  • Even though ETICS allows to create project or subsystem configuration which contain build or test commands, EMI must only use the project and subsystem configurations to group children configurations and let only the component configuration to actually build or test by specifying commands
  • No properties, environments, dependencies or commands must be added to subsystem configurations

3.5. Configuration naming

  • configuration names should be of the following format: [component name]_R_[version] or [component name]_B_[branch name]
    [component name]
    must start with "emi-" and be dash-separated. Example: emi-cream-api-java, emi-dcache-srmclient, emi-arc-client-nox, emi-unicore-ucc
    R or B
    the type of configuration which can be "R" for release if the configuration is bound to a VCS tag, or "B" for branch if the configuration is bound to a VCS branch
    underscore-separated major, minor, revision and age (or release) versions. Example: 1_2_3_1, 1_0_0_1, 2_5_0_1
    [branch name]
    name of the branch as set in the VCS. Examples: HEAD, TRUNK, dev

  • Examples:
    • emi-unicore-ucc_B_TRUNK
    • emi-nordugrid-arc-nox_R_1_0_0_1
    • emi-glite-ce-cream-client-api-c_R_1_7_1_1
    • emi-dcache-nameserver-pnfs_B_HEAD

3.6. Configuration fields

  • The following fields have the same meaning as the ones found in the modules and the same rules apply: ETICS name, display name, description, vcsroot, created, modified, id.
  • Unless the property ${package.summary} is set, this description text is introduced in the Summary field of the packages by the ETICS packager. For RPM please refer to Fedora Guidelines - Summary and Description [R4], for Debian please refer to Debian Policy Manual - Description [R5]
  • The description name of a configuration must be used to provide a short summary of the changes which characterize the new release

composed of major, minor and revision, it defines the version of the software defined in the configuration
also known as release, it defines the changes in packaging
if a VCS is used, this field defines the tag or branch to be used in the checkout command. This is done to avoid changing the checkout commands at every new release and only change this field which is then used in the checkout command as system property ${tag}
it is used to specify a list of profiles which trigger the ETICS plugins. For instance adding the string 'findbugs' would trigger the findbugs plugin during the build
download from
see section below

  • Mandatory fields: version, age, tag and download from=${projectName}/${moduleName}/${version}/${platformName}/${packageName}-${version}-${age}.tar.gz (see below)
  • Version must be of the format Major.Minor.Revision
    • Major: non-backward compatible changes
    • Minor: backward compatible changes
    • Revision: bugfixes
  • Age must increase upon changes in the packaging

3.7. Download From

  • The download from field always starts with the ETICS repository URL and usually contains the default value: ${projectName}/${moduleName}/${version}/${platformName}/${packageName}-${version}-${age}.tar.gz

  • This value is used to generate the upload/download locations of all types of packages: TAR.GZ, DEB, RPM.
    • to address TAR.GZ is used as it is
    • to address RPM, the TAR.GZ file name is removed and the following RPM name is added (preserving the directories): ${packageName}-${version}-${age}.${architecture}.rpm
    • to address DEB, the TAR.GZ file name is removed and the following DEB name is added (preserving the directories): ${packageName}_${version}-${age}_${os}_${architecture}.deb

  • To change the standard RPM or DEB package names to be used to replace the TAR.GZ package name it is possible to define the system properties ${} and ${}.
  • This field can also be reset to directly point to the RPM or the DEB file.

  • this is the location used for dependencies to:
    • check if the package is available in binary format in the repository.
      • If the RPM is found and the build has root or sudo privileges, the package is installed in the build node.
      • If the RPM or the privileges are missing but the tar.gz is found, it can be downloaded as binary during the checkout.
      • If not, the component is built from source
    • upload the binaries in the ETICS repository after the build from source

  • Unless you know what you are doing, do not change the 'download from' default value

3.8. Platforms

  • The supported platform for EMI 0 and EMI 1 is "sl5_x65_64_gcc412EPEL".
  • For EMI 0 and EMI 1 RC0:
    • This platform has been created starting from SL5 x86_64 and by adding all the required build dependency RPMs as specified by SA1.
    • A list of installed RPMs is available here: EMI_SL5_x86_64_EPEL_rpmlist.txt [R2]
    • The only exception not installed via RPM is Maven2 which has been installed using a tar.gz in /usr/local/apache-maven-2.2.1 and linking mvn mvnDebug from /usr/local/bin
  • For EMI 1 RC1 and future releases:
    • The ETICS Worker Nodes are configured to use a minimal VM images with only the set of packages required to bootstrap the build. (See for instance: Fedora BuildRequires Exceptions [R3])
    • The ETICS client additionally checks for the availability of CVS, SVN and Autotools packages before the build. This packages are installed if not available.
  • For EMI 2 - No new requirements
  • In case PTs need to change the platform definition in batch. Please contact the ETICS team.

3.9. Properties

  • Properties are key=value pairs which can be used in the VCS/build/test commands.
  • Properties can be added/edited and removed in each configuration.
  • A property reference can be added in commands by typing ${PROPERTY_NAME} and it will be replaced at runtime with its value from the ETICS CLI client.
  • Properties are inherited from parent configurations and get overwritten in the following order Project -> Subsystem -> Component (i.e. properties in component configuration overwrite properties with the same name in subsystem configurations)
  • Properties can be prefixed with the module name (i.e ${MODULE_NAME.PROPERTY_NAME}) to access properties of other components (if these components are first level dependencies).
  • Four types of Properties are available:
    • User properties: user defined properties can be used as variables in the commands. Users define both the property KEY and VALUE and then uses the property as ${KEY} in the commands.
      • This allows editing of command parameters without the need of changing the command itself but instead by just changing the property value.
      • Properties can be explicitly defined in the ETICS CLI client when executing a command (etics-checkout, etics-build or etics-test) using the option -p and, if set, they overwrite all properties available in the configurations. This can be used for customization of single jobs.
      • Since properties are inherited, a property set at project/subsystem level can then be used in hundreds of component configurations. This then allows users to change the behavior of many configurations by editing a single variable at project or subsystem level.
    • System properties: are ETICS-defined properties which can be used to customize the system or to get useful information from the system. A full list of System properties is available with description in the Configuration WA in the "Add System Property" panel. Examples are:
      • Many properties can be used to tune the ETICS packager such as: ${package.prefix} which defines the root of the package, ${package.configFiles} which is a comma-separated list of files to be marked as CONFIG files
      • ETICS Plugins are usually configured using properties such as: ${findbugs.src.location} which defines the source location of the Java code to be analyzed, ${junit.failure} which defines whether the component must be marked as Failed if some unit tests fail
      • Several properties provide the user information about the platform on which the job is running such as: ${libDir} which is defined as "lib", "lib64" or "lib32" according to what OS and architecture the job is running on
    • Filed properties: are properties that match exactly fields of a module or a configuration. In general, every field of the current module or configuration can be accessed as property. ${tag} accesses the current configuration field named "Tag", ${moduleName} accesses the current module name.
    • Dependency resolution properties: are properties used to resolve dynamic or version constrained dependencies.
      • They are usually set in project configurations (to have the same version of a component in the whole project) , dependency resolution properties are of the format: moduleName.DEFAULT=configurationName
      • This properties are then used by the ETICS CLI client to resolve the exact versions of dependencies which have been set as dynamic in the component configurations
      • If more than one definition is found in the build, the latest version found is used as dependency for all the component no matter what was the original definition specified
      • See section below for more information on dependencies.

  • No .DEFAULT properties are allowed in component or subsystem configurations. .DEFAULT properties can only be present in the project configuration. .DEFAULT are not required anymore as of release EMI 1 RC1.
  • No system properties that overwrite configuration or component attributes are allowed (${location}, ${[DEPENDENCY].location}, ${majorVersion}, ${minorVersion}, ${revisionVersion}, ${age}, ${packageName}, etc).
  • The package.prefix property must not be set by components. This property is set at project level as /.
  • The package.autoreqprov must be set only in project configuration and its value must be yes.
  • Exception are handled via the EMT.

3.10. Dependencies

  • Dependencies are used to relate component configurations. Dependencies have a scope which can be "Build-time", "Runtime" or "Build and Runtime" and a type which can be "Static", "Dynamic" or "Version constrained"
  • Scope:
    • Build-time dependencies are used when a component needs some files from another component while building (compile/link/document/etc.)
      • Once a Build-time dependency is set, ETICS gives to the component a property named ${[COMPONENT NAME].location} which points to the root of the binaries of the dependency-component in order to address the needed files.
      • ETICS also resolved the build order accordingly making sure components are built AFTER their dependencies
    • Runtime dependencies are instead used to add in the binary package metadata (RPMs or DEBs) the right REQUIRES tags in order to force the installation of the dependency when the package is installed
      • Runtime (only) dependency are usually not checked-out nor built as they are only used to configure package metadata. If YUM repositories are created and users want to have also runtime dependencies added into the repository. An option can be used to force the checkout/download of runtime dependency: --runtimedeps (or "checkout runtime dependency as well" from the web application submission form)
    • Build-time and Runtime dependencies behave as both runtime and build-time dependencies

  • Type:
    • Static dependencies are dependencies which do not use the ETICS default version of a component, but hardcode a specific version in their dependency metadata. This is done by setting the specific configuration (therefore version) of the dependency they want to use
    • Dynamic dependencies are dependencies which specify only the module name and let the version be resolved at higher level. The versions get resolved by the ETICS CLI client by analyzing the properties defined as moduleName.DEFAULT=configurationName
    • Version constrained dependencies are dependencies which specify a version range (i.e. > X.Y.Z) as acceptable for a component. As runtime dependencies, the package metadata (i.e. REQUIRES) is set with the version constrained (> X.Y.Z). As build-time, the ETICS CLI client will just verify if the default version (the one specified by ${moduleName.DEFAULT}) satisfies the constraint. If it satisfies, that version is used. If not, an error is triggered.

  • No static dependencies allowed unless requested to the EMT upon emergency and approved.
    • Version constrained dependencies (DEPENDENCY-NAME > X.Y.Z) are NOT static dependencies only if they include in their acceptable range the OS default version.
  • Dynamic dependencies are added by referencing a component from the "externals". The component must have the same name (or package-name attribute) as the RPM or DEB available in the authorized YUM or APT repositories. If such component is not available, an external registration request must be filed to the ETICS Team using the "Request" TAB of the ETICS Portal.
  • The use of ${[COMPONENT NAME].location} is exceptionally accepted upon prior approval from the EMT for externals downloaded as tarball from the ETICS repository. For EMI builds, all the externals get installed in the WN from EPEL or the OS so the dependency must be taken from the default installed path (/usr/bin, /usr/lib64, etc). No ${[COMPONENT NAME].location} are allowed for externals which get installed in the WN.
  • For internal dependencies (i.e. dependencies which are part of EMI and therefore built from source), the variable to use is the ${stageDir} which is the location where all built components end up.

3.11. VCS commands

  • VCS commands are usually used to download somehow the source code into the build machine
  • The checkout command is a shell line which is executed by ETICS from the workspace directory.
  • Useful system properties which can be used in the checkout command are:
    the name of the module (usually is the component name since the commands sit only in component configurations)
    the TAG field of the configuration
    ${majorVersion}, ${minorVersion}, ${revisionVersion} and ${age}
    the various parts of the version field of the configuration M.m.R-A
    the vcsroot field of the configuration

  • When checking-out a module (project, subsystem or component), by default the specified module and all its children modules are checked-out from source by executing their checkout commands
  • Everything else is:
    • For dependencies resolved as OS.DEFAULT:
      • If the build has root or sudo privileges, it is installed from YUM or APT
      • If not, it is marked as Unresolved, and the package name appears in the list of packages to install (Section Execution Info of the ETICS report)
    • For dependencies resolved to configurations:
      • If already installed in the system, it is just used
      • If not installed, an RPM is found in the registered repository (according to downloadFrom) and the build runs with root or sudo privileges, it is installed
      • If an RPM is not found or the privileges are not correct, the tar.gz is downloaded from binary from the registered repository and placed in the ${stageDir}
      • If the tar.gz is not found either, the checkout command of its configuration is executed
  • The behavior of how to checkout components which are not the selected module or its direct children, can be changed using options when launching etics-checkout or when submitting a remote-build or remote-test

  • Only the checkout command must be used.
  • The checkout command must create a directory in the workspace with the name identical to the module name.

* Examples are:

mkdir -p ${moduleName}
if no source code at all is required
cvs -d ${vcsroot} co -r ${tag} myCVSandETICSmoduleName
if the CVS module name does correspond to the ETICS module name
cvs -d ${vcsroot} co -r ${tag} -d ${moduleName} myCVSmoduleName
if the CVS module name does not correspond to the ETICS module name
svn co ${vcsroot}/${moduleName}/tags/${tag} ${moduleName}
typical subversion command
mkdir -p ${moduleName}/src; cd ${moduleName}/src; wget; tar xzf myPackage.tar.gz; rm -rf myPackage.tar.gz;
any shell command can be specified if it creates the right directory and downloads somehow the source code.

  • Mistakes are:
    echo "NO CHECKOUT"
    because it does not create the directory
    cvs -d ${vcsroot} co -r ${tag} myCVSmoduleName
    if the CVS module name DOES NOT correspond to the ETICS module name

3.12. Build commands

  • Build commands are executed for each built configuration after the checkout phase (by executing the command etics-build). ETICS automatically generates a build order to properly satisfy build-time dependencies.
  • Build commands are executed inside the component directory within the workspace (in the ${workspaceDir}/{moduleName} directory unless the property ${srcDir} which overwrites this behavior is defined)
  • All targets must include shell commands which will be executed as they are after each property is replaced.
  • The build commands are composed of targets which are executed in order: init, configure, compile, doc, checkstyle, install, packaging, test, prepublish, publish, postpublish.
  • Two targets have a special behavior:
    • install is used to define which files have to be packaged/staged. This is done by copying all the files in a special directory which can be addressed via the property ${prefix}.
    • packaging is used to create packages (RPMs, TGZs, DEBs). If this target is left empty, the ETICS packager will execute and package the files previously copied in the directory ${prefix}. The package format depends on the platform but usually is TGZ and (DEB or RPM). If this target is instead defined, ETICS will just execute the specified command.
  • The "clean" target of each built component is instead only executed (alone) when the option "-t clean" is added to the etics-build command

  • In order to reference files from build-time dependencies within build targets:
    • For external dependencies, since they are installed in the OS, use the default locations, m4 macros or PKG-CONFIG. Do not use the ETICS properties ${[COMPONENT NAME].location}
    • For internal dependencies, which are built from source before the current component, use the ETICS property ${stageDir} which points to the area where the packages are staged after the compilation (usually ${workspaceDir}/stage). Inside the stage area the files match the package structure defined by the component developer.

3.13. Configuration Locking

  • Configuration Locking is required to produce packages permanently stored in the ETICS Registered Repository.
  • Configurations must be locked without specifying any context. This way no properties are inherited from the project. The only consequence of the locking will be the freeze of its metadata.
  • Be aware that, this way, a locked configuration is not self-contained nor reproducible.
  • Even though already locked configurations could produce new packages if built with new project configurations, this is not allowed as the version cannot change. Therefore a configuration cloning is required.
  • Builds with registration must be submitted with the current production project configuration which will be used to resolve dependencies and generate the package.
  • Only a registered package in the ETICS permanent repository can be considered a final artefact.

4. Contacts


5. Table of References

URL Reference
R1 EMI SA2 Configuration and Integration Task Force
R2 SL5/64bit Images
R3 Fedora BuildRequires Exceptions
R4 Fedora Guidelines - Summary and Description
R5 Debian Policy Manual - Description

6. Logbook

v3.0 (Approved on 23.01.2012)

  • 16.01.2012: Final changes to adapt the policy to SL6 and Debian6

v2.1 (Not approved)

  • 07.11.2011: Changes to adapt information to SL6 and Debian6

v2.0 (Not approved)

  • 25.08.2011: No changes in content: section numbers, table of contents and cover.
  • 23.02.2011: Changes in the policy after a new release of the ETICS client.

v1.0 (Approved on 03.12.2010)

  • 03.12.2010: First version of the policy was approved.
Edit | Attach | Watch | Print version | History: r17 < r16 < r15 < r14 < r13 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r17 - 2012-01-25 - unknown
    • Cern Search Icon Cern Search
    • TWiki Search Icon TWiki Search
    • Google Search Icon Google Search

    EMI All webs login

This site is powered by the TWiki collaboration platform Powered by PerlCopyright & 2008-2023 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
or Ideas, requests, problems regarding TWiki? use Discourse or Send feedback