@@ -113,6 +113,7 @@ TECH_DOCS += MyFirstObjectWalk
TECH_DOCS += SubmittingPatches
TECH_DOCS += ToolsForGit
TECH_DOCS += technical/bitmap-format
+TECH_DOCS += technical/build-systems
TECH_DOCS += technical/bundle-uri
TECH_DOCS += technical/hash-function-transition
TECH_DOCS += technical/long-running-process-protocol
new file mode 100644
@@ -0,0 +1,224 @@
+= Build Systems
+
+The build system is the primary way for both developers and system integrators
+to interact with the Git project. As such, being easy to use and extend for
+those who are not directly developing Git itself is just as important as other
+requirements we have on any potential build system.
+
+This document outlines the different requirements that we have for the build
+system and then compares available build systems using these criteria.
+
+== Requirements
+
+The following subsections present a list of requirements that we have for any
+potential build system. Sections are sorted by decreasing priority.
+
+=== Platform support
+
+The build system must have support for all of our platforms that we continually
+test against as outlined by our platform support policy. These platforms are:
+
+ - Linux
+ - Windows
+ - macOS
+
+Furthermore, the build system should have support for the following platforms
+that generally have somebody running test pipelines against regularly:
+
+ - AIX
+ - FreeBSD
+ - NetBSD
+ - NonStop
+ - OpenBSD
+
+The platforms which must be supported by the tool should be aligned with our
+[platform support policy](platform-support.txt).
+
+=== Auto-detection of supported features
+
+The build system must support auto-detection of features which are or aren't
+available on the current platform. Platform maintainers should not be required
+to manually configure the complete build.
+
+Auto-detection of the following items is considered to be important:
+
+ - Check for the existence of headers.
+ - Check for the existence of libraries.
+ - Check for the existence of exectuables.
+ - Check for the runtime behavior of specific functions.
+ - Check for specific link order requirements when multiple libraries are
+ involved.
+
+=== Ease of use
+
+The build system should be both easy to use and easy to extend. While this is
+naturally a subjective metric it is likely not controversial to say that some
+build systems are considerably harder to use than others.
+
+=== IDE support
+
+The build system should integrate with well-known IDEs. Well-known IDEs include:
+
+ - Microsoft Visual Studio
+ - Visual Studio Code
+ - Xcode
+
+There are four levels of support:
+
+ - Native integration into the IDE.
+ - Integration into the IDE via a plugin.
+ - Integration into the IDE via generating a project description with the build
+ system.
+ - No integration.
+
+Native integration is preferable, but integration via either a plugin or by
+generating a project description via the build system are considered feasible
+alternatives.
+
+Another important distinction is the level of integration. There are two
+features that one generally wants to have:
+
+ - Integration of build targets.
+ - Automatic setup of features like code completion with detected build
+ dependencies.
+
+The first bullet point is the bare minimum, but is not sufficient to be
+considered proper integration.
+
+=== Out-of-tree builds
+
+The build system should support out-of-tree builds. Out-of-tree builds allow a
+developer to configure multiple different build directories with different
+configuration, e.g. one "debug" build and one "release" build.
+
+=== Cross-platform builds
+
+The build system should support cross-platform builds, e.g. building for arm on
+an x86-64 host.
+
+=== Language support
+
+The following languages and toolchains are of relevance and should be supported
+by the build system:
+
+ - C: the primary compiled language used by Git, must be supported. Relevant
+ toolchains are GCC, Clang and MSVC.
+ - Rust: candidate as a second compiled lanugage, should be supported. Relevant
+ toolchains is the LLVM-based rustc.
+
+Built-in support for the respective languages is preferred over support that
+needs to be wired up manually to avoid unnecessary complexity. Native support
+includes the following features:
+
+ - Compiling objects.
+ - Dependency tracking.
+ - Detection of available features.
+ - Discovery of relevant toolchains.
+ - Linking libraries and executables.
+ - Templating placeholders in scripts.
+
+=== Test integration
+
+It should be possible to integrate tests into the build system such that it is
+possible to build and test Git within the build system. Features which are nice
+to have:
+
+ - Track build-time dependencies for respective tests. Unit tests have
+ different requirements than integration tests.
+ - Allow filtering of which tests to run.
+ - Allow running tests such that utilities like `test_pause` or `debug` work.
+
+== Comparison
+
+The following list of build systems are considered:
+
+- GNU Make
+- autoconf
+- CMake
+- Meson
+
+=== GNU Make
+
+- Platform support: ubitquitous on all platforms, but not well-integrated into Windows.
+- Auto-detection: no built-in support for auto-detection of features.
+- Ease of use: easy to use, but discovering available options is hard. Makefile
+ rules can quickly get out of hand once reaching a certain scope.
+- IDE support: execution of Makefile targets is supported by many IDEs
+- Out-of-tree builds: supported in theory, not wired up in practice.
+- Cross-platform builds: supported in theory, not wired up in practice.
+- Language support:
+ - C: Limited built-in support, many parts need to be wired up manually.
+ - Rust: No built-in support, needs to be wired up manually.
+- Test integration: partially supported, many parts need to be wired up
+ manually.
+
+=== autoconf
+
+- Platform support: ubiquitous on all platforms, but not well-integrated into Windows.
+- Auto-detection: supported.
+- Ease of use: easy to use, discovering available options is comparatively
+ easy. The autoconf syntax is prohibitively hard to extend though due to its
+ complex set of interacting files and the hard-to-understand M4 language.
+- IDE support: no integration into IDEs at generation time. The generated
+ Makefiles have the same level of support as GNU Make.
+- Out-of-tree builds: supported in theory, not wired up in practice.
+- Cross-platform builds: supported.
+- Language support:
+ - C: Limited built-in support, many parts need to be wired up manually.
+ - Rust: No built-in support, needs to be wired up manually.
+- Test integration: partially supported, many parts need to be wired up
+ manually.
+
+=== CMake
+
+- Platform support: not as extensive as GNU Make or autoconf, but all major
+ platforms are supported.
+ - AIX
+ - Cygwin
+ - FreeBSD
+ - Linux
+ - OpenBSD
+ - Solaris
+ - Windows
+ - macOS
+- Ease of use: easy to use, discovering available options is not always
+ trivial. The scripting language used by CMake is somewhat cumbersome to use,
+ but extending CMake build instructions is doable.
+- IDE support: natively integrated into Microsoft Visual Studio. Can generate
+ project descriptions for Xcode. An extension is available for Visual Studio
+ Code. Many other IDEs have plugins for CMake.
+- Out-of-tree builds: supported.
+- Cross-platform builds: supported.
+- Language support:
+ - C: Supported for GCC, Clang, MSVC and other toolchains.
+ - Rust: No built-in support, needs to be wired up manually.
+- Test integration: supported, even though test dependencies are a bit
+ cumbersome to use via "test fixtures". Interactive test runs are not
+ supported.
+
+=== Meson
+
+- Platform: not as extensive as GNU Make or autoconf, but all major platforms
+ and some smaller ones are supported.
+ - AIX
+ - Cygwin
+ - DragonflyBSD
+ - FreeBSD
+ - Haiku
+ - Linux
+ - NetBSD
+ - OpenBSD
+ - Solaris
+ - Windows
+ - macOS
+- Ease of use: easy to use, discovering available options is easy. The
+ scripting language is straight-forward to use.
+- IDE support: Supports generating build instructions for Xcode and Microsoft
+ Visual Studio, a plugin exists for Visual Studio Code.
+- Out-of-tree builds: supported.
+- Cross-platform builds: supported.
+- Language support:
+ - C: Supported for GCC, Clang, MSVC and other toolchains.
+ - Rust: Supported for rustc.
+- Test integration: supported. Interactive tests are supported starting with
+ Meson 1.5.0 via the `--interactive` flag.
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> --- Documentation/Makefile | 1 + Documentation/technical/build-systems.txt | 224 ++++++++++++++++++++++++++++++ 2 files changed, 225 insertions(+)