ModelSpace uses CMake as its build configuration system. CMake is a cross-platform build configuration tool designed to configure projects of multiple languages. CMake is highly regarded for its cross-platform capabilities, allowing developers to generate build systems for various environments from a single configuration file. This flexibility simplifies the process of compiling code across different operating systems. Moreover, CMake’s out-of-source builds prevent source directories from becoming cluttered with build files, enhancing organization and cleanliness in project management. Its wide adoption and strong community support provide extensive documentation and troubleshooting resources, making it an effective tool for modern software development projects.

What the ModelSpace CMake Does

Initial ModelSpace Setup

All build work, including C++ object files, SWIG files, auto-generated Python, and other code, as well as documentation, is generated in a build/ directory. This keeps the source directories clean and makes rebuilding ModelSpace in the event of bad object directories. The first step in building ModelSpace is to create a build/ directory and configuring it with cmake.

Note: It is important that the build directory is named build/

To set up ModelSpace build, start at the top-level directory.

mkdir build
cd build
cmake ..

How to Build Things

All build commands should be executed from the build/ directory

Compiling the Code

Invoking the make command builds the ModelSpace C++ code, including any extensions your team developed. For simulation, it also SWIG wraps the code for use in multiple languages.

To build, run the command

make -jn

where n is the number of cores to use. For instance, make -j4.

Building the Docs

To build the ModelSpace documentation, run the following commands:

All the Docs

make docs

Just Doxygen

make doc_doxygen

Just Asciidoc

make doc_adoc

How to Run Things

Running the ModelSpace C++ Unit Tests

To run the C++ unit tests, simply execute the following command:

make test

Running the Python Unit Tests

TBD

Running the C++ Scripts

C++ scripts are output to the build/ directory in a location that mirrors their location the cpp/scripts directory. To run them, simply execute

./cpp/scripts/<script_name>

Running Python Scripts

Unlike C++ stuff, Python scripts are run at the location they are defined. For ModelSpace, that is in the Python directory. At the location of the script or test, just run the normal command with python3.

python3 <file> <arg1> ...

Evaluating Code Coverage

ModelSpace also has built-in tools to evaluate code coverage. To run, first execute the C++ unit tests with

make test

Then generate the code coverage output with

make coverage

The code coverage results will write to coverage/index.html. The file can be viewed using the same method as used to view the docs. If a code coverage report is generated, it will render into the docs.