Policy guidelines for building installing and deploying products

As a result of further discussions with Marc Paterno and Ron Rechenmacher, some additions and modifications have been made as of 9/14/2010.

As a result of discussions as part of artfest IV some additions and modifications have been made as of 10/18/2010 to be consistent with the new instructions on product building / deployment.

NOTE As of 10/18/2010, most of this policy is encoded in the cmake files found in the ToyCmake example of the cetbuildtools package. Please keep your package's cmake files up-to-date with the latest version of this example package.

  • The product directory structure is now allowed to be the following:
    • product/version/flavor independent stuff
    • product/version/flavor-qualifier/flavor and qualifier dependent stuff
    • PRODUCT_DIR is .../product/version
    • PRODUCT_FQ_DIR is .../product/version/flavor-qualifier
    • The flavor independent stuff will include a ups directory where the table file lives and might also include source code, documentation, headers, etc.
    • The flavor dependent stuff will include executables, libraries, and perhaps generated code.
    • Headers might live under either $PRODUCT_DIR or under $PRODUCT_FQ_DIR. In most cases the headers are common, but in some special cases the headers might need to be massaged for the debug build. If that happens, all necessary headers will be found in (say) $PRODUCT_FQ_DIR/include instead of $PRODUCT_DIR/include.
  • All products must define 5 environment variables:
    • PRODUCT_DIR (base directory, used as the install target)
    • PRODUCT_FQ_DIR (base directory for a specific flavor-qualifier combination)
      • In most cases, $PRODUCT_LIB will also be added to LD_LIBRARY_PATH (or the equivalent).
      • The table file can search a list of possible header directories
      • The table file will choose the first match it finds, and the directory search always starts in $PRODUCT_FQ_DIR
      • Same as the ups version name (vx_y_z)?
      • Alternatively, x.y.z
      • Used both in cmake and to create the ups table file
      • The actual scheme will depend on what works with the least pain in both places, so far we seem to be OK with vx_y_z
    • If PRODUCT_FQ_DIR/bin exists, it will be added to the PATH
      • It may be useful to define PRODUCT_BIN
  • No source code repository will contain any directories named build, install, lib, etc.
  • The build, install, and source code directories should all be distinct and can be in arbitrary places
  • Cmake will check for the presence of PRODUCT_VERSION for each dependent product and fail if the variable is not set
    • Eventually cmake will check the version number for compatibility with the product source
  • UPS qualifiers will be used to distinguish builds of a product against different dependencies
  • Possible dependencies
    • Compiler version
    • Optimized versus debug
    • Multithreading versus no threading
    • Boost version
    • Swig version
    • Python version
    • Root version
    • ... and the list goes on
  • Given that we do not want a long string as a qualifier, and that you can always use "ups depend" to verify the list of dependent products, use a short, arbitrary, string as a qualifier
  • Qualifier defaults (never specified, always implicit)
    • optimized
    • no profiling
    • multithreaded
  • Possible qualifiers based on the above rules:
    • a1
    • a1:debug
    • mu1
    • mu2:debug
    • mozart
  • The UPS table file will be created at build time from a template
    • This allows us to embed the actual versions of dependent products without editing code from the repository
  • The UPS version file can also be created at build time from a template
  • Each product will also have a script that can be used by the developer to establish the necessary environment in cases where ups is not used
  • Products are expected to have a $PRODUCT_DIR/ups directory when they are installed.
  • Products are expected to have (as relevant) include, bin, lib, and doc subdirectories in either $PRODUCT_DIR or $PRODUCT_FQ as appropriate.
  • The tarball naming convention is described at
  • Flavor-qualifier strings
    • the ups default flavor is Linux64bit+2.6-2.5 for 64-bit Scientific Linux 5.x on a 64bit OS
    • We propose to use a string which matches our tarball naming for the flavor-qualifier directory
      • sl5.x86_64 means 64bit SL 5.x and is the same as Linux64bit+2.6-2.5
      • sl4.i686 means 32bit SL 4.x
      • Qualifiers will be added to the end of the flavor descriptor: sl5.x86_64.cet
      • MacOSX flavor strings will be Darwin8 (Tiger), Darwin9 (Leopard), Darwin10 (Snow Leopard), with .i386 or .x86_64 as appropriate