Skip to content

Commit 75b3d98

Browse files
dav-ogdav-og
committed
Merge branch 'main' into pr/70
2 parents 31ba69a + d4766c3 commit 75b3d98

3 files changed

Lines changed: 134 additions & 1 deletion

File tree

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 National Renewable Energy Laboratory
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎docs/_main_pages/developer_docs/build_instructions.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,8 @@ This is the recommended way to build HydroChrono.
7878
```
7979
Note: The Chrono build directory typically contains a `cmake` folder with the Chrono CMake configuration files.
8080

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+
8183
3. **Build the Project**
8284
Compile the project using the following command:
8385
```powershell
@@ -103,13 +105,15 @@ If you prefer using Visual Studio, you can use the CMake GUI to generate a Visua
103105
- Enable the following options for additional features: `HYDROCHRONO_ENABLE_DEMOS`, `HYDROCHRONO_ENABLE_IRRLICHT`, and `HYDROCHRONO_ENABLE_TESTS`
104106
- To build the docs: set `Python3_ROOT_DIR` to your Python environment with required packages
105107

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+
106110
3. Click "Generate" to create the Visual Studio solution.
107111

108112
4. Open the generated solution in Visual Studio and build the project.
109113

110114
## Post-Build Steps
111115

112-
1. Copy the `chrono_build/bin/data` file from the Project Chrono build directory to your build directory's `data` folder to obtain optional shaders and logos.
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.
113117

114118
2. Copy the following DLL files from your Chrono build directory to your build directory's `demos/Release` folder:
115119
- ChronoEngine.dll

‎docs/_main_pages/developer_docs/cmake_build_basics.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
# 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 |
25+
| ----------------- | -------------------- | ---------------------------------------------------- | ----------------- |
26+
| **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.
66+
67+
## Common Build Types
68+
69+
| Type | Description |
70+
| ---------------- | ------------------------------------- |
71+
| `Debug` | No optimizations, full debug symbols |
72+
| `Release` | Full optimizations, no debug symbols |
73+
| `RelWithDebInfo` | Optimized, but includes debug symbols |
74+
| `MinSizeRel` | Optimized for smallest binary size |
75+
76+
Choose the **same build type** for both HydroChrono and Project Chrono to avoid linker errors or runtime issues.
77+
78+
## Why Build Type Consistency Matters
79+
80+
Mismatching build types (e.g., HydroChrono in `Release` but Chrono in `RelWithDebInfo`) can lead to:
81+
82+
- Linker errors (e.g., unresolved symbols)
83+
- ODR (One Definition Rule) violations
84+
- Runtime crashes or inconsistent behavior
85+
86+
Always match the build type of your dependencies.
87+
88+
## Troubleshooting
89+
90+
- 🔍 Not sure what build type Chrono was built with? Check `CMakeCache.txt` in its build directory.
91+
- 🧹 Switching build types? Delete your build directory and reconfigure (`rm -rf build/`).
92+
93+
## Best Practices
94+
95+
- Always explicitly specify your build type.
96+
- Use consistent build types across all dependencies.
97+
- Prefer out-of-source builds (`mkdir build && cd build`) to keep files clean.
98+
- Document your build settings to avoid confusion later.
99+
100+
## See Also
101+
102+
- [CMake: CMAKE\_BUILD\_TYPE](https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html)
103+
- [CMake: CMAKE\_CONFIGURATION\_TYPES](https://cmake.org/cmake/help/latest/variable/CMAKE_CONFIGURATION_TYPES.html)
104+
105+
---
106+
107+
By understanding how CMake generators and build types work, you can avoid many common pitfalls when building and working with HydroChrono and its dependencies.
108+

0 commit comments

Comments
 (0)