------------------------------------------------------------------------------ Trilinos CMake Quickstart ------------------------------------------------------------------------------ Section A: Getting Started -- Installing CMake from binary -- Installing CMake from source Section B: Getting Help -- CMake website -- Local CMake help Section C: Configuring Trilinos -- Setting up a build directory -- Basic configuration -- Selecting packages to enable -- Selecting compiler and linker options. -- Disabling Fortran -- Runtime Debug support -- Configuring MPI support -- Building shared libraries -- Configuring with third party libraries (TPLS) -- Getting verbose output -- Disabling dependency testing -- Enable coverage testing -- Viewing configure options and documentation -- Reconfiguring from scratch -- Viewing configure errors Section D: Building -- Building everything -- Building all the libraries for a package -- Building a single object Section E: Testing -- Using ctest -- Running tests for a single package -- Running a single test with output -- Running memory testing Section F: Installing -- Setting the install prefix -- How to install Section G: Packaging -- Creating a tarball package Section H: Dashboard testing -- Submitting an experimental build -- Environment variables for controlling the build -- Dashboard submission notes Getting set up to use CMake ------------------------------ (*) Installing a binary release of CMake [Recommended for Trilinos users]: Download and install the binary (currently version 2.8 is required) from: http://www.cmake.org/cmake/resources/software.html (*) Installing CMake from source [Recommended for Trilinos developers]: If you have access to the Trilinos CVS repository, then install CMake with: $ $TRILINOS_HOME/cmake/python/install-cmake.py --install-dir=INSTALL_BASE_DIR This will result in cmake and related CMake tools being installed in INSTALL_BASE_DIR/bin. Getting help for installing CMake with this script: $ $TRILINOS_HOME/cmake/python/install-cmake.py --help NOTE: you will want to read the help message about how to use sudo to install in a privileged location (like the default /usr/local/bin). Getting Help --------------- (*) Finding CMake help at the website: http://www.cmake.org (*) Building CMake help locally: $ cmake --help-full cmake.help.html (Open your web browser to the file cmake.help.html) Configuring (Makefile Generator) ----------------------------------- (*) Setting up a build directory: $ mkdir SOME_BUILD_DIR $ cd SOME_BUILD_DIR NOTE: You can create a build directory from any location you would like. It can be a sub-directory of the Trilinos base source directory or anywhere else. (*) Basic configuration of Trilinos: a) [Recommended] Create a 'do-configure' script like: EXTRA_ARGS=$@ cmake \ -D CMAKE_BUILD_TYPE:STRING=DEBUG \ -D Trilinos_ENABLE_:BOOL=ON \ -D Trilinos_ENABLE_TESTS:BOOL=ON \ -D DART_TESTING_TIMEOUT:STRING=600 \ $EXTRA_ARGS \ ${TRILINOS_HOME} where is Epetra, AztecOO, etc. and TRILINOS_HOME is set to the Trilinos source base directory (or your can just give it explicitly). You can then run the script as: $ ./do-configure [OTHER_OPTIONS] See Trilinos/sampleScripts/*cmake for real examples. b) Using ccmake to configure: $ ccmake $TRILINOS_HOME (*) Selecting the list of packages to enable: a) Configuring a package(s) along with all of the packages it can use: $ ./do-configure \ -D Trilinos_ENABLE_:BOOL=ON \ -D Trilinos_ENABLE_ALL_OPTIONAL_PACKAGES:BOOL=ON \ -D Trilinos_ENABLE_TESTS:BOOL=ON NOTE: This set of arguments allows a user to turn on as well as all packages that can use. However, tests and examples will only be turned on for (or any other packages specifically enabled). b) Configuring Trilinos to test all effects of changing a given package(s): $ ./do-configure \ -D Trilinos_ENABLE_:BOOL=ON \ -D Trilinos_ENABLE_ALL_FORWARD_DEP_PACKAGES:BOOL=ON \ -D Trilinos_ENABLE_TESTS:BOOL=ON NOTE: The above set of arguments will result in package and all packages that depend on to be enabled and have all of their tests turned on. Tests will not be enabled in packages that do not depend on in this case. This speeds up and robustifies pre-checkin testing. c) Configuring Trilinos to build all stable packages with all tests and examples: $ ./do-configure \ -D Trilinos_ENABLE_ALL_PACKAGES:BOOL=ON \ -D Trilinos_ENABLE_TESTS:BOOL=ON NOTE: Specific packages can be disabled with Trilinos_ENABLE_:BOOL=OFF. This will also disable all packages that depend on . NOTE: All examples are enabled by default when setting Trilinos_ENABLE_TESTS:BOOL=ON. NOTE: By default, setting Trilinos_ENABLE_ALL_PACKAGES=ON only enables Primary Stable Code. To have this also enable all secondary stable code, you must also you must set Trilinos_ENABLE_SECONDARY_STABLE_CODE=ON. d) Disable a package and all its dependencies: $ ./do-configure \ -D Trilinos_ENABLE_:BOOL=ON \ -D Trilinos_ENABLE_ALL_OPTIONAL_PACKAGES:BOOL=ON \ -D Trilinos_ENABLE_:BOOL=OFF Above, this will enable and all of the packages that it depends on except for and all of its forward dependencies. For example, if you run $ ./do-configure \ -D Trilinos_ENABLE_Thyra:BOOL=ON \ -D Trilinos_ENABLE_ALL_OPTIONAL_PACKAGES:BOOL=ON \ -D Trilinos_ENABLE_Epetra:BOOL=OFF The packages Thyra, RTOp, and Teuchos will be enabled, but the packages Epetra, EpetraExt will be disabled. e) Removing all package enables in the Cache $ ./-do-confiugre -D Trilinos_UNENABLE_ENABLED_PACKAGES:BOOL=TRUE This option will set to empty '' all package enables, leaving all other cache variables as they are. You can then reconfigure with a new set of package enables for a different set of packages. This allows you to avoid more expensive configure time checks and to preserve other cache variables that you have set and don't want to loose. (*) Selecting compiler and linker options: a) Configuring to build with default debug or release compiler flags: To build a debug version, pass into 'cmake': -D CMAKE_BUILD_TYPE:STRING=DEBUG This will result in default debug flags getting passed to the compiler. To build a release (optimized) version, pass into 'cmake': -D CMAKE_BUILD_TYPE:STRING=RELEASE This will result in optimized flags getting passed to the compiler. b) Adding arbitrary compiler flags but keeping other default flags: To append arbitrary compiler flags, configure with: -DCMAKE__FLAGS:STRING="" where = C, CXX, Fortran and are your extra compiler options like "-DSOME_MACRO_TO_DEFINE -funroll-loops". NOTE: Compiler options set with CMAKE__FLAGS will *not* override the set debug or release options which come after on the compile line. Therefore, this approach should only be used for options that will not get overridden by the internally-set debug or release compiler options. However, setting CMAKE__FLAGS will work well for adding extra compiler defines for example. NOTE: Any options that you set through the cache varible CMAKE__FLAGS_ (where = DEBUG or RELEASE) will get overridden in the code so don't try to manually set CMAKE__FLAGS_. c) Overriding debug/release compiler options: To pass in compiler options that override the default debug or release options use: -D CMAKE_BUILD_TYPE:STRING=NONE \ -D CMAKE_C_FLAGS:STRING="-04 -funrool-loops" \ -D CMAKE_CXX_FLAGS:STRING="-03 -fexceptions" where LANGUAGE = C, CXX, Fortran, etc. NOTE: Using CMAKE_BUILD_TYPE:STRING=NONE allows you to take complete control over what debug or release compiler optimizations or related options are passed to the compiler. d) Appending arbitrary link flags to every executable: In order to append any set of arbitrary link flags to your executables use: -D Trilinos_EXTRA_LINK_FLAGS:STRING="$EXTRA_LINK_FLAGS" Above, you can pass any type of library and they will always be the last libraries listed, even after all of the TPL. NOTE: This is how you must set extra libraries like Fortran libraries and MPI libraries (when using raw compilers). Please only use this variable as a last resort. NOTE: You must only pass in libraries in Trilinos_EXTRA_LINK_FLAGS and *not* arbitrary linker flags. To pass in extra linker flags that are not libraries, use the built-in CMake variable CMAKE_EXE_LINKER_FLAGS instead. e) Overriding all (strong warnings and debug/release) compiler options: To override all compiler options, including both strong warning options and debug/release options, configure with: -D CMAKE_BUILD_TYPE:STRING=NONE \ -D Trilinos_ENABLE_STRONG_C_COMPILE_WARNINGS:BOOL=OFF \ -D Trilinos_ENABLE_STRONG_CXX_COMPILE_WARNINGS:BOOL=OFF \ -D CMAKE_C_FLAGS:STRING="-04 -funrool-loops" \ -D CMAKE_CXX_FLAGS:STRING="-03 -fexceptions" \ f) Enable and disable shadowing warnings for all Trilinos packages: To enable shadowing warnings for all Trilinos packages (that don't already have them turned on) then use: -D Trilinos_ENABLE_SHADOW_WARNINGS:BOOL=ON To disable shadowing warnings for all Trilinos packages then use: -D Trilinos_ENABLE_SHADOW_WARNINGS:BOOL=OFF NOTE: The default value is empty '' which lets each Trilinos package decide for itself if shadowing warnings will be turned on or off for that package. g) Removing warnings as errors for CLEANED packages: To remove the -Werror flag (or some other flag that is set) from being applied to compile CLEANED packages like Teuchos, set the following when configuring: -D Trilinos_WARNINGS_AS_ERRORS_FLAGS:STRING="" (*) Disabling the Fortran compiler and all Fortran code: To disable the Fortran compiler and all Trilinos code that depends on Fortran set: -D Trilinos_ENABLE_Fortran:BOOL=OFF The user cache variable Trilinos_ENABLE_Fortran is used as a trigger in the Trilinos CMake build system to enable Fortran support or not. NOTE: The fortran compiler will be disabled automatically by default on systems like MS Windows. NOTE: Macs do not come with a compatible Fortran compiler by default so you must turn off Fortran if you don't have a compatible Fortran compiler. (*) Enabling runtime debug checking: a) Enabling Trilinos ifdefed runtime debug checking: To turn on optional ifdefed runtime debug checking, configure with: -D Trilinos_ENABLE_DEBUG=ON This will result in a number of ifdefs to be enabled that will perform a number of runtime checks. Nearly all of the debug checks in Trilinos will get turned on by default by setting this option. This option can be set independent of CMAKE_BUILD_TYPE. NOTE: The variable CMAKE_BUILD_TYPE controls what compiler options are passed to the compiler by default while Trilinos_ENABLE_DEBUG controls what defines are set in config.h files that control ifdefed debug checks. NOTE: Setting -DCMAKE_BUILD_TYPE:STRING=DEBUG will automatically set the default Trilinos_ENABLE_DEBUG=ON. b) Enabling checked STL implementation: To turn on the checked STL implementation set: -D Trilinos_ENABLE_CHECKED_STL:BOOL=ON NOTE: By default, this will set -D_GLIBCXX_DEBUG as a compile option for all C++ code. This only works with GCC currently. NOTE: This option is disabled by default because to enable it by default can cause runtime segfaults when linked against code that was compiled without -D_GLIBCXX_DEBUG set. (*) Configuring Trilinos for MPI support: To enable MPI support you must minimally: -D TPL_ENABLE_MPI:BOOL=ON There is built-in logic to try to find the various MPI components on your system but you can override (or make suggestions) with: -D MPI_BASE_DIR:PATH="path" Base path of a standard MPI installation which has the subdirs 'bin', 'libs', 'include' etc. -D MPI_BIN_DIR:PATH="path1;path2;...;pathn" Paths where the MPI executables (e.g. mpiCC, mpicc, mpirun, mpiexec) can be found. By default this is set to ${MPI_BASE_DIR}/bin if MPI_BASE_DIR is set. The value of LD_LIBRARY_PATH will also automatically be set to ${MPI_BASE_DIR}/lib if it exists. This is needed for the basic compiler tests for some MPI implementations that are installed in non-standard locations. a) Configuring build using MPI compiler wrappers: The MPI compiler wrappers are turned on by default. There is built-in logic that will try to find the right compiler wrappers. However, you can specifically select them by setting: -D MPI_[C,CXX_Fortran]_COMPILER:FILEPATH="exec_name" The name of the MPI C/C++/Fortran compiler wrapper executable. If this is just the name of the program it will be looked for in ${MPI_BIN_DIR} and in other standard locations with that name. If this is an absolute path, then this will be used as CMAKE_[C,CXX,Fortran]_COMPILER to compile and link code. b) Configuring to build using raw compilers and flags/libraries: While using the MPI compiler wrappers as described above is the preferred way to enable support for MPI, you can also just use the raw compilers and then pass in all of the other information that will be used to compile and link your code. To turn off the MPI compiler wrappers, set: -D MPI_USE_COMPILER_WRAPPERS:BOOL=ON You will then need to manually pass in the compile and link lines needed to compile and link MP programs. The compile flags can be set through: -D CMAKE_[C,CXX,Fortran]_FLAGS:STRING="$EXTRA_COMPILE_FLAGS" The link and library flags must be set through: -D Trilinos_EXTRA_LINK_FLAGS:STRING="$EXTRA_LINK_FLAGS" Above, you can pass any type of library or other linker flags in and they will always be the last libraries listed, even after all of the TPLs. NOTE: A good way to get the extra compile and link flags for MPI is to use: export EXTRA_COMPILE_FLAGS="`$MPI_BIN_DIR/mpiCC --showme:compile`" export EXTRA_LINK_FLAGS="`$MPI_BIN_DIR/mpiCC --showme:link`" where MPI_BIN_DIR is set to your MPI installations binary directory. c) Setting up to run MPI programs In order to use the ctest program to run MPI tests, you must set the mpi run command and the options it takes. The built-in logic will try to find the right program and options but you will have to override them in many cases. MPI test and example executables are run as: ${MPI_EXEC} ${MPI_EXEC_PRE_NUMPROCS_FLAGS} ${MPI_EXEC_NUMPROCS_FLAG} \ ${MPI_EXEC_POST_NUMPROCS_FLAGS} where TEST_EXECUTABLE_PATH, TEST_ARGS, and NP are specific to the test being run. The test-independent MPI arguments are: -D MPI_EXEC:FILEPATH="exec_name" The name of the MPI run command (e.g. mpirun, mpiexec) that is used to run the MPI program. This can be just the name of the program in which case the full path will be looked for in ${MPI_BIN_DIR} as described above. If it is an absolute path, it will be used without question. -D MPI_EXEC_MAX_NUMPROCS:STRING=4 The maximum number of processes to allow when setting up and running MPI test and example executables. The default is set to '4' and only needs to be changed when needed or desired. -D MPI_EXEC_NUMPROCS_FLAG:STRING=-np The command-line option just before the number of processes to use . The default value is based on the name of ${MPI_EXEC}. -D MPI_EXEC_PRE_NUMPROCS_FLAGS:STRING="arg1 arg2 ... argn" Other command-line arguments that must come *before* the numprocs argument. The default is empty "". -D MPI_EXEC_POST_NUMPROCS_FLAGS:STRING="arg1 arg2 ... argn" Other command-line arguments that must come *after* the numprocs argument. The default is empty "". (*) Enabling shared libraries: -D BUILD_SHARED_LIBS:BOOL=ON NOTE: The above option will result in all shared libraries to be build on all systems (i.e. *.so on Unix/Linux systems, *.dylib on Mac OS X, and *.dll on Windows systems). (*) Enabling support for optional Third-Party Libraries (TPLs): Pass into 'cmake': -D TPL_ENABLE_:BOOL=ON where = Boost, ParMETIS, etc. The headers, libraries, and library directories can then be specified with the input cache variables: _INCLUDE_DIRS:PATH: List of paths to the header include directories. Example: -D Boost_INCLUDE_DIRS:PATH=/usr/local/boost/include _LIBRARY_NAMES:STRING: List of unadorned library names, in the order of the link line. The platform-specific prefixes (e.g.. 'lib') and postfixes (e.g. '.a', '.lib', or '.dll') will be added automatically. Example: -D BLAS_LIBRARY_NAMES:STRING="blas;gfortran" _LIBRARY_DIRS:PATH: The list of directories where the library files can be found. Example: -D BLAS_LIBRARY_DIRS:PATH=/usr/local/blas NOTE: The variables TPL__INCLUDE_DIRS and TPL__LIBRARIES are what are directly used by the CMake build infrastructure. These variables are normally set by the variables _INCLUDE_DIRS, _LIBRARY_NAMES, and _LIBRARY_DIRS using find commands but you can always override these by setting the (type FILEPATH) cache variables TPL__INCLUDE_DIRS and TPL__LIBRARIES. This gives the user complete and direct control in specifying exactly what is used in the build process. The other variables that start with _ are just a convenience to make it easier to specify the location of the libraries. NOTE: In order to allow a TPL that normally requires one or more libraries to ignore the libraries, you can set: -D BLAS_LIBRARY_NAMES:STIRNG="" Optional package-specific support for a TPL can be turned off by passing into 'cmake': -D _ENABLE_:BOOL=OFF where is Epetra, NOX etc. This gives the user full control over what TPLs are supported by which package independently. Support for an optional TPL can also be turned on implicitly by setting: -D _ENABLE_:BOOL=ON That will result in setting TPL_ENABLE_=ON internally (but not set in the cache) if TPL_ENABLE_=OFF is not already set. (*) Getting verbose output from configure: $ ./do_configure -D Trilinos_VERBOSE_CONFIGURE:BOOL=ON NOTE: This produces a *lot* of output but can be very useful when debugging configuration problems (*) Getting verbose output from the makefile: $ ./do_configure -D CMAKE_VERBOSE_MAKEFILE:BOOL=TRUE (*) Getting very verbose output from configure: $ ./do_configure -D Trilinos_VERBOSE_CONFIGURE:BOOL=ON --debug-output --trace NOTE: This will print a complete stack trace to show exactly where you are. (*) Disabling framework level dependency tests: -D Trilinos_ENABLE_DEPENDENCY_UNIT_TESTS:BOOL=OFF \ -D Trilinos_ENABLE_ALL_PACKAGES:BOOL=OFF NOTE: Above will disable the Trilinos framework-level dependency unit tests which have names like TrilinosDep_* and TrilinosOutputDep_*. You should turn these off, for example, when you are doing a dynamic analysis (i.e. memcheck with valgrind) test. (*) Disable update of package dependency information: To turn off the update of the various XML and HTML dependency files back into the Trilinos source tree, use the configure option: -D Trilinos_DEPS_XML_OUTPUT_FILE:FILEPATH= NOTE: You must start from a clean cache for this to work. NOTE: Disabling the update of these XML and HTML files back into the source tree will speed up successive re-configures by a few seconds. (*) Enabling support for coverage testing: -D Trilinos_ENABLE_COVERAGE_TESTING:BOOL=ON NOTE: The above will set the compile and link options -fprofile-arcs -ftest-coverage when the compiler is GNU. NOTE: You can run the coverage tests and submit to the dashboard with 'make dashboard' (see below). (*) Viewing configure options and documentation: a) Viewing available configure-time options with documentation $ cd $BUILD_DIR $ rm CMakeCache.txt $ cmake -LAH -D Trilinos_ENABLE_ALL_PACKAGES:BOOL=ON \ $TRILINOS_HOME NOTE: You can also just look at the text file CMakeCache.txt after configure which gets created in the build directory and has all of the cache variables and documentation. b) Viewing available configure-time options without documentation $ cd $BUILD_DIR $ rm CMakeCache.txt $ cmake -LA SAME_AS_ABOVE $TRILINOS_HOME c) Viewing current values of cache variables $ cmake -LA $TRILINOS_HOME or just examine and grep the file CMakeCache.txt. (*) Reconfiguring from scratch $ rm CMakeCache.txt ; ./do-configure NOTE: Removing the CMakeCache.txt file is often needed when removing variables from the configure line. (*) Viewing configure errors Configure time errors are shown in the file: $BUILD_BASE_DIR/CMakeFiles/CMakeError.log Building (Makefile generator) -------------------------------- (*) Building all targets: $ make [-jN] (where N is the number of processes to use) (*) Discovering what targets are available to build after configuration: $ make help (*) See all of the targets to build for a package: $ make help | grep _ (where = Teuchos, Epetra, NOX, etc.) or: $ cd packages/ $ make help (*) Building all of the targets for a package: $ make _all (where = Teuchos, Epetra, NOX, etc.) or: $ cd packages/ $ make (*) Building all of the libraries for a package: $ make _libs (where = Teuchos, Epetra, NOX, etc.) (*) Building all of the libraries for all enabled Trilinos packages: $ make libs NOTE: This target depends on the _libs targets for all of the enabled Trilinos packages. NOTE: You can also use the target name 'Trilinos_libs'. (*) Building a single object file: First, look for the name of the object file to build based on the source file SomeSourceFile.cpp: $ make help | grep SomeSourceFile.o Build the source file: $ rm WHATEVER_WAS_RETURNED_ABOVE ; make WHATEVER_WAS_RETURNED_ABOVE NOTE: CMake does not seem to correctly address dependencies when building just object files so you need to always delete the object file first to make sure that it gets rebuilt correctly. (*) Building with verbose output without reconfiguring: $ make [] VERBOSE=1 (*) Relink a target without considering dependencies: $ make /fast Testing with CTest --------------------- (*) [Recommended] Testing using 'ctest' $ ctest -W 100 (see output in Testing/Temporary/LastTest.log) NOTE: The -W argument is only supported in the CVS version of CMake obtained as explained above. See detailed test output with: $ ctest -VV (*) Only running tests for a single package Running a single package test: $ ctest -W 100 -R '^_' (e.g. PACKAGE = Teuchos, Epetra, etc.) (see output in Testing/Temporary/LastTest.log) or: $ cd packages/ $ ctest -W 100 (*) Running a single test with full output to the console: $ ctest -R ^FULL_TEST_NAME$ -VV (e.g. FULL_TEST_NAME = Teuchos_Comm_test, Epetra_MultiVector_test, etc. ) (*) Running memory checking: To run the memory tests for just a single package, from the *base* build directory, run: $ ctest -R '^_' -T memcheck (where = Epetra, NOX etc.). (see the detailed output in ./Testing/Temporary/LastDynamicAnalysis_DATE_TIME.log) NOTE: If you try to run memory tests from any subdirectories, that does not seem to work. You have to run them from the base build directory and then use -R '^_' with ctest in order to run your packages tests. (*) Testing using 'make test' $ make test NOTE: This is equivalent to just running 'ctest' without any arguments. Installing ------------- (*) Setting the install prefix at configure time $ ./do-configure \ -D CMAKE_INSTALL_PREFIX:PATH=$HOME/PROJECTS/install/trilinos/mpi/opt NOTE: The script 'do-configure' is just a simple shell script that calls CMake as shown above. (*) Installing after configuration $ make install (will build all of the targets needed before the install) (*) Uninstall $ make uninstall Packaging ------------ (*) Creating a tarball of the source tree: $ make package_source NOTE: The above command will tar up *everything* in the source tree (except for files explicitly excluded in the CMakeLists.txt files) so make sure that you start with a totally clean source tree before you do this. Or, you could build Doxygen documentation first and then tar up Trilinos and that would give you the source with Doxygen documentation. NOTE: You can control what gets put into the tarball by setting the cache variable CPACK_SOURCE_IGNORE_FILES when configuring with CMake. Dashboard submissions ------------------------ You can use the extended CTest scripting system in Trilinos to submit package-by-package build, test, coverage, memcheck results to the dashboard. To do this, just configure a build directory like you would for any other purpose and they type: $ make dashboard This invokes the advanced CTest script Trilinos/cmake/ctest/experimental_build_test.cmake to do an experimental build for all of the packages that you have explicitly enabled. The packages that are implicitly enabled due to package dependencies are not directly processed by the experimental_build_test.cmake script. There are a number of options that you can set in the environment to control what this script does. This set of options can be found by doing: $ grep 'SET_DEFAULT_AND_FROM_ENV(' \ Trilinos/cmake/ctest/TrilinosCTestDriverCore.cmake Currently, this options includes: SET_DEFAULT_AND_FROM_ENV( CTEST_TEST_TYPE Nightly ) SET_DEFAULT_AND_FROM_ENV( CTEST_SITE ${CTEST_SITE_DEFAULT} ) SET_DEFAULT_AND_FROM_ENV( CTEST_DASHBOARD_ROOT "" ) SET_DEFAULT_AND_FROM_ENV( BUILD_TYPE NONE ) SET_DEFAULT_AND_FROM_ENV(COMPILER_VERSION UNKNOWN) SET_DEFAULT_AND_FROM_ENV( CTEST_BUILD_NAME SET_DEFAULT_AND_FROM_ENV( CTEST_START_WITH_EMPTY_BINARY_DIRECTORY TRUE ) SET_DEFAULT_AND_FROM_ENV( CTEST_WIPE_CACHE TRUE ) SET_DEFAULT_AND_FROM_ENV( CTEST_CMAKE_GENERATOR "Unix Makefiles") SET_DEFAULT_AND_FROM_ENV( CTEST_DO_UPDATES TRUE ) SET_DEFAULT_AND_FROM_ENV( CTEST_GENERATE_DEPS_XML_OUTPUT_FILE FALSE ) SET_DEFAULT_AND_FROM_ENV( CTEST_UPDATE_ARGS "-q -z3") SET_DEFAULT_AND_FROM_ENV( CTEST_BUILD_FLAGS "-j2") SET_DEFAULT_AND_FROM_ENV( CTEST_DO_BUILD TRUE ) SET_DEFAULT_AND_FROM_ENV( CTEST_DO_TEST TRUE ) SET_DEFAULT_AND_FROM_ENV( Trilinos_WARNINGS_AS_ERRORS_FLAGS "" ) SET_DEFAULT_AND_FROM_ENV( CTEST_DO_COVERAGE_TESTING FALSE ) SET_DEFAULT_AND_FROM_ENV( CTEST_COVERAGE_COMMAND gcov ) SET_DEFAULT_AND_FROM_ENV( CTEST_DO_MEMORY_TESTING FALSE ) SET_DEFAULT_AND_FROM_ENV( CTEST_MEMORYCHECK_COMMAND valgrind ) SET_DEFAULT_AND_FROM_ENV( CTEST_DO_SUBMIT TRUE ) SET_DEFAULT_AND_FROM_ENV( Trilinos_ENABLE_SECONDARY_STABLE_CODE OFF ) SET_DEFAULT_AND_FROM_ENV( Trilinos_ADDITIONAL_PACKAGES "" ) SET_DEFAULT_AND_FROM_ENV( Trilinos_EXCLUDE_PACKAGES "" ) SET_DEFAULT_AND_FROM_ENV( Trilinos_PACKAGES "${Trilinos_PACKAGES_DEFAULT}" ) For example, to run an experimental build and in the process change the build name and the options to pass to 'make', use: $ env CTEST_BUILD_NAME=MyBuild CTEST_BUILD_FLAGS='-j8' \ make dashboard After this finishes running, look for the build 'MyBuild' (or whatever build name you used above) in the Trilinos CDash dashboard. NOTE: It is useful to set CTEST_BUILD_NAME to some unique name to make it easier to find your results in the CDash dashboard. NOTE: A number of the defaults set in TrilinosCTestDriverCore.cmake are overridden from experimental_build_test.cmake so you will want to look at experimental_build_test.cmake to see how these are changed. The script experimental_build_test.cmake sets reasonable values for these options in order to use the 'make dashboard' target in iterative development. NOTE: The target 'dashboard' is not directly related to the built-in CMake targets 'Experimental*' that run a standard dashboard with CTest without the custom package-by-package driver in TrilinosCTestDriverCore.cmake. The package-by-package extended CTest driver is more appropriate for Trilinos. NOTE: Once you configure with -DTrilinos_ENABLE_COVERAGE_TESTING:BOOL=ON, the environment variable CTEST_DO_COVERAGE_TESTING=TRUE is automatically set by the target 'dashboard' so you don't have to set this yourself. NOTE: Doing a memory check with Valgrind requires that you set CTEST_DO_MEMORY_TESTING=TRUE with the 'env' command as: $ env CTEST_DO_MEMORY_TESTING=TRUE make dashboard