Skip to content

Commit

Permalink
Updated compiling commands
Browse files Browse the repository at this point in the history
  • Loading branch information
@LiamBindle
LiamBindle committed Nov 10, 2020
1 parent a72f92c commit 2dbb304
Show file tree
Hide file tree
Showing 3 changed files with 179 additions and 54 deletions.
2 changes: 1 addition & 1 deletion docs/source/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -63,5 +63,5 @@
html_theme_options = {
'logo_only': True,
'display_version': False,
'style_nav_header_background': '#FCFCFC',
'style_nav_header_background': '#F0F0F0' # '#FCFCFC',
}
200 changes: 158 additions & 42 deletions docs/source/user-guide/compiling.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,76 +2,192 @@
Compiling GCHP
==============

.. note::
This user guide assumes you have loaded a computing environment that satisfies
:ref:`GCHP's software requirements <software_requirements>`.

Building with CMake is different than with GNU Make (the way to build GEOS-Chem versions prior to
13.0). With CMake, there are two steps: (1) a cmake command, and (2) a make command. The cmake
command is used to set major options, and is often run just once per build directory. Running this
command with :literal:`-DCMAKE_BUILD_TYPE=Debug` will result in a GCHP build with bounds checking and other
debug options. Additional compile options, such as :literal:`LUO_WETDEP`, can be appended with :literal:`-D`, e.g.
:literal:`-DLUO_WETDEP=y`.
There are two steps to build GCHP. The first step is configuring your build.
To configure your build you use :program:`cmake` to configure build settings.
Build settings cover options like enabling or disabling components like
RRTMG, specifying run directories to install GCHP to, or whether GCHP should be compiled in Debug mode.

Create your build directory
---------------------------
The second step is compiling. To compile GCHP you use :program:`make`. This
compiles GCHP according to your configuration from the first step.

The build directory will contain all files related to building GCHP with a specific environment and
set of compiler flags. All source code directories outside of the build directory remain unchanged
during compilation, unlike in earlier versions of GCHP in which :literal:`*.o` files (for example) were
scattered throughout the source code tree. You can put your build directory in the root directory of
Code.GCHP or you can put it anywhere else.

For your very first built we recommend that you build from the source code for simplicity.
Create a build directory
------------------------

Create a build directory. This directory is going to be the working directory
for your build. The configuration and compile steps generate a
bunch of build files, and this directory is going to store those. You can
think of a build directory as representing a GCHP build. It stores configuration
settings, information about your system, and intermediate files from the compiler.

A build directory is self contained, so you can delete it at any point to erase
the build and its configuration. You can have as many build directories as you
would like. Most users only need one build directory, since they only build GCHP
once; but, for example, if you were building GCHP with Intel and GNU compilers to
compare performance, you would have two build directories: one for the Intel build,
and one for the GNU build. You can name your build directories whatever you want, but a good choice is :file:`build/`.
There is one rule for build directories: **a build directory should be a new directory**.

Create a build directory and initialize it. You initialize a build directory by
running :program:`cmake` with the path to the GCHP source code. Here is an example
of creating a build directory in the top-level of the GCHP source code:

.. code-block:: console
gcuser:~$ cd ~/GCHP.Code
gcuser:~/GCHP.Code$ mkdir build # create the build dir
gcuser:~/Code.GCHP$ cd build
gcuser:~/Code.GCHP/build$ cmake ~/Code.GCHP # initialize the build
-- The Fortran compiler identification is GNU 9.2.1
-- The CXX compiler identification is GNU 9.2.1
-- The C compiler identification is GNU 9.2.1
-- Check for working Fortran compiler: /usr/bin/f95
-- Check for working Fortran compiler: /usr/bin/f95 -- works
...
-- Configuring done
-- Generating done
-- Build files have been written to: /src/build
gcuser:~/Code.GCHP/build$
$ cd Code.GCHP
$ mkdir build
Configure your build
--------------------

As you get more advanced, you may wish to create your build directory in your run directory or in a
directory specific to GCHP version.
Build settings are controlled by :program:`cmake` commands with the following
form:

Configure CMake
---------------
.. code-block:: none
The first argument passed to the cmake command must be the relative path to the root GCHP directory.
For the case of the build directory within source code directory, the root GCHP directory is one
level up.
$ cmake . -D<NAME>="<VALUE>"
.. code-block:: console
where :literal:`<NAME>` is the name of the setting, and :literal:`<VALUE>` is the
value that you are assigning it. These settings are persistent and saved in your build directory.
You can set multiple variables in a single command, and you can run :program:`cmake` as many times
as you need to configure your desired settings.

$ cd build
$ cmake ..
.. note::
The :literal:`.` argument is important. It is the path to your build directory which
is :literal:`.` here.

If you store your build directory in your run directory instead then the relative path would be
:file:`../CodeDir`, making use of the symbolic link to the source code that is automatically generated when
creating a run directory.
GCHP has no required build settings. You can find the complete list of GCHP's build settings `here <Build options for GCHP>`_.
The most frequently used build setting is :literal:`RUNDIR` which lets you specify one or more run directories
to install GCHP to. Here, "install" refers to copying the compiled executable, and some supplemental files
with build settings, to your run directories.

If the last few lines of output from :program:`cmake` look similar to the following snippet then your build was
configured successfully.
.. note::
You can even update build settings after you compile GCHP. Simply rerun :program:`make` and
(optionally) :program:`make install`, and the build system will automatically figure out
what needs to be recompiled.

.. code-block:: none
Since there are no required build settings, for this tutorial we will stick with the
default settings.

You should notice that when you run :program:`cmake` it ends with:

.. code-block:: console
...
-- Configuring done
-- Generating done
-- Build files have been written to: /data10/bindle/Code.GCHP/build
-- Build files have been written to: /src/build
This tells you the configuration was successful, and that you are ready to compile.

Compile
-------

The full build does not occur until you run the :program:`make` command.
You compile GCHP with:

.. code-block:: console
gcuser:~/Code.GCHP/build$ make -j # -j enables compiling in parallel
Optionally, you can use the :literal:`VERBOSE=1` argument to see the compiler commands.

This step creates :file:`./bin/gchp` which is the compiled executable. You can copy
this executable to your run directory manually, or you can do

.. code-block:: console
gcuser:~/Code.GCHP/build$ make install
which copies :file:`./bin/gchp` (and some supplemental files) to
the run directories specified in :ref:`RUNDIR <build_setting_rundir>`.

$ make -j
Now you have compiled GCHP, and you are ready to move on to creating a run directory!

------------

Recompiling
-----------

Once the above steps have been performed only the :program:`make` step should be necessary each time you need
to rebuild the code. The exceptions to this are if you change your environment or your compile
options. In all cases it should never be necessary to run :command:`make clean`. The :program:`make` command already
checks all components of the build for changes. If you want to rebuild from scratch because you
changed environments, simply delete all files from the :file:`build/` directory and recompile. You can also
create a new build directory (with a different name) and compile from there to preserve your
previous build.
You need to recompile GCHP if you update a build setting or make a modification to the source code.
However, with CMake, you don't need to clean before recompiling. The build system automatically
figure out which files need to be recompiled based on your modification. This is known as incremental compiling.

To recompile GCHP, simply do

.. code-block:: console
gcuser:~/Code.GCHP/build$ make -j # -j enables compiling in parallel
and optionally, do :command:`make install`.

------------


GCHP build options
------------------

These are persistent build setting that are set with :program:`cmake` commands
with the following form

.. code-block:: none
$ cmake . -D<NAME>="<VALUE>"
where :literal:`<NAME>` is the name of the build setting, and :literal:`<VALUE>` is the value you
are assigning it. Below is the list of build settings for GCHP.

.. _build_setting_rundir:

RUNDIR
Paths to run directories where :command:`make install` installs GCHP. Multiple
run directories can be specified by a semicolon separated list. A warning is
issues if one of these directories does not look like a run directory.

These paths can be relative paths or absolute paths. Relative paths are interpreted as relative to your build directory.

CMAKE_BUILD_TYPE
The build type. Valid values are :literal:`Release`, :literal:`Debug`, and :literal:`RelWithDebInfo`.
Set this to :literal:`Debug` if you want to build in debug mode.

CMAKE_PREFIX_PATH
One or more directories that are searched for external libraries like NetCDF or MPI. You
can specify multiple paths with a semicolon separated list.

GEOSChem_Fortran_FLAGS_<COMPILER_ID>
Compiler options for GEOS-Chem for all build types. Valid values for :literal:`<COMPILER_ID>` are :literal:`GNU` and
:literal:`Intel`.

GEOSChem_Fortran_FLAGS_<BUILD_TYPE>_<COMPILER_ID>
Additional compiler options for GEOS-Chem for build type :literal:`<BUILD_TYPE>`.

HEMCO_Fortran_FLAGS_<COMPILER_ID>
Same as :literal:`GEOSChem_Fortran_FLAGS_<COMPILER_ID>`, but for HEMCO.

HEMCO_Fortran_FLAGS_<BUILD_TYPE>_<COMPILER_ID>
Same as :literal:`GEOSChem_Fortran_FLAGS_<BUILD_TYPE>_<COMPILER_ID>`, but for HEMCO.

RRTMG
Switch to enable/disable the RRTMG component.

OMP
Switch to enable/disable OpenMP multithreading. As is standard in CMake (see `here <https://cmake.org/cmake/help/latest/command/if.html>`_) valid values are :literal:`ON`, :literal:`YES`, :literal:`Y`, :literal:`TRUE`, or :literal:`1` (case-insensitive) and valid
false values are their opposites.

INSTALLCOPY
Similar to :literal:`RUNDIR`, except the directories do not need to be run directories.
31 changes: 20 additions & 11 deletions docs/source/user-guide/downloading.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,21 +3,30 @@
Downloading GCHP
================

When cloning GCHP you will get the :literal:`main` branch by default.
You can download the GCHP source code from Github:

.. code-block:: console
$ git clone https://github.com/geoschem/gchpctm.git Code.GCHP
$ cd Code.GCHP
$ git submodule update --init --recursive
gcuser:~$ git clone https://github.com/geoschem/GCHPctm.git Code.GCHP
If you would like a different version of GCHP you can checkout the branch or tag from the top-level
directory. Beware that you must always then update the submodules again to checkout the compatible
submodule versions. If you have any unsaved changes in a submdodule, such as local GEOS-Chem
development, make sure you commit those to a branch prior to updating versions.
Next you need to update all the submodules. These are other repositories
that are nested in the GCHP source code. You can initialize the submodules
with

.. code-block:: console
gcuser:~$ cd Code.GCHP
gcuser:~/Code.GCHP$ git submodule update --init --recursive
By default, your source code will be on the :literal:`main` branch. It is a good
idea to checkout an official release rather than use the :literal:`main` branch.
You can find the list of GCHP releases `here <https://github.com/geoschem/GCHPctm/releases>`_.
Once you have decided which version you want to work with, check it out and update your
submodules:

.. code-block:: console
$ cd Code.GCHP
$ git checkout tags/13.0.0-alpha.6
$ git submodule update --init --recursive
gcuser:~/Code.GCHP$ git checkout 13.0.0
gcuser:~/Code.GCHP$ git submodule update --init --recursive

0 comments on commit 2dbb304

Please sign in to comment.