CASA Build Tool Wrappers User's Guide

STATUS: Early Draft

About

CASA Build Tool Wrappers wrap the CASA build and test tools to:
  • help developers think about what they want to do, not how to do it (in the typical case), and
  • provide a simple abstraction layer that other build and test automation can be built on.

Note: this abstraction will not be complete. It is NOT a goal of this project to hide the build and test tools from developers. The goal is to help developers to work more quickly and consistently in the typical case.

See the project page for information about development or to suggest improvements.

Note: These tools are immature and under active development.

Installation

  1. "cd" to your top level CASA work directory. This is usually the directory containing your checked out copy of casacore, code, gcwrap, etc..
  2. Download buildToolWrappers-X.Y.Z.tgz from the job page on the CASA continuous build/test server.
  3. untar this package. This will unpack a file named .btwrc, and a directory named buildToolWrappers-X.Y.Z.
  4. edit .btwrc for your preferences. See Configuration.
  5. add buildToolWrappers-X.Y.Z/bin to your path every time you start work in a new shell in that CASA work directory.

Configuring Build Tool Wrappers

CASA Build Tool Wrappers are designed to be customized per project. Edit .btwrc as needed.

Do NOT change anything below the line "DO NOT CHANGE ANYTHING BELOW!"

Configurable options:

  • btwBranch - valid values are
    • "trunk" - default. All new development (except special case branches) belongs on trunk.
    • "test" - for bug fixing on the test branch. This will not be valid for much longer.
    • "stable-YYYY-MM" - for bug fixing on the current stable branch. "YYYY" is the year. "MM" is the month.
    • "release-X_Y_Z - for bug fixing leading up to the next release.

  • btwCpuCores - default is 2. If you have enough CPU cores available, increase it for faster builds.

  • btwLogLevel - default is 4, which will show all messages. Valid values are:
    • fatal - 0
    • error - 1
    • warning - 2
    • info - 3
    • debug - 4

  • btwLogTimeFormat - allows you to prepend a date/time stamp to messages. Format strings must be valid options for the date command. To suppress date/time stamps, set to an empty string.

  • btwAdditionalCmake*Options - allow you to add to generated CMake command line options. These will be appended to the end of generated CMake options. These are intended for addressing host specific issues or experimental changes to generated CMake options. Variables are named:
    • btwAdditionalCmakeAsapOptions - options to add to the asap CMake command line.
    • btwAdditionalCmakeCasacoreOptions - options to add to the casacore CMake command line.
    • btwAdditionalCmakeCodeOptions - options to add to the code CMake command line.
    • btwAdditionalCmakeGcwrapOptions - options to add to the gcwrap CMake command line.

  • btwAdditionalMake*Options - allow you to add make command line options to calls to make in compile*, install*, and test* scripts. The same options are applied to all calls to make within a build component. Common uses may include to set "VERBOSE=1" to enable very verbose make output, or set "-d" or "--debug[=FLAGS]" for finer control of debug output. See "man make".
    • btwAdditionalMakeAsapOptions - options added to calls to make in compileAsap, installAsap, and testAsap.
    • btwAdditionalMakeCasacoreOptions - options added to calls to make in compileCasacore, installCasacore, and testCasacore.
    • btwAdditionalMakeCodeOptions - options added to calls to make in compileCode, installCode, and testCode.
    • btwAdditionalMakeGcwrapOptions - options added to calls to make in compileGcwrap, installGcwrap, and testGcwrap.

  • defaultCasaDataPath - allow you to specify where your copy of the CASA Data Repository is on disk.

Available Tools

Checkout Tools

There is only one command to check out CASA source code - checkoutCasa. This command checks out all code required to build CASA from the branch recorded in $btwBranch. It checks out each CASA build component (asap, casacore, code, doc, gcwrap, pipeline, system-test) as a separate checkout in the development directory. This is to allow developers to checkout the subset of these build components that they will need for their work, and prevent an accidental "svn update" in the development directory from checking out unwanted code. In some cases, like system-test, this can be a very long and very annoying accident, as system-test will eventually include many GiBs of test data.

Command line options:
  • -h : Display help on command line options.
  • -d : Checkout documentation source code.
  • -p : Checkout pipeline source code.
  • -s : Checkout system tests and supporting data.

When checking out trunk, documentation source, pipeline source, and system test source and data are not checked out by default. When checking out any branch or tag, EVERYTHING on that branch or tag is checked out because branches and tags are used primarily to prepare packages. Also, when checking out trunk, doxygen.cfg and mainpage.dox are not checked out. They are copied from change control into the development directory to allow developers to build Doxygen docs. If you need to change these files, check just these files out in another directory for editing. This may be done with the command:

svn co --depth=files https://svn.cv.nrao.edu/svn/casa/trunk/

This will check out only doxygen.cfg and mainpage.dox into the current working directory.

Warning: If you checkout doxygen.cfg and mainpage.dox in a directory that you previously checked out CASA into using checkoutCasa, your next svn update in that directory will pull in all of the code not checked out previously.

I don't know of a way to check out a subset of the CASA trunk and doxygen.cfg and mainpage.dox in the same directory while preventing svn update from pulling in CASA build components you previously excluded.

End to End Build Tools

Each tool either builds all CASA build components (asap, casacore, code, gcwrap) in the correct order, or runs the sequence of configure, compile and link, test (optional), and install on the named build component.

  • buildCasa - runs the other build* tools in the correct order.

buildCasa does not take any command line arguments, but it will pass any command line arguments along to build* scripts it calls.

  • buildAsap
  • buildCasacore
  • buildCode
  • buildGcwrap
    • Command line options:
      • -h : Display help on command line options.
      • -r : Retry a failed incremental compile.
      • -s : Skip tests.

By default tests are run before installing build results. If tests fail, build results will not be installed. This helps keep the "installed" builds free of code that fails tests.

Compile Tools

Each tool compiles the named build component.

  • compileAsap
  • compileCasacore
  • compileCode
  • compileGcwrap

Configure Tools

Each tool configures the named build component.

  • configureAsap
  • configureCasacore
  • configureCode
  • configureGcwrap

The configure* commands accept the option "-c" to clean out build directories before configuring code.

Install Tools

Each tool installs the named build component.

  • installAsap
  • installCasacore
  • installCode
  • installGcwrap

Test Tools

Each tool runs build component tests for the named build component. These are tests that only require the build component and its prerequisites to be built to run. This excludes all end-to-end, "runUnitTest.py", and "regression.py" tests.

  • testAsap
  • testCasacore
  • testCode
  • testGcwrap

-- ScottRankin - 2014-02-21
Topic revision: r23 - 2014-03-11, ScottRankin
This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding NRAO Public Wiki? Send feedback