The update CTEST interface. David Adams January 24, 2005 Introduction ============ CTEST is an interface for software packages to describe themselves so they may be built singly or collectively with an advertised, noncircular dependency structure. The package has an assumed structure including a collection of configuration files. All file references below are relative to the to top level directory of the package. It is assumed the suffix of this directory is the package name. Package names may be hierarchical, expressed as a directory path, i.e. mypkg, mydir1/mypkg and mydir2/mydir1/mypkg are all valid package names. The last entry in the hierarchy (mypkg in all the examples) is the base package name, denoted . This base package must be unique. The top level includes the following directories: - holding public header files src - holding the sources for building the library, binaries and tests scripts - holds public scripts doc - holding documentation and change log external - see section "Externals" below. The top level also includes the following configuration files: VERSION - Package version in the format i-j-k or i.j.k. MAKEDIRS - list of subdirectories requiring prebuild make--see the section describing prebuild makes LIBDEPS - list of packages upon which this package depends COMPONENTS - list of names of components used to construct the library FCOMPONENTS - list of names of fortran components used to construct the library BINARIES - list of C++ binaries SCRIPTS - lists of scripts to be installed LIBDEPS is called the dependency configuration file or simply the dependency file. COMPONENTS, FCOMPONENTS, BINARIES and SCRPTS are the component configuration files aka component files. Rules ===== A CTEST-compliant build system should provide commands to build, test and install the packge based on this package structure. Rules are as follows. 1. A full list of dependencies is constructed from LIBDEPS and recursively the LIBDEPS files for the dependencies. The entries in LIBDEPS are full package names. The LIBDEPS file itself and the generated full list are in strict dependency order, i.e. each entry depends only on those listed earlier. Circular dependencies are not allowed. The packages listed in in the full list of dependencies are called the depend packages, their public headers the depend headers, their libraies are the depend libraries, and their binaries are the depend binaries. This full list of dependencies is written to /FULLDEPS. 2. Header myclass.h in the package is referenced from sources by #include "/myclass.h" 4. Build means to build a library, binary, a test for each component and a test for each binary. 5. Building the library means to construct a library lib.so from objects obtained by compiling files corresponding to each of the entries in COMPONENTS. For each entry NAME, the C++ file src/NAME.cxx is used as the source. The depend and current headers are accessible during compilation. The depend libraries are accessible for linking. 6. Building binaries means to build and executable NAME for each entry NAME in BINARIES. The executable is built from the file src/NAME.cxx. The depend and current headers are available during compilation. The depend and current libraries are available for linking. Thus the library must be built before the binaries. 7. Building tests means to build an executable NAME_t for each NAME in COMPONENTS and BINARIES. The source for each is src/NAME_t.cxx and must include a main entry point if CTEST_MAIN is cpp defined. It is conventional to not provide the entry point if CTEST_MAIN is undefined and isntead to provide the entry point CTEST_t. The depend and current headers are available for comilation and the depend and current libraries are available for linking. 8. Test means to run each of these test executables in an empty directory. Success is assumed if andd only if the executable returns zero. 9. Install means to make the public headers, scripts, library, binaries and available outlide the ctest system, typically by copying to an installation directory with the respective subdirectories include, scripts, lib and bin. 10. For each package and external setup file extsetup_.sh is generate and written to the sbin subdirectory of the the install area. This file should set the required external packages up in dependency order so that path appends result in dependency ordering and prepends (typical) result in reverse dependency ordering. Externals ========= A CTEST module may describe one external software package dependency. Standard packages use the LIBDEPS mechanism to express dependencies on special packages that serve primarily to describe such dependencies. These are often held in the container external, e.g. external/myslq. The external dependency is described by a directory external with the following contents: NAME - name for the external software INCDIRS - Relative directories holding include files. The include path is constructed from this list. LIBDIRS - Relative directories containg libraries. The library path (e.g. LD_LIBRARY_PATH) constructed from this list. BINDIRS - Relative directories containing binaries or scripts. The executable path (typically PATH) is constructucted from this. LIBS - Names of the libraries to be linked against, e.g. mylib to link against libmylib.so. ENVS - Environment variables to define before using the software. DATA - Files to be copied to data/ during installation. To preseve directory structure, copy directory name OPTIONAL - Keywords indicating when the external package is required. The package managment ingterface pkgmgr is used to find the package location using the name. All the above directories are relative to this location. Each referenced external software packages must be installed in a manner consistent with this description when the CTEST package are built, tested or run. A setup file based on pkgmgr is created for each package so that the software may be built with one set of external packages and run with another, e.g. on a different machine. The list of environmental variables in ENVS has the format VARVAL for each entry. The following value of are allowed: = Assign the value VAL to the varible VAR == Assign the value /VAL to the variable VAR -= Prepend the value VAL to the path VAR -== Prepend the value /VAL to the path VAR += Append the value VAL to the path VAR +== Append the value /VAL to the path VAR Here is the location of the external package specified in NAME. In the cases making use of this location (==, -== and +==), VAL may be left blank and the assigned value is . The build system is expected to create an external setup file for the package which sets up each of the external packages in accordance with these instructions. The file OPTIONAL may hold any of the following keywords with the indicated meanings: build - External package need not be present for building. run - External package need not be present for runnning. If build is not specified then the build system exits with error if the referenced package is not found. If run is not specified, then the external setup script should not fail if the external package is not found. Prebuild makes ============== The configuration file MAKEDIRS lists the package subdirectories in which processing is to be done before building. The instructions for processing are carried in three files: Makefile - Processed before building and after reading dependency and component files CompMakefile - Processed before reading component files and after reading dependency files DepMakefile - Processed before reading dependency files One or more of these files must be present if any processing is to be carrried out. Makefile may be replaced by Makefile.in. DepMakfile is typically used to construct