1 # Overview of the build system
3 The COVID-19 CovidSim model uses the [CMake](www.cmake.org) build tool to
4 generate build files for other build systems. Currently, building using clang
5 and gcc with Makefiles and MSVC with Visual Studio are supported.
7 ## Building with Makefiles
9 From the command line inside a git clone, run the following:
20 Once `make` has completed use:
26 to run the regressions tests.
28 The tests can take a while, and may produce no output for >10 minutes.
41 May be more reassuring that something is happening.
43 ## Building with Visual Studio project files from Cmake
45 From the command line inside a git clone, run the following:
53 This will create project files inside the `build` directory that can be opened
54 in Visual Studio. Modifications to the CMake configuration may require
55 regenerating the Visual Studio projects.
59 To enable Visual Studio to pick up the tests added by CMake:
61 * Open the `Tests` menu in the Visual Studio menu bar
63 * Choose `Run CTests`.
65 ## Building directly with CMake in Visual Studio 2019
67 Visual Studio 2019 supports using CMake to manage the build directly by
68 selecting File -> Open -> Cmake... and opening `src/CMakeLists.txt`. Then
69 Visual Studio's normal build shortcuts will update the CMake configuration
70 as well as building the project.
72 CMake options are configured using the `CMakeSettings.json` file, which
73 Visual Studio will generate when `CMakeLists.txt` is opened.
77 To enable Visual Studio to pick up the tests added by CMake:
79 * Open the `Tests` menu in the Visual Studio menu bar
81 * Choose `Run CTests`.
85 Additional configuration variables can be provided in the `cmake` invocation.
87 - `USE_OPENMP` determines whether the model is compiled with parallelization
88 using OpenMP. This option defaults to on, but can be disabled by passing
89 `-DUSE_OPENMP=OFF`. The simulation is designed to be run on multi-core systems.
90 Performance improvements are approximately linear up to 24 to 32 cores,
91 depending on memory performance.
93 For Makefile builds, use `-DCMAKE_BUILD_TYPE=` to specify the output format:
100 By default, Makefile builds will use `RelWithDebInfo`.
102 ## VisualStudio solution
104 A manually created VS-2019 solution and project is included for convenience,
105 but it should not be considered the source of truth for the project.
109 The regression tests are not supported in the Visual Studio stand-alone
114 The CMake custom target `doxygen` builds the Doxygen documentation
115 (`make doxygen`). Some IDEs do not expose this so alternatively setting the
116 `BUILD_DOC` CMake option to `ON` will cause the documentation to be built
117 every time the software is built regardless of whether anything has changed.
119 To generate any diagrams [GraphViz](https://graphviz.org/) must be installed.
121 ### Replaying warnings in Visual Studio
123 The Doxygen warnings can be navigated to in Visual Studio:
124 1. From the `Tools` menu select `External Tools...` to launch the
125 `External Tools` dialogue box.
126 2. Press the `Add` button.
127 3. For `Title` enter `CovidSim`.
128 4. For `Command` enter `cmd.exe`.
129 5. For `Arguments` enter `/c type \path\to\warnings.txt`.
130 6. Check `Use Output window`.
132 8. From the `Tools` menu select `CovidSim` to replay the file.
133 9. Double click on a line in the `Output` window which begins with a filename
134 to jump to that file.