COMPILING.md

   1 # Compiling OpenTTD
   2
   3 ## Required/optional libraries
   4
   5 OpenTTD makes use of the following external libraries:
   6
   7 - (encouraged) zlib: (de)compressing of old (0.3.0-1.0.5) savegames, content downloads,
   8    heightmaps
   9 - (encouraged) liblzma: (de)compressing of savegames (1.1.0 and later)
  10 - (encouraged) libpng: making screenshots and loading heightmaps
  11 - (optional) liblzo2: (de)compressing of old (pre 0.3.0) savegames
  12
  13 For Linux, the following additional libraries are used (for non-dedicated only):
  14
  15 - libSDL2: hardware access (video, sound, mouse)
  16 - libfreetype: loading generic fonts and rendering them
  17 - libfontconfig: searching for fonts, resolving font names to actual fonts
  18 - libicu: handling of right-to-left scripts (e.g. Arabic and Persian) and
  19    natural sorting of strings
  20
  21 OpenTTD does not require any of the libraries to be present, but without
  22 liblzma you cannot open most recent savegames and without zlib you cannot
  23 open most older savegames or use the content downloading system.
  24
  25 ## Windows
  26
  27 You need Microsoft Visual Studio 2017 or more recent.
  28
  29 You can download the free Visual Studio Community Edition from Microsoft at
  30 https://visualstudio.microsoft.com/vs/community/.
  31
  32 OpenTTD needs the Platform SDK, if it isn't installed already. This can be
  33 done during installing Visual Studio, by selecting
  34 `Visual C++ MFC for x86 and x64` (and possibly
  35 `Visual C++ ATL for x86 and x64` depending on your version). If not, you
  36 can get download it as [MS Windows Platform SDK](https://developer.microsoft.com/en-US/windows/downloads/windows-10-sdk).
  37
  38 Install the SDK by following the instructions as given.
  39
  40 Dependencies for OpenTTD on Windows are handled via
  41 [vcpkg](https://github.com/Microsoft/vcpkg/). First you need to install vcpkg
  42 by following the `Quick Start` instructions of their
  43 [README](https://github.com/Microsoft/vcpkg/blob/master/README.md).
  44
  45 After this, you can install the dependencies OpenTTD needs. We advise to use
  46 the `static` versions, and OpenTTD currently needs the following dependencies:
  47
  48 - liblzma
  49 - libpng
  50 - lzo
  51 - zlib
  52
  53 To install both the x64 (64bit) and x86 (32bit) variants (though only one is necessary), you can use:
  54
  55 ```ps
  56 .\vcpkg install liblzma:x64-windows-static libpng:x64-windows-static lzo:x64-windows-static zlib:x64-windows-static
  57 .\vcpkg install liblzma:x86-windows-static libpng:x86-windows-static lzo:x86-windows-static zlib:x86-windows-static
  58 ```
  59
  60 You can open the folder (as a CMake project). CMake will be detected, and you can compile from there.
  61 If libraries are installed but not found, you need to set VCPKG_TARGET_TRIPLET in CMake parameters.
  62 For Visual Studio 2017 you also need to set CMAKE_TOOLCHAIN_FILE.
  63 (Typical values are shown in the MSVC project file command line example)
  64
  65 Alternatively, you can create a MSVC project file via CMake. For this
  66 either download CMake from https://cmake.org/download/ or use the version
  67 that comes with vcpkg. After that, you can run something similar to this:
  68
  69 ```powershell
  70 mkdir build
  71 cd build
  72 cmake.exe .. -G'Visual Studio 16 2019' -DCMAKE_TOOLCHAIN_FILE="<location of vcpkg>\vcpkg\scripts\buildsystems\vcpkg.cmake" -DVCPKG_TARGET_TRIPLET="x64-windows-static"
  73 ```
  74
  75 Change `<location of vcpkg>` to where you have installed vcpkg. After this
  76 in the build folder are MSVC project files. MSVC can rebuild the project
  77 files himself via the `ZERO_CHECK` project.
  78
  79 ## All other platforms
  80 Minimum required version of CMake is 3.9.
  81 By default this produces a Debug build with assertations enabled.
  82 This is a far slower build than release builds.
  83
  84 ```bash
  85 mkdir build
  86 cd build
  87 cmake ..
  88 make
  89 ```
  90
  91 For more information on how to use CMake (including how to make Release builds),
  92 we urge you to read [their excellent manual](https://cmake.org/cmake/help/latest/guide/user-interaction/index.html).
  93
  94 ## CMake Options
  95
  96 Via CMake, several options can be influenced to get different types of
  97 builds.
  98
  99 - `-DCMAKE_BUILD_TYPE=RelWithDebInfo`: build a release build. This is
 100    significant faster than a debug build, but has far less useful information
 101    in case of a crash.
 102 - `-DOPTION_DEDICATED=ON`: build OpenTTD without a GUI. Useful if you are
 103    running a headless server, as it requires less libraries to operate.
 104 - `-DOPTION_USE_ASSERTS=OFF`: disable asserts. Use with care, as assert
 105    statements capture early signs of trouble. Release builds have them
 106    disabled by default.
 107 - `-DOPTION_USE_THREADS=OFF`: disable the use of threads. This will block
 108    the interface in many places, and in general gives a worse experience of
 109    the game. Use with care.
 110 - `-DOPTION_TOOLS_ONLY=ON`: only build tools like `strgen`. Does not build
 111    the game itself. Useful for cross-compiling.
 112
 113 ## Supported compilers
 114
 115 Every compiler that is supported by CMake and supports C++17, should be
 116 able to compile OpenTTD. As the exact list of compilers changes constantly,
 117 we refer to the compiler manual to see if it supports C++17, and to CMake
 118 to see if it supports your compiler.
 119
 120 ## Compilation of base sets
 121
 122 To recompile the extra graphics needed to play with the original Transport
 123 Tycoon Deluxe graphics you need GRFCodec (which includes NFORenum) as well.
 124 GRFCodec can be found at
 125 https://www.openttd.org/downloads/grfcodec-releases/latest.html.
 126
 127 Having GRFCodec installed can cause regeneration of the `.grf` files, which
 128 are written in the source directory. This can leave your repository in a
 129 modified state, as different GRFCodec versions can cause binary differences
 130 in the resulting `.grf` files. Also translations might have been added for
 131 the base sets which are not yet included in the base set information files.
 132 To avoid this behaviour, disable GRFCodec (and NFORenum) in CMake cache
 133 (`GRFCODEC_EXECUTABLE` and `NFORENUM_EXECUTABLE`).
 134
 135 ## Developers settings
 136
 137 You can control some flags directly via `CXXFLAGS` (any combination
 138 of these flags will work fine too):
 139
 140 - `-DRANDOM_DEBUG`: this helps with debugging desyncs.
 141 - `-fno-inline`: this avoids creating inline functions; this can make
 142   debugging a lot easier.
 143 - `-O0`: this disables all optimizations; this can make debugging a
 144   lot easier.
 145 - `-p`: this enables profiling.
 146
 147 Always use a clean buildfolder if you changing `CXXFLAGS`, as this
 148 value is otherwise cached. Example use:
 149
 150 `CXXFLAGS="-fno-inline" cmake ..`