-
-
Notifications
You must be signed in to change notification settings - Fork 374
/
COMPILING.txt
379 lines (256 loc) · 12.8 KB
/
COMPILING.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
Table of Contents
=================
1 How to compile Pioneer
1.1 Linux - CMake
1.1a Linux - VSCode + CMake
1.2 Windows - MSVC
1.3 Windows - CMake and MSYS2 (and MinGW-w64)
1.4 Windows - CMake and MSVC
1.5 OS X - Homebrew
1.6 OS X - CMake and XCode
2 pioneer-thirdparty
2.1 Linux - Autotools
2.2 Windows - MSVC
2.3 Windows - Autotools (Linux cross-compile)
2.4 OSX
3 Building documentation
3.1 Lua API - Natural Docs
3.2 C++ source - Doxygen
4 Faster startup
4.1 precompile models
5 Installing Pioneer
6 For Packagers
7 Build Flags
1 How to compile Pioneer
========================
Pioneer is known to build on the following platforms and build systems:
Linux: CMake with GCC 9+ or Clang 7+
Windows: Microsoft Visual C++ 2019 (Community or Pro)
CMake with MSYS2 (and MinGW-w64)
OS X: XCode 4 or Homebrew or CMake
There is an additional repository called pioneer-thirdparty that contains
various files that may assist with building. This is intended for Windows
builds and is otherwise not actively maintained. Read the section below for
details on using it for your platform.
If you're having trouble compiling, please ask in #pioneer on
irc.libera.chat. Most users are available to answer during CET daytime, but
questions are welcome anytime.
1.1 Linux - CMake
---------
1. Install the following libraries (with development headers) for your system.
If your system is not Debian/Ubuntu based, they may have different names.
Debian/Ubuntu
-------------
g++
cmake
mesa-common-dev
libfreeimage-dev
libglew-dev
libfreetype6-dev
libsigc++-2.0
libsigc++-2.0-dev
libvorbis-dev
libassimp-dev >= 5.0.1
libsdl2-dev
libsdl2-image-dev
If your platform doesn't have assimp 5, you'll need to build it from
source. It's available in pioneer-thirdparty, see below.
2. Run './bootstrap' to generate CMake build files in the 'build' folder.
For advanced users, this command passes any additional arguments to the
CMake process.
3. Run 'make -C build -jX', where X is the number of CPU cores you have. If in
doubt, 4 is a good default. This will compile the pioneer executable.
4. Run `./pioneer` to start the game!
1.1a Linux - VSCode + CMake
---------
1. Install the required libraries as for '1.1 Linux - CMake'.
You'll also need to install the Ninja build generator. This is usually
available as ninja or ninja-build in most distributions' package archives.
You'll want to install several VSCode extensions for best results:
CMake Tools (ms-vscode.cmake-tools)
C/C++ (ms-vscode.cpptools)
clangd (llvm-vs-code-extensions.vscode-clangd)
Code LLDB (vadimcn.vscode-lldb)
Lua (sumneko.lua)
Git Graph (mhutchie.git-graph)
Of these extensions, only CMake Tools is required to compile the game from
within VSCode. All other extensions help to improve the development process
if you intend on making changes to the game's files.
2. Copy ./pioneer-default.code-workspace to ./pioneer.code-workspace and
open it. This provides a quick-start workspace setup with useful workflow
defaults pre-configured. This file is ignored by Git and you can configure
the workspace to your liking from there.
3. From the bottom bar, select a configure preset for your platform. 'Release'
is recommended unless you're in the process of debugging a specific issue.
This will generate CMake files in the 'build/' folder.
4. Click the build button on the bottom toolbar, or execute the Run Build Task
command from the command pallette (Ctrl+Shift+P), selecting 'Build Pioneer'.
If all goes well, Pioneer should successfully compile.
5. Click the triangle ("launch") button in the bottom toolbar and select
'pioneer' as the active launch target.
1.2 Windows - MSVC
------------------
1. Get both the pioneer and the pioneer-thirdparty repositories and keep them
in a directory side by side. Don't rename pioneer-thirdparty because the
relative path to it is included in the project files.
2. Open the pioneer folder which should open as a CMake project
see https://learn.microsoft.com/en-us/cpp/build/cmake-projects-in-visual-studio?view=msvc-160
3. Build and run the project or solution. Note: the default is to build debug
version, which is what you want if developing, but release gives an executable
optimized for performance.
1.3 Windows - CMake and MSYS2 (and MinGW-w64)
---------------------------------------------
1. Install MSYS2 (https://www.msys2.org).
2. Install MinGW-w64 from MSYS2. Use the mingw64 shell.
3. Install the dependencies (similar to dependencies of Linux) using the
'pacman' command. Note: you should install the dependencies from the
MinGW-w64 repository.
4. Additionally, install GLEW.
5. Goto the root directory of Pioneer, run 'mkdir build; cd build'. Then run
'cmake .. -G "MinGW Makefiles" -DCMAKE_SH="CMAKE_SH-NOTFOUND" -DUSE_SYSTEM_LIBGLEW=ON'
Alternatively, these command can be run using the ./bootstrap file with
additional arguments.
6. Compile Pioneer by running 'mingw32-make.exe'.
7. Now, you can go back to the root directory of Pioneer and do './build/pioneer.exe'
to play the game.
1.4 Windows - CMake and MSVC
----------------------------
1. Get both the pioneer and the pioneer-thirdparty repositories and keep them
in a directory side by side. Don't rename pioneer-thirdparty because the
relative path to it is included in the project files.
2. Open Visual Studio 2019 and do not open a solution or project ('Continue without code').
3. Go to File->Open->CMake and select pioneer/CMakeLists.txt
4. Select the appropriate build type (x64-Debug or x64-Release) under the configuration
drop down on the main toolbar, located next to the run button.
5. Build the project (Build->Build All).
6. Pioneer can be run and debugged by selecting 'pioneer.exe' on the
'Select Startup Item' menu (click the small down arrow on the run button), and then clicking run.
Be sure to select 'pioneer.exe' and not 'pioneer.exe (install)'.
1.5 OS X - Homebrew
-------------------
1. Install Homebrew package manager (http://brew.sh/) if you don't have one yet.
2. Build and install pioneer. Required dependencies will be installed together.
brew install pioneer
If you want master branch from GitHub, add '--HEAD' option.
brew install --HEAD pioneer
1.6 OS X - CMake and XCode
--------------------------
THESE INSTRUCTIONS ARE APPROXIMATE AND ARE UNTESTED; PLEASE SUBMIT CORRECTIONS!
1. Install XCode (free download from Apple) as in the 'OS X Autotools'
instructions.
2. Install required libraries, as in the 'OS X Autotools' instructions.
3. Install CMake, from https://cmake.org/download/, or via MacPorts.
4. Create a new directory for the build files. Use the CMake GUI to generate
an XCode project in the new directory.
5. Open the project in XCode and build 'pioneer'.
2 pioneer-thirdparty
====================
The pioneer-thirdparty repository contains:
- source for dependencies that may be difficult to obtain or build
- pre-built dependencies for MSVC targets
To get it, clone git://github.com/pioneerspacesim/pioneer-thirdparty.git.
2.1 Linux - Autotools and CMake
---------------------
1. Clone the thirdparty repo to './pioneer-thirdparty' inside the pioneer
repository and 'cd' into it.
2. Run 'autoconf' to generate configuration files, then run './configure' to
configure the build.
3. Run make <package> to compile and prepare the named package for use with
Pioneer, or just run make without a target to build everything.
4. From the pioneer directory, run `./bootstrap thirdparty` to generate a CMake
configuration that builds with the thirdparty libraries.
5. Build pioneer as described in section 1.1.
2.2 Windows - MSVC
------------------
1. After cloning the repo, move it to a folder called "pioneer-thirdparty"
alongside your "pioneer" folder.
2.3 Windows - Autotools (Linux cross-compile)
---------------------------------------------
1. After cloning the repo, run autoconf to generate 'configure'.
2. Run ./configure --with-mxe=/path/to/mxe to configure the build.
3. Run make <package> to compile and prepare the named package for use with
Pioneer, or just run make alone to build everything.
2.4 OSX
-------
- pioneer-thirdparty currently not required.
3 Building documentation
========================
This section describes how to build html-documentation which is stored on disk
for the local pioneer source tree.
3.1 Lua API - Natural Docs
--------------------------
Pioneer is extensible through the Lua scripting language. It is used for
modules such as missions and BBS interaction. See the pioneer wiki for further
details. For up-to-date documentation one can build it locally from the
pioneer source
0. Install dependencies: naturaldocs (v 1.x)
1. Run make -C build codedoc
2. The html documentation can be found in the codedoc/ folder
3.2 C++ source - Doxygen
------------------------
To build html-documentation of the pioneer C++ source, doxygen needs to be
installed, as well as the graphviz package, from where dot is used for
visualizing inheritance as graphs. To enable LaTeX output, set GENERATE_LATEX
= YES in the configuration file doxygen/Doxyfile. Same goes for xml, man, rtf.
0. Install dependencies: doxygen and graphviz
1. Run doxygen from the doxygen/ folder.
2. The html documentation will be available from doxygen/html/index.html
4 Faster startup
================
4.1 Precompile model files
--------------------------
Long startup times for pioneer this can be alleviated by precompiling all
models into *.sgm files. This uses the modelcompiler, invoked through CMake.
From the pioneer root directory the following will batch compile all models:
1. make -C build/ build-data
5 Installing Pioneer
====================
Pioneer is designed to be able to run in "portable mode", where the program
is located next to the data directory and does not use system files.
If you would like to install Pioneer in a system-wide fashion, please refer
to the release steps used in the Github Actions workflow files for details
regarding the commands used on each platform to generate release archives.
If you are creating an installed version of Pioneer, you will need to
ensure that you precompile the model files as described in 4.1 before
running the install step, as installed versions do not package the model
source files and depend on the *.sgm files for efficient loading of assets.
6 For Packagers
===============
Pioneer provides a set of CMake Presets for use when packaging the game for
distribution by third party packagers. These presets are found in
scripts/CMakeBuildPresetsCI.json, and when used should be copied to
./CMakeUserPresets.json (which is not tracked by Git) so they can be found by
CMake's --preset command-line option.
Distribution packagers that build Pioneer without Git repository information
available (or apply patches in a way that changes the git commit hash) are
encouraged to set the PROJECT_VERSION_INFO CMake variable to a value that
clearly identifies the source version the package is built from. This helps
when triaging issue reports from unstable / Git builds specifically, but also
to identify any third-party changes or patches which might contribute to a bug
report.
7 Build Flags
=============
This section attempts to non-exhaustively cover some of the important levers
that can be tweaked when building Pioneer by passing various CMake arguments.
- PROFILER_ENABLED=1 (default 0): Include profiling facilities for taking
detailed measurements of the game's performance. If enabled, will write
profile traces to the user://profiler/ folder on each run.
- USE_SSE42=1 (default 1): Enable optimizations targeting the SSE4.2
instruction set extension (widely available since 2013).
The compiled executable will require a CPU that supports the instruction set
to run - Pioneer does not officially target pre-SSE4 CPUs as part of the
minimum spec, but you may try turning this option off if desired.
- USE_AVX2=1 (default 0): Enable optimizations targeting the AVX2
instruction set extension (widely available since 2015).
The compiled executable will require a CPU that supports the AVX2 instruction
set to run. Pioneer does not target AVX2 as a minimum requirement, but
optimizations may be introduced which take advantage of this build
configuration to improve the game's performance on newer CPUs which support
this instruction set.
- USE_TIME_TRACE=1 (default 0): Requires the Clang compiler. Dumps information
about compilation times (using -ftime-trace) to profile and optimize the
compile time of the codebase.
- REMOTE_LUA_REPL=1 (default 0): Enable a remote TCP-based REPL
(read-evaluate-print-loop) endpoint to interactively run external Lua
commands. This option is primarily intended for developers and should not
be enabled in shipping builds.