Skip to content

Commit 00ab97b

Browse files
pks-tgitster
pks-t
authored and
gitster
committed
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 <[email protected]> Signed-off-by: Junio C Hamano <[email protected]>
1 parent 5ee8927 commit 00ab97b

File tree

2 files changed

+225
-0
lines changed

2 files changed

+225
-0
lines changed

‎Documentation/Makefile

+1
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,7 @@ TECH_DOCS += MyFirstObjectWalk
113113
TECH_DOCS += SubmittingPatches
114114
TECH_DOCS += ToolsForGit
115115
TECH_DOCS += technical/bitmap-format
116+
TECH_DOCS += technical/build-systems
116117
TECH_DOCS += technical/bundle-uri
117118
TECH_DOCS += technical/hash-function-transition
118119
TECH_DOCS += technical/long-running-process-protocol

‎Documentation/technical/build-systems.txt

+224
Original file line numberDiff line numberDiff line change
@@ -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.

0 commit comments

Comments
 (0)