COMPILING.txt

Table of Contents
=================
1 How to compile Pioneer
  1.1 Linux - 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


1 How to compile Pioneer
========================

Pioneer is known to build on the following platforms and build systems:

Linux: CMake with GCC 4.9+ or Clang 6+
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.freenode.net. 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 >= 3.2
    libsdl2-dev
    libsdl2-image-dev

   If your platform doesn't have assimp 3.2, 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.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 solution from /win32/vc2019/pioneer.sln.

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 Sudio 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