# 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.