README.compile

PREREQUISITES
=============

To build SpaceXpanse from its sources you need a C++ compiler able to create Windows binaries.
SpaceXpanse has been built successfully with Visual Studio 2019 Community
https://visualstudio.microsoft.com/downloads/

VS 2019 also has built-in support for CMake. If you use a different version or want to
configure the SpaceXpanse build separately, you also need to install CMake.
https://cmake.org/download/

If you want to build the SpaceXpanse documentation, you need a tool that can compile
OpenDocument Text files (ODT) into PDF files. By default, the SpaceXpanse build is configured to
use LibreOffice for this, but Microsoft Word or other tools may also work, if you
reconfigure the build parameters accordingly.
https://www.libreoffice.org/download/download/

To also build the SpaceXpanse Technical Notes, you need LaTeX. Multiple LaTeX distros for
Windows are available, for example MiKTeX.
https://miktex.org/download

To build the code-level documentation, you need doxygen.
https://www.doxygen.nl/index.html


BUILDING SPACEXPANSE
================
After cloning the SpaceXpanse Git repository, you can either

- Load the SpaceXpanse download directory as a local directory into VS2019 or later.
  
- Select Project | CMake Settings for SpaceXpanse
  to check the build settings and make sure that all required components are found
  
- Select Project | Configure SpaceXpanse
  This will configure the CMake build files.

- Select Build | Build All
  to build SpaceXpanse and all its components.
  
Or, run CMake externally:

- Create a build directory separate from the SpaceXpanse source directory.

- Run CMake, and select the correct source and build directories.

- Select Configure, and pick the Win32 platform

- Edit options as required.

- Select Generate, then close CMake

- This should have generated a solution file (SpaceXpanse.sln) in the build directory.
  Load this into Visual Studio, and Build All.
  
  
PLANETARY TEXTURES
==================
The SpaceXpanse git repository does not include the planetary texture files for most
celestial bodies. You need to install these separately (e.g. by installing SpaceXpanse
2016 and optionally downloading high-res texture packs from the SpaceXpanse website).
During CMake configuration, specify the location of the texture files in the
SPACEXPANSE_PLANET_TEXTURE_INSTALL_DIR entry. For example, if SpaceXpanse 2016 is installed
in c:\spacexpanse2016, the texture directory would be c:\spacexpanse2016\Textures.

Alternatively, you can set the planetary texture directory after building
SpaceXpanse by setting the PlanetTexDir entry in SpaceXpanse.cfg.


TROUBLESHOOTING
===============
* If you get errors during build, in particular when building documentation (pdf from
odt or latex sources), try disabling multithreaded build support (limit to a single
thread). Some of the document converters/compilers you are using may not be
thread-safe. 

* CMake errors during build (cannot find system include files etc.). This may happen
when using the Ninja generator. You may need to install and configure vcpkg to allow
Ninja to find the VS2019 toolset (https://github.com/microsoft/vcpkg).

* LaTeX build components not found: If using MiKTeX, make sure you install it for all
users instead of locally for a single user. CMake won't automatically find the 
single-user installation, so you would have to specify the paths to all components
manually.

* Problems launching SpaceXpanse from the build directory: If you use the VS2019
generator, it puts binaries in configuration-dependent subdirectories (Debug/Release).
This means that SpaceXpanse may not find plugin DLLs. You need to run SpaceXpanse from
the install directory. The Ninja generator separates the Debug and Release builds
at the top level and doesn't have that problem.