/*! \mainpage Trilinos/CMake

------------------------------------------------------------------------------
                         Trilinos CMake Quickstart
------------------------------------------------------------------------------

<ul>
<li>\ref Getting_started
<li>\ref Getting_help
<li>\ref Configuring
<li>\ref Building
<li>\ref Testing
<li>\ref Installing
<li>\ref Packaging
<li>\ref Dashboard
</ul>

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
    --  Enabling/disabling deprecated warnings
    --  Disable update of package dependency information
    --  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


\section Getting_started A) 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).



\section Getting_help B) 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)



\section Configuring C) 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_<PACKAGE>:BOOL=ON \
          -D Trilinos_ENABLE_TESTS:BOOL=ON \
          -D DART_TESTING_TIMEOUT:STRING=600 \
          $EXTRA_ARGS \
          ${TRILINOS_HOME}

      where <PACKAGE> 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_<PACKAGE>: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 <PACKAGE> as well as
    all packages that <PACKAGE> can use.  However, tests and examples will
    only be turned on for <PACKAGE> (or any other packages specifically
    enabled).
  
  b) Configuring Trilinos to test all effects of changing a given package(s):
  
    $ ./do-configure \
       -D Trilinos_ENABLE_<PACKAGE>: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 <PACKAGE> and all
    packages that depend on <PACKAGE> to be enabled and have all of their
    tests turned on.  Tests will not be enabled in packages that do not depend
    on <PACKAGE> 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_<PACKAGE>:BOOL=OFF.  This will also disable all packages
    that depend on <PACKAGE>.
  
    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_<PACKAGE_A>:BOOL=ON \
         -D Trilinos_ENABLE_ALL_OPTIONAL_PACKAGES:BOOL=ON \
         -D Trilinos_ENABLE_<PACKAGE_B>:BOOL=OFF

     Above, this will enable <PACKAGE_A> and all of the packages that it
     depends on except for <PACKAGE_B> 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_<COMPILER>_FLAGS:STRING="<EXTRA_COMPILER_OPTIONS>"

    where <COMPILER> = C, CXX, Fortran and <EXTRA_COMPILER_OPTIONS> are your
    extra compiler options like "-DSOME_MACRO_TO_DEFINE -funroll-loops".

    NOTE: Compiler options set with CMAKE_<COMPILER>_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_<COMPILER>_FLAGS will work well for adding extra
    compiler defines for example.

    NOTE: Any options that you set through the cache varible
    CMAKE_<COMPILER>_FLAGS_<BUILD_TYPE> (where <BUILD_TYPE> = DEBUG or
    RELEASE) will get overridden in the code so don't try to manually set
    CMAKE_<COMPILER>_FLAGS_<BUILD_TYPE>.
  
  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 -funroll-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 -funroll-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.

    NOTE: In order to turn on the maximum testing on for the Teuchos memory
    management classes (like Teuchos::RCP), then you need to configure with
    -DTeuchos_ENABLE_DEBUG_RCP_NODE_TRACING:BOOL=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=OFF

    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} <NP> \
        ${MPI_EXEC_POST_NUMPROCS_FLAGS} <TEST_EXECUTABLE_PATH> <TEST_ARGS>

    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
        <NP>.  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_<TPLNAME>:BOOL=ON

  where <TPLNAME> = Boost, ParMETIS, etc.

  The headers, libraries, and library directories can then be specified with
  the input cache variables:

    <TPLNAME>_INCLUDE_DIRS:PATH: List of paths to the header include
      directories.

      Example:
 
       -D Boost_INCLUDE_DIRS:PATH=/usr/local/boost/include

      <TPLNAME>_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"

    <TPLNAME>_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_<TPLNAME>_INCLUDE_DIRS and TPL_<TPLNAME>_LIBRARIES
  are what are directly used by the CMake build infrastructure.  These
  variables are normally set by the variables <TPLNAME>_INCLUDE_DIRS,
  <TPLNAME>_LIBRARY_NAMES, and <TPLNAME>_LIBRARY_DIRS using find commands but
  you can always override these by setting the (type FILEPATH) cache
  variables TPL_<TPLNAME>_INCLUDE_DIRS and TPL_<TPLNAME>_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 <TPLNAME>_ 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 <PACKAGE>_ENABLE_<TPLNAME>:BOOL=OFF

  where <PACKAGE> 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 <PACKAGE>_ENABLE_<TPLNAME>:BOOL=ON

  That will result in setting TPL_ENABLE_<TPLNAME>=ON internally (but not set
  in the cache) if TPL_ENABLE_<TPLNAME>=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.


(*) Enabling/disabling deprecated warnings:

    -D Trilinos_SHOW_DEPRECATED_WARNINGS:BOOL=OFF

  Above will disable, by default, all deprecated warnings in Trilinos.  By
  default, deprecated warnings are enabled.

  To enable/disable deprecated warnings for a single Trilinos package use:

    -D <PACKAGE>_SHOW_DEPRECATED_WARNINGS:BOOL=OFF

  This will override the global behavior set by
  Trilinos_SHOW_DEPRECATED_WARNINGS for individual packages <PACKAGE>
  (e.g. <PACKAGE> = Teuchos, Thyra, etc.)


(*) 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 different test categories:

    -D Trilinos_TEST_CATEGORIES:STRING="<CATEGORY1>;<CATEGORY2>;..." 

  Valid categories include BASIC, NIGHTLY, and PERFORMANCE.  BASIC tests get
  built and run for pre-push testing and nighly testing.  NIGHTY tests are for
  pos-push and nighly testing.  PERFORAMNCE tests are for perforamnce testing
  only.


(*) 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 ; find . -name CMakeFiles -exec rm -rf {} \;
      $ ./do-configure
  
    NOTE: Removing the CMakeCache.txt file is often needed when removing
    variables from the configure line.  Removing the CMakeFiles directories is
    needed if there are changes in some CMake modules or the CMake version
    itself.


(*) Viewing configure errors

  Configure time errors are shown in the file:

      $BUILD_BASE_DIR/CMakeFiles/CMakeError.log



\section Building D) 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 <PACKAGE>_

  (where <PACKAGE> = Teuchos, Epetra, NOX, etc.)

  or:

     $ cd packages/<PACKAGE>
     $ make help


(*) Building all of the targets for a package:

     $ make <PACKAGE>_all

  (where <PACKAGE> = Teuchos, Epetra, NOX, etc.)

  or:

    $ cd packages/<PACKAGE>
    $ make


(*) Building all of the libraries for a package:

    $ make <PACKAGE>_libs

  (where <PACKAGE> = Teuchos, Epetra, NOX, etc.)


(*) Building all of the libraries for all enabled Trilinos packages:

    $ make libs

  NOTE: This target depends on the <PACAKGE>_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 [<SOME_TARGET>] VERBOSE=1


(*) Relink a target without considering dependencies:

    $ make <SOME_TARGET>/fast



\section Testing E) Testing with CTest
---------------------


(*) [Recommended] Testing using 'ctest'

    $ ctest -j4

  (see output in Testing/Temporary/LastTest.log)

  NOTE: The -jN argument allows CTest to use more processes to run
  tests but will not exceed the max number of processes specified at
  configure time.

  See detailed test output with:

    $ ctest -j4 -VV


(*) Only running tests for a single package

  Running a single package test:

    $ ctest -j4 -R '^<PACKAGE>_'

  (e.g. PACKAGE = Teuchos, Epetra, etc.)
  (see output in Testing/Temporary/LastTest.log)

  or:

    $ cd packages/<PACKAGE>
    $ ctest -j4


(*) 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 '^<PACKAGE>_' -T memcheck

  (where <PACKAGE> = 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 '^<PACKAGE>_' 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.



\section Installing F) 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



\section Packaging G) 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.


\section Dashboard H) 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:

  $ env CTEST_BUILD_FLAGS=-j4 CTEST_PARALLEL_LEVEL=4 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(Trilinos_TRACK "")
  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 ${DEFAULT_GENERATOR})
  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 "")
  SET_DEFAULT_AND_FROM_ENV( CTEST_UPDATE_OPTIONS "")
  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( MPI_EXEC_MAX_NUMPROCS 4 )
  SET_DEFAULT_AND_FROM_ENV( CTEST_PARALLEL_LEVEL 1 )
  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_BRANCH "" )
  SET_DEFAULT_AND_FROM_ENV( Trilinos_REPOSITORY_LOCATION "software.sandia.gov:/space/git/${CTEST_SOURCE_NAME}" )
  SET_DEFAULT_AND_FROM_ENV( Trilinos_PACKAGES "${Trilinos_PACKAGES_DEFAULT}" )
  SET_DEFAULT_AND_FROM_ENV( CTEST_SELECT_MODIFIED_PACKAGES_ONLY OFF )

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' CTEST_PARALLEL_LEVEL=8 \
    make dashboard

After this finishes running, look for the build 'MyBuild' (or whatever build
name you used above) in the Trilinos CDash dashboard.

NOTE: The 'make dashboard' target sets 

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 (such as
CTEST_TEST_TYPE=Experimental) 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 for experimental builds.

NOTE: The target 'dashboard' is not directly related to the built-in
CMake targets 'Experimental*' that run standard dashboards 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

*/
