Difference between revisions of "CMake FAQ"

From Geos-chem
Jump to: navigation, search
m (When will CMake support be available?)
m (How do I build GEOS-Chem as a part of an other project?)
 
(21 intermediate revisions by 2 users not shown)
Line 5: Line 5:
 
CMake is a program that generates Makefiles. This is an oversimplification, but it describes the essence of CMake.
 
CMake is a program that generates Makefiles. This is an oversimplification, but it describes the essence of CMake.
  
=== When will CMake support be available? ===
+
=== What versions of GEOS-Chem support CMake? ===
CMake support was added to GEOS-Chem Classic in [[GEOS-Chem_12#12.6.0|GEOS-Chem 12.6.0]]. GCHP is expected to support CMake by the end of 2019.
+
GEOS-Chem Classic [[GEOS-Chem_12#12.6.0|12.6.0]] and later support CMake.  
  
=== What are the benefits of CMake? ===
+
GCHP is expected to support CMake by the end of 2019.
# You environment is verified ''before'' you compile.
+
# Incremental compiling and a simpler build procedure.
+
# Fewer wasted HPC jobs due to failed builds.
+
  
=== What is incremental compiling? ===
+
== Usage ==
 
+
=== What is an "out of source" build? ===
+
 
+
== Using CMake ==
+
  
 
=== How do I build GEOS-Chem with CMake? ===
 
=== How do I build GEOS-Chem with CMake? ===
Line 27: Line 20:
 
  make install                            # 6. Install the geos executable in your run directory
 
  make install                            # 6. Install the geos executable in your run directory
  
Refer to [[Building GEOS-Chem with CMake]] for a detailed overview of building GEOS-Chem with CMake.
+
See [[Building GEOS-Chem with CMake]] more details.
  
 
==== Can I build GEOS-Chem Classic and GCHP in the same environment? ====
 
==== Can I build GEOS-Chem Classic and GCHP in the same environment? ====
Line 37: Line 30:
  
 
=== How do I <code>make clean</code>? ===
 
=== How do I <code>make clean</code>? ===
You don't need to do this anymore. When you run a <code>make</code> command, the build system automatically figures out what needs to be recompiled. A "<code>clean</code>" target still exists, but it cleans ''everything''.  
+
You don't need to do this anymore. Now, when you run <code>make</code>, the build system automatically figures out what needs to be recompiled. A "<code>clean</code>" target still exists, but it cleans ''everything''.  
  
 
If you want to restart the build from scratch, you can do
 
If you want to restart the build from scratch, you can do
Line 49: Line 42:
  
 
==== How do I clean my build's configuration (i.e. CMake's files)? ====
 
==== How do I clean my build's configuration (i.e. CMake's files)? ====
 +
Just delete your build directory, and remake it.
 
  rm -rf build
 
  rm -rf build
 
  mkdir build
 
  mkdir build
 
  cd build
 
  cd build
 +
 +
==== When should I delete my build directory (i.e. clean my build's configuration)? ====
 +
You build directory holds information about your build environment&mdash;things like which compilers you are using and the paths to dependencies like NetCDF. Because of this, you should create a new build directory whenever your environment changes. Don't hesitate to delete your build directory&mdash;they are easy to remake.
  
 
=== How do I change GEOS-Chem's build options? ===
 
=== How do I change GEOS-Chem's build options? ===
Build options set through CMake variables. You can set CMake variables with <code>-D<name>="<value>"</code> arguments. Note that "ON", "OFF", "TRUE", "FALSE", etc., are valid booleans in CMake.
+
Build options set through CMake variables. You can set CMake variables with <code>-D<name>="<value>"</code> arguments. Note that "ON", "OFF", "TRUE", "FALSE", etc. are valid booleans in CMake.
  
 
  cmake . -DFOO="BAR"    # set's the variable FOO equal to "BAR"
 
  cmake . -DFOO="BAR"    # set's the variable FOO equal to "BAR"
Line 70: Line 67:
 
  cmake . -DCMAKE_BUILD_TYPE=Debug
 
  cmake . -DCMAKE_BUILD_TYPE=Debug
  
== Advanced topics ==
+
==== How do I build with custom compiler flags? ====
 +
You can specify custom compiler flags with the <code>CMAKE_Fortran_FLAGS</code> variable. These will be ''added'' to the list of compiler flags that GEOS-Chem is compiler with.
 +
cmake . -DCMAKE_Fortran_FLAGS="-march=skylake"
 +
 
 +
=== I got a CMake error. How do I fix it? ===
 +
 
 +
==== CMake can't find NetCDF. How do I fix this? ====
 +
If CMake is not finding NetCDF and NetCDF-Fortran on your machine it will print the following error message.
 +
 
 +
  CMake Error at /usr/share/cmake-3.5/Modules/FindPackageHandleStandardArgs.cmake:148 (message):
 +
 
 +
        NETCDF_F_LIBRARY: Path to "libnetcdff.so"
 +
        NETCDF_C_LIBRARY: Path to "libnetcdf.so"
 +
        NETCDF_C_INCLUDE_DIR: Directory containing "netcdf.h"
 +
        NETCDF_F90_INCLUDE_DIR: Directory containing "netcdf.mod"
 +
        NETCDF_F77_INCLUDE_DIR: Directory containing "netcdf.inc"
 +
 
 +
    Find the directories/files that are listed above.  Specify the directories
 +
    you want CMake to search with the CMAKE_PREFIX_PATH variable (or the
 +
    NetCDF_ROOT environment variable).
 +
 
 +
    (missing:  NETCDF_F_LIBRARY NETCDF_C_LIBRARY NETCDF_C_INCLUDE_DIR NETCDF_F90_INCLUDE_DIR NETCDF_F77_INCLUDE_DIR)
 +
  Call Stack (most recent call first):
 +
    /usr/share/cmake-3.5/Modules/FindPackageHandleStandardArgs.cmake:388 (_FPHSA_FAILURE_MESSAGE)
 +
    CMakeScripts/FindNetCDF.cmake:138 (find_package_handle_standard_args)
 +
    CMakeLists.txt:44 (find_package)
 +
 
 +
 
 +
  -- Configuring incomplete, errors occurred!
 +
  See also "/stetson-home/bindle/geos-chem/build/CMakeFiles/CMakeOutput.log".
 +
 
 +
To resolve this, you need to point CMake to where NetCDF and NetCDF-Fortran are installed. This can be done by setting ''environment variables'' <code>NetCDF_ROOT</code>, <code>NetCDF_C_ROOT</code>, or <code>NetCDF_Fortran</code> to the directory/directories where NetCDF is installed. The directory/directories where NetCDF is installed should have subdirectories like <code>lib/</code> and <code>include/</code>.
 +
 
 +
== Advanced ==
 +
 
 +
=== Can I build GEOS-Chem without a run directory? ===
 +
 
 +
Yes. Initialize your build directory with the following command
 +
  cmake -DRUNDIR=IGNORE -DRUNDIR_SIM=standard /path/to/your/source/code
  
 
=== Can I use Ninja rather than GNU Make? ===
 
=== Can I use Ninja rather than GNU Make? ===
Line 79: Line 114:
  
 
=== How do I build GEOS-Chem as a part of an other project? ===
 
=== How do I build GEOS-Chem as a part of an other project? ===
 +
 +
Currently, this is an undocumented feature (see: https://github.com/geoschem/geos-chem/issues/195).
 +
 +
== Further reading ==
 +
 +
#[[Compiling with CMake]] section of ''[[Getting Started with GEOS-Chem]]''
 +
#[https://cmake.org/cmake/help/latest/guide/tutorial/index.html ''CMake tutorial'' (cmake.org)]
 +
#[https://learnxinyminutes.com/docs/cmake/ ''Learn X in Y minutes (where X is CMake)'']
 +
 +
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 20:58, 20 December 2019 (UTC)

Latest revision as of 23:09, 21 February 2020

General

What is CMake?

CMake is a program that generates Makefiles. This is an oversimplification, but it describes the essence of CMake.

What versions of GEOS-Chem support CMake?

GEOS-Chem Classic 12.6.0 and later support CMake.

GCHP is expected to support CMake by the end of 2019.

Usage

How do I build GEOS-Chem with CMake?

cd <run directory>                       # 1. Go to your run directory
mkdir build                              # 2. Create a build directory
cd build                                 # 3. cd into your build directory
cmake <path to GEOS-Chem's source code>  # 4. Configure GEOS-Chem's build
make -j                                  # 5. Compile GEOS-Chem
make install                             # 6. Install the geos executable in your run directory

See Building GEOS-Chem with CMake more details.

Can I build GEOS-Chem Classic and GCHP in the same environment?

Yes. Because GEOS-Chem Classic's requirements are a subset of GCHP's.

How do I build specific targets?

Pass the target's name as an argument to make. You can build multiple specific targets by passing multiple names.

make <name>

How do I make clean?

You don't need to do this anymore. Now, when you run make, the build system automatically figures out what needs to be recompiled. A "clean" target still exists, but it cleans everything.

If you want to restart the build from scratch, you can do

make clean

How do I continue a build that was terminated before it finished?

Run your make command again. The build system will automatically pick up where it left off.

How do I recompile after I make modifications to the source code?

The build system will automatically figure out what needs to be recompiled when you run make. There is no need to run "cleaning" commands.

How do I clean my build's configuration (i.e. CMake's files)?

Just delete your build directory, and remake it.

rm -rf build
mkdir build
cd build

When should I delete my build directory (i.e. clean my build's configuration)?

You build directory holds information about your build environment—things like which compilers you are using and the paths to dependencies like NetCDF. Because of this, you should create a new build directory whenever your environment changes. Don't hesitate to delete your build directory—they are easy to remake.

How do I change GEOS-Chem's build options?

Build options set through CMake variables. You can set CMake variables with -D<name>="<value>" arguments. Note that "ON", "OFF", "TRUE", "FALSE", etc. are valid booleans in CMake.

cmake . -DFOO="BAR"    # set's the variable FOO equal to "BAR"

How do I disable multithreading (i.e. OpenMP)?

cmake . -DOMP=OFF

How do I disable colorized output?

cmake . -DCMAKE_COLOR_MAKEFILE=FALSE

How do I increase the build's verbosity?

cmake . -DCMAKE_VERBOSE_MAKEFILE=TRUE

How do I build for debugging?

cmake . -DCMAKE_BUILD_TYPE=Debug

How do I build with custom compiler flags?

You can specify custom compiler flags with the CMAKE_Fortran_FLAGS variable. These will be added to the list of compiler flags that GEOS-Chem is compiler with.

cmake . -DCMAKE_Fortran_FLAGS="-march=skylake"

I got a CMake error. How do I fix it?

CMake can't find NetCDF. How do I fix this?

If CMake is not finding NetCDF and NetCDF-Fortran on your machine it will print the following error message.

 CMake Error at /usr/share/cmake-3.5/Modules/FindPackageHandleStandardArgs.cmake:148 (message):
 
       NETCDF_F_LIBRARY: Path to "libnetcdff.so"
       NETCDF_C_LIBRARY: Path to "libnetcdf.so"
       NETCDF_C_INCLUDE_DIR: Directory containing "netcdf.h"
       NETCDF_F90_INCLUDE_DIR: Directory containing "netcdf.mod"
       NETCDF_F77_INCLUDE_DIR: Directory containing "netcdf.inc"
 
   Find the directories/files that are listed above.  Specify the directories
   you want CMake to search with the CMAKE_PREFIX_PATH variable (or the
   NetCDF_ROOT environment variable).
 
    (missing:  NETCDF_F_LIBRARY NETCDF_C_LIBRARY NETCDF_C_INCLUDE_DIR NETCDF_F90_INCLUDE_DIR NETCDF_F77_INCLUDE_DIR) 
 Call Stack (most recent call first):
   /usr/share/cmake-3.5/Modules/FindPackageHandleStandardArgs.cmake:388 (_FPHSA_FAILURE_MESSAGE)
   CMakeScripts/FindNetCDF.cmake:138 (find_package_handle_standard_args)
   CMakeLists.txt:44 (find_package)
 
 
 -- Configuring incomplete, errors occurred!
 See also "/stetson-home/bindle/geos-chem/build/CMakeFiles/CMakeOutput.log".

To resolve this, you need to point CMake to where NetCDF and NetCDF-Fortran are installed. This can be done by setting environment variables NetCDF_ROOT, NetCDF_C_ROOT, or NetCDF_Fortran to the directory/directories where NetCDF is installed. The directory/directories where NetCDF is installed should have subdirectories like lib/ and include/.

Advanced

Can I build GEOS-Chem without a run directory?

Yes. Initialize your build directory with the following command

 cmake -DRUNDIR=IGNORE -DRUNDIR_SIM=standard /path/to/your/source/code

Can I use Ninja rather than GNU Make?

Yes. You'll need CMake version 3.7 or greater and Kitware's Ninja distribution (for Fortran futures). To use the Ninja generator rather than the Makefile generator, initialize your build directory with cmake -GNinja <path to source code>.

Are the environment variables like FC and ESMF_ROOT necessary?

No, these are just for convenience. You can configure the build with the standard CMAKE_C_COMPILER, CMAKE_CXX_COMPILER, CMAKE_Fortran_COMPILER, and CMAKE_PREFIX_PATH variables, rather than environment variables, if you'd prefer. This means GEOS-Chem doesn't impose environment variable requirements on superprojects.

How do I build GEOS-Chem as a part of an other project?

Currently, this is an undocumented feature (see: https://github.com/geoschem/geos-chem/issues/195).

Further reading

  1. Compiling with CMake section of Getting Started with GEOS-Chem
  2. CMake tutorial (cmake.org)
  3. Learn X in Y minutes (where X is CMake)

--Bob Yantosca (talk) 20:58, 20 December 2019 (UTC)