Build System

Building EPANET requires CMake -- an industry standard build system for C/C++ projects that supports Windows, Linux, and MacOS builds. It can be used to generate platform native build systems for your compiler of choice. CMake automatically detects the platform it is running on and generates the appropriate build system for the platform default compiler. Different generators can also be specified. To install or learn more about CMake use the links immediately below.

CMake Download: https://cmake.org/download/

CMake Documentation: https://cmake.org/documentation/

Organization

CMake is powerful and can be used to customize virtually every aspect of the build process. Unfortunately, it can be difficult to configure. The EPANET project maintains the CMake build system configuration for the benefit of the developer community and to facilitate Continuous Integration as part of our project quality management plan.

CMake itself is an executable that gets installed on the build machine. Using it is a two step process. The first step is to run CMake to generate the build system. The second is to run the build system to generate the software artifacts. Configuration files (CMakeLists.txt) located in the project root directory and nearly every other folder throughout the project describe the build system configuration for creating each desired build artifact.

A build "artifact" is a discrete build product like a library, an executable, or a bundle of generated documents. Artifacts are the runnable files created when the build system gets executed. The CMakeLists.txt configuration files found throughout the project are organized so that each artifact is described separately. This makes it easier to create and maintain the configuration files and makes clear the build dependencies within the project.

The most important CMakeLists.txt file is located in the project root directory, epanet/. It is the configuration file that gets passed to the CMake executable when the build system gets generated. It contains settings global to the project and references each subdirectory containing a configuration file defining the overall structure of the project. A map of the build system is provided in Table 1. There are three main build artifacts described in the project -- the output library, the command line executable, and the solver library. The source code for these artifacts is found in the src/ folder.

Table 1: Build System Map

Project Folder	Purpose	Dependencies
epanet/	Global settings, options, add	None
	subdirs, install, and pack
/bindings	Install files	None
/doc	Generate and install docs	Doxygen
/src/outfile	Build, install, stage for test	Shared, epanet-output
/src/run	Build, install, stage for test	Epanet2
/src/shared	Build	None
/src/solver	Build, install, stage for test	None
/tests	Find package, build, and add tests	Boost, epanet2
/tests/outfile	Build test	Boost, epanet-output
/tests/shared	Build tests	Boost, shared
/tests/solver	Build tests	Boost, epanet2

Generation and Build

To build the EPANET library and its command line executable using CMake, first open a command prompt console window and navigate to the project's root directory. Then enter the following commands:

\> cd epanet
\epanet>cmake -E make_directory build
\epanet>cmake -E chdir build cmake -G "Visual Studio 15 2017" ..
\epanet>cmake --build .\build --config Release --target ALL_BUILD

The commands above can be modified to meet different build requirements. To build 64Bit on Windows substitute the following -G "Visual Studio 15 2017 Win64" .., to build in Debug mode substitute --config Debug, and to build various targets substitute any of the build targets from Table 2 for the --target command.

Table 2: Build Targets

Build Target	Purpose
ALL_BUILD	Builds all targets associated with the project
ZERO_CHECK	Runs CMake to regenerate build system
RUN_TESTS	Runs tests registered with CTest (Req -DBUILD_TESTS=ON)
INSTALL	Prepare the install directory
PACKAGE	Run CPack to generate install packaging (zip archive)
doxygen	Builds Toolkit documentation (Req -DBUILD_DOCS=ON)
clean	Removes all generated files

Options are available to further customize a build, see Table 3. For example, the following commands can be used to generate Toolkit documentation provided doxygen has been installed.

\epanet>cmake -DBUILD_DOCS=ON .\build
\epanet>cmake --build .\build --config Release --target doxygen

Table 3: Build Options

Build Option	Purpose
BUILD_TESTS	Build unit tests
BUILD_DOCS	Build Toolkit documentation
BUILD_COVERAGE	Instrument build for coverage

Build Artifacts

Build artifacts can be accessed directly from the build\install folder using the INSTALL target. The install folder can be automatically packaged using the PACKAGE target.

\epanet>cmake --build .\build --config Release --target install
\epanet>cmake --build .\build --config Release --target package

The epanet-solver project can easily be included in another CMake based project using the target import scripts found in the install\cmake folder by including the following commands in your project CMakeLists.txt file.

set(epanet2_DIR "<path to install>/cmake")
find_package(epanet2)