Project

General

Profile

How to build, package and deploy CET UPS products on oink.

Overview

  • Product development, building and packaging should be done as yourself, in your own home directory structure or scratch area.
  • Product installation on oink must be done as the products user, not yourself or root.

Product structure

The product structure should have the same overall structure as the ToyCmake package under the cetbuildtools product ($CETBUILDTOOLS_DIR/example) on oink. In order to gain access to the UPS products on oink, do:

source /products/setup

To view the available versions of the cetbuildtools product:
ups list -aK+ cetbuildtools

To access the cetbuildtools product:
setup cetbuildtools <version>

The structure as of v1_1_0 looks like:

CMakeLists.txt

Main directives.

README

Optional package information.

ToyCmake/

Source code and headers, named for the package.

example/

Post-install validation tests and examples.

test/

Development tests.

ups/

Templates for table and version files.

Populating the ups directory.

The cetbuildtools product has a templates directory. In there you will find generic template table and version files, and a README file describing how to customize them and install with appropriate names in your product's ups directory. Do not use the version and table files to be found in the ToyCmake/ups directory.

CMake files.

Each directory should contain a CMakeLists.txt file. Overall instructions are to be found in the top level CMakeLists.txt file. Explicit instructions for building libraries and executables are in the source code subdirectory, which should have the same name as your package. Similarly, instructions for building tests should be in the tests/CMakeLists.txt file. The ups/CmakeLists.txt file contains instructions on turning the template table and version files into version-specific table and version files.

The top-level CMakeLists.txt file should define the version and a qualifier for your product:

SET (version v0_0_0)
SET (qualifier a1)

Installed structure.

make install will create a file named, <product>/<version>.version and a directory tree <product>/<version>, where <product> and <version> will be defined in the top level CmakeLists.txt file.

Note: if the <product> level of the hierarchy is missing, you are probably using CMakeLists.txt files derived from an older version of CETBUILDTOOLS. In this case, you should manually port in any changes from the latest version of CETBUILDTOOLS and then re-do the invocation of CMake, build and install. Lynn or Chris G. can help with any problems in this regard.

The as-installed structure under <product>/<version>/

  • <arch-spec-dir>/
  • <arch-spec-dir>/bin/
  • <arch-spec-dir>/lib/
  • <arch-spec-dir>/example/
  • include/<package-name>/
  • source/ (optional)
  • ups

Setting up your CMakeLists.txt files to build and install.

The $CETBUILDTOOLS_DIR/example/ToyCmake tree contains CMakeList.txt files in each directory intended to be used as templates for the corresponding CMakeLists.txt files in the corresponding locations in your own package.

Dependencies.

The top-level CMakeLists.txt file should verify that all dependencies have been set up, and where appropriate, are at specified minimum version levels. For each product satisfying a dependency, the environment variable $<PRODUCT>_VERSION must exist. The top-level CMakeList.txt file should have a clause (eg):

# require GCC
set( GCC_VERSION $ENV{GCC_VERSION} )
if ( NOT GCC_VERSION )
  message(FATAL_ERROR "Can't locate GCC_VERSION, required for building ToyCmake")
endif ()

The CMakeLists.txt top-level file as taken from $CETBUILDTOOLS_DIR/example/ToyCmake should contain directives to ascertain correctly the flavor qualifiers for the current build and install. If your package does not yet model its build procedures from this latest version however, the flavor qualifier should be set explicitly in CMakeLists.txt and should be one of:

SET (flavorqual sl4.i686.${qualifier})
SET (flavorqual sl4.x86_64.${qualifier})
SET (flavorqual sl5.i686.${qualifier})
SET (flavorqual sl5.x86_64.${qualifier})
For purposes of robustness and flexibility, timely migration to cmake files that calculate automatically the flavor qualifier is recommended.

When the ups/ table file template is processed by CMake, the version from $<PRODUCT_VERSION> will be used in the generated table file to produce an explicit dependency of your installed product on the specific version of each dependency in use at the time your product is packaged.

NOTE: If during development, you change the version of one or more dependencies, CMake must be re-run explicitly -- a change in any environment variable cannot be automatically detected.

Building your product.

The CMakeList.txt files as built from the templates in the ToyCMake product are configured for out-of-source builds per the CET package policy. Therefore, there are actually three parallel directory structures pertinent to a build:

  • The source directory structure (as found in the source code repository).
  • The build directory structure.
  • The as-installed directory structure.

In order to utilize this structure efficiently:

  1. Create a top-level install directory outside the source tree,
  2. Create a top-level build directory outside the source and install trees and change directory into it.
  3. Execute the following CMake command:
    cmake -DCMAKE_INSTALL_PREFIX=<install-dir> <source-dir>

You will then be able to build your package with:

make

Any tests should be executed with:

make test
(they will have been built during the initial make).

In order to copy all product files into their final structure, execute:

make install
Everything should be put into <install-dir>/<product> and below.

At this point, you should check the installed package. Once you are happy with the install step, you can make a package tarball.

Distributing your product.

make package

This creates a tarball in your top build directory with the correct name.

Installing your product on oink.

First, ensure that the tarball will be visible from another account (you may need to chmod 755 ~). Then:

ssh -l products oink

Note: if this fails for you, get someone for whom this works to add your principal to ~products/.k5login.
cd /products
tar zxf <tarball>

You may need or wish to install other product or roll-up tarballs from ~distro on oink in the same way; or install individual centrally-provided packages.

Validating your installation on oink.

As yourself (not products) in a fresh login shell:

source /products/setup
setup <product> <version> -q<qual>

If applicable, you should run any post-install validation from $PRODUCT_FQ_DIR/example.