Skip to content

docs: Replace build guides and rewrite build configurations page #93

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Jaredl-Dev wants to merge 4 commits into
base: main
Choose a base branch
from
Open

docs: Replace build guides and rewrite build configurations page #93

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f209687
docs: Replace build guides with the astro rebuild versions
Jaredl-Dev Aug 30, 2026
21c1582
docs: Rewrite the build configurations page
Jaredl-Dev Aug 30, 2026
1cf7237
docs: Move the macOS guide out of the build guides
Jaredl-Dev Aug 30, 2026
d4c23d3
docs: Remove the jmarshall2323 fork build guide
Jaredl-Dev Aug 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
164 changes: 82 additions & 82 deletions SourceCode/Builds/build_configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,113 +1,113 @@
# Build Configurations Overview

This page describes the various build configurations used in the project, detailing the different types of builds, their
purpose, and the associated compiler flags for each configuration. These configurations control how the code is compiled
and optimized for different development and release scenarios.
This page describes the build configurations GeneralsGameCode supports and the CMake options that control them. For
presets, targets, and installation, see the [Building with CMake guide](cmake_guide).

## Build Configurations
Configurations are selected through CMake cache variables, which the presets in `CMakePresets.json` set for you. You
rarely need to set them by hand; pass them while configuring only when you want a combination no preset provides.

There are four main build configurations in the project, each designed for different purposes:
## Configurations

### 1. **Release (O2, _RELEASE)**
| Configuration | VC6 preset | Win32 preset | Cache variables set by the preset |
| ------------- | ------------- | --------------- | ------------------------------------------------------- |
| Release | `vc6` | `win32` | none; this is the default |
| Debug | `vc6-debug` | `win32-debug` | `RTS_BUILD_OPTION_DEBUG=ON` |
| Profile | `vc6-profile` | `win32-profile` | `RTS_BUILD_OPTION_PROFILE=ON` |

- **Purpose:** The release configuration is used for building the final version of the game that will be distributed to
end users.
- **Features:**
- Maximum optimization (`/O2`) for better performance.
- No debugging information is included to ensure smaller binary size and improved performance.
- Suitable for production builds.
Two differences between the toolchains are worth noting:

- **Compiler Flags:**
- `/O2`: Optimization for speed.
- `/D "_RELEASE"`: Defines the release configuration.
- `/D "NDEBUG"`: Disables debugging code.
- `vc6-debug` also sets `CMAKE_BUILD_TYPE=Debug`, because the VC6 presets use Ninja, a single-configuration generator.
The `win32` presets are multi-configuration, so the configuration is chosen when building instead.
- `win32-profile` additionally sets `RTS_BUILD_OPTION_PROFILE_TRACY=ON`. The VC6 profile build does not use Tracy.

- **Use Case:** This configuration is used when preparing the game for release to the end user.
> **Retail compatibility:** Only the `vc6` Release build is compatible with retail multiplayer and replays. See
> [Build presets](cmake_guide#build-presets).

### 2. **Debug (Od, _DEBUG)**
## Configuration definitions

- **Purpose:** The debug configuration is used for development and debugging. It includes debugging symbols and disables
optimizations to make it easier to step through code.
- **Features:**
- No optimization (`/Od`), making debugging easier but with slower execution.
- Debugging symbols and additional information are included to help track issues.
- The build is less efficient but provides full access to debugging features.
Each configuration compiles the code with a different set of preprocessor definitions:

- **Compiler Flags:**
- `/Od`: Disables optimizations to facilitate debugging.
- `/D "_DEBUG"`: Defines the debug configuration.
- `/ZI`: Generates debugging information.
- `/Gm`: Enables minimal rebuilds.
| Configuration | Definitions |
| ------------- | ---------------------------------------------- |
| Release | `RTS_RELEASE`, `NDEBUG` |
| Debug | `RTS_DEBUG`, `WWDEBUG`, `DEBUG` |
| Profile | `RTS_RELEASE`, `NDEBUG`, `RTS_PROFILE_LEGACY` |

- **Use Case:** Used during development for debugging and resolving issues in the code.
The Profile configuration builds on Release, so it defines `RTS_RELEASE` and `NDEBUG` as well.

> **⚠️ Debug Build Requirements:** To run a debug build of the game, you need to have
> the following two files in the game directory alongside the built executable:
>
> - [`MSVCRTD.DLL`](https://github.com/TheSuperHackers/GeneralsWiki/raw/refs/heads/main/SourceCode/Builds/files/MSVCRTD.DLL)
> Microsoft Visual C++ Runtime Library (Debug)
> - [`MSVCIRTD.DLL`](https://github.com/TheSuperHackers/GeneralsWiki/raw/refs/heads/main/SourceCode/Builds/files/MSVCIRTD.DLL)
> Microsoft Visual C++ Internationalization Runtime Library (Debug)
Two further definitions are applied by platform rather than by configuration:

### 3. **Profile (O2, IG_DEBUG_STACKTRACE, _RELEASE, _PROFILE)**
- On MSVC: `_CRT_NONSTDC_NO_WARNINGS` and `_CRT_SECURE_NO_WARNINGS`, plus `_DEBUG_CRT` in the Debug configuration.
- On Unix: `_UNIX`.

- **Purpose:** The profile configuration is used for performance profiling and optimization. It is designed to help
developers analyze performance bottlenecks and gather performance data.
- **Features:**
- Includes optimization (`/O2`) and performance profiling flags.
- Supports detailed stack tracing (`IG_DEBUG_STACKTRACE`) to gather performance metrics.
- Designed for analyzing how the game performs under various conditions and measuring optimization effectiveness.
> [!NOTE]
> Optimization and debug-information flags such as `/O2`, `/Od`, and `/Zi` are not set by the project. They come
> from the compiler defaults CMake applies for the selected `CMAKE_BUILD_TYPE`. The presets set warning level `/W3`
> through the `RTS_FLAGS` cache variable.

- **Compiler Flags:**
- `/O2`: Optimization for performance.
- `/D "_PROFILE"`: Enables profiling configuration.
- `/D "IG_DEBUG_STACKTRACE"`: Enables stack trace debugging for performance analysis.
- `/D "NDEBUG"`: Disables debugging code in the final build.
The Debug configuration has one additional runtime requirement.

- **Use Case:** Used for profiling and performance analysis to optimize code and identify potential bottlenecks.
> [!IMPORTANT]
> Debug builds require the Microsoft debug runtime libraries in the same directory as the built executable.
> See [VC6 Debug runtime](cmake_guide#vc6-debug-runtime) for the required files.

---
## Build options

## Key Compiler Flags
These options change how the code is built. All default to `OFF`.

Below is a list of the key compiler flags used across different configurations:
| Option | Effect |
| --------------------------------- | ------------------------------------------------------------------- |
| `RTS_BUILD_OPTION_DEBUG` | Builds the Debug configuration |
| `RTS_BUILD_OPTION_PROFILE` | Builds the Profile configuration |
| `RTS_BUILD_OPTION_PROFILE_TRACY` | Enables Tracy profiler integration |
| `RTS_BUILD_OPTION_ASAN` | Builds with Address Sanitizer (`/fsanitize=address`) |
| `RTS_BUILD_OPTION_VC6_FULL_DEBUG` | Builds VC6 with full debug information (`/Zi`) |
| `RTS_BUILD_OPTION_FFMPEG` | Enables FFmpeg support |

### Optimization Flags
There is also `RTS_BUILD_OUTPUT_SUFFIX`, a string appended to the output names of installable targets. It is empty by
default, which is why the executables are named `generalsv.exe` and `generalszh.exe`.

- **`/O2`**: Optimizes the code for speed. This flag is typically used in release builds and performance profiling
builds.
- **`/Od`**: Disables optimizations, which is useful during debugging when you want to ensure that the debugger can
easily track code execution.
## Debug feature options

### Debugging Flags
These options control individual debug features independently of the configuration, so a Release build can keep
logging or assert dialogs enabled.

- **`/D "_DEBUG"`**: Defines the build as a debug version, enabling debugging-specific features in the code.
- **`/D "_RELEASE"`**: Defines the build as a release version, disabling debugging features and optimizing for
performance.
- **`/D "NDEBUG"`**: Disables debugging code, typically used in release builds.
The following four accept `DEFAULT`, `ON`, or `OFF`. `DEFAULT` leaves the feature to the configuration, where it is
enabled for Debug and Internal builds:

### Profiling Flags
| Option | `ON` defines | `OFF` defines |
| ---------------------- | ------------------- | --------------------------- |
| `RTS_DEBUG_LOGGING` | `DEBUG_LOGGING` | `DISABLE_DEBUG_LOGGING` |
| `RTS_DEBUG_CRASHING` | `DEBUG_CRASHING` | `DISABLE_DEBUG_CRASHING` |
| `RTS_DEBUG_STACKTRACE` | `DEBUG_STACKTRACE` | `DISABLE_DEBUG_STACKTRACE` |
| `RTS_DEBUG_PROFILE` | `DEBUG_PROFILE` | `DISABLE_DEBUG_PROFILE` |

- **`/D "_PROFILE"`**: Enables performance profiling in the build. This flag is used to gather performance data during
runtime.
- **`/D "IG_DEBUG_STACKTRACE"`**: Enables stack trace generation, which helps in analyzing performance issues and
crashes.
Each of these definitions is set to `1`. Enabling `RTS_DEBUG_STACKTRACE` also enables debug logging.

### Additional Flags
The remaining options are simple on/off switches, all `OFF` by default:

- **`/ZI`**: Generates debugging information and supports editing and continuing in Visual Studio.
- **`/WX`**: Treats warnings as errors, which is often used to enforce strict coding standards.
- **`/Gm`**: Enables minimal rebuild, allowing faster incremental builds.
- **`/MD`**: Links with the dynamic version of the C runtime library, commonly used for Windows builds.
- **`/Yu"PreRTS.h"`**: Tells the compiler to use precompiled headers, which can speed up compilation time.
| Option | Defines | Purpose |
| ---------------------------------------- | -------------------------------- | ---------------------------------------- |
| `RTS_DEBUG_CHEATS` | `_ALLOW_DEBUG_CHEATS_IN_RELEASE` | Enables debug cheats in release builds |
| `RTS_DEBUG_INCLUDE_DEBUG_LOG_IN_CRC_LOG` | `INCLUDE_DEBUG_LOG_IN_CRC_LOG` | Includes the debug log in the CRC log |
| `RTS_DEBUG_MULTI_INSTANCE` | `RTS_MULTI_INSTANCE` | Allows running multiple client instances |

---
## Additional presets

## When to Use Each Configuration
Two VC6 presets combine a Release build with debug features:

- **Release:** Use this configuration when preparing the final version of the game for distribution. It ensures the game
is optimized for performance with no debugging overhead.
- **Debug:** Use this configuration during development when you need to debug issues. It disables optimizations and
includes debugging information.
- **Profile:** Use this configuration when analyzing the performance of the game. It helps identify bottlenecks and
areas that can be optimized further.
| Preset | Cache variables | Purpose |
| ----------------- | ------------------------------------------------ | ---------------------------------------- |
| `vc6-releaselog` | `RTS_DEBUG_LOGGING=ON`, `RTS_DEBUG_CRASHING=ON` | Release build with logging and asserts |
| `vc6-weekly` | `RTS_BUILD_OPTION_VC6_FULL_DEBUG=ON` | Release build with full debug info |

List every preset in your checkout with `cmake --list-presets=all`.

## Example

Configure a Release build with debug logging enabled and build it:

```shell
cmake --preset vc6 -DRTS_DEBUG_LOGGING=ON
cmake --build --preset vc6
```
102 changes: 20 additions & 82 deletions SourceCode/Builds/build_guides.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,94 +1,32 @@
# Build Guides

This page provides an overview of the official and community-supported build guides for **TheSuperHackers** project. It
includes both the official build guides for the main repository and guides for community forks of the project. The
guides cover different environments, configurations, and setups for building the project.
Instructions for building GeneralsGameCode and configuring its build system.

## Build Configurations Overview
## Available build guides

Before diving into the build guides, it's important to understand the different build configurations used in the
project. These configurations dictate how the project is built, whether for debugging, profiling or release.
Both `vc6` and `win32` produce 32-bit Windows builds. `vc6` uses the original Visual C++ 6 toolchain for
retail-compatible Release builds, while `win32` uses a modern Visual Studio toolchain.

- **Release:** Optimized for end-users, providing a smaller, faster executable with no debugging information.
- **Debug:** Includes debugging information, making it easier to trace and debug the code, but without optimization to
ensure ease of debugging.
- **Profile:** Used for performance profiling, with optimizations enabled and additional debugging options to collect
profiling data.
### Windows

Each configuration is designed for a different purpose, whether you're building for development, debugging, testing, or
releasing the final product. You can find more details about the build configurations in
the [Build Configurations](build_configuration) page.
| Guide | Toolchain |
| ------------------------------------------------------ | ----------- |
| [CMake and Visual Studio 6](visual_studio_6) | VC6 |
| [Build with CLion using VC6 or Win32](clion_vc6_win32) | VC6 / Win32 |
| [Visual Studio 2022 and 2026](visual_studio) | Win32 |

> **⚠️ Debug Build Requirements:** To run a debug build of the game, you need to have
> the following two files in the game directory alongside the built executable:
>
> - [`MSVCRTD.DLL`](https://github.com/TheSuperHackers/GeneralsWiki/raw/refs/heads/main/SourceCode/Builds/files/MSVCRTD.DLL)
> Microsoft Visual C++ Runtime Library (Debug)
> - [`MSVCIRTD.DLL`](https://github.com/TheSuperHackers/GeneralsWiki/raw/refs/heads/main/SourceCode/Builds/files/MSVCIRTD.DLL)
> Microsoft Visual C++ Internationalization Runtime Library (Debug)
### Linux

## Architectures and Toolchains
| Guide | Toolchain |
| ------------------------------------------ | --------- |
| [Build on Linux with Docker](linux_docker) | VC6 |

The project supports multiple architectures and toolchains, which is why there are various build guides tailored to
different environments. An **architecture** refers to the target platform, such as **x86** (32-bit) or **x64** (64-bit),
while a **toolchain** is the set of tools (compilers, linkers, etc.) used to build the project. Different toolchains may
support different optimizations, libraries, or debugging features that influence how the build process is conducted.
## CMake guide

> [!WARNING]
> The Wiki is under work in progress. The content is subject to change and may not be complete.
> Not all build guides are available yet, but you can contribute by adding new guides or updating existing ones.
The [Building with CMake guide](cmake_guide) covers the shared command-line workflow, common presets and
options, target selection, installation, and build-specific requirements.

## CMake Overview
## Build configurations

This [CMake Guide](cmake_guide) provides an overview of how to configure and build **Generals** and its expansion
*Zero Hour* using **CMake** via the command line. It covers the various options and flags defined in the CMake files that
control the build process, allowing you to choose different components of the game and tools to build.

## Official Build Guides

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

### **Visual Studio 6 Guides**

1. **Using pure Visual Studio 6 (x86) (Windows)**
- A guide for building the project using only Visual Studio 6 on Windows for the x86 architecture.
[Build with pure Visual Studio 6 (x86) (Windows)](build_with_ea_msvc6)

2. **Using Cmake & Visual Studio 6 (x86) (Windows)**
- A guide for building the project using CMake with Visual Studio 6 on Windows for the x86 architecture.
[Build with CMake & Visual Studio 6 (x86) (Windows)](build_with_msvc6)

#### Sub-guides

- **CLion & VC6 Toolchain**
- A guide for using CLion with the Visual Studio 6 (VC6) toolchain for building the project.
[Build with CLion & VC6 Toolchain](build_with_clion_vc6_toolchain)
- **Docker & VC6**
- A guide for setting up Docker with the Visual Studio 6 (VC6) toolchain for building the project in a
containerized environment.
[Build with Docker & VC6](build_with_msvc6_on_docker)
- **Build on Linux**
- A guide for building the project on Linux using Docker with convenience scripts.
Includes instructions for installing built executables to an existing game.
[Build on Linux](build_on_linux)

### **Visual Studio 2022 Guides**

1. **Using Cmake (x86) (Windows)**
- A guide for building the project using CMake with Visual Studio 2022 on Windows for the x86 architecture.
[Build with CMake (x86) (Windows)](build_with_msvc22)

2. **Using Cmake (Linux)**
- A guide for building the project using CMake with Visual Studio 2022 on Linux.
[Build with CMake (Linux)](build_with_msvc22_linux)

## Community Forks Build Guides

These are the guides provided for community-supported forks of **TheSuperHackers** project. These forks are customized
versions of the original repository and may have unique build setups.

1. **MSVC22 (x64) Generals Only (Windows)**
- A guide for building a custom fork of the project using MSVC 2022 (x64) for Windows, specifically tailored for
the "Generals Only" version.
[Build with MSVC22 (x64) Generals Only (Windows)](build_with_msvc22_x64_jmarshall2323)
The [Build Configurations Overview](build_configuration) describes the Release, Debug, and Profile configurations, the
build options, and the debug feature options that control them.
Loading
Loading