COMPILING.txt

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.