Skip to content

Commit a920a73

Browse files
DevGeniusCodeDevGeniusCode
authored
Add CMake Command Line Usage Guide (#39)
1 parent e297169 commit a920a73

File tree

3 files changed

+251
-0
lines changed

3 files changed

+251
-0
lines changed

‎SourceCode/Builds/build_guides.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,12 @@ support different optimizations, libraries, or debugging features that influence
3333
> The Wiki is under work in progress. The content is subject to change and may not be complete.
3434
> Not all build guides are available yet, but you can contribute by adding new guides or updating existing ones.
3535
36+
## CMake Overview
37+
38+
This [CMake Guide](cmake_guide) provides an overview of how to configure and build **Generals** and its expansion
39+
*Zero Hour* using **CMake** via the command line. It covers the various options and flags defined in the CMake files that
40+
control the build process, allowing you to choose different components of the game and tools to build.
41+
3642
## Official Build Guides
3743

3844
These are the official guides provided by **TheSuperHackers** for building the project using various toolchains and

‎SourceCode/Builds/cmake_guide.md

Lines changed: 243 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,243 @@
1+
# **CMake Command Line Usage Guide**
2+
3+
This guide provides an overview of how to configure and build **Generals** and its expansion **Zero Hour** using **CMake**
4+
via the command line. It covers the various options and flags defined in the CMake files that control the build process,
5+
allowing you to choose different components of the game and tools to build.
6+
7+
For more details on using **Visual Studio 2022**, **Visual Studio 6**, or **CLion**, please refer to the respective
8+
guides.
9+
10+
> [!NOTE]
11+
> CMake retains previous configurations. If you encounter any issues or strange behavior, it is recommended to delete
12+
> the `build` directory and start fresh to ensure the build process uses the latest settings.
13+
14+
- [Build Configuration (Preset)](#1-build-configuration-preset)
15+
- [Selecting Game and Tools](#2-selecting-game-and-tools)
16+
- [Building the Project](#3-building-the-project)
17+
- [Install the Project](#4-install-the-project)
18+
- [Define a Custom Installation Path](#5-define-a-custom-installation-path)
19+
- [Building Specific Targets](#6-building-specific-targets)
20+
- [Examples](#7-examples)
21+
22+
---
23+
24+
## 1. **Build Configuration (Preset)**
25+
26+
The **preset** defines the predefined build configuration. The available presets for this project are:
27+
28+
### For Visual Studio 2022 or Ninja
29+
30+
- `win32`: Release build.
31+
- `win32dgb`: Debug build.
32+
- `win32int`: Internal build.
33+
- `win32prof`: Profile build.
34+
35+
### For Visual Studio 6
36+
37+
- `vc6`: Release build.
38+
- `vc6dgb`: Debug build.
39+
- `vc6int`: Internal build.
40+
- `vc6prof`: Profile build.
41+
42+
### Usage
43+
44+
```bash
45+
cmake --preset <preset>
46+
```
47+
48+
### Using the Default Workflow
49+
50+
You can simplify the build process by using the **workflow** option, which automatically selects the appropriate
51+
configurations based on the preset and the project’s default settings. This eliminates the need to manually specify
52+
build options. For example, to perform a release build with the default configuration, you can run:
53+
54+
```bash
55+
cmake --workflow --preset win32
56+
```
57+
58+
After the build process is complete, you can proceed with the installation using the default settings, as outlined in
59+
the installation section (not the custom path). To install the project, simply use:
60+
61+
```bash
62+
cmake --install build/win32 --config Release
63+
```
64+
65+
This will install the project to the default installation location based on the preset configuration.
66+
67+
---
68+
69+
## 2. **Selecting Game and Tools**
70+
71+
You can specify various options to select which parts of the project to build.
72+
73+
### The available options are
74+
75+
- `DGENZH_BUILD_GENERALS`: Build the base Generals code, default is `ON`.
76+
- `DGENZH_BUILD_GENERALS_TOOLS`: Build tools for Generals, default is `ON`.
77+
- `DGENZH_BUILD_GENERALS_EXTRAS`: Build additional tools/tests for Generals, default is `OFF`.
78+
- `DGENZH_BUILD_ZEROHOUR`: Build the Zero Hour code, default is `ON`.
79+
- `DGENZH_BUILD_ZEROHOUR_TOOLS`: Build tools for Zero Hour, default is `ON`.
80+
- `DGENZH_BUILD_ZEROHOUR_EXTRAS`: Build additional tools/tests for Zero Hour, default is `OFF`.
81+
82+
You can find the list of tools included in the targets list below.
83+
84+
### Example Usage
85+
86+
To build Zero Hour and its tools while excluding Generals:
87+
88+
```bash
89+
cmake -DGENZH_BUILD_ZEROHOUR=ON -DGENZH_BUILD_GENERALS=OFF -DGENZH_BUILD_ZEROHOUR_TOOLS=ON
90+
```
91+
92+
---
93+
94+
## 3. **Building the Project**
95+
96+
After configuring the project with CMake, you can proceed with the build step. To build the project in the appropriate
97+
mode, use:
98+
99+
```bash
100+
cmake --build build/win32
101+
```
102+
103+
> [!NOTE]
104+
> Replace the folder preset name as needed.
105+
106+
The build process will place the compiled executable files in the appropriate directories based on the configuration,
107+
for example, `build/win32/GeneralsMD/Release` for the release build of Zero Hour.
108+
109+
---
110+
111+
## 4. **Install the Project**
112+
113+
To install the built project, use:
114+
115+
```bash
116+
cmake --install build/win32
117+
```
118+
119+
> [!NOTE]
120+
> Replace the folder preset name as needed. This installs the executable project in the specified paths (see next
121+
> section).
122+
<!-- markdownlint-disable-line -->
123+
> [!IMPORTANT]
124+
> In the `win32` preset, use also `--config Release` to install the release executable, because the default installation
125+
> path looks in the debug folder.
126+
127+
---
128+
129+
## 5. **Define a Custom Installation Path**
130+
131+
> [!NOTE]
132+
> To define a custom installation path, it must be set during the preset configuration. The installation path cannot be
133+
> changed after the build is complete.
134+
135+
By default, CMake installs the build executable in the retail game directory. If you want to specify a custom
136+
installation path, use the following option:
137+
138+
For Generals:
139+
140+
```bash
141+
cmake -DGENZH_GENERALS_INSTALL_PREFIX="/path/to/install" .
142+
```
143+
144+
For the Zero Hour expansion:
145+
146+
```bash
147+
cmake -DGENZH_ZEROHOUR_INSTALL_PREFIX="/path/to/install" .
148+
```
149+
150+
---
151+
152+
## 6. **Building Specific Targets**
153+
154+
> [!IMPORTANT]
155+
> Please note that specific **targets** (such as `z_generals` or `z_worldbuilder`) will only work if the corresponding
156+
> game source tree is enabled through the appropriate **preset** (e.g., `DGENZH_BUILD_ZEROHOUR` or
157+
> `DGENZH_BUILD_ZEROHOUR_TOOLS`). Make sure the relevant game sources are included in the configuration before
158+
> attempting to build the **targets**.
159+
160+
You can build specific targets by specifying them in the build command. The common targets are:
161+
162+
> [!TIP]
163+
> The list below are suitable zero hour targets, to build base Generals targets, replace `z` with `g`.
164+
165+
- `z_generals`: Build the Zero Hour code.
166+
167+
### Tools
168+
169+
- `z_debugwindow`: Build the Debug Window tool.
170+
- `z_guiedit`: Build the GUI Editor tool.
171+
- `z_imagepacker`: Build the Image Packer tool.
172+
- `z_mapcachebuilder`: Build the Map Cache Builder tool.
173+
- `z_particleeditor`: Build the Particle Editor tool.
174+
- `z_worldbuilder`: Build the World Builder tool.
175+
<!-- markdownlint-disable-next-line -->
176+
### Usage
177+
178+
```bash
179+
cmake --build build/win32 --target z_generals
180+
```
181+
182+
Replace the folder preset name as needed.
183+
184+
> [!NOTE]
185+
> If from the beginning you build only with specific targets, the installation step will fail because the other targets
186+
> are not built yet. To fix this, you need to build all targets or build the missing targets before installing. Or you
187+
> can install the targets manually by copying the files to the correct directories from the build folder.
188+
189+
---
190+
191+
## 7. **Examples**
192+
193+
### **Build Zero Hour with Debug Configuration and Tools:**
194+
195+
To build the Zero Hour code along with its tools in debug mode, use the following command:
196+
197+
```bash
198+
# Step 1: Configure the build with a preset and additional options
199+
cmake --preset win32dgb -DGENZH_BUILD_ZEROHOUR=ON -DGENZH_BUILD_ZEROHOUR_TOOLS=ON
200+
201+
# Step 2: Build the project
202+
cmake --build build/win32dbg
203+
204+
# Step 3: Install the project to the default installation path
205+
cmake --install build/win32dbg
206+
```
207+
<!-- markdownlint-disable-next-line -->
208+
### **Build Only World Builder Tool:**
209+
210+
To build only the World Builder tool for Zero Hour, use the following command:
211+
212+
```bash
213+
# Step 1: Configure the build with specific target
214+
cmake --preset win32 --target z_worldbuilder
215+
216+
# Step 2: Build the project
217+
cmake --build build/win32
218+
219+
# Step 3: Install the project to the default installation path
220+
cmake --install build/win32 --config Release
221+
```
222+
<!-- markdownlint-disable-next-line -->
223+
### **Build Generals with Extras and Custom Installation Path:**
224+
225+
To build the Generals code with additional extras, configure the build for release, and then install the executable to a
226+
custom directory, you can run the following commands in sequence:
227+
228+
```bash
229+
# Step 1: Configure the build with a preset and additional options
230+
cmake --preset win32 -DGENZH_BUILD_GENERALS=ON -DGENZH_BUILD_GENERALS_EXTRAS=ON -DGENZH_GENERALS_INSTALL_PREFIX="/custom/install/path"
231+
232+
# Step 2: Build the project
233+
cmake --build build/win32
234+
235+
# Step 3: Install the project to the specified custom directory with release configuration
236+
cmake --install build/win32 --config Release
237+
```
238+
239+
---
240+
241+
**Reminder:**
242+
If you encounter issues from previous configurations, make sure to clear the `build` directory and restart the
243+
configuration process.

‎SourceCode/_Sidebar.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@
1414

1515
## [Builds](build_guides)
1616
- [Build Configuration Overview](build_configuration)
17+
- [CMake Overview](cmake_guide)
18+
1719
### **TheSuperHackers Official Guides**:
1820
- **Visual Studio 6 Guides**:
1921
- [Using pure Visual Studio 6 (x86) (Windows)](build_with_ea_msvc6)

0 commit comments

Comments
 (0)