covid-sim
/home/abuild/rpmbuild/BUILD/covid-sim-0.14.0/docs/build.md
1 # Overview of the build system
2 
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.
6 
7 ## Building with Makefiles
8 
9 From the command line inside a git clone, run the following:
10 
11 ```sh
12 mkdir build
13 cd build
14 cmake ..
15 make
16 ```
17 
18 ### Testing
19 
20 Once `make` has completed use:
21 
22 ```sh
23 make test
24 ```
25 
26 to run the regressions tests.
27 
28 The tests can take a while, and may produce no output for >10 minutes.
29 Therefore using:
30 
31 ```sh
32 make test ARGS="-V"
33 ```
34 
35 or
36 
37 ```sh
38 ctest -V
39 ```
40 
41 May be more reassuring that something is happening.
42 
43 ## Building with Visual Studio project files from Cmake
44 
45 From the command line inside a git clone, run the following:
46 
47 ```sh
48 mkdir build
49 cd build
50 cmake ..
51 ```
52 
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.
56 
57 ### Testing
58 
59 To enable Visual Studio to pick up the tests added by CMake:
60 
61  * Open the `Tests` menu in the Visual Studio menu bar
62 
63  * Choose `Run CTests`.
64 
65 ## Building directly with CMake in Visual Studio 2019
66 
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.
71 
72 CMake options are configured using the `CMakeSettings.json` file, which
73 Visual Studio will generate when `CMakeLists.txt` is opened.
74 
75 ### Testing
76 
77 To enable Visual Studio to pick up the tests added by CMake:
78 
79  * Open the `Tests` menu in the Visual Studio menu bar
80 
81  * Choose `Run CTests`.
82 
83 ### Build options
84 
85 Additional configuration variables can be provided in the `cmake` invocation.
86 
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.
92 
93 For Makefile builds, use `-DCMAKE_BUILD_TYPE=` to specify the output format:
94 
95 - `Debug`
96 - `MinSizeRel`
97 - `Release`
98 - `RelWithDebInfo`
99 
100 By default, Makefile builds will use `RelWithDebInfo`.
101 
102 ## VisualStudio solution
103 
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.
106 
107 ## Testing
108 
109 The regression tests are not supported in the Visual Studio stand-alone
110 solution.
111 
112 ## Doxygen
113 
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.
118 
119 To generate any diagrams [GraphViz](https://graphviz.org/) must be installed.
120 
121 ### Replaying warnings in Visual Studio
122 
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`.
131 7. Click `Apply`.
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.