Building

Prerequisites

This section describes the steps to build ngen from source.

Caution

ngen does not support building on Windows or with MSVC.

Required Dependencies

ngen requires the following dependencies for core execution:

• C/C++ Compiler supporting C++14
  • gcc (≥8.0.0)
  • clang (≥3.4)
  • IntelLLVM (icx/icpx)
• CMake (≥3.17)
• UDUNITS
• Boost (≥1.79.0)

Note

Only Boost headers are required. As a result, we will vendor in a copy of 1.79.0 after cloning the ngen repository. Package managers typically support installing a system-wide version of Boost, and that will be okay as long as the installed version is at least 1.79.0.

Ubuntu

apt-get install build-essential cmake libudunits2-dev

RHEL7

yum install devtoolset-8 cmake udunits2-devel
# scl enable devtoolset-8 bash # enable to use gcc

RHEL8

dnf install gcc-toolset-8 cmake udunits2-devel
# scl enable gcc-toolset-8 bash # enable to use gcc

macOS

brew install gcc cmake udunits

Optional Dependencies

The following optional dependencies allow for additional features when building ngen:

• Python (≥3.9)
  • Enables embedded Python support and routing support.
• SQLite3
  • Enables GeoPackage reading support.
• NetCDF
  • Enables NetCDF I/O support.
• OpenMPI / MPI Implementation
  • Enables parallel orchestration.

Building

Clone the ngen repo:

git clone https://github.com/NOAA-OWP/ngen.git
cd ngen

Update git submodules:

git submodule update --init --recursive

Tip

If you do not have a system Boost installation, then you can vendor 1.79.0:

curl -L -o boost_1_79_0.tar.bz2 https://sourceforge.net/projects/boost/files/boost/1.79.0/boost_1_79_0.tar.bz2/download
tar xjf boost_1_79_0.tar.bz2

This will download Boost 1.79.0 into your current directory, then untar it as boost_1_79_0/. To use this directory when building ngen, add -DBOOST_ROOT=boost_1_79_0/ to the command-line options below. If you need to force this vendored copy to be used, then add -DBoost_NO_BOOST_CMAKE:BOOL=ON as well.

Create an out-of-source build with any required options set, it allows you to automatically build the submodule libraries (you will need to remove the comments):

cmake \
    -DNetCDF_ROOT=<Directory_to_NetCDF>    \ # Directory that contain <include> and <lib> for NetCDF package
    -DNGEN_WITH_MPI:BOOL=OFF         \ # Enable MPI
    -DNGEN_WITH_NETCDF:BOOL=ON       \ # Enable NetCDF
    -DNGEN_WITH_SQLITE:BOOL=OFF      \ # Enable SQLite
    -DNGEN_WITH_UDUNITS:BOOL=ON      \ # Enable UDUNITS
    -DNGEN_WITH_BMI_FORTRAN:BOOL=OFF \ # Enable Fortran
    -DNGEN_WITH_BMI_C:BOOL=ON        \ # Enable C
    -DNGEN_WITH_PYTHON:BOOL=ON       \ # Enable Python
    -DNGEN_WITH_ROUTING:BOOL=ON      \ # Enable t-route
    -DNGEN_WITH_TESTS:BOOL=OFF       \ # Build unit tests
    -DNGEN_QUIET:BOOL=OFF            \ # Suppress output
    -B cmake_build                   \ # Build directory
    -S .

Warning

If you are reading through ngen documentation, you may come across CMake configuration options that resemble NGEN_ACTIVATE_PYTHON or UDUNITS_ACTIVE. These options will work in place of the corresponding NGEN_WITH_* option, however, they are deprecated and will output a depreciation warning on build. See the root CMakeLists for options that are considered deprecated.

Build the ngen executable:

cmake --build cmake_build -t ngen -- -j $(nproc)

Now, you can run ./cmake_build/ngen to see the usage text.

Additional Considerations

Using Intel MPI

If using Intel MPI version 2021.x, ensure that the MPI environment variables script is sourced into your environment before configuring with CMake. For example, source /path/to/intel-oneapi/mpi/latest/env/vars.sh. This script adds necessary paths to environment variables like LD_LIBRARY_PATH. If this is not done beforehand, you may encounter a CMake error similar to:

...

-- Could NOT find MPI_C (missing: MPI_C_WORKS) 
-- Could NOT find MPI_CXX (missing: MPI_CXX_WORKS) 
-- Configuring incomplete, errors occurred!
CMake Error at /usr/share/cmake/Modules/FindPackageHandleStandardArgs.cmake:230 (message):
  Could NOT find MPI (missing: MPI_C_FOUND MPI_CXX_FOUND)

...

Testing

In order to facilitate streamlined and automated unit testing, ngen uses the Google Test framework. The code for Google Test is stored in a Git Submodule in the test directory. The above instructions ensure that the Google Test submodule is updated, but if you need to update it specifically, you can do so by running the command:

git submodule update --init --recursive -- test/googletest

If you'd like to run ngen's unit testing suite, then you can additionally build the test_unit target. Before running the following command, it is reminded that in the configuration step described in the Building section, you need to set the option -DNGEN_WITH_TESTS:BOOL=ON, then run:

cmake --build cmake_build -t test_unit -- -j $(nproc)

Then, running ./cmake_build/test/test_unit will execute ngen's unit tests.

Note

For more information on the testing framework, see the Testing README.