Skip to content

Commit 27f0644

Browse files
sebyx07claude
sebyx07
and
claude
committed
docs(build): Add Linux build support and comprehensive documentation
- Add BUILDING.md with detailed build instructions for Windows and Linux - Add build-linux.sh script for easy Docker-based builds on Linux - Add install-to-game.sh script for installing builds to existing game - Add CLAUDE.md with AI assistant guidelines including SOLID principles - Update README.md with quick start build instructions - Update .gitignore to exclude /tmp/ directory The Linux build uses Docker with Wine and VC6 to produce Windows-compatible executables that can be run with Wine. Tested successfully with Zero Hour. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
1 parent 5dba2a0 commit 27f0644

File tree

6 files changed

+1126
-3
lines changed

6 files changed

+1126
-3
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@ thumbs.db
4747
.clang-format
4848
/.vscode
4949
/Dependencies/MaxSDK/maxsdk
50+
/tmp/
5051

5152
## IntelliJ, CLion, etc.
5253
/.idea

‎BUILDING.md‎

Lines changed: 335 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,335 @@
1+
# Building Generals Game Code
2+
3+
This document provides comprehensive instructions for building Command & Conquer: Generals and Zero Hour from source on Windows and Linux.
4+
5+
## Table of Contents
6+
7+
- [Overview](#overview)
8+
- [Prerequisites](#prerequisites)
9+
- [Building on Windows](#building-on-windows)
10+
- [Visual Studio 2022 Build](#visual-studio-2022-build)
11+
- [VC6 Build (Retail Compatible)](#vc6-build-retail-compatible)
12+
- [Building on Linux](#building-on-linux)
13+
- [Docker Build (Recommended)](#docker-build-recommended)
14+
- [Running the Game on Linux](#running-the-game-on-linux)
15+
- [Build Presets](#build-presets)
16+
- [Build Targets](#build-targets)
17+
- [Troubleshooting](#troubleshooting)
18+
19+
## Overview
20+
21+
The Generals Game Code can be built using different compilers and configurations:
22+
23+
| Build Type | Platform | Compiler | Notes |
24+
|------------|----------|----------|-------|
25+
| VC6 | Windows | Visual Studio 6 | Retail-compatible binaries |
26+
| Win32 | Windows | Visual Studio 2022 | Modern build with C++20 |
27+
| Docker | Linux | Wine + VC6 | Cross-compiles Windows binaries |
28+
29+
**Important**: The game engine uses DirectX 8, Miles Sound System, and Bink Video, which are Windows-only technologies. All builds produce Windows executables (.exe files). Linux users run these via Wine.
30+
31+
## Prerequisites
32+
33+
### Windows
34+
35+
- **CMake 3.25+**: Download from [cmake.org](https://cmake.org/download/)
36+
- **Ninja**: Download from [ninja-build.org](https://ninja-build.org/) or install via package manager
37+
- **Git**: For cloning the repository and fetching dependencies
38+
39+
For **Visual Studio 2022** builds:
40+
- Visual Studio 2022 with "Desktop development with C++" workload
41+
- Windows SDK
42+
43+
For **VC6** builds (retail-compatible):
44+
- Visual Studio 6.0 (MSVC 6) - see CI configuration for setup
45+
46+
### Linux
47+
48+
- **Docker**: Install from [docker.com](https://docs.docker.com/engine/install/)
49+
- **Wine** (optional): For running the built executables
50+
51+
```bash
52+
# Debian/Ubuntu
53+
sudo apt-get install docker.io wine
54+
55+
# Fedora
56+
sudo dnf install docker wine
57+
58+
# Arch Linux
59+
sudo pacman -S docker wine
60+
```
61+
62+
## Building on Windows
63+
64+
### Visual Studio 2022 Build
65+
66+
This is the recommended build for development on Windows.
67+
68+
```powershell
69+
# Configure
70+
cmake --preset win32
71+
72+
# Build (Release)
73+
cmake --build build/win32 --config Release
74+
75+
# Build (Debug)
76+
cmake --build build/win32 --config Debug
77+
```
78+
79+
Executables are placed in `build/win32/GeneralsMD/` and `build/win32/Generals/`.
80+
81+
### VC6 Build (Retail Compatible)
82+
83+
The VC6 build produces binaries compatible with the retail game, allowing replay compatibility testing.
84+
85+
```powershell
86+
# Configure
87+
cmake --preset vc6
88+
89+
# Build
90+
cmake --build build/vc6
91+
```
92+
93+
**Note**: VC6 builds require the Visual Studio 6 toolchain. The CI uses [itsmattkc/MSVC600](https://github.com/itsmattkc/MSVC600) portable installation.
94+
95+
## Building on Linux
96+
97+
### Docker Build (Recommended)
98+
99+
The Docker build compiles Windows executables using Wine and VC6 inside a container. This is the recommended way to build on Linux.
100+
101+
#### Quick Start
102+
103+
```bash
104+
# Full build (both games)
105+
./scripts/build-linux.sh
106+
107+
# Build Zero Hour only
108+
./scripts/build-linux.sh --game zh
109+
110+
# Build Generals only
111+
./scripts/build-linux.sh --game generals
112+
```
113+
114+
#### Using the Docker Script Directly
115+
116+
```bash
117+
# Build with the original script
118+
./scripts/dockerbuild.sh
119+
120+
# Force CMake reconfiguration
121+
./scripts/dockerbuild.sh --cmake
122+
123+
# Enter interactive shell in container
124+
./scripts/dockerbuild.sh --bash
125+
```
126+
127+
#### Build Output
128+
129+
After a successful build, executables are located in:
130+
131+
```
132+
build/docker/
133+
GeneralsMD/ # Zero Hour
134+
generalszh.exe # Main game
135+
WorldBuilderZH.exe # Map editor
136+
W3DViewZH.exe # 3D model viewer
137+
guiedit.exe # GUI editor
138+
ParticleEditor.dll # Particle editor
139+
...
140+
Generals/ # Original Generals
141+
generalsv.exe # Main game
142+
WorldBuilderV.exe # Map editor
143+
W3DViewV.exe # 3D model viewer
144+
...
145+
```
146+
147+
### Installing to Existing Game
148+
149+
The build produces Windows executables that need the original game data files (textures, sounds, maps, etc.) to run. You must have a legal copy of Command & Conquer: Generals Zero Hour installed.
150+
151+
#### Using the Installation Script
152+
153+
```bash
154+
# Auto-detect game installation and install built files
155+
./scripts/install-to-game.sh --detect
156+
157+
# Or specify the game directory manually
158+
./scripts/install-to-game.sh "/path/to/Generals Zero Hour"
159+
160+
# Restore original files
161+
./scripts/install-to-game.sh --restore "/path/to/Generals Zero Hour"
162+
163+
# Dry run (show what would be installed)
164+
./scripts/install-to-game.sh --dry-run "/path/to/Generals Zero Hour"
165+
```
166+
167+
#### Manual Installation
168+
169+
If you prefer manual installation:
170+
171+
1. Locate your game installation directory (e.g., `C:\Program Files\EA Games\Command and Conquer Generals Zero Hour\Data\`)
172+
2. Backup the original executables (e.g., `generalszh.exe` → `generalszh.exe.backup`)
173+
3. Copy the built executables from `build/docker/GeneralsMD/` to the game's `Data/` directory:
174+
- `generalszh.exe` - Main game
175+
- `WorldBuilderZH.exe` - Map editor
176+
- `W3DViewZH.exe` - Model viewer
177+
- `DebugWindow.dll` - Debug tools
178+
- `ParticleEditor.dll` - Particle editor
179+
180+
**Important**: Do NOT copy `mss32.dll` or `binkw32.dll` from the build directory - these are stub libraries for compilation only. Keep the original DLLs from your game installation.
181+
182+
### Running the Game on Linux
183+
184+
After installing the built executables to your game directory:
185+
186+
```bash
187+
# Set up Wine prefix (first time only)
188+
export WINEPREFIX=~/.wine-generals
189+
export WINEARCH=win32
190+
wineboot
191+
192+
# Run the game
193+
cd "/path/to/Generals Zero Hour/Data"
194+
wine generalszh.exe
195+
196+
# With quickstart (skip intro videos)
197+
wine generalszh.exe -quickstart
198+
```
199+
200+
**Requirements**:
201+
- Original game data files installed (from retail, Origin, or other legal source)
202+
- Wine 5.0+ recommended (Wine 10.0+ for best compatibility)
203+
- DirectX 8 compatible graphics (Wine handles translation)
204+
205+
#### Wine Configuration Tips
206+
207+
```bash
208+
# Use winetricks for better DirectX support
209+
winetricks d3dx9 vcrun6
210+
211+
# Use 32-bit Wine prefix (required for this game)
212+
WINEPREFIX=~/.wine32 WINEARCH=win32 wine generalszh.exe
213+
214+
# Enable DXVK for better performance (optional)
215+
# Install DXVK to your Wine prefix for DirectX to Vulkan translation
216+
```
217+
218+
## Build Presets
219+
220+
Available CMake presets:
221+
222+
| Preset | Description |
223+
|--------|-------------|
224+
| `vc6` | VC6 release build (retail compatible) |
225+
| `vc6-debug` | VC6 debug build |
226+
| `vc6-profile` | VC6 with profiling enabled |
227+
| `win32` | VS2022 release build |
228+
| `win32-debug` | VS2022 debug build |
229+
| `win32-vcpkg` | VS2022 with vcpkg dependencies |
230+
| `unix` | Unix experimental build (limited) |
231+
232+
List all presets:
233+
```bash
234+
cmake --list-presets
235+
```
236+
237+
## Build Targets
238+
239+
### Game Executables
240+
241+
| Target | Game | Description |
242+
|--------|------|-------------|
243+
| `generalszh` | Zero Hour | Main game executable |
244+
| `generalsv` | Generals | Main game executable |
245+
246+
### Tools
247+
248+
| Target | Description |
249+
|--------|-------------|
250+
| `generalszh_tools` | All Zero Hour tools |
251+
| `generalsv_tools` | All Generals tools |
252+
| `WorldBuilderZH` | Zero Hour map editor |
253+
| `WorldBuilderV` | Generals map editor |
254+
| `W3DViewZH` | Zero Hour 3D model viewer |
255+
| `W3DViewV` | Generals 3D model viewer |
256+
257+
Build specific target:
258+
```bash
259+
cmake --build build/vc6 --target generalszh
260+
```
261+
262+
## Build Options
263+
264+
CMake options that can be set during configuration:
265+
266+
| Option | Default | Description |
267+
|--------|---------|-------------|
268+
| `RTS_BUILD_ZEROHOUR` | ON | Build Zero Hour code |
269+
| `RTS_BUILD_GENERALS` | ON | Build Generals code |
270+
| `RTS_BUILD_OPTION_DEBUG` | OFF | Debug build (breaks retail compatibility) |
271+
| `RTS_BUILD_OPTION_PROFILE` | OFF | Enable profiling |
272+
| `RTS_BUILD_OPTION_FFMPEG` | OFF | Enable FFmpeg support |
273+
274+
Example:
275+
```bash
276+
cmake --preset vc6 -DRTS_BUILD_GENERALS=OFF # Zero Hour only
277+
```
278+
279+
## Troubleshooting
280+
281+
### Docker Build Issues
282+
283+
**"Permission denied" when running Docker**
284+
```bash
285+
# Add user to docker group
286+
sudo usermod -aG docker $USER
287+
# Log out and back in, or run:
288+
newgrp docker
289+
```
290+
291+
**Build fails with "out of memory"**
292+
- Increase Docker memory limit in Docker Desktop settings
293+
- Or build specific targets instead of all:
294+
```bash
295+
./scripts/build-linux.sh --target generalszh
296+
```
297+
298+
### Wine Runtime Issues
299+
300+
**"d3d8.dll not found"**
301+
- Install Wine's DirectX components:
302+
```bash
303+
winetricks d3dx9
304+
```
305+
306+
**Game crashes on startup**
307+
- Try using a 32-bit Wine prefix
308+
- Check game data files are properly installed
309+
- Verify registry paths point to correct game directory
310+
311+
### Windows Build Issues
312+
313+
**"CMake Error: CMake was unable to find a build program"**
314+
- Ensure Ninja is installed and in PATH
315+
- Or use Visual Studio generator: `cmake -G "Visual Studio 17 2022" -A Win32 ..`
316+
317+
**"Cannot find compiler"**
318+
- Open "Developer Command Prompt for VS 2022" before running CMake
319+
- Or ensure Visual Studio C++ tools are installed
320+
321+
### General Issues
322+
323+
**Replay compatibility test failures**
324+
- Use VC6 optimized build with `RTS_BUILD_OPTION_DEBUG=OFF`
325+
- Don't mix debug and release builds
326+
327+
**Missing dependencies**
328+
- Dependencies are fetched automatically via CMake FetchContent
329+
- Ensure internet connection during first build
330+
331+
## Additional Resources
332+
333+
- [CLAUDE.md](CLAUDE.md) - AI assistant instructions for this codebase
334+
- [.github/workflows/](.github/workflows/) - CI build configurations
335+
- [cmake/](cmake/) - CMake configuration modules

0 commit comments

Comments
 (0)