You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
commit 530e270
Author: David Ogden <david.ogden.nrel@outlook.com>
Date: Sun Jul 20 10:59:33 2025 +0100
Add CMake build configuration guide
Adds a new markdown guide explaining single- vs. multi-config CMake generators, build types, and best practices for consistent builds across platforms.
commit 8ba0b2a
Author: David Ogden <david.ogden.nrel@outlook.com>
Date: Sat Jul 19 15:22:49 2025 +0100
Clarify build type consistency and platform scope in developer docs
- Added note on matching build type with Project Chrono
- Clarified Windows-specific scope of instructions
commit 904baa9
Author: David Ogden <david.ogden.nrel@outlook.com>
Date: Sat Jul 19 15:14:14 2025 +0100
Clarify build instructions for Windows and macOS/Linux, with platform-specific guidance
- Split build instructions into separate sections for Windows and macOS/Linux
- Explained differences in setting build type: --config (Windows) vs -DCMAKE_BUILD_TYPE (Unix)
- Emphasized the need to match HydroChrono’s build type with Project Chrono’s
- Moved post-build steps to occur before running tests
- Updated clean build instructions to reflect platform differences
commit a96e642
Author: David Ogden <david.ogden.nrel@outlook.com>
Date: Mon Jun 16 14:35:56 2025 +0100
Include cl build instructions
working with Chrono v9.0.1 and Visual Studio 2022
**Post-Build Steps (Required before running tests):**
87
+
88
+
Copy the following shared library files from your Chrono build directory to your build directory's `demos` folder:
89
+
- libChronoEngine.so (Linux) or libChronoEngine.dylib (macOS)
90
+
- libChronoEngine_irrlicht.so (Linux) or libChronoEngine_irrlicht.dylib (macOS) (if using Irrlicht)
91
+
- libIrrlicht.so (Linux) or libIrrlicht.dylib (macOS) (if using Irrlicht)
92
+
93
+
**Run the tests:**
94
+
```bash
95
+
ctest --output-on-failure
96
+
```
97
+
98
+
### Clean Build
99
+
100
+
To perform a clean rebuild of the project:
101
+
102
+
**Windows:**
103
+
```powershell
104
+
# From the project root
105
+
Remove-Item -Recurse -Force build
106
+
mkdir build
107
+
cd build
108
+
```
109
+
Then return to the [Windows build steps](#windows-visual-studio) above.
110
+
111
+
**macOS / Linux:**
112
+
```bash
113
+
# From the project root
114
+
rm -rf build
115
+
mkdir build
116
+
cd build
117
+
```
118
+
Then return to the [macOS / Linux build steps](#macos--linux) above.
119
+
120
+
For detailed build instructions, including Visual Studio setup and running demos, see the [developer documentation](https://nrel.github.io/HydroChrono/developer_docs/build_instructions.html).
This page provides instructions on how to build HydroChrono and its associated demos.
11
+
This page provides instructions on how to build HydroChrono and its associated demos on Windows.
12
12
13
13
## Prerequisites
14
14
15
15
Before attempting to build HydroChrono, ensure you have installed and built all of the required [prerequisites](/developer_docs/prerequisites). The exact versions listed in the prerequisites are essential for proper functionality.
16
16
17
-
## Building HydroChrono
17
+
- CMake 3.16 or higher
18
+
- A C++ compiler (Visual Studio 2019 or higher, or GCC through MinGW/MSYS2)
19
+
- Project Chrono (built from source, tested with v9.0.0 and v9.0.1)
20
+
- HDF5 1.10.8 or higher
21
+
- Python 3.8 or higher (with numpy and matplotlib)
18
22
19
-
1. Clone this project into a directory and set up a build folder.
20
-
- For instance, clone the project into a `HydroChrono` directory and set up a `HydroChrono_build` adjacent directory.
23
+
### Additional Python Requirements for Documentation
24
+
If you plan to build the documentation, you'll need these additional Python packages:
25
+
- matplotlib
26
+
- sphinx
27
+
- sphinxcontrib-bibtex
28
+
- breathe
29
+
- h5py
21
30
22
-
2. Using the CMake GUI, specify the location of the source files and built binaries for HydroChrono (`HydroChrono` and `HydroChrono_build` respectively). Configure and generate the solution with the following settings:
23
-
24
-
- Set `Chrono_DIR` to the Chrono Build location (typically `../chrono_build/cmake`).
25
-
- Set `HDF5_DIR` to your HDF5 build location, such as `../CMake-hdf5-1.10.8/CMake-hdf5-1.10.8/build/HDF5-1.10.8-win64/HDF5-1.10.8-win64/share/cmake`. Note that version 1.10.8 of HDF5 is best suited for Visual Studio 2019.
26
-
- Enable the following options for additional features: `HYDROCHRONO_ENABLE_DEMOS`, `HYDROCHRONO_ENABLE_IRRLICHT`, and `HYDROCHRONO_ENABLE_TESTS`. For best results, enable all of these features. Note that the Irrlicht module requires Project Chrono to be built with the Irrlicht module enabled.
27
-
- To build the docs: create a new entry in cmake-gui (Name: `Python3_ROOT_DIR`, Type: `PATH`) and set it to the path of your virtual Python environment where you have the `matplotlib`, `sphinx`, `sphinxcontrib-bibtex`, `breathe` and `h5py` packages installed (these are required to build the docs).
31
+
## Clean Build Process
28
32
29
-
3. Navigate to the build folder and open the generated solution in Visual Studio (or click "Open Project" in the CMake GUI). Build the HydroChrono solution with your preferred configuration option (e.g. `RelWithDebInfo`). For comprehensive building and linking, use the `ALL_BUILD` project.
33
+
To perform a complete clean rebuild of the project, follow these steps:
30
34
31
-
## Post-Build Steps
35
+
1.**Clean the Build Directory**
36
+
If you have an existing build directory, you can clean it in one of two ways:
37
+
38
+
a. **Remove and recreate the build directory** (recommended for a completely fresh start):
39
+
```powershell
40
+
# From the project root
41
+
Remove-Item -Recurse -Force build
42
+
mkdir build
43
+
cd build
44
+
```
45
+
46
+
b. **Clean using CMake** (if you want to preserve the build directory):
47
+
```powershell
48
+
# From the build directory
49
+
cmake --build . --target clean
50
+
```
51
+
52
+
2.**Clean CMake Cache** (optional, but recommended for a fresh configuration):
Note: The Chrono build directory typically contains a `cmake` folder with the Chrono CMake configuration files.
80
+
81
+
**⚠️ Important:** The build type (e.g., Release, Debug, RelWithDebInfo) used to build HydroChrono **must match** the build type used when building Project Chrono. On Windows, this is set when running `cmake --build . --config Release`. For more context on build configurations and CMake behavior across platforms, see [CMake Build Configuration Basics](/developer_docs/cmake_build_basics).
82
+
83
+
3.**Build the Project**
84
+
Compile the project using the following command:
85
+
```powershell
86
+
cmake --build . --config Release
87
+
```
88
+
The build output will be in the `Release` folder (or `Debug` if you used that configuration).
89
+
90
+
4.**Run Tests**
91
+
After building, you can run the tests to ensure everything is working correctly:
92
+
```powershell
93
+
ctest -C Release --output-on-failure
94
+
```
95
+
96
+
## Building with Visual Studio
32
97
33
-
1. Copy the `chrono_build/bin/data` file from the Project Chrono build directory to `HydroChrono_build/data`to obtain optional shaders and logos.
98
+
If you prefer using Visual Studio, you can use the CMake GUI to generate a Visual Studio solution.
34
99
35
-
2. Navigate to the `chrono_build/bin/RelWithDebInfo` directory and copy all `.dll` and `.pdb` files (excluding those for demos) to `HydroChrono_build/demos/RelWithDebInfo`. Files to copy include:
100
+
1. Open CMake GUI and set the source directory to your HydroChrono directory and the build directory to where you want to build.
36
101
102
+
2. Configure the project with the following settings:
103
+
- Set `Chrono_DIR` to the Chrono Build location (the directory containing Chrono's CMake files)
104
+
- Set `HDF5_DIR` to your HDF5 build location
105
+
- Enable the following options for additional features: `HYDROCHRONO_ENABLE_DEMOS`, `HYDROCHRONO_ENABLE_IRRLICHT`, and `HYDROCHRONO_ENABLE_TESTS`
106
+
- To build the docs: set `Python3_ROOT_DIR` to your Python environment with required packages
107
+
108
+
**⚠️ Important:** The build type (e.g., Release, Debug, RelWithDebInfo) used to build HydroChrono **must match** the build type used when building Project Chrono. On Windows, this is set when running `cmake --build . --config Release`. For more context on build configurations and CMake behavior across platforms, see [CMake Build Configuration Basics](/developer_docs/cmake_build_basics).
109
+
110
+
3. Click "Generate" to create the Visual Studio solution.
111
+
112
+
4. Open the generated solution in Visual Studio and build the project.
113
+
114
+
## Post-Build Steps
115
+
116
+
1. Copy the `chrono_build/bin/data` folder from the Project Chrono build directory to your build directory's `data` folder to obtain optional shaders and logos.
117
+
118
+
2. Copy the following DLL files from your Chrono build directory to your build directory's `demos/Release` folder:
37
119
- ChronoEngine.dll
38
-
- ChronoEngine.pdb
39
-
- ChronoEngine_irrlicht.dll
40
-
- ChronoEngine_irrlicht.pdb
41
-
- ChronoEngine_postprocess.dll
42
-
- ChronoEngine_postprocess.pdb
43
-
- Irrlicht.dll (note: no `.pdb` for Irrlicht)
44
-
- Other `ChronoEngine_moduleName.dll` and `ChronoEngine_moduleName.pdb` files as relevant.
120
+
- ChronoEngine_irrlicht.dll (if using Irrlicht)
121
+
- Irrlicht.dll (if using Irrlicht)
45
122
46
123
## Running Demos
47
124
48
-
1. To run the demos, navigate to `HydroChrono_build/demos/RelWithDebInfo`.
125
+
1. To run the demos, navigate to your build directory's `demos/Release` folder.
49
126
50
127
2. Demos require a command line argument indicating the location of input files. To specify this:
51
-
52
-
- Run demo executables from the command line with an argument pointing to the absolute location of `<path>/HydroChrono/demos`. For example, executing `> ./sphere_decay.exe C:\\Users\\USERNAME\\HydroChrono\\demos` from the `HydroChrono_build/demos/RelWithDebInfo` directory would run the sphere heave decay test demo with the correct input file locations.
53
-
- Alternatively, in Visual Studio 2019, you can set this command line argument for debug mode in a demo's properties. Navigate to the Solution Explorer, right-click a demo, select `properties > Configuration Properties > Debugging`, and set the Command Arguments to the appropriate path, like `C:\\Users\\USERNAME\\HydroChrono\\demos`.
128
+
- Run demo executables from the command line with an argument pointing to the absolute location of `<path>/HydroChrono/demos`.
129
+
130
+
## Environment Setup
131
+
132
+
Before running the tests, set the `HYDROCHRONO_DATA_DIR` environment variable to point to the demos directory:
# CMake Build Configuration Basics for HydroChrono
2
+
3
+
This guide explains how CMake handles build configurations across platforms, and how to correctly configure and build HydroChrono to avoid common issues.
4
+
5
+
## Overview
6
+
7
+
HydroChrono uses [CMake](https://cmake.org/) as its build system. CMake generates native build files (like Makefiles or Visual Studio projects) that compile your source code. One key part of this process is choosing a **build configuration**, which determines things like optimization level, debug symbol inclusion, and compatibility with dependencies.
8
+
9
+
## What Are CMake Generators?
10
+
11
+
A **generator** is the type of build system CMake creates. Common examples:
12
+
13
+
-**Unix Makefiles** (Linux/macOS)
14
+
-**Ninja** (cross-platform)
15
+
-**Visual Studio** (Windows)
16
+
-**Xcode** (macOS)
17
+
18
+
CMake picks a default generator based on your platform, but you can override it using `-G` (e.g., `-G Ninja`).
19
+
20
+
## Single-Config vs. Multi-Config Generators
21
+
22
+
CMake generators fall into two categories:
23
+
24
+
| Type | Examples | When You Choose Build Type | Typical Platforms |
|**Single-Config**| Makefiles, Ninja | At **configure time** using `-DCMAKE_BUILD_TYPE=...`| Linux, macOS |
27
+
|**Multi-Config**| Visual Studio, Xcode | At **build time** using `--config ...`| Windows, macOS |
28
+
29
+
### 🧹 What's the difference?
30
+
31
+
-**Single-config generators** create a build setup for *one* build type (like `Release` or `Debug`) at a time. If you want to switch types, you need to reconfigure the build or use a separate build directory.
32
+
33
+
> ✅ Pro: Simple, fast\
34
+
> ❌ Con: Not flexible — can't build both Debug and Release without reconfiguring
35
+
36
+
-**Multi-config generators** support *multiple* build types in a single configuration. You choose which type to build at build time with `--config`.
37
+
38
+
> ✅ Pro: Flexible — build Debug and Release from the same configuration\
39
+
> ❌ Con: Only available with certain IDEs like Visual Studio and Xcode
40
+
41
+
### Single-Config Example (Linux/macOS)
42
+
43
+
```bash
44
+
cmake .. -DCMAKE_BUILD_TYPE=Release
45
+
cmake --build .
46
+
```
47
+
48
+
To switch to Debug:
49
+
50
+
```bash
51
+
rm -rf build
52
+
mkdir build &&cd build
53
+
cmake .. -DCMAKE_BUILD_TYPE=Debug
54
+
cmake --build .
55
+
```
56
+
57
+
### Multi-Config Example (Windows with Visual Studio)
58
+
59
+
```powershell
60
+
cmake ..
61
+
cmake --build . --config Release
62
+
cmake --build . --config Debug
63
+
```
64
+
65
+
> ⚠️ On Windows with Visual Studio, `-DCMAKE_BUILD_TYPE` is ignored.
By understanding how CMake generators and build types work, you can avoid many common pitfalls when building and working with HydroChrono and its dependencies.
0 commit comments