Building

Prerequisites

This section describes the steps to build ngen from source.

Important 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.72.0)

Note Only Boost headers are required. As a result, we will vendor in a copy of 1.72.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.72.0.

Ubuntu

apt-get install \
    build-essential \ # for gcc
    cmake           \ # for cmake
    libudunits2-dev   # for udunits2

RHEL7

yum install \
    devtoolset-8 \ # for gcc 8
    cmake \        # for cmake
    udunits2-devel # for udunits2

# 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

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

wget https://boostorg.jfrog.io/artifactory/main/release/1.72.0/source/boost_1_72_0.tar.gz
tar -xvf boost_1_72_0.tar.gz

This will download Boost 1.72.0 into your current directory, then untar it as boost_1_72_0/. To use this directory when building ngen, add -DBOOST_ROOT=boost_1_72_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:

cmake \
    -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 .

Build the ngen executable:

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

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

Testing

If you'd like to run the unit testing suite, then you can additionally build the test_unit target:

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

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