Skip to content

Commit 998ca3b

Browse files
alkurbatovalkurbatov
committed
docs: Refine build instructions
- Drop rarely used usecases. - Split the prerequisites per platform. - Introduce separate troubleshooting section. - Many small syntax improvements. Signed-off-by: Alexander Kurbatov <[email protected]>
1 parent e4e7baf commit 998ca3b

File tree

1 file changed

+96
-69
lines changed

1 file changed

+96
-69
lines changed

‎docs/building.md‎

Lines changed: 96 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -1,108 +1,126 @@
11
# Build instructions
22

3-
## Prerequisites
3+
> :construction: This project requires a compiler with C++17 support.
4+
5+
<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->
6+
**Table of Contents**
7+
8+
- [Build instructions](#build-instructions)
9+
- [Windows](#windows)
10+
- [macOS](#macos)
11+
- [Linux](#linux)
12+
- [Compilation options](#compilation-options)
13+
- [Game client version](#game-client-version)
14+
- [Troubleshooting](#troubleshooting)
15+
- [Build freezes (Linux or macOS)](#build-freezes-linux-or-macos)
16+
- [WSL2 Support](#wsl2-support)
17+
- [Requirements](#requirements)
18+
- [Building](#building)
19+
- [Downstream Projects](#downstream-projects)
20+
21+
<!-- markdown-toc end -->
22+
23+
## Windows
424

525
For building for Windows under WSL2, see [WSL2 Support](#wsl2-support).
626

7-
1. Download and install [CMake](https://cmake.org/download/).
27+
1. Install [CMake](https://cmake.org/download/).
828

9-
2. A compiler with C++17 support.
29+
1. Download and install Visual Studio ([2017](https://www.visualstudio.com/downloads/) or newer).
1030

11-
3. Windows: Download and install Visual Studio ([2017](https://www.visualstudio.com/downloads/) or newer).
31+
1. Clone the project.
1232

13-
4. Linux: Install 'gcc-c++'.
33+
```bat
34+
git clone [email protected]:cpp-sc2/cpp-sc2.git
35+
```
1436

15-
5. Linux: Install the 'make' utility.
37+
1. Enter the working directory.
1638

17-
6. OS X: Install XCode.
39+
```bat
40+
cd cpp-sc2
41+
```
1842

19-
7. OS X: Install XCode command-line tools.
43+
1. Create Visual Studio project files.
44+
E.g. for Visual Studio 2022:
2045

21-
## Windows (Visual Studio)
22-
```bat
23-
:: Clone the project.
24-
$ git clone [email protected]:cpp-sc2/cpp-sc2.git
46+
```bat
47+
cmake -B build -G "Visual Studio 17 2022"
48+
```
2549

26-
:: Enter the working directory.
27-
$ cd cpp-sc2
50+
1. Build the project using Visual Studio.
2851

29-
:: Create Visual Studio project files.
30-
:: E.g. for Visual Studio 2022:
31-
$ cmake -B build -G "Visual Studio 17 2022"
52+
```bat
53+
start build\cpp-sc2.sln
54+
```
3255

33-
:: Build the project using Visual Studio.
34-
$ start build\cpp-sc2.sln
35-
```
56+
## macOS
3657

37-
## Windows (cmdline)
38-
```bat
39-
:: Clone the project.
40-
$ git clone [email protected]:cpp-sc2/cpp-sc2.git
58+
1. Install [CMake](https://cmake.org/download/).
4159

42-
:: Enter the working directory.
43-
$ cd cpp-sc2
60+
1. Install XCode.
4461

45-
:: Configure the project.
46-
$ cmake -B build
62+
1. Install XCode command-line tools.
4763

48-
:: Build the project.
49-
$ cmake --build build --parallel
50-
```
64+
1. Clone the project.
5165

52-
## Mac (Xcode)
53-
```bash
54-
# Clone the project.
55-
$ git clone [email protected]:cpp-sc2/cpp-sc2.git
66+
```bash
67+
git clone [email protected]:cpp-sc2/cpp-sc2.git
68+
```
5669

57-
# Enter the working directory.
58-
$ cd cpp-sc2
70+
1. Enter the working directory.
5971

60-
# Create Xcode project files.
61-
$ cmake -B build -G Xcode
72+
```bash
73+
cd cpp-sc2
74+
```
6275

63-
# Build the project using Xcode.
64-
$ open build/cpp-sc2.xcodeproj
65-
```
76+
1. Create makefiles.
6677

67-
## Mac (cmdline)
68-
```bash
69-
# Clone the project.
70-
$ git clone [email protected]:cpp-sc2/cpp-sc2.git
78+
```bash
79+
cmake -B build
80+
```
7181

72-
# Enter the working directory.
73-
$ cd cpp-sc2
82+
1. Build the project.
7483

75-
# Create makefiles.
76-
$ cmake -B build
84+
```bash
85+
cmake --build build --parallel $(nproc)
86+
```
7787

78-
# Build the project.
79-
$ cmake --build build --parallel $(nproc)
88+
## Linux
8089

81-
# If building freezes in above step, decrease nproc to 1 or more, e.g.:
82-
cmake --build build --parallel $(nproc --ignore=1)
83-
```
90+
1. Install [CMake](https://cmake.org/download/).
8491

85-
## Linux (cmdline)
86-
```bash
87-
# Clone the project.
88-
$ git clone [email protected]:cpp-sc2/cpp-sc2.git
92+
1. Install `gcc-c++`.
8993

90-
# Enter the working directory.
91-
$ cd cpp-sc2
94+
1. Install the `make` utility.
9295

93-
# Create makefiles.
94-
$ cmake -B build
96+
1. Clone the project.
9597

96-
# Build the project.
97-
$ cmake --build build --parallel $(nproc)
98+
```bash
99+
git clone [email protected]:cpp-sc2/cpp-sc2.git
100+
```
98101

99-
# If building freezes in above step, decrease nproc to 1 or more, e.g.:
100-
cmake --build build --parallel $(nproc --ignore=1)
101-
```
102+
1. Enter the working directory.
103+
104+
```bash
105+
cd cpp-sc2
106+
```
107+
108+
1. Create makefiles.
109+
110+
```bash
111+
cmake -B build
112+
```
113+
114+
1. Build the project.
115+
116+
``` bash
117+
cmake --build build --parallel $(nproc)
118+
```
102119

103120
## Compilation options
104121

105122
### Game client version
123+
106124
By default, the API assumes the latest version of the game client. The assumed version can be found in cmake's output, e.g.:
107125
```bash
108126
$ cmake ../ | grep 'SC2 version'
@@ -116,6 +134,16 @@ always behind the Windows version. It is possible by specifying the game version
116134
$ cmake -DSC2_VERSION=4.10.0 ../
117135
```
118136

137+
## Troubleshooting
138+
139+
### Build freezes (Linux or macOS)
140+
141+
If project compilation freezes, decrease nproc to 1 or more, e.g.:
142+
143+
``` bash
144+
$ cmake --build build --parallel $(nproc --ignore=1)
145+
```
146+
119147
## WSL2 Support
120148

121149
Thanks to interoperability between the [Windows and Linux file systems](https://docs.microsoft.com/en-us/windows/wsl/filesystems) in WSL2, it is possible to cross compile `cpp-sc2` under WSL2 for Windows and launch the executables from the WSL2 context using the Windows Starcraft II installation. Current implementation may not support custom installs of Starcraft II (e.g. to an external hard drive).
@@ -175,7 +203,6 @@ When including `cpp-sc2` as a dependency (whether as a git submodule, or using C
175203
2. Set `CMAKE_TOOLCHAIN_FILE` as the path to the toolchain file, and the `WSL2_CROSS_COMPILE` option to `ON` when cross compiling:
176204

177205
```bash
178-
# From the command line
179206
$ cmake -B build \
180207
-DCMAKE_TOOLCHAIN_FILE=/path/to/toolchain/file \
181208
-DWSL2_CROSS_COMPILE=ON

0 commit comments

Comments
 (0)