[RFC,v2,23/24] Documentation: add comparison of build systems

Commit Message

Patrick Steinhardt Oct. 9, 2024, 2:57 p.m. UTC

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 <[e-mail]>
---
 Documentation/Makefile                    |   1 +
 Documentation/technical/build-systems.txt | 224 ++++++++++++++++++++++
 2 files changed, 225 insertions(+)
 create mode 100644 Documentation/technical/build-systems.txt

Comments

Phillip Wood Oct. 14, 2024, 3:23 p.m. UTC | #1

Hi Patrick

On 09/10/2024 15:57, Patrick Steinhardt wrote:

Thanks for putting this together, I've left a few comments below.

> +== Requirements
> +
> +The following subsections present a list of requirements that we have for any
> +potential build system. Sections are sorted by decreasing priority, even though
> +these priorities will naturally differ between users.

This last sentence sounds a bit self contradictory - whose priorities 
are we using?

> +=== Platform support
> +
> +The build system must have support for all of our primary platforms as outlined
> +by. These platforms are:

Something seems to have been lost when the first sentence was edited.

> +  - Linux
> +  - Windows
> +  - macOS
> +
> +Furthermore, the build system should have support for the following secondary
> +platforms:
> +
> +  - AIX
> +  - FreeBSD
> +  - NetBSD
> +  - OpenBSD
> +
> +The platforms which must be supported by the tool should be aligned with our
> +[platform support policy](platform-support.txt).

The platform support document does not use the terms primary or 
secondary when talking about support so I'm not sure what distinction 
we're trying to make here. Also where does NonStop fit into this?

> +=== 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.

The tricky part is deciding how to measure ease of use if we're going to 
use it as a metric for selecting a build system.

> +=== Out-of-tree builds
> +
> +The build system should support out-of-tree builds.

Yes please!

> +=== 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.

Do we want a section about templating (i.e. substituting @XXX@) support 
which we use when installing 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 interactive tests that drop the user into a shell with `test_pause` or
> +    `debug`.

Does this last point mean we want to be able to selectively pass 
--interactive to the test script(s) being run?

> +=== 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

This matches the list in the CMake README but in practice it is 
available for a much wider range of platforms including all those listed 
below for meson.

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

This is my main concern about meson - it means we either loose the nice 
integration on Windows that we have with CMake or we have to continue to 
maintain both. As I understand it Microsoft Visual Studio support 
requires the user to open a mingw terminal and run some to generate a 
build description which they can then use form the GUI which is what the 
CMake support was added to avoid. I guess they also need to install 
meson somehow as well.

Best Wishes

Phillip

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

Patrick Steinhardt Oct. 15, 2024, 12:12 p.m. UTC | #2

On Mon, Oct 14, 2024 at 04:23:33PM +0100, Phillip Wood wrote:
> On 09/10/2024 15:57, Patrick Steinhardt wrote:
> > +== Requirements
> > +
> > +The following subsections present a list of requirements that we have for any
> > +potential build system. Sections are sorted by decreasing priority, even though
> > +these priorities will naturally differ between users.
> 
> This last sentence sounds a bit self contradictory - whose priorities are we
> using?

I guess it's priorities as received by the author, namely me. I didn't
quite know how to write this, as I didn't want to force my own prios on
everybody else without saying so. But if people agree with the general
ordering I'm happy to drop this sentence.

> > +=== Platform support
> > +
> > +The build system must have support for all of our primary platforms as outlined
> > +by. These platforms are:
> 
> Something seems to have been lost when the first sentence was edited.
> 
> > +  - Linux
> > +  - Windows
> > +  - macOS
> > +
> > +Furthermore, the build system should have support for the following secondary
> > +platforms:
> > +
> > +  - AIX
> > +  - FreeBSD
> > +  - NetBSD
> > +  - OpenBSD
> > +
> > +The platforms which must be supported by the tool should be aligned with our
> > +[platform support policy](platform-support.txt).
> 
> The platform support document does not use the terms primary or secondary
> when talking about support so I'm not sure what distinction we're trying to
> make here. Also where does NonStop fit into this?

Yes, true, and that's an issue from my point of view. I think we should
make explicit the different kinds of support we have and have a proper
list of systems that are supported and their general "support tier".
Anyway, that's a different can of worms that I don't want to open right
now. My table is still crawling with worms from previously-opened cans.

I've reworded this slightly now and added NonStop.

> > +=== 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.
> 
> The tricky part is deciding how to measure ease of use if we're going to use
> it as a metric for selecting a build system.

Yup. It's part of the reason why I wanted to have all build systems in
the tree, such that it is possible to compare them by just having a look
for how it looks like.

Things are naturally going to be subjective, and that is fine. But I
guess that we can mostly agree on some general things, like "autoconf
looks like gibberish".

> > +=== 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.
> 
> Do we want a section about templating (i.e. substituting @XXX@) support
> which we use when installing scripts?

It doesn't hurt.

> > +=== 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 interactive tests that drop the user into a shell with `test_pause` or
> > +    `debug`.
> 
> Does this last point mean we want to be able to selectively pass
> --interactive to the test script(s) being run?

What I mean by this is that when I see that a specific test fails, I
want to be able to execute only that single test such that things like
`test_pause` fail. What I don't mean is that the build system should
know to automatically rerun failing tests with that.

I've reformulated it to "Allow running tests such that utilities like
`test_pause` or `debug` work."

> > +=== 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
> 
> This matches the list in the CMake README but in practice it is available
> for a much wider range of platforms including all those listed below for
> meson.

I was searching for an official statement, but couldn't find anything.
Do you maybe have a pointer?

> > +- 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.
> 
> This is my main concern about meson - it means we either loose the nice
> integration on Windows that we have with CMake or we have to continue to
> maintain both. As I understand it Microsoft Visual Studio support requires
> the user to open a mingw terminal and run some to generate a build
> description which they can then use form the GUI which is what the CMake
> support was added to avoid. I guess they also need to install meson somehow
> as well.

I'm personally not particularly worried about having to generate the
MSVC solution from the command line once, as long as things just work
from thereon without requiring the developer to jump through hoops to
get it set up. It certainly doesn't seem like a particularly high
barrier to me, and should be a huge improvement compared to our current
Makefile.

I'm mostly there by now with the subprojects added in this version of
the patch series, which make it way easier to use MSVC without all deps
having been installed. But I still have to port over the SANE_TOOL_PATH
hack that we have in CMake.

I do understand that just clicking a button to import a CMakeLists.txt
is easier. It's mostly that I personally value the sanity that Meson
brings with it higher, which is of course a subjective opinion.

Patrick

Phillip Wood Oct. 16, 2024, 1:36 p.m. UTC | #3

Hi Patrick

On 15/10/2024 13:12, Patrick Steinhardt wrote:
> On Mon, Oct 14, 2024 at 04:23:33PM +0100, Phillip Wood wrote:
>> On 09/10/2024 15:57, Patrick Steinhardt wrote:
>>> +== Requirements
>>> +
>>> +The following subsections present a list of requirements that we have for any
>>> +potential build system. Sections are sorted by decreasing priority, even though
>>> +these priorities will naturally differ between users.
>>
>> This last sentence sounds a bit self contradictory - whose priorities are we
>> using?
> 
> I guess it's priorities as received by the author, namely me. I didn't
> quite know how to write this, as I didn't want to force my own prios on
> everybody else without saying so. But if people agree with the general
> ordering I'm happy to drop this sentence.

I think that would make sense - anyone who objects to the order you've 
selected can also say so in a review.

>>> +=== Platform support
>>> +
>>> +The build system must have support for all of our primary platforms as outlined
>>> +by. These platforms are:
>>
>> Something seems to have been lost when the first sentence was edited.
>>
>>> +  - Linux
>>> +  - Windows
>>> +  - macOS
>>> +
>>> +Furthermore, the build system should have support for the following secondary
>>> +platforms:
>>> +
>>> +  - AIX
>>> +  - FreeBSD
>>> +  - NetBSD
>>> +  - OpenBSD
>>> +
>>> +The platforms which must be supported by the tool should be aligned with our
>>> +[platform support policy](platform-support.txt).
>>
>> The platform support document does not use the terms primary or secondary
>> when talking about support so I'm not sure what distinction we're trying to
>> make here. Also where does NonStop fit into this?
> 
> Yes, true, and that's an issue from my point of view. I think we should
> make explicit the different kinds of support we have and have a proper
> list of systems that are supported and their general "support tier".

That would probably be clearer but as you say it can wait

> Anyway, that's a different can of worms that I don't want to open right
> now. My table is still crawling with worms from previously-opened cans.

It's going to take a while for me to get that image out of my mind!

> I've reworded this slightly now and added NonStop.

Great

>>> +=== 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 interactive tests that drop the user into a shell with `test_pause` or
>>> +    `debug`.
>>
>> Does this last point mean we want to be able to selectively pass
>> --interactive to the test script(s) being run?
> 
> What I mean by this is that when I see that a specific test fails, I
> want to be able to execute only that single test such that things like
> `test_pause` fail. What I don't mean is that the build system should
> know to automatically rerun failing tests with that.
> 
> I've reformulated it to "Allow running tests such that utilities like
> `test_pause` or `debug` work."

Ah so this is basically "there should be a way to disable 
parallelization and let the test access the terminal"?

>>> +=== 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
>>
>> This matches the list in the CMake README but in practice it is available
>> for a much wider range of platforms including all those listed below for
>> meson.
> 
> I was searching for an official statement, but couldn't find anything.
> Do you maybe have a pointer?

I've not been able to find any documentation but 
https://github.com/Kitware/CMake/tree/9c25632ba0ad0525b20195d371b3d78a8bcc4113/Modules/Platform 
seems to show which platforms and compilers are supported.

>>> +- 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.
>>
>> This is my main concern about meson - it means we either loose the nice
>> integration on Windows that we have with CMake or we have to continue to
>> maintain both. As I understand it Microsoft Visual Studio support requires
>> the user to open a mingw terminal and run some to generate a build
>> description which they can then use form the GUI which is what the CMake
>> support was added to avoid. I guess they also need to install meson somehow
>> as well.
> 
> I'm personally not particularly worried about having to generate the
> MSVC solution from the command line once, as long as things just work
> from thereon without requiring the developer to jump through hoops to
> get it set up. It certainly doesn't seem like a particularly high
> barrier to me, and should be a huge improvement compared to our current
> Makefile.

It's an improvement on our Makefile but a regression compared to our 
CMakeList.txt which was specifically aimed making it easy for new 
contributors to get started without downloading any extra software or 
running terminal commands.

> I'm mostly there by now with the subprojects added in this version of
> the patch series, which make it way easier to use MSVC without all deps
> having been installed. But I still have to port over the SANE_TOOL_PATH
> hack that we have in CMake.
> 
> I do understand that just clicking a button to import a CMakeLists.txt
> is easier. It's mostly that I personally value the sanity that Meson
> brings with it higher, which is of course a subjective opinion.

Right, I suspect the people who added support for building git in Visual 
Studio with CMake have different priorities. It's a real shame the meson 
there isn't a meson plugin for Visual Studio.

Best Wishes

Phillip

Patrick Steinhardt Oct. 17, 2024, 9:36 a.m. UTC | #4

On Wed, Oct 16, 2024 at 02:36:54PM +0100, [e-mail] wrote:
> > > > +=== 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 interactive tests that drop the user into a shell with `test_pause` or
> > > > +    `debug`.
> > > 
> > > Does this last point mean we want to be able to selectively pass
> > > --interactive to the test script(s) being run?
> > 
> > What I mean by this is that when I see that a specific test fails, I
> > want to be able to execute only that single test such that things like
> > `test_pause` fail. What I don't mean is that the build system should
> > know to automatically rerun failing tests with that.
> > 
> > I've reformulated it to "Allow running tests such that utilities like
> > `test_pause` or `debug` work."
> 
> Ah so this is basically "there should be a way to disable parallelization
> and let the test access the terminal"?

Exactly.

With out-of-tree builds the development process is going to change a
bit, and it is going to be closer integrated with the build system.
Right now it's easy to manually execute a test and thus give it access
to the terminal. And while that shouldn't go away, you'd now have to set
up an additional environment variable to tell the test where the build
directory lives. There isn't really a way to avoid that.

But to me that also means that it's important that features we're all
used to remain easily accessible, and `test_pause` and `debug` are two
things that many developers probably use on a daily basis. I was worried
about that a when starting out on the Meson journey, but now I actually
have to say that I already favor the Meson workflow over the Makefile
workflow. Previously, I always used to do:

    $ make -C .. -j20 && ./t1234-something.sh

With Meson that becomes:

    $ meson test -i t1234-something

Which, at least to me, somehow feels way more enjoyable.

> > > > +- 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.
> > > 
> > > This is my main concern about meson - it means we either loose the nice
> > > integration on Windows that we have with CMake or we have to continue to
> > > maintain both. As I understand it Microsoft Visual Studio support requires
> > > the user to open a mingw terminal and run some to generate a build
> > > description which they can then use form the GUI which is what the CMake
> > > support was added to avoid. I guess they also need to install meson somehow
> > > as well.
> > 
> > I'm personally not particularly worried about having to generate the
> > MSVC solution from the command line once, as long as things just work
> > from thereon without requiring the developer to jump through hoops to
> > get it set up. It certainly doesn't seem like a particularly high
> > barrier to me, and should be a huge improvement compared to our current
> > Makefile.
> 
> It's an improvement on our Makefile but a regression compared to our
> CMakeList.txt which was specifically aimed making it easy for new
> contributors to get started without downloading any extra software or
> running terminal commands.

Yeah, that's fair enough.

> > I'm mostly there by now with the subprojects added in this version of
> > the patch series, which make it way easier to use MSVC without all deps
> > having been installed. But I still have to port over the SANE_TOOL_PATH
> > hack that we have in CMake.
> > 
> > I do understand that just clicking a button to import a CMakeLists.txt
> > is easier. It's mostly that I personally value the sanity that Meson
> > brings with it higher, which is of course a subjective opinion.
> 
> Right, I suspect the people who added support for building git in Visual
> Studio with CMake have different priorities. It's a real shame the meson
> there isn't a meson plugin for Visual Studio.

It certainly would be great to have such a plugin. There is one for
Visual Studio Code, but of course MSVC and VSC aren't the same. Which
reminds me, I should give that plugin a try.

In any case, my hope would be that eventually such a plugin does show
up. My gut feeling tells me that Meson has been picking up quite a bit
of steam over the last couple years, and more and more projects are
picking it up. And that makes me hopeful that we would eventually get
such a plugin.

It's of course wishful thinking, but as said, meanwhile we do have a way
for MSVC by generating the solution manually. So I'd already see it as a
net win if the official build system supports MSVC, even though not as
easily as with the click of a button.

Patrick

Patrick Steinhardt Oct. 17, 2024, 10:58 a.m. UTC | #5

On Thu, Oct 17, 2024 at 11:36:25AM +0200, Patrick Steinhardt wrote:
> On Wed, Oct 16, 2024 at 02:36:54PM +0100, [e-mail] wrote:
> > > I'm mostly there by now with the subprojects added in this version of
> > > the patch series, which make it way easier to use MSVC without all deps
> > > having been installed. But I still have to port over the SANE_TOOL_PATH
> > > hack that we have in CMake.
> > > 
> > > I do understand that just clicking a button to import a CMakeLists.txt
> > > is easier. It's mostly that I personally value the sanity that Meson
> > > brings with it higher, which is of course a subjective opinion.
> > 
> > Right, I suspect the people who added support for building git in Visual
> > Studio with CMake have different priorities. It's a real shame the meson
> > there isn't a meson plugin for Visual Studio.
> 
> It certainly would be great to have such a plugin. There is one for
> Visual Studio Code, but of course MSVC and VSC aren't the same. Which
> reminds me, I should give that plugin a try.
> 
> In any case, my hope would be that eventually such a plugin does show
> up. My gut feeling tells me that Meson has been picking up quite a bit
> of steam over the last couple years, and more and more projects are
> picking it up. And that makes me hopeful that we would eventually get
> such a plugin.
> 
> It's of course wishful thinking, but as said, meanwhile we do have a way
> for MSVC by generating the solution manually. So I'd already see it as a
> net win if the official build system supports MSVC, even though not as
> easily as with the click of a button.

So I've had a look at Visual Studio Code now. Things didn't work as-is
yet, but I've made some changes and now things work out of the box. You
install the Meson plugin, clone the Git project, and Meson configures
automatically. The only requirement is that you've got Git for Windows
installed, which provides all the build tools and which gets picked up
by Meson automatically now.

Afterwards you can just click on any build and/or test target and then
VS Code builds dependencies, including subprojects like curl, zlib,
openssl and the like, and executes the tests for you.

Patrick

Patch

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 0f55baa252f..e23cffb5f9a 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -111,6 +111,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
diff --git a/Documentation/technical/build-systems.txt b/Documentation/technical/build-systems.txt
new file mode 100644
index 00000000000..c00d9b71978
--- /dev/null
+++ b/Documentation/technical/build-systems.txt
@@ -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, even though
+these priorities will naturally differ between users.
+
+=== Platform support
+
+The build system must have support for all of our primary platforms as outlined
+by. These platforms are:
+
+  - Linux
+  - Windows
+  - macOS
+
+Furthermore, the build system should have support for the following secondary
+platforms:
+
+  - AIX
+  - FreeBSD
+  - NetBSD
+  - 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.
+
+=== 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 interactive tests that drop the user into a shell with `test_pause` or
+    `debug`.
+
+== 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.