COMPILING.md

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