Documentation/technical/build-systems.txt

   1 = Build Systems
   2
   3 The build system is the primary way for both developers and system integrators
   4 to interact with the Git project. As such, being easy to use and extend for
   5 those who are not directly developing Git itself is just as important as other
   6 requirements we have on any potential build system.
   7
   8 This document outlines the different requirements that we have for the build
   9 system and then compares available build systems using these criteria.
  10
  11 == Requirements
  12
  13 The following subsections present a list of requirements that we have for any
  14 potential build system. Sections are sorted by decreasing priority.
  15
  16 === Platform support
  17
  18 The build system must have support for all of our platforms that we continually
  19 test against as outlined by our platform support policy. These platforms are:
  20
  21   - Linux
  22   - Windows
  23   - macOS
  24
  25 Furthermore, the build system should have support for the following platforms
  26 that generally have somebody running test pipelines against regularly:
  27
  28   - AIX
  29   - FreeBSD
  30   - NetBSD
  31   - NonStop
  32   - OpenBSD
  33
  34 The platforms which must be supported by the tool should be aligned with our
  35 [platform support policy](platform-support.txt).
  36
  37 === Auto-detection of supported features
  38
  39 The build system must support auto-detection of features which are or aren't
  40 available on the current platform. Platform maintainers should not be required
  41 to manually configure the complete build.
  42
  43 Auto-detection of the following items is considered to be important:
  44
  45   - Check for the existence of headers.
  46   - Check for the existence of libraries.
  47   - Check for the existence of exectuables.
  48   - Check for the runtime behavior of specific functions.
  49   - Check for specific link order requirements when multiple libraries are
  50     involved.
  51
  52 === Ease of use
  53
  54 The build system should be both easy to use and easy to extend. While this is
  55 naturally a subjective metric it is likely not controversial to say that some
  56 build systems are considerably harder to use than others.
  57
  58 === IDE support
  59
  60 The build system should integrate with well-known IDEs. Well-known IDEs include:
  61
  62   - Microsoft Visual Studio
  63   - Visual Studio Code
  64   - Xcode
  65
  66 There are four levels of support:
  67
  68   - Native integration into the IDE.
  69   - Integration into the IDE via a plugin.
  70   - Integration into the IDE via generating a project description with the build
  71     system.
  72   - No integration.
  73
  74 Native integration is preferable, but integration via either a plugin or by
  75 generating a project description via the build system are considered feasible
  76 alternatives.
  77
  78 Another important distinction is the level of integration. There are two
  79 features that one generally wants to have:
  80
  81   - Integration of build targets.
  82   - Automatic setup of features like code completion with detected build
  83     dependencies.
  84
  85 The first bullet point is the bare minimum, but is not sufficient to be
  86 considered proper integration.
  87
  88 === Out-of-tree builds
  89
  90 The build system should support out-of-tree builds. Out-of-tree builds allow a
  91 developer to configure multiple different build directories with different
  92 configuration, e.g. one "debug" build and one "release" build.
  93
  94 === Cross-platform builds
  95
  96 The build system should support cross-platform builds, e.g. building for arm on
  97 an x86-64 host.
  98
  99 === Language support
 100
 101 The following languages and toolchains are of relevance and should be supported
 102 by the build system:
 103
 104   - C: the primary compiled language used by Git, must be supported. Relevant
 105     toolchains are GCC, Clang and MSVC.
 106   - Rust: candidate as a second compiled lanugage, should be supported. Relevant
 107     toolchains is the LLVM-based rustc.
 108
 109 Built-in support for the respective languages is preferred over support that
 110 needs to be wired up manually to avoid unnecessary complexity. Native support
 111 includes the following features:
 112
 113   - Compiling objects.
 114   - Dependency tracking.
 115   - Detection of available features.
 116   - Discovery of relevant toolchains.
 117   - Linking libraries and executables.
 118   - Templating placeholders in scripts.
 119
 120 === Test integration
 121
 122 It should be possible to integrate tests into the build system such that it is
 123 possible to build and test Git within the build system. Features which are nice
 124 to have:
 125
 126   - Track build-time dependencies for respective tests. Unit tests have
 127     different requirements than integration tests.
 128   - Allow filtering of which tests to run.
 129   - Allow running tests such that utilities like `test_pause` or `debug` work.
 130
 131 == Comparison
 132
 133 The following list of build systems are considered:
 134
 135 - GNU Make
 136 - autoconf
 137 - CMake
 138 - Meson
 139
 140 === GNU Make
 141
 142 - Platform support: ubitquitous on all platforms, but not well-integrated into Windows.
 143 - Auto-detection: no built-in support for auto-detection of features.
 144 - Ease of use: easy to use, but discovering available options is hard. Makefile
 145   rules can quickly get out of hand once reaching a certain scope.
 146 - IDE support: execution of Makefile targets is supported by many IDEs
 147 - Out-of-tree builds: supported in theory, not wired up in practice.
 148 - Cross-platform builds: supported in theory, not wired up in practice.
 149 - Language support:
 150   - C: Limited built-in support, many parts need to be wired up manually.
 151   - Rust: No built-in support, needs to be wired up manually.
 152 - Test integration: partially supported, many parts need to be wired up
 153   manually.
 154
 155 === autoconf
 156
 157 - Platform support: ubiquitous on all platforms, but not well-integrated into Windows.
 158 - Auto-detection: supported.
 159 - Ease of use: easy to use, discovering available options is comparatively
 160   easy. The autoconf syntax is prohibitively hard to extend though due to its
 161   complex set of interacting files and the hard-to-understand M4 language.
 162 - IDE support: no integration into IDEs at generation time. The generated
 163   Makefiles have the same level of support as GNU Make.
 164 - Out-of-tree builds: supported in theory, not wired up in practice.
 165 - Cross-platform builds: supported.
 166 - Language support:
 167   - C: Limited built-in support, many parts need to be wired up manually.
 168   - Rust: No built-in support, needs to be wired up manually.
 169 - Test integration: partially supported, many parts need to be wired up
 170   manually.
 171
 172 === CMake
 173
 174 - Platform support: not as extensive as GNU Make or autoconf, but all major
 175   platforms are supported.
 176   - AIX
 177   - Cygwin
 178   - FreeBSD
 179   - Linux
 180   - OpenBSD
 181   - Solaris
 182   - Windows
 183   - macOS
 184 - Ease of use: easy to use, discovering available options is not always
 185   trivial. The scripting language used by CMake is somewhat cumbersome to use,
 186   but extending CMake build instructions is doable.
 187 - IDE support: natively integrated into Microsoft Visual Studio. Can generate
 188   project descriptions for Xcode. An extension is available for Visual Studio
 189   Code. Many other IDEs have plugins for CMake.
 190 - Out-of-tree builds: supported.
 191 - Cross-platform builds: supported.
 192 - Language support:
 193   - C: Supported for GCC, Clang, MSVC and other toolchains.
 194   - Rust: No built-in support, needs to be wired up manually.
 195 - Test integration: supported, even though test dependencies are a bit
 196   cumbersome to use via "test fixtures". Interactive test runs are not
 197   supported.
 198
 199 === Meson
 200
 201 - Platform: not as extensive as GNU Make or autoconf, but all major platforms
 202   and some smaller ones are supported.
 203   - AIX
 204   - Cygwin
 205   - DragonflyBSD
 206   - FreeBSD
 207   - Haiku
 208   - Linux
 209   - NetBSD
 210   - OpenBSD
 211   - Solaris
 212   - Windows
 213   - macOS
 214 - Ease of use: easy to use, discovering available options is easy. The
 215   scripting language is straight-forward to use.
 216 - IDE support: Supports generating build instructions for Xcode and Microsoft
 217   Visual Studio, a plugin exists for Visual Studio Code.
 218 - Out-of-tree builds: supported.
 219 - Cross-platform builds: supported.
 220 - Language support:
 221   - C: Supported for GCC, Clang, MSVC and other toolchains.
 222   - Rust: Supported for rustc.
 223 - Test integration: supported. Interactive tests are supported starting with
 224   Meson 1.5.0 via the `--interactive` flag.