CMake Build System - Revision history

Yjzhang at 16:52, 18 December 2014

2014-12-18T16:52:01Z

Yjzhang at 16:49, 18 December 2014

2014-12-18T16:49:23Z

Yjzhang: /* SELFE Prerequisites */

2013-09-21T02:29:35Z

‎SELFE Prerequisites

Eli: /* Basic CMake Usage */

2013-04-09T16:56:50Z

‎Basic CMake Usage

Eli: /* Basic CMake Usage */

2013-04-09T16:55:56Z

‎Basic CMake Usage

Yjzhang at 13:06, 6 September 2012

2012-09-06T13:06:21Z

Yjzhang at 13:06, 6 September 2012

2012-09-06T13:06:10Z

Yjzhang at 13:05, 6 September 2012

2012-09-06T13:05:10Z

Yjzhang at 13:04, 6 September 2012

2012-09-06T13:04:48Z

Yjzhang at 13:04, 6 September 2012

2012-09-06T13:04:33Z

@@ Line 23: / Line 23: @@
 * all (default)
 * individual libraries: sediment, ecosim, wwm (assuming you configured CMAKE with USE_XXX)
-* pelfe (with whatever features you toggled on)
+* pschism (with whatever features you toggled on)
 * utility (all utility scripts)
 * pyutil (all python utilities)
@@ Line 75: / Line 75: @@
 *  performance/build parameters (BUILD_TYPE=Debug, MPIVERSION=2, USE_TIMING)
-'''Custom compiler flags''': Flag choices are often re-usable across similar systems.  If you are setting up flags that should be the standard for your architecture, I would urge you to contribute to selfe/cmake/SELFECompile.cmake so that others can make use of your work and so that your personal configuration is not mixed up with stuff that is just standard for your architecture. If you are tweaking the flags for real then you should follow the directions below.
+'''Custom compiler flags''': Flag choices are often re-usable across similar systems.  If you are setting up flags that should be the standard for your architecture, I would urge you to contribute to /cmake/SCHISMCompile.cmake so that others can make use of your work and so that your personal configuration is not mixed up with stuff that is just standard for your architecture. If you are tweaking the flags for real then you should follow the directions below.
 One class of flags that seems to be a bit of a special case are the flags that force static linking such as '''-Bstatic''' or '''-static'''. I am pretty open to fixing the cmake files so that they will do what you want, but rather than instinctively adding these flags you should investigate first whether maybe CMake already will do what you want ... it generally favors static linking, although MPI can be an exception.
@@ Line 88: / Line 88: @@
 The CMake -D option forcibly defines a variable. It might be more immediately intuitive for GNU make users who set a variable
-and expect their orders to be followed.  To use the -D method, create a shell script in /selfe that looks like this:
+and expect their orders to be followed.  To use the -D method, create a shell script in / that looks like this:
   mkdir build
   cd build
@@ Line 100: / Line 100: @@
 ===== METHOD #2 Use -C <cache-init-file> to populate the cmake cache. =====
-The notion of the CMake cache takes some getting used to.  The first time you run cmake, a number of compiler and build options will be placed in a file called CMakeCache.txt. The -C option allows you to specify an input cmake script that has nothing but SET statements that the user can use to populate options ... an example of such a file is /selfe/cmake/SELFE.local.cmake
+The notion of the CMake cache takes some getting used to.  The first time you run cmake, a number of compiler and build options will be placed in a file called CMakeCache.txt. The -C option allows you to specify an input cmake script that has nothing but SET statements that the user can use to populate options ... an example of such a file is /cmake/SCHISM.local.cmake
 After the first run, the cache can be manipulated with text, cursor or graphical tools (ccmake or QT based) or by repeating the cmake invocation with new -D options. I don't use the graphical tools much, but ccmake in non-advanced view is nice because it shows you an all-encompassing view of user-configurable variables.
@@ Line 111: / Line 111: @@
   $ rm -rf build
   $ cd build
-  $ cmake  -C ../cmake/SELFE.local.cmake ../src
+  $ cmake  -C ../cmake/SCHISM.local.cmake ../src
 == Developer Documentation ==
@@ Line 117: / Line 117: @@
 Here are common use cases:
-=== Modifying SELFE modules ===
+=== Modifying SCHISM modules ===
 Here are some common cases:
 ==== Adding a file to an existing module ====
@@ Line 130: / Line 130: @@
 If you are creating a new directory, you will need to add_directory() in the /utility level CMakeLists.txt. The rest happens at the directory level of the script. Make sure to create a dependency of "utility" on your new script so that "make utility" works correctly.
-==== Adding a new selfe module ====
+==== Adding a new SCHISM module ====
 Again, learning by example is a good way to tackle this. There is a macro for CMakeLists.txt in the /src level CMakeLists.txt. It will help you bind together:
 # a directory name (usually capitalized)
@@ Line 143: / Line 143: @@
 First one obvious caveat -- extra libraries should be avoided if possible.
-Dependencies should also be introduced to cmake at the lowest level they are needed. You can introduce the dependency in the /src level CMakeLists.txt if it is going to be used by several modules including Hydro (e.g. NetCDF). However, if it is only going to be used by one module for the moment, (as PETSc is needed by WWM) try to keep it in the module directory. Among other things, you then do not have to put an IF block around it to check if the selfe module is being used because the whole directory will be skipped if the module is toggled off. Someone who isn't using your module can skip the dependency entirely.
+Dependencies should also be introduced to cmake at the lowest level they are needed. You can introduce the dependency in the /src level CMakeLists.txt if it is going to be used by several modules including Hydro (e.g. NetCDF). However, if it is only going to be used by one module for the moment, (as PETSc is needed by WWM) try to keep it in the module directory. Among other things, you then do not have to put an IF block around it to check if the SCHISM module is being used because the whole directory will be skipped if the module is toggled off. Someone who isn't using your module can skip the dependency entirely.
-The first step with dependent libraries is to get a FindXXX.cmake script for the library if one is not already included in CMake 2.6 and put it in selfe/cmake/modules. You may be tempted to avoid this and try to figure another way, but a suitable script is almost always available on the web and I have found that subverting this feature of CMake makes it fragile. There are some slight tricks making it compatible with cmake 2.6 (specifically the way you include other scripts). The names of the scripts that are included are usually always about the same, so you can probably just look at a script that is already in selfe/cmake/modules. If you have any issues feel free to email me (eli@water.ca.gov).
+The first step with dependent libraries is to get a FindXXX.cmake script for the library if one is not already included in CMake 2.6 and put it in /cmake/modules. You may be tempted to avoid this and try to figure another way, but a suitable script is almost always available on the web and I have found that subverting this feature of CMake makes it fragile. There are some slight tricks making it compatible with cmake 2.6 (specifically the way you include other scripts). The names of the scripts that are included are usually always about the same, so you can probably just look at a script that is already in /cmake/modules. If you have any issues feel free to email me (eli@water.ca.gov).

@@ Line 1: / Line 1: @@
 == Introduction ==
-CMake is one option currently available for building SELFE. This documentation covers the SELFE cmake build system under Linux. While CMake is highly portable and probably could be made to work under Windows and Mac, no one has tested it under those operating systems. For more information on cmake and documentation, see the [http://www.cmake.org cmake] web site.
+CMake is one option currently available for building SCHISM. This documentation covers the SCHISM cmake build system under Linux. While CMake is highly portable and probably could be made to work under Windows and Mac, no one has tested it under those operating systems. For more information on cmake and documentation, see the [http://www.cmake.org cmake] web site.
 == User Documentation ==
 === Basic CMake Usage ===
-On Linux, Cmake is just a preprocessor for Make much like a typical ''configure'' script. There are also generators for Eclipse and some other native build systems including Windows and Mac. When you reconfigure the project a lot by swapping modules, compiler options, build type (debug/release) or changing compilers, you re-run cmake ... but most of the time you just use ''make'' or some other build tool. You can create an out-of-source build from the /selfe directory by doing the following:
+On Linux, Cmake is just a preprocessor for Make much like a typical ''configure'' script. There are also generators for Eclipse and some other native build systems including Windows and Mac. When you reconfigure the project a lot by swapping modules, compiler options, build type (debug/release) or changing compilers, you re-run cmake ... but most of the time you just use ''make'' or some other build tool. You can create an out-of-source build from the v4.X directory by doing the following:
   (make sure you have the following directories: src/, test/unittest/ besides the cmake/ dir)
@@ Line 13: / Line 13: @@
   > setenv FC ifort/pgf90/gfortran    # Might be shell-dependent. The default (no action needed) is gfortran
                        # on bash, use export FC=ifort
-  > cmake ../src (or: cmake -C ../cmake/SELFE.local.cmake ../src; in order to define paths to some local settings; see below)
+  > cmake ../src (or: cmake -C ../cmake/SCHISM.local.cmake ../src; in order to define paths to some local settings; see below)
   > make -j8
   (executables are stored in bin/)
-If you have the prerequisites in typical places or set up your environment as recommended below this sequence will produce a Hydro-only build with default options including the selfe executable and all utilities. More realistically, you will probably have to set some library locations. Configuration is considered in more detail below.
+If you have the prerequisites in typical places or set up your environment as recommended below this sequence will produce a Hydro-only build with default options including the SCHISM executable and all utilities. More realistically, you will probably have to set some library locations. Configuration is considered in more detail below.
 In this case CMake is really just building a Makefile. The Makefile that gets produced has the following targets:
@@ Line 37: / Line 37: @@
   > cmake ../src
-=== SELFE Prerequisites ===
+=== SCHISM Prerequisites ===
 To build the model, you will need the following libraries:
 ;CMake:  The build system is tested against version 2.8+
@@ Line 72: / Line 72: @@
 *  the name of the compiler
 *  custom library locations,
-*  choosing selfe modules to include in the driver
+*  choosing SCHISM modules to include in the driver
 *  performance/build parameters (BUILD_TYPE=Debug, MPIVERSION=2, USE_TIMING)

@@ Line 39: / Line 39: @@
 === SELFE Prerequisites ===
 To build the model, you will need the following libraries:
-;CMake:  The build system is tested against version 2.6 and 2.8
+;CMake:  The build system is tested against version 2.8+
 ;Parmetis: Domain decomposition and sparse matrix ordering library
 * Required for Hydro.

@@ Line 33: / Line 33: @@
 If you change the library or compiler options -- or run into problems -- you should consider blowing away the whole /build directory and starting over:
-  $ rm -rf build/*
+  > rm -rf build/*
-  $ cd build
+  > cd build
-  $ cmake ../src
+  > cmake ../src
 === SELFE Prerequisites ===

@@ Line 33: / Line 33: @@
 If you change the library or compiler options -- or run into problems -- you should consider blowing away the whole /build directory and starting over:
-  selfe$ rm -rf build/*
+  $ rm -rf build/*
-  selfe$ cd build
+  $ cd build
-  selfe$ cmake ../src
+  $ cmake ../src
 === SELFE Prerequisites ===

@@ Line 11: / Line 11: @@
   > mkdir build
   > cd build
-  > setenv FC ifort/pgf90    # Might be shell-dependent. The default (no action needed) is gfortran
+  > setenv FC ifort/pgf90/gfortran    # Might be shell-dependent. The default (no action needed) is gfortran
                        # on bash, use export FC=ifort
   > cmake ../src (or: cmake -C ../cmake/SELFE.local.cmake ../src; see below)