Re: [RFC PATCH 01/21] Documentation: add comparison of build systems

[Patrick Steinhardt <ps@pks.im>]

On Wed, Oct 02, 2024 at 11:14:52AM -0700, Junio C Hamano wrote:
> Patrick Steinhardt <ps@pks.im> writes:
> > diff --git a/Documentation/technical/build-systems.txt b/Documentation/technical/build-systems.txt
> > new file mode 100644
> > index 0000000000..8fac36ce1d
> > --- /dev/null
> > +++ b/Documentation/technical/build-systems.txt
> > @@ -0,0 +1,164 @@
> > += Build Systems
> > +
> > +The build system is the primary way for both developers and system integrators
> > +to interact with the Git project. As such, we consider it important to pick a
> > +build system that fulfills our requirements while being easy to use and extend.
> 
> Maybe it is me, but this sounds as if _we_ do not need "easy to use
> and extend", but "easy to use and extend" are extra afterthought
> consideration we are making for others, which is a bit disturbing.
> 
> Let me try paraphrasing what I think you wanted to say
> 
> 	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.
> 
> which hopefully would sound more like we are not treating those who
> only build and tweak the product of our project as second-class
> citizens.

Oh, that sounds way better, yes!

> > +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 prevent a list of requirements that we have for any
> 
> I think you meant "present".

Yup.

> > +potential build system. Sections are sorted by decreasing priority, even though
> > +these priorities will naturally differ between users.
> > +
> > +=== Platform support
> > +
> > +The most important criterium is whether the build system supports all of the
> > +platforms that Git supports. The most important platforms include:
> 
> Maybe it is just me, but when I hear "The most", I expect an
> exhaustive list (hence "include" that came later somewhat surprised
> me), and I consider these "the more important systems" (implying
> "than others").

Fair point. Ideally, I would be able to just point to our platform
support policy, but that document stops short of defining what kind of
guarantees we give for each platform.

So what are our primary platforms? Based on the criteria we have it
would be Windows, Ubuntu and macOS because we have CI runners for these,
all of which are included. Providing support for the BSDs is nice, but
these are likely rather "secondary" platforms.

> > +=== 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.
> 
> If we want to pull RFC-2119/BCP-14 with shouting "SHOULD", we
> probably should use something similar in the previous "Platform
> support" section.

I think I originally wanted to use RFC-2119, but then noticed that it's
rather pointless. I'll stop shouting.

> > +=== IDE support
> > +=== Out-of-tree builds
> 
> Cross platform builds (e.g., building for arm on x86-64 host)?

Oh, yes, that one is indeed an ommission in the current doc.

> > +=== Rust support
> > +
> > +Many long-time Git contributors are nowadays in favor of adopting Rust as a
> > +second language next to C. The build system SHOULD thus support Rust such that
> > +we do not have to reopen the discussion once we decide to pick up Rust.
> 
> What reasons do you have in mind that, without spelling this out,
> Rust will be left behind while C is fully supported?  If the build
> system can keep track of dependencies by knowing foo.o is made from
> foo.c and turning foo.c into foo.o takes running cc, it can do the
> same for rustc.  Do you mean include file dependencies and the like?

> If the reason why we say "Language X needs to be supported" is
> because it is not enough to be able to run a compiler on source
> files written in the language, but it is also necessary to know when
> to run the compiler (i.e., by dependency tracking), it is better to
> spell it out.

Eli already did a good job of explaining this. While it should be
possible to "retrofit" Rust support to basically all build systems out
there, it certainly would be nice if we could hide away most of the
intricate details of how Rust code needs to be compiled. It can get
complex rather fast.

> In any case, instead of singling out Rust in the title, name the
> section "languate support", and give an enumeration of compilers
> languages, processors that we care about, just like we did for
> platforms.  For exaple, we may not necessarily want to treat "C
> support, done as an afterthought of supporting C++" and "C support,
> done natively" as equivalents (of course, the latter is better).

That makes sense to me, will do.

> Shouldn't it also "support" asciidoc/asciidoctor/makeinfo for
> the documentation toolchain?

It certainly should be flexible enough to allow for this, yes.

> Are there other things we use Makefile for in our current system
> that we are forgetting in this requirements section, like "running
> lint" or "running tests"?

I was a bit torn on whether or not to add "running tests", mostly
because it was supported by all of the proposed build systems. But
that's probably not a good reason to not make this requirement explicit.

Patrick