Update build docs

Chrismarsh · May 20, 2024 · f484a8f · f484a8f
1 parent f1ed288
commit f484a8f
Show file tree

Hide file tree

Showing 2 changed files with 137 additions and 114 deletions.
diff --git a/README.md b/README.md
@@ -1,5 +1,10 @@
+> [!WARNING]
+> The default branch was renamed from `master` to `develop`. `Develop` will always be in a state of development
+> with tags  serving to marke quasi-stable releases
+> 
 ![](https://raw.githubusercontent.com/Chrismarsh/CHM/dev/docs/images/mesh.png)
 
+
 # The Canadian Hydrological Model 
 The Canadian Hydrological Model (CHM) is a novel modular unstructured mesh based approach for hydrological modelling. It can move between spatial scale, temporal scale, and spatial extents. It is designed for developing and testing process representations for hydrological models. 
 

diff --git a/docs/build.rst b/docs/build.rst
@@ -4,73 +4,86 @@ Compilation
 .. warning::
     Conan is no longer used to build CHM. Spack is now used
 
-
+.. note::
+   Building CHM without MPI support is now deprecated. MPI is now required.
 
 CHM uses `spack <https://spack.readthedocs.io/>`__ to manage and build all
 dependencies. Because of the various requirements on build
-configuration, versions, and inter-dependencies, using system libraries
-it not supported.
+configuration, versions, and inter-dependencies, using system libraries (apt/yum/brew/&c)
+it not recommended. Take care when compiling against homebrew libraries. Because homebrew releases
+new versions of libraries often, it often results in having to frequently recompile CHM.
 
+However, as the build system uses cmake to locate libraries, there are no assumptions about using spack, so any
+library provider will work, such as the above noted system libraries or other dependency management tools
+like easy_build.
 
-Build requirements
-*******************
+Environment requirements
+**************************
 
 Linux (x86_64) and Macos (arm64) are the only supported environments.
 
-The following have been tested
-
-=======  =====  ========  =====
-   Linux          Macos
---------------  ---------------
-Ubuntu   18.04
-  -      20.04
-  -      22.04  Ventura  13
-=======  =====  ========  =====        
-
 Build env requirements:
-   - cmake >=3.21  (via apt-get/brew)
-   - C++14 compiler (gcc 9.3.0+) (via apt-get/brew)
-   - Fortran 90+ compiler (gfortran) (via apt-get/brew)
+   - cmake >=3.21
+   - C++20 compiler (e.g., gcc 9.3.0+)
+   - Fortran 90+ compiler (e.g., gfortran)
+   - OpenMPI or IntelMPI
 
 .. warning::
    Unfortunately the Intel compiler doesn't currently work with applications that also
    link against GSL. This is being investigated. For now, please do no build CHM with Intel Compilers.
 
 
+Spack will build all required libraries and their dependencies, including compilers and MPI as required.
+This is the recommended approach.
 
-Build dependencies
-*********************
+CHM source
+*************
 
-OpenMP
-~~~~~~~~
+An out of source build should be used. That is, build in a separate folder outside of the CHM source.
+This makes it easier to clean up and start from scratch and to keep seperate release and debug builds.
 
-On Macos, the ``openmp`` library should be installed via homebrew:
+An example is given below:
 
 ::
 
-   brew install libomp
-
+   cd ~/
+   git clone --recurse-submodules https://github.com/Chrismarsh/CHM
+   mkdir ~/build-CHM
+   cd ~/build-CHM
+   # This is where the build configuration will occur in the next steps
 
-OpenMPI
-~~~~~~~~~
-.. note::
 
-   Building CHM without MPI support is now deprecated. MPI is now required.
 
+CHM with spack
+***************
 
-Other MPI versions probably work, but only OpenMPI has been tested.
-      Ensure MPI is installed on linux:
-      ``libopenmpi-dev`` and ``openmpi-bin``
+Install spack
++++++++++++++++
+Install `spack <https://spack-tutorial.readthedocs.io/en/latest/tutorial_basics.html>`__
 
+Use the git repository and use the develop branch, as significant bug fixes to packages CHM uses have been made in
+this branch.
 
+Configure Spack
++++++++++++++++++++
+It is critical to ensure spack is correctly
+configured, as described in the `Spack Getting Started <https://spack.readthedocs.io/en/latest/getting_started.html>`__
+guide.
 
+If you need to build a compiler via spack to use to build CHM and the spack libraries, this is the time to do it.
+Otherwise, ensure
+the `external compiler is found by
+spack <https://spack.readthedocs.io/en/latest/getting_started.html#spack-compiler-find>`__ and correctly configured.
 
-Install spack
--------------
+If you use a system MPI or intel-oneapi-(mkl|tbb) (i.e., a not-spack built version), this is when it should be configured
+`as a spack external <https://spack.readthedocs.io/en/latest/packages_yaml.html#external-packages>`__ package.
 
-Install `spack <https://spack-tutorial.readthedocs.io/en/latest/tutorial_basics.html>`__.
+On macos, apple-clang does not have a fortran compiler. The current suggestion is to install gfortran via gcc in brew
+and it will be detected as the fortran compiler for apple-clang in spack. Note th at when gcc updates, you'll need to
+rebuild impacted packages.
 
-Clone the CHM spac-repo
+CHM uses some libraries that are not currently in mainline spack. Until they have been accepted, please clone
+the CHM spack-repo
 
 ::
 
@@ -88,33 +101,89 @@ It will look like this
     	  - $spack/var/spack/repos/builtin
 
 
-Setup CHM source folders
-------------------------
+Build dependencies
++++++++++++++++++++++
 
-An out of source build should be used. That is, build in a separate folder removed from the CHM source. This makes it easier to clean up
-and start from scratch. An example is given below:
+This step will build and install the dependencies via spack.
 
 ::
 
-   cd ~/
-   git clone --recurse-submodules https://github.com/Chrismarsh/CHM
+    spack env create chm ~/CHM/spack.yaml
+    spack env activate chm
+    spack concretize
+    spack install -j 8 # number of parallel builds, adjust accordingly
 
-   mkdir ~/build-CHM
 
-Build dependencies
----------------------
+CHM with easy_build
+**********************
+When targetting the Digital Alliance Canada stack, `this repository <https://github.com/Chrismarsh/easy_build>`__ hosts
+the easy_build scripts needed for missing libraries. They can be installed in a depdency-preserving order with ``install-all.sh``.
 
-This step will build and install the dependencies via spack.
+Digitial Alliance Canada
+-----------------------------
+
+Ensure the environment is correctly setup
 
 ::
 
-    spack env create chm path/to/CHM/spack.yml
-    spack concretize
-    spack install -j 8 # number of parallel builds, adjust accordingly
+   module load armadillo/10.4.1
+   module load cgal/5.2.1
+   module load hdf5/1.10.6
+   module load meteoio
+   module load func
+   module load netcdf/4.7.4
+   module load gdal/3.2.3
+   module load boost-mpi/1.72.0
+   module load openblas/0.3.9
+   module load gsl/2.6
+   module load eigen/3.3.7
+   module load sparsehash
+   module load tbb/2020.2
+   module load trilinos/15.0.0
+   module load netcdf-c++4/4.3.1
+   module load vtk/9.0.1
+   module load proj/9.0.1
+   module load jemalloc/5.3.0
+   module load cmake
 
+Optionally you can save this with ``module save chm``.
 
-Build CHM
-***********
+
+CHM with system packages
+**************************
+
+Please install the following libraries using the package manager of your choice:
+  - boost >= 1.74.0 with: system, filesystem, date_time, thread, regex, iostreams, program_options, mpi, serialization
+  - cgal (header-only)
+  - hdf5 with c++ bindings
+  - netcdf
+  - netcdf-cxx4 >= 4.3
+  - gdal >= 3.6
+  - proj >=9
+  - sparsehash
+  - gperftools (only needed if tcmalloc is enabled)
+  - gsl
+  - armadillo
+  - intel-oneapi-tbb
+  - eigen
+  - meteoio
+  - func
+  - [email protected] with mpi, optionally openmp & threadsafe if CHM is built with omp
+  - jemalloc (only needed if jemalloc is enabled)
+  - vtk >= 9.2
+  - spdlog
+  - openblas
+  - MPI
+
+.. warning::
+    apple-clang doesn't ship with an OpenMP library,
+    so OpenMP `should be installed <https://mac.r-project.org/openmp/>`__.
+    Doing so via homebrew (``brew install libomp``) is likely the easiest.
+
+Compile CHM
+**************
+
+Regardless of what method was used to build the libraries, the configuration of CHM is the same.
 
 .. note::
    The follow instructions assume that they are invoked from within ``~/build-CHM`` (or your equivalent).
@@ -123,52 +192,52 @@ Build CHM
 Run cmake
 ---------
 
-You can set the install prefix to be anywhere, such as shown in the
-example below
+This guide assumes you are building CHM to build and debug it. However, you can set the install prefix to be anywhere,
+such as shown in the example below
 
 ::
 
    cmake ~/CHM -DCMAKE_INSTALL_PREFIX=/opt/chm-install
 
-Both ``ninja`` and ``make``
-(this is the default) are supported. To use ``ninja``, add
+Both ``ninja`` and ``make`` (this is the default) are supported. To use ``ninja``, add
 
 ::
 
    cmake ~/CHM -DCMAKE_INSTALL_PREFIX=/opt/chm-install -G "Ninja"
 
-Ninja speeds up compilation of CHM by ~6%.
 
 The default build option creates an optimizted “release” build. To build
 a debug build, use ``-DCMAKE_BUILD_TYPE=Debug``.
 
 
-
-
-Intel compiler
+Set compiler
 ~~~~~~~~~~~~~~
 
-If the Intel compiler is used, add the following cmake flags:
+CMake does not always detect the most-optimal compiler you wish to use. The compiler can be manually specified to cmake.
+For example, if the Intel compiler is used, add the following cmake flags:
 
 ::
 
    -DCMAKE_CXX_COMPILER=icpc -DCMAKE_C_COMPILER=icc -DCMAKE_FORTRAN_COMPILER=ifort
 
+If using spack to build the compiler (e.g., gcc), use ``spack find -p gcc`` to find the spack-built compiler.
+
 High performance allocators
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 By default jemalloc is used.
 
 ``-DUSE_TCMALLOC=FALSE -DUSE_JECMALLOC=TRUE``.
 
+
 Building
 --------
 
 Using make
 
 ::
 
-   make -jN CHM
+   make -jN
 
 where N is the number of parallel jobs (e.g., total core count).
 
@@ -182,7 +251,7 @@ Run tests
 ---------
 
 Tests can be enabled with ``-DBUILD_TESTS=TRUE`` and run with
-``make check``/ ``ninja check``
+``make check``/ ``ninja check``. These have not been updated and currently fail
 
 Install
 -------
@@ -230,62 +299,11 @@ Building on Compute Canada (WestGrid)
 To build on Compute Canada stack machines, such as Graham, all dependencies must be built
 from source to ensure the correct optimizations are used. This should be done with the Compute Canada easybuild system.
 
-Only the ``gcc/9.3.0`` environment is supported. This can be enabled with
+Only the ``gcc/9.3.0`` compiler in ``StdEnv/2020`` is supported. This can be enabled with
 
 ::
 
    module load gcc/9.3.0
 
 
-easybuild
------------
-
-Build all dependencies that are not available from compute canada stack
-
-::
-
-   git clone https://github.com/Chrismarsh/easy_build.git
-   cd easy_build
-   chmod +x install-all.sh
-   ./install-all.sh
-
-Building CHM
-------------
-
-Ensure the environment is correctly setup
-
-::
-
-   module load armadillo/10.4.1
-   module load cgal/5.2.1
-   module load hdf5/1.10.6
-   module load meteoio
-   module load func
-   module load netcdf/4.7.4
-   module load gdal/3.2.3
-   module load boost-mpi/1.72.0
-   module load openblas/0.3.9
-   module load gsl/2.6
-   module load eigen/3.3.7
-   module load sparsehash
-   module load tbb/2020.2
-   module load trilinos/13.3.0
-   module load netcdf-c++4/4.3.1
-   module load vtk/9.0.1
-   module load proj/9.0.1
-   module load jemalloc/5.3.0
-   module load cmake
-
-Optionally you can save this with ``module save chm``.
-
-
-Then build CHM
-
-::
-
-   git clone https://github.com/Chrismarsh/CHM  # get CHM source code
-   mkdir ~/chm-build && cd ~/chm-build # make build directory
-   cmake ../CHM -DENABLE_SAFE_CHECKS=ON -DBoost_NO_BOOST_CMAKE=ON -DUSE_TCMALLOC=FALSE -DUSE_JEMALLOC=TRUE -DCMAKE_BUILD_TYPE=Release
-   make -j10
-