Documentation: add comparison of build systems
We're contemplating whether to eventually replace our build systems with a build system that is easier to use. Add a comparison of build systems to our technical documentation as a baseline for discussion. Signed-off-by: Patrick Steinhardt <ps@pks.im> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Patrick Steinhardt committed
Dec 6, 2024 at 14:24 UTC
00ab97b1bc07206be4d05547fe44bfd7afd607dc
2 files changed
+225
Documentation/Makefile
+1
@@ -113,6 +113,7 @@ TECH_DOCS += MyFirstObjectWalk
113
TECH_DOCS += SubmittingPatches
114
TECH_DOCS += ToolsForGit
115
TECH_DOCS += technical/bitmap-format
116
+TECH_DOCS += technical/build-systems
117
TECH_DOCS += technical/bundle-uri
118
TECH_DOCS += technical/hash-function-transition
119
TECH_DOCS += technical/long-running-process-protocol
Documentation/technical/build-systems.txt
new
+224
@@ -0,0 +1,224 @@
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.