Build System

EPANET 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 generates 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 build dependencies within the project more clear.

The most important CMakeLists.txt file is located in the project root directory. 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. Several build options are also defined, see Table 1.

Table 1: Build Options

Build Option	Purpose
BUILD_TESTS	Configure to build unit tests
BUILD_DOCS	Configure to build Toolkit Documentation
BUILD_COVERAGE	Instrument build for coverage analysis

Table 2: 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

Execution

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:

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

Note: Use -G "Visual Studio 15 2017 Win64" .. as the third command for a 64-bit build on Windows.

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 (Requires -DBUILD_TESTS)
INSTALL	Prepare the install directory
PACKAGE	Run CPack to generate install packaging (zip archive)
doxygen	Builds Toolkit documentation (Requires -DBUILD_DOCS)
clean	Removes all generated files

Under Windows the resulting EPANET toolkit library epanet2.dll and its command line executable runepanet.exe will be in the build\bin\Release directory. The build\lib\Release directory contains an epanet2.lib file which is needed to build C/C++ applications using the Windows version of the library. For Linux and Mac OS the EPANET toolkit shared library libepanet2.so appears in the build/lib directory and the command line executable runepanet is in the build/bin directory.