IntrepidNotes: Trilinos10CMakeQuickstart.txt

File Trilinos10CMakeQuickstart.txt, 33.4 KB (added by jacob, 8 years ago)
Line 
1/*! \mainpage Trilinos/CMake
2
3------------------------------------------------------------------------------
4                         Trilinos CMake Quickstart
5------------------------------------------------------------------------------
6
7
8Section A: Getting Started
9  --  Installing a binary release of CMake
10  --  Installing CMake from source
11Section B: Getting Help
12    --  CMake website
13    --  Local CMake help
14Section C: Configuring Trilinos
15  --  Setting up a build directory
16  --  Basic configuration
17  --  Selecting packages to enable
18  --  Selecting compiler and linker options.
19  --  Disabling Fortran
20  --  Runtime Debug support
21  --  Configuring MPI support
22  --  Building shared libraries
23  --  Configuring with third party libraries (TPLS)
24  --  Disabling tentatively enabled TPLs
25  --  Getting verbose output
26  --  Enabling/disabling deprecated warnings
27  --  Disable update of package dependency information
28  --  Enable coverage testing
29  --  Viewing configure options and documentation
30  --  Enabling extra external repositories with add-on packages
31  --  Reconfiguring from scratch
32  --  Viewing configure errors
33Section D: Building
34  --  Building everything
35  --  Building all the libraries for a package
36  --  Building a single object
37Section E: Testing
38  --  Using ctest
39  --  Running tests for a single package
40  --  Running a single test with output
41  --  Running memory testing
42Section F: Installing
43  --  Setting the install prefix
44  --  How to install
45Section G: Packaging
46  --  Creating a tarball package
47Section H: Dashboard testing
48  --  Submitting an experimental build
49  --  Environment variables for controlling the build
50  --  Dashboard submission notes
51
52
53A) Getting set up to use CMake
54------------------------------
55
56
57(*) Installing a binary release of CMake [Recommended for Trilinos users]:
58
59  Download and install the binary (currently version 2.8 is required) from:
60
61    http://www.cmake.org/cmake/resources/software.html
62
63
64(*) Installing CMake from source [Recommended for Trilinos developers]:
65
66  If you have access to the Trilinos CVS repository, then install CMake with:
67
68    $ $TRILINOS_HOME/cmake/python/install-cmake.py --install-dir=INSTALL_BASE_DIR
69
70  This will result in cmake and related CMake tools being installed in
71  INSTALL_BASE_DIR/bin.
72
73  Getting help for installing CMake with this script:
74
75    $ $TRILINOS_HOME/cmake/python/install-cmake.py --help
76
77  NOTE: you will want to read the help message about how to use sudo to
78  install in a privileged location (like the default /usr/local/bin).
79
80
81
82B) Getting Help
83---------------
84
85
86(*) Finding CMake help at the website:
87
88    http://www.cmake.org
89
90
91(*) Building CMake help locally:
92
93  $ cmake --help-full cmake.help.html
94
95  (Open your web browser to the file cmake.help.html)
96
97
98
99C) Configuring (Makefile Generator)
100-----------------------------------
101
102
103(*) Setting up a build directory:
104
105    $ mkdir SOME_BUILD_DIR
106    $ cd SOME_BUILD_DIR
107
108  NOTE: You can create a build directory from any location you would like.  It
109  can be a sub-directory of the Trilinos base source directory or anywhere
110  else.
111
112
113(*) Basic configuration of Trilinos:
114
115  a) [Recommended] Create a 'do-configure' script like:
116
117        EXTRA_ARGS=$@
118       
119        cmake \
120          -D CMAKE_BUILD_TYPE:STRING=DEBUG \
121          -D Trilinos_ENABLE_<PACKAGE>:BOOL=ON \
122          -D Trilinos_ENABLE_TESTS:BOOL=ON \
123          $EXTRA_ARGS \
124          ${TRILINOS_HOME}
125
126      where <PACKAGE> is Epetra, AztecOO, etc. and TRILINOS_HOME is set to the
127      Trilinos source base directory (or your can just give it explicitly).
128
129      You can then run the script as:
130
131        $ ./do-configure [OTHER_OPTIONS]
132
133      See Trilinos/sampleScripts/*cmake for real examples.
134
135  b) Using ccmake to configure:
136
137    $ ccmake $TRILINOS_HOME
138
139
140(*) Selecting the list of packages to enable:
141
142  a) Configuring a package(s) along with all of the packages it can use:
143 
144      $ ./do-configure \
145         -D Trilinos_ENABLE_<PACKAGE>:BOOL=ON \
146         -D Trilinos_ENABLE_ALL_OPTIONAL_PACKAGES:BOOL=ON \
147         -D Trilinos_ENABLE_TESTS:BOOL=ON
148 
149    NOTE: This set of arguments allows a user to turn on <PACKAGE> as well as
150    all packages that <PACKAGE> can use.  However, tests and examples will
151    only be turned on for <PACKAGE> (or any other packages specifically
152    enabled).
153 
154  b) Configuring Trilinos to test all effects of changing a given package(s):
155 
156    $ ./do-configure \
157       -D Trilinos_ENABLE_<PACKAGE>:BOOL=ON \
158       -D Trilinos_ENABLE_ALL_FORWARD_DEP_PACKAGES:BOOL=ON \
159       -D Trilinos_ENABLE_TESTS:BOOL=ON
160 
161    NOTE: The above set of arguments will result in package <PACKAGE> and all
162    packages that depend on <PACKAGE> to be enabled and have all of their
163    tests turned on.  Tests will not be enabled in packages that do not depend
164    on <PACKAGE> in this case.  This speeds up and robustifies pre-checkin
165    testing.
166 
167  c) Configuring Trilinos to build all stable packages with all tests and
168  examples:
169 
170      $ ./do-configure \
171         -D Trilinos_ENABLE_ALL_PACKAGES:BOOL=ON \
172         -D Trilinos_ENABLE_TESTS:BOOL=ON
173 
174    NOTE: Specific packages can be disabled with
175    Trilinos_ENABLE_<PACKAGE>:BOOL=OFF.  This will also disable all packages
176    that depend on <PACKAGE>.
177 
178    NOTE: All examples are enabled by default when setting
179    Trilinos_ENABLE_TESTS:BOOL=ON.
180
181    NOTE: By default, setting Trilinos_ENABLE_ALL_PACKAGES=ON only enables
182    Primary Stable Code.  To have this also enable all secondary stable code,
183    you must also you must set Trilinos_ENABLE_SECONDARY_STABLE_CODE=ON.
184
185  d) Disable a package and all its dependencies:
186 
187      $ ./do-configure \
188         -D Trilinos_ENABLE_<PACKAGE_A>:BOOL=ON \
189         -D Trilinos_ENABLE_ALL_OPTIONAL_PACKAGES:BOOL=ON \
190         -D Trilinos_ENABLE_<PACKAGE_B>:BOOL=OFF
191
192     Above, this will enable <PACKAGE_A> and all of the packages that it
193     depends on except for <PACKAGE_B> and all of its forward dependencies.
194     For example, if you run
195
196      $ ./do-configure \
197         -D Trilinos_ENABLE_Thyra:BOOL=ON \
198         -D Trilinos_ENABLE_ALL_OPTIONAL_PACKAGES:BOOL=ON \
199         -D Trilinos_ENABLE_Epetra:BOOL=OFF
200
201     The packages Thyra, RTOp, and Teuchos will be enabled, but the packages
202     Epetra, EpetraExt will be disabled.
203
204  e) Removing all package enables in the Cache
205
206      $ ./-do-confiugre -D Trilinos_UNENABLE_ENABLED_PACKAGES:BOOL=TRUE
207
208    This option will set to empty '' all package enables, leaving all other
209    cache variables as they are.  You can then reconfigure with a new set of
210    package enables for a different set of packages.  This allows you to avoid
211    more expensive configure time checks and to preserve other cache variables
212    that you have set and don't want to loose.
213
214
215(*) Selecting compiler and linker options:
216
217  a) Configuring to build with default debug or release compiler flags:
218 
219    To build a debug version, pass into 'cmake':
220 
221      -D CMAKE_BUILD_TYPE:STRING=DEBUG
222 
223    This will result in default debug flags getting passed to the compiler.
224 
225    To build a release (optimized) version, pass into 'cmake':
226 
227      -D CMAKE_BUILD_TYPE:STRING=RELEASE
228 
229    This will result in optimized flags getting passed to the compiler.
230 
231  b) Adding arbitrary compiler flags but keeping other default flags:
232
233    To append arbitrary compiler flags, configure with:
234
235      -DCMAKE_<COMPILER>_FLAGS:STRING="<EXTRA_COMPILER_OPTIONS>"
236
237    where <COMPILER> = C, CXX, Fortran and <EXTRA_COMPILER_OPTIONS> are your
238    extra compiler options like "-DSOME_MACRO_TO_DEFINE -funroll-loops".
239
240    NOTE: Compiler options set with CMAKE_<COMPILER>_FLAGS will *not* override
241    the set debug or release options which come after on the compile line.
242    Therefore, this approach should only be used for options that will not get
243    overridden by the internally-set debug or release compiler options.
244    However, setting CMAKE_<COMPILER>_FLAGS will work well for adding extra
245    compiler defines for example.
246
247    NOTE: Any options that you set through the cache varible
248    CMAKE_<COMPILER>_FLAGS_<BUILD_TYPE> (where <BUILD_TYPE> = DEBUG or
249    RELEASE) will get overridden in the code so don't try to manually set
250    CMAKE_<COMPILER>_FLAGS_<BUILD_TYPE>.
251 
252  c) Overriding debug/release compiler options:
253 
254    To pass in compiler options that override the default debug or release
255    options use:
256 
257      -D CMAKE_BUILD_TYPE:STRING=NONE \
258      -D CMAKE_C_FLAGS:STRING="-04 -funroll-loops" \
259      -D CMAKE_CXX_FLAGS:STRING="-03 -fexceptions"
260 
261    where LANGUAGE = C, CXX, Fortran, etc.
262
263    NOTE: Using CMAKE_BUILD_TYPE:STRING=NONE allows you to take complete
264    control over what debug or release compiler optimizations or related
265    options are passed to the compiler.
266 
267  d) Appending arbitrary link flags to every executable:
268 
269    In order to append any set of arbitrary link flags to your executables use:
270 
271      -D Trilinos_EXTRA_LINK_FLAGS:STRING="$EXTRA_LINK_FLAGS"
272 
273    Above, you can pass any type of library and they will always be the last
274    libraries listed, even after all of the TPL.
275 
276    NOTE: This is how you must set extra libraries like Fortran libraries and
277    MPI libraries (when using raw compilers).  Please only use this variable
278    as a last resort.
279
280    NOTE: You must only pass in libraries in Trilinos_EXTRA_LINK_FLAGS and
281    *not* arbitrary linker flags.  To pass in extra linker flags that are not
282    libraries, use the built-in CMake variable CMAKE_EXE_LINKER_FLAGS instead.
283 
284  e) Overriding all (strong warnings and debug/release) compiler options:
285 
286    To override all compiler options, including both strong warning options
287    and debug/release options, configure with:
288 
289      -D CMAKE_BUILD_TYPE:STRING=NONE \
290      -D Trilinos_ENABLE_STRONG_C_COMPILE_WARNINGS:BOOL=OFF \
291      -D Trilinos_ENABLE_STRONG_CXX_COMPILE_WARNINGS:BOOL=OFF \
292      -D CMAKE_C_FLAGS:STRING="-04 -funroll-loops" \
293      -D CMAKE_CXX_FLAGS:STRING="-03 -fexceptions" \
294
295  f) Enable and disable shadowing warnings for all Trilinos packages:
296 
297    To enable shadowing warnings for all Trilinos packages (that don't already
298    have them turned on) then use:
299 
300      -D Trilinos_ENABLE_SHADOW_WARNINGS:BOOL=ON
301
302    To disable shadowing warnings for all Trilinos packages then use:
303 
304      -D Trilinos_ENABLE_SHADOW_WARNINGS:BOOL=OFF
305
306    NOTE: The default value is empty '' which lets each Trilinos package
307    decide for itself if shadowing warnings will be turned on or off for that
308    package.
309 
310  g) Removing warnings as errors for CLEANED packages:
311 
312    To remove the -Werror flag (or some other flag that is set) from being
313    applied to compile CLEANED packages like Teuchos, set the following when
314    configuring:
315 
316      -D Trilinos_WARNINGS_AS_ERRORS_FLAGS:STRING=""
317
318
319(*) Disabling the Fortran compiler and all Fortran code:
320
321  To disable the Fortran compiler and all Trilinos code that depends on
322  Fortran set:
323
324    -D Trilinos_ENABLE_Fortran:BOOL=OFF
325
326  The user cache variable Trilinos_ENABLE_Fortran is used as a trigger in the
327  Trilinos CMake build system to enable Fortran support or not.
328
329  NOTE: The fortran compiler will be disabled automatically by default on
330  systems like MS Windows.
331
332  NOTE: Macs do not come with a compatible Fortran compiler by default so you
333  must turn off Fortran if you don't have a compatible Fortran compiler.
334
335
336(*) Enabling runtime debug checking:
337 
338  a) Enabling Trilinos ifdefed runtime debug checking:
339 
340    To turn on optional ifdefed runtime debug checking, configure with:
341 
342      -D Trilinos_ENABLE_DEBUG=ON
343 
344    This will result in a number of ifdefs to be enabled that will perform a
345    number of runtime checks.  Nearly all of the debug checks in Trilinos will
346    get turned on by default by setting this option.  This option can be set
347    independent of CMAKE_BUILD_TYPE.
348 
349    NOTE: The variable CMAKE_BUILD_TYPE controls what compiler options are
350    passed to the compiler by default while Trilinos_ENABLE_DEBUG controls
351    what defines are set in config.h files that control ifdefed debug checks.
352 
353    NOTE: Setting -DCMAKE_BUILD_TYPE:STRING=DEBUG will automatically set the
354    default Trilinos_ENABLE_DEBUG=ON.
355
356    NOTE: In order to turn on the maximum testing on for the Teuchos memory
357    management classes (like Teuchos::RCP), then you need to configure with
358    -DTeuchos_ENABLE_DEBUG_RCP_NODE_TRACING:BOOL=ON
359 
360  b) Enabling checked STL implementation:
361 
362    To turn on the checked STL implementation set:
363 
364      -D Trilinos_ENABLE_CHECKED_STL:BOOL=ON
365 
366    NOTE: By default, this will set -D_GLIBCXX_DEBUG as a compile option for
367    all C++ code.  This only works with GCC currently.
368 
369    NOTE: This option is disabled by default because to enable it by default
370    can cause runtime segfaults when linked against code that was compiled
371    without -D_GLIBCXX_DEBUG set.
372
373
374(*) Configuring Trilinos for MPI support:
375
376  To enable MPI support you must minimally:
377
378    -D TPL_ENABLE_MPI:BOOL=ON
379
380  There is built-in logic to try to find the various MPI components on your
381  system but you can override (or make suggestions) with:
382
383    -D MPI_BASE_DIR:PATH="path"
384
385      Base path of a standard MPI installation which has
386      the subdirs 'bin', 'libs', 'include' etc.
387
388    -D MPI_BIN_DIR:PATH="path1;path2;...;pathn"
389
390      Paths where the MPI executables (e.g. mpiCC, mpicc, mpirun, mpiexec)
391      can be found.  By default this is set to ${MPI_BASE_DIR}/bin if
392      MPI_BASE_DIR is set.
393
394  The value of LD_LIBRARY_PATH will also automatically be set to
395  ${MPI_BASE_DIR}/lib if it exists.  This is needed for the basic compiler
396  tests for some MPI implementations that are installed in non-standard
397  locations.
398
399  a) Configuring build using MPI compiler wrappers:
400
401    The MPI compiler wrappers are turned on by default.  There is built-in
402    logic that will try to find the right compiler wrappers.  However, you can
403    specifically select them by setting:
404
405      -D MPI_[C,CXX_Fortran]_COMPILER:FILEPATH="exec_name"
406
407        The name of the MPI C/C++/Fortran compiler wrapper executable.
408        If this is just the name of the program it will be looked for
409        in ${MPI_BIN_DIR} and in other standard locations with that name.
410        If this is an absolute path, then this will be used as
411        CMAKE_[C,CXX,Fortran]_COMPILER to compile and link code.
412
413  b) Configuring to build using raw compilers and flags/libraries:
414
415    While using the MPI compiler wrappers as described above is the preferred
416    way to enable support for MPI, you can also just use the raw compilers and
417    then pass in all of the other information that will be used to compile and
418    link your code.
419
420    To turn off the MPI compiler wrappers, set:
421
422      -D MPI_USE_COMPILER_WRAPPERS:BOOL=OFF
423
424    You will then need to manually pass in the compile and link lines needed
425    to compile and link MP programs.  The compile flags can be set through:
426
427      -D CMAKE_[C,CXX,Fortran]_FLAGS:STRING="$EXTRA_COMPILE_FLAGS"
428
429    The link and library flags must be set through:
430
431      -D Trilinos_EXTRA_LINK_FLAGS:STRING="$EXTRA_LINK_FLAGS"
432
433    Above, you can pass any type of library or other linker flags in and they
434    will always be the last libraries listed, even after all of the TPLs.
435
436    NOTE: A good way to get the extra compile and link flags for MPI is to
437    use:
438
439      export EXTRA_COMPILE_FLAGS="`$MPI_BIN_DIR/mpiCC --showme:compile`"
440     
441      export EXTRA_LINK_FLAGS="`$MPI_BIN_DIR/mpiCC --showme:link`"
442     
443    where MPI_BIN_DIR is set to your MPI installations binary directory.
444
445  c) Setting up to run MPI programs
446
447    In order to use the ctest program to run MPI tests, you must set the mpi
448    run command and the options it takes.  The built-in logic will try to find
449    the right program and options but you will have to override them in many
450    cases.
451
452    MPI test and example executables are run as:
453
454      ${MPI_EXEC} ${MPI_EXEC_PRE_NUMPROCS_FLAGS} ${MPI_EXEC_NUMPROCS_FLAG} <NP> \
455        ${MPI_EXEC_POST_NUMPROCS_FLAGS} <TEST_EXECUTABLE_PATH> <TEST_ARGS>
456
457    where TEST_EXECUTABLE_PATH, TEST_ARGS, and NP are specific to the test
458    being run.
459
460    The test-independent MPI arguments are:
461
462      -D MPI_EXEC:FILEPATH="exec_name"
463
464        The name of the MPI run command (e.g. mpirun, mpiexec) that is used to
465        run the MPI program.  This can be just the name of the program in which
466        case the full path will be looked for in ${MPI_BIN_DIR} as described
467        above.  If it is an absolute path, it will be used without question.
468
469      -D MPI_EXEC_MAX_NUMPROCS:STRING=4
470
471        The maximum number of processes to allow when setting up and running
472        MPI test and example executables.  The default is set to '4' and only
473        needs to be changed when needed or desired.
474
475      -D MPI_EXEC_NUMPROCS_FLAG:STRING=-np
476
477        The command-line option just before the number of processes to use
478        <NP>.  The default value is based on the name of ${MPI_EXEC}.
479
480      -D MPI_EXEC_PRE_NUMPROCS_FLAGS:STRING="arg1 arg2 ... argn"
481
482        Other command-line arguments that must come *before* the numprocs
483        argument.  The default is empty "".
484
485      -D MPI_EXEC_POST_NUMPROCS_FLAGS:STRING="arg1 arg2 ... argn"
486
487        Other command-line arguments that must come *after* the numprocs
488        argument.  The default is empty "".
489
490
491(*) Enabling shared libraries:
492
493    -D BUILD_SHARED_LIBS:BOOL=ON
494
495  NOTE: The above option will result in all shared libraries to be build on
496  all systems (i.e. *.so on Unix/Linux systems, *.dylib on Mac OS X,
497  and *.dll on Windows systems).
498
499
500(*) Enabling support for optional Third-Party Libraries (TPLs):
501
502  Pass into 'cmake':
503
504    -D TPL_ENABLE_<TPLNAME>:BOOL=ON
505
506  where <TPLNAME> = Boost, ParMETIS, etc.
507
508  The headers, libraries, and library directories can then be specified with
509  the input cache variables:
510
511    <TPLNAME>_INCLUDE_DIRS:PATH: List of paths to the header include
512      directories.
513
514      Example:
515 
516       -D Boost_INCLUDE_DIRS:PATH=/usr/local/boost/include
517
518      <TPLNAME>_LIBRARY_NAMES:STRING: List of unadorned library names,
519      in the order of the link line.  The platform-specific prefixes
520      (e.g.. 'lib') and postfixes (e.g. '.a', '.lib', or '.dll') will be
521      added automatically.
522
523      Example:
524
525        -D BLAS_LIBRARY_NAMES:STRING="blas;gfortran"
526
527    <TPLNAME>_LIBRARY_DIRS:PATH: The list of directories where the
528      library files can be found.
529
530      Example:
531
532        -D BLAS_LIBRARY_DIRS:PATH=/usr/local/blas
533
534  NOTE: The variables TPL_<TPLNAME>_INCLUDE_DIRS and TPL_<TPLNAME>_LIBRARIES
535  are what are directly used by the CMake build infrastructure.  These
536  variables are normally set by the variables <TPLNAME>_INCLUDE_DIRS,
537  <TPLNAME>_LIBRARY_NAMES, and <TPLNAME>_LIBRARY_DIRS using find commands but
538  you can always override these by setting the (type FILEPATH) cache
539  variables TPL_<TPLNAME>_INCLUDE_DIRS and TPL_<TPLNAME>_LIBRARIES.  This gives
540  the user complete and direct control in specifying exactly what is used in
541  the build process.  The other variables that start with <TPLNAME>_ are just a
542  convenience to make it easier to specify the location of the libraries.
543
544  NOTE: In order to allow a TPL that normally requires one or more libraries
545  to ignore the libraries, you can set:
546
547    -D BLAS_LIBRARY_NAMES:STIRNG=""
548
549  Optional package-specific support for a TPL can be turned off by passing
550  into 'cmake':
551
552    -D <PACKAGE>_ENABLE_<TPLNAME>:BOOL=OFF
553
554  where <PACKAGE> is Epetra, NOX etc.  This gives the user full control over
555  what TPLs are supported by which package independently.
556
557  Support for an optional TPL can also be turned on implicitly by setting:
558
559    -D <PACKAGE>_ENABLE_<TPLNAME>:BOOL=ON
560
561  That will result in setting TPL_ENABLE_<TPLNAME>=ON internally (but not set
562  in the cache) if TPL_ENABLE_<TPLNAME>=OFF is not already set.
563
564
565(*) Disabling tentatively enabled TPLs:
566
567    -D TPL_ENABLE_<TPLNAME>:BOOL=OFF
568
569  where <TPLNAME> = BinUtils, Boost, etc.
570
571  NOTE: Some TPLs in Trilinos are always tentatively enabled (e.g. BinUtils
572  for C++ stacktracing) and if all of the components for the TPL are found
573  (e.g. headers and libraries) then support for the TPL will be enabled,
574  otherwise it will be disabled.  This is to allow as much functionality as
575  possible to get automatically enabled without the user having to learn about
576  the TPL, explicitly enable the TPL, and then see if it is supported or not
577  on the given system.  However, if the TPL is not supported on a given
578  platform, then it may be better to explicitly disable the TPL (as shown
579  above) so as to avoid the output from the CMake configure process that shows
580  the tentatively enabled TPL being processes and then failing to be enabled.
581  Also, it is possible that the enable process for the TPL may pass, but the
582  TPL may not work correctly on the given platform.  In this case, one would
583  also want to explicitly disable the TPL as shown above.
584
585
586(*) Getting verbose output from configure:
587
588    $ ./do_configure -D Trilinos_VERBOSE_CONFIGURE:BOOL=ON
589
590  NOTE: This produces a *lot* of output but can be very useful when debugging
591  configuration problems
592
593
594(*) Getting verbose output from the makefile:
595
596    $ ./do_configure -D CMAKE_VERBOSE_MAKEFILE:BOOL=TRUE
597
598
599(*) Getting very verbose output from configure:
600
601    $ ./do_configure -D Trilinos_VERBOSE_CONFIGURE:BOOL=ON --debug-output --trace
602
603  NOTE: This will print a complete stack trace to show exactly where you are.
604
605
606(*) Enabling/disabling deprecated warnings:
607
608    -D Trilinos_SHOW_DEPRECATED_WARNINGS:BOOL=OFF
609
610  Above will disable, by default, all deprecated warnings in Trilinos.  By
611  default, deprecated warnings are enabled.
612
613  To enable/disable deprecated warnings for a single Trilinos package use:
614
615    -D <PACKAGE>_SHOW_DEPRECATED_WARNINGS:BOOL=OFF
616
617  This will override the global behavior set by
618  Trilinos_SHOW_DEPRECATED_WARNINGS for individual packages <PACKAGE>
619  (e.g. <PACKAGE> = Teuchos, Thyra, etc.)
620
621
622(*) Disable update of package dependency information:
623
624  To turn off the update of the various XML and HTML dependency files back
625  into the Trilinos source tree, use the configure option:
626
627    -D Trilinos_DEPS_XML_OUTPUT_FILE:FILEPATH=
628
629  NOTE: You must start from a clean cache for this to work.
630
631  NOTE: Disabling the update of these XML and HTML files back into the source
632  tree will speed up successive re-configures by a few seconds.
633
634
635(*) Enabling different test categories:
636
637    -D Trilinos_TEST_CATEGORIES:STRING="<CATEGORY1>;<CATEGORY2>;..."
638
639  Valid categories include BASIC, NIGHTLY, and PERFORMANCE.  BASIC tests get
640  built and run for pre-push testing and nighly testing.  NIGHTY tests are for
641  pos-push and nighly testing.  PERFORAMNCE tests are for perforamnce testing
642  only.
643
644
645(*) Enabling support for coverage testing:
646
647    -D Trilinos_ENABLE_COVERAGE_TESTING:BOOL=ON
648
649  NOTE: The above will set the compile and link options -fprofile-arcs
650  -ftest-coverage when the compiler is GNU.
651
652  NOTE: You can run the coverage tests and submit to the dashboard with
653  'make dashboard' (see below).
654
655
656(*) Viewing configure options and documentation:
657 
658  a) Viewing available configure-time options with documentation
659 
660    $ cd $BUILD_DIR
661    $ rm CMakeCache.txt
662    $ cmake -LAH -D Trilinos_ENABLE_ALL_PACKAGES:BOOL=ON \
663      $TRILINOS_HOME
664 
665    NOTE: You can also just look at the text file CMakeCache.txt after
666    configure which gets created in the build directory and has all of the
667    cache variables and documentation.
668 
669 
670  b) Viewing available configure-time options without documentation
671 
672    $ cd $BUILD_DIR
673    $ rm CMakeCache.txt
674    $ cmake -LA SAME_AS_ABOVE $TRILINOS_HOME
675 
676 
677  c) Viewing current values of cache variables
678 
679      $ cmake -LA $TRILINOS_HOME
680 
681    or just examine and grep the file CMakeCache.txt.
682
683
684(*) Enabling extra external repositories with add-on packages:
685
686    -DTrilinos_EXTRA_REPOSITORIES:STRING=<EXTRAREPO>
687
688  Here, <EXTRAREPO> is the name of an extra external repository that has been
689  cloned under the main 'Trilinos' source directory as:
690
691    Trilinos/<EXTRAREPO>
692
693  For example, to enable <EXTRAREPO> = preCopyrightTrilinos you would:
694
695    $ cd $TRILINOS_HOME_DIR
696    $ eg clone software.sandia.gov:/space/git/preCopyrightTrilinos
697    $ cd $BUILD_DIR
698    $ ./do-configure -DTrilinos_EXTRA_REPOSITORIES:STRING=preCopyrightTrilinos
699
700  After that, all of the extra packages defined in <EXTRAREPO> will appear in
701  the list of official Trilinos packages and you are free to enable any that
702  you would like just like any other Trilinos package.
703
704 
705(*) Reconfiguring from scratch
706 
707      $ rm CMakeCache.txt ; find . -name CMakeFiles -exec rm -rf {} \;
708      $ ./do-configure
709 
710    NOTE: Removing the CMakeCache.txt file is often needed when removing
711    variables from the configure line.  Removing the CMakeFiles directories is
712    needed if there are changes in some CMake modules or the CMake version
713    itself.
714
715
716(*) Viewing configure errors:
717
718  Configure time errors are shown in the file:
719
720      $BUILD_BASE_DIR/CMakeFiles/CMakeError.log
721
722
723
724D) Building (Makefile generator)
725--------------------------------
726
727(*) Building all targets:
728
729     $ make [-jN]
730
731   (where N is the number of processes to use)
732
733
734(*) Discovering what targets are available to build after configuration:
735
736     $ make help
737
738
739(*) See all of the targets to build for a package:
740
741     $ make help | grep <PACKAGE>_
742
743  (where <PACKAGE> = Teuchos, Epetra, NOX, etc.)
744
745  or:
746
747     $ cd packages/<PACKAGE>
748     $ make help
749
750
751(*) Building all of the targets for a package:
752
753     $ make <PACKAGE>_all
754
755  (where <PACKAGE> = Teuchos, Epetra, NOX, etc.)
756
757  or:
758
759    $ cd packages/<PACKAGE>
760    $ make
761
762
763(*) Building all of the libraries for a package:
764
765    $ make <PACKAGE>_libs
766
767  (where <PACKAGE> = Teuchos, Epetra, NOX, etc.)
768
769
770(*) Building all of the libraries for all enabled Trilinos packages:
771
772    $ make libs
773
774  NOTE: This target depends on the <PACAKGE>_libs targets for all of the
775  enabled Trilinos packages.
776
777  NOTE: You can also use the target name 'Trilinos_libs'.
778
779
780(*) Building a single object file:
781
782  First, look for the name of the object file to build based on the source
783  file SomeSourceFile.cpp:
784
785    $ make help | grep SomeSourceFile.o
786
787  Build the source file:
788
789    $ rm WHATEVER_WAS_RETURNED_ABOVE ; make WHATEVER_WAS_RETURNED_ABOVE
790
791
792  NOTE: CMake does not seem to correctly address dependencies when building
793  just object files so you need to always delete the object file first to make
794  sure that it gets rebuilt correctly.
795
796
797(*) Building with verbose output without reconfiguring:
798
799    $ make [<SOME_TARGET>] VERBOSE=1
800
801
802(*) Relink a target without considering dependencies:
803
804    $ make <SOME_TARGET>/fast
805
806
807
808E) Testing with CTest
809---------------------
810
811
812(*) [Recommended] Testing using 'ctest'
813
814    $ ctest -j4
815
816  (see output in Testing/Temporary/LastTest.log)
817
818  NOTE: The -jN argument allows CTest to use more processes to run
819  tests but will not exceed the max number of processes specified at
820  configure time.
821
822  See detailed test output with:
823
824    $ ctest -j4 -VV
825
826
827(*) Only running tests for a single package
828
829  Running a single package test:
830
831    $ ctest -j4 -R '^<PACKAGE>_'
832
833  (e.g. PACKAGE = Teuchos, Epetra, etc.)
834  (see output in Testing/Temporary/LastTest.log)
835
836  or:
837
838    $ cd packages/<PACKAGE>
839    $ ctest -j4
840
841
842(*) Running a single test with full output to the console:
843
844    $ ctest -R ^FULL_TEST_NAME$ -VV
845
846  (e.g. FULL_TEST_NAME = Teuchos_Comm_test, Epetra_MultiVector_test, etc. )
847
848
849(*) Running memory checking:
850
851  To run the memory tests for just a single package, from the *base* build
852  directory, run:
853
854    $ ctest -R '^<PACKAGE>_' -T memcheck
855
856  (where <PACKAGE> = Epetra, NOX etc.).
857
858  (see the detailed output in
859  ./Testing/Temporary/LastDynamicAnalysis_DATE_TIME.log)
860
861  NOTE: If you try to run memory tests from any subdirectories, that does not
862  seem to work.  You have to run them from the base build directory and then
863  use -R '^<PACKAGE>_' with ctest in order to run your packages tests.
864
865
866(*) Testing using 'make test'
867
868    $ make test
869
870  NOTE: This is equivalent to just running 'ctest' without any arguments.
871
872
873
874F) Installing
875-------------
876
877
878(*) Setting the install prefix at configure time
879
880    $ ./do-configure \
881      -D CMAKE_INSTALL_PREFIX:PATH=$HOME/PROJECTS/install/trilinos/mpi/opt
882
883  NOTE: The script 'do-configure' is just a simple shell script that calls
884  CMake as shown above.
885
886
887(*) Installing after configuration
888
889    $ make install
890
891    (will build all of the targets needed before the install)
892
893
894(*) Uninstall
895
896    $ make uninstall
897
898
899
900G) Packaging
901------------
902
903
904(*) Creating a tarball of the source tree:
905
906   $ make package_source
907
908   NOTE: The above command will tar up *everything* in the source tree (except
909   for files explicitly excluded in the CMakeLists.txt files) so make sure
910   that you start with a totally clean source tree before you do this.  Or,
911   you could build Doxygen documentation first and then tar up Trilinos and
912   that would give you the source with Doxygen documentation.
913
914   NOTE: You can control what gets put into the tarball by setting the cache
915   variable CPACK_SOURCE_IGNORE_FILES when configuring with CMake.
916
917
918H) Dashboard submissions
919------------------------
920
921You can use the extended CTest scripting system in Trilinos to submit
922package-by-package build, test, coverage, memcheck results to the dashboard.
923To do this, just configure a build directory like you would for any other
924purpose and they type:
925
926  $ env CTEST_BUILD_FLAGS=-j4 CTEST_PARALLEL_LEVEL=4 make dashboard
927
928This invokes the advanced CTest script
929Trilinos/cmake/ctest/experimental_build_test.cmake to do an experimental build
930for all of the packages that you have explicitly enabled.  The packages that
931are implicitly enabled due to package dependencies are not directly processed
932by the experimental_build_test.cmake script.
933
934There are a number of options that you can set in the environment to control
935what this script does.  This set of options can be found by doing:
936
937  $ grep 'SET_DEFAULT_AND_FROM_ENV(' \
938      Trilinos/cmake/ctest/TrilinosCTestDriverCore.cmake
939
940Currently, this options includes:
941
942  SET_DEFAULT_AND_FROM_ENV( CTEST_TEST_TYPE Nightly )
943  SET_DEFAULT_AND_FROM_ENV(Trilinos_TRACK "")
944  SET_DEFAULT_AND_FROM_ENV( CTEST_SITE ${CTEST_SITE_DEFAULT} )
945  SET_DEFAULT_AND_FROM_ENV( CTEST_DASHBOARD_ROOT "" )
946  SET_DEFAULT_AND_FROM_ENV( BUILD_TYPE NONE )
947  SET_DEFAULT_AND_FROM_ENV(COMPILER_VERSION UNKNOWN)
948  SET_DEFAULT_AND_FROM_ENV( CTEST_BUILD_NAME
949  SET_DEFAULT_AND_FROM_ENV( CTEST_START_WITH_EMPTY_BINARY_DIRECTORY TRUE )
950  SET_DEFAULT_AND_FROM_ENV( CTEST_WIPE_CACHE TRUE )
951  SET_DEFAULT_AND_FROM_ENV( CTEST_CMAKE_GENERATOR ${DEFAULT_GENERATOR})
952  SET_DEFAULT_AND_FROM_ENV( CTEST_DO_UPDATES TRUE )
953  SET_DEFAULT_AND_FROM_ENV( CTEST_GENERATE_DEPS_XML_OUTPUT_FILE FALSE )
954  SET_DEFAULT_AND_FROM_ENV( CTEST_UPDATE_ARGS "")
955  SET_DEFAULT_AND_FROM_ENV( CTEST_UPDATE_OPTIONS "")
956  SET_DEFAULT_AND_FROM_ENV( CTEST_BUILD_FLAGS "-j2")
957  SET_DEFAULT_AND_FROM_ENV( CTEST_DO_BUILD TRUE )
958  SET_DEFAULT_AND_FROM_ENV( CTEST_DO_TEST TRUE )
959  SET_DEFAULT_AND_FROM_ENV( MPI_EXEC_MAX_NUMPROCS 4 )
960  SET_DEFAULT_AND_FROM_ENV( CTEST_PARALLEL_LEVEL 1 )
961  SET_DEFAULT_AND_FROM_ENV( Trilinos_WARNINGS_AS_ERRORS_FLAGS "" )
962  SET_DEFAULT_AND_FROM_ENV( CTEST_DO_COVERAGE_TESTING FALSE )
963  SET_DEFAULT_AND_FROM_ENV( CTEST_COVERAGE_COMMAND gcov )
964  SET_DEFAULT_AND_FROM_ENV( CTEST_DO_MEMORY_TESTING FALSE )
965  SET_DEFAULT_AND_FROM_ENV( CTEST_MEMORYCHECK_COMMAND valgrind )
966  SET_DEFAULT_AND_FROM_ENV( CTEST_DO_SUBMIT TRUE )
967  SET_DEFAULT_AND_FROM_ENV( Trilinos_ENABLE_SECONDARY_STABLE_CODE OFF )
968  SET_DEFAULT_AND_FROM_ENV( Trilinos_ADDITIONAL_PACKAGES "" )
969  SET_DEFAULT_AND_FROM_ENV( Trilinos_EXCLUDE_PACKAGES "" )
970  SET_DEFAULT_AND_FROM_ENV( Trilinos_BRANCH "" )
971  SET_DEFAULT_AND_FROM_ENV( Trilinos_REPOSITORY_LOCATION "software.sandia.gov:/space/git/${CTEST_SOURCE_NAME}" )
972  SET_DEFAULT_AND_FROM_ENV( Trilinos_PACKAGES "${Trilinos_PACKAGES_DEFAULT}" )
973  SET_DEFAULT_AND_FROM_ENV( CTEST_SELECT_MODIFIED_PACKAGES_ONLY OFF )
974
975For example, to run an experimental build and in the process change the build
976name and the options to pass to 'make', use:
977
978  $ env CTEST_BUILD_NAME=MyBuild CTEST_BUILD_FLAGS='-j8' CTEST_PARALLEL_LEVEL=8 \
979    make dashboard
980
981After this finishes running, look for the build 'MyBuild' (or whatever build
982name you used above) in the Trilinos CDash dashboard.
983
984NOTE: It is useful to set CTEST_BUILD_NAME to some unique name to make it
985easier to find your results in the CDash dashboard.
986
987NOTE: A number of the defaults set in TrilinosCTestDriverCore.cmake
988are overridden from experimental_build_test.cmake (such as
989CTEST_TEST_TYPE=Experimental) so you will want to look at
990experimental_build_test.cmake to see how these are changed.  The
991script experimental_build_test.cmake sets reasonable values for these
992options in order to use the 'make dashboard' target in iterative
993development for experimental builds.
994
995NOTE: The target 'dashboard' is not directly related to the built-in
996CMake targets 'Experimental*' that run standard dashboards with CTest
997without the custom package-by-package driver in
998TrilinosCTestDriverCore.cmake.  The package-by-package extended CTest
999driver is more appropriate for Trilinos.
1000
1001NOTE: Once you configure with -DTrilinos_ENABLE_COVERAGE_TESTING:BOOL=ON, the
1002environment variable CTEST_DO_COVERAGE_TESTING=TRUE is automatically set by the
1003target 'dashboard' so you don't have to set this yourself.
1004
1005NOTE: Doing a memory check with Valgrind requires that you set
1006CTEST_DO_MEMORY_TESTING=TRUE with the 'env' command as:
1007
1008  $ env CTEST_DO_MEMORY_TESTING=TRUE make dashboard
1009
1010NOTE: The CMake cache variable Trilinos_DASHBOARD_CTEST_ARGS can be set on the
1011cmake configure line in order to pass additional arguments to 'ctest -S' when
1012invoking the package-by-package CTest driver.  For example:
1013
1014  -D Trilinos_DASHBOARD_CTEST_ARGS:STRING="-VV"
1015
1016will set verbose output with CTest.
1017
1018*/