COMPILING.md

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