Re: [PATCH RFC v7 21/22] Introduce support for the Meson build system

[Patrick Steinhardt <ps@pks.im>]

On Fri, Nov 15, 2024 at 01:20:55PM +0100, Christian Couder wrote:
> On Fri, Nov 15, 2024 at 8:21 AM Patrick Steinhardt <ps@pks.im> wrote:
> 
> > +# Basic usage
> > +# ===========
> > +#
> > +# In the most trivial case, you can configure, build and install Git like this:
> > +#
> > +#  1. Set up the build directory. This only needs to happen once per build
> > +#     directory you want to have. You can also configure multiple different
> > +#     build directories with different configurations.
> > +#
> > +#      $ meson setup build/
> > +#
> > +#     The build directory gets ignored by Git automatically as Meson will write
> > +#     a ".gitignore" file into it. From hereon, we will assume that you execute
> > +#     commands inside this build directory.
> > +#
> > +# 2. Compile Git. You can either use Meson, Ninja or Samurai to do this, so all
> > +#    of the following invocations are equivalent:
> > +#
> > +#      $ meson compile
> > +#      $ ninja
> > +#      $ samu
> > +#
> > +#   The different invocations should ultimately not make much of a difference.
> > +#   Using Meson also works with other generators though, like when the build
> > +#   directory has been set up for use with Microsoft Visual Studio.
> 
> I think it might be helpful to say if the above commands are using
> multiple processes in parallel (like `make -j 10` for example) to
> build or not. If they are using multiple processes, it might be useful
> to shortly say how the number of processes used is computed. If they
> are not using multiple processes, it might be interesting to say if an
> option exists for this or not, and if not, why.

Yup, will add a note. Ninja and Samurai scale with the number of
processor cores by default. The number of jobs can be changed with the
`-jN` flag.

> If the above commands use ccache or can use it, or similar tools, it
> could be interesting to say so too.

Added a note.

> > +#
> > +# 3. Execute tests. Again, you can either use Meson, Ninja or Samurai to do this:
> > +#
> > +#      $ meson test
> > +#      $ ninja test
> > +#      $ samu test
> > +#
> > +#   It is recommended to use Meson in this case though as it also provides you
> > +#   additional features that the other build systems don't have available.
> > +#   You can e.g. pass additional arguments to the test executables or run
> > +#   individual tests:
> > +#
> > +#      # Execute the t0000-basic integration test and t-reftable-stack unit test.
> > +#      $ meson test t0000-basic t-reftable-stack
> > +#
> > +#      # Execute all reftable unit tests.
> > +#      $ meson test t-reftable-*
> > +#
> > +#      # Execute all tests and stop with the first failure.
> > +#      $ meson test --maxfail 1
> > +#
> > +#      # Execute single test interactively such that features like `debug ()` work.
> > +#      $ meson test -i --test-args='-ix' t1400-update-ref
> 
> How about executing tests in parallel? I am asking because it's an
> easy way to speed up test execution.

Tests are executed in parallel by default. Same as above, you can change
this with `-jN`.

> > +# 4. Install the Git distribution. Again, this can be done via Meson, Ninja or
> > +#    Samurai:
> > +#
> > +#      $ meson install
> > +#      $ ninja install
> > +#      $ samu install
> > +#
> > +#    The prefix into which Git shall be installed is defined when setting up
> > +#    the build directory. More on that in the "Configuration" section.
> > +#
> > +# Meson supports multiple backends. The default backend generates Ninja build
> > +# instructions, but it also supports the generation of Microsoft Visual
> > +# Studio solutions as well as Xcode projects. IDEs like Eclipse and Visual
> > +# Studio Code provide plugins to import Meson files directly.
> 
> So I guess it's not necessary to configure Meson to make it use a
> backend that generates VS Code or Xcode projects.

I've added a note on how to set the backend.

> > +# Configuration
> > +# =============
> > +#
> > +# The exact configuration of Git is determined when setting up the build
> > +# directory via `meson setup`. Unless told otherwise, Meson will automatically
> > +# detect the availability of various bits and pieces. There are two different
> > +# kinds of options that can be used to further tweak the build:
> > +#
> > +#   - Built-in options provided by Meson.
> > +#
> > +#   - Options defined by the project in the "meson_options.txt" file.
> > +#
> > +# Both kinds of options can be inspected by running `meson configure` in the
> > +# build directory, which will give you a list of the current value for all
> > +# options.
> > +#
> > +# Options can be configured either when setting up the build directory or can
> > +# be changed in preexisting build directories:
> > +#
> > +#      # Set up a new build directory with optimized settings that will be
> > +#      # installed into an alternative prefix.
> > +#      $ meson setup --buildtype release --optimization 3 --strip --prefix=/home/$USER build
> 
> "build" is the name that was already given to the build directory
> above in this doc, so it might be better to use something else, like
> maybe "build-optimized/".

It's only an example anyway, so I don't think it matters much whether
the directory names repeat. Same with the following commands.

> > +#      # Set up a new build directory with a higher warning level. Level 2 is
> > +#      # mostly equivalent to setting DEVELOPER=1, level 3 and "everything"
> > +#      # will enable even more warnings.
> > +#      $ meson setup -Dwarning_level=2
> 
> There is no name for the new build directory in the above command,
> maybe something like "build-warning/" should be added.
> 
> > +#      # Set up a new build directory with 'address' and 'undefined' sanitizers
> > +#      # using Clang.
> > +#      $ CC=clang meson setup -Db_sanitize=address,undefined build
> 
> Maybe "build-address/" instead of "build".
> 
> > +#      # Disable tests in a preexisting build directory.
> > +#      $ meson configure -Dtests=false
> 
> What happens if we run `meson test` then?

Meson simply prints "No tests defined."

> > +#      # Disable features based on Python
> > +#      $ meson configure -Dpython=disabled
> > +#
> > +# Options have a type like booleans, choices, strings or features. Features are
> > +# somewhat special as they can have one of three values: enabled, disabled or
> > +# auto. While the first two values are self-explanatory, "auto" will enable or
> > +# disable the feature based on the availability of prerequisites to support it.
> > +# Python-based features for example will be enabled automatically when a Python
> > +# interpreter could be found. The default value of such features can be changed
> > +# globally via `meson setup --auto-features={enabled,disabled,auto}`, which
> > +# will set the value of all features with a value of "auto" to the provided one
> > +# by default.
> 
> "globally" here means for all the builds directories of the current
> system user, or for all the build directories inside the directory
> where `meson setup --auto-features={enabled,disabled,auto}` was run,
> or just for all the features in the current build directory if this is
> run inside a build directory?

The last one. I'll just drop this word.

> > +# It is also possible to store a set of configuration options in machine files.
> > +# This can be useful in case you regularly want to reuse the same set of options:
> > +#
> > +#   [binaries]
> > +#   c = ['clang']
> > +#   ar = ['ar']
> > +#
> > +#   [project options]
> > +#   gettext = 'disabled'
> > +#   default_editor = 'vim'
> > +#
> > +#   [built-in options]
> > +#   b_lto = true
> > +#   b_sanitize = 'address,undefined'
> > +#
> > +# These machine files can be passed to Meson via `meson setup --native-file`.
> 
> I think it might be helpful to say that "machine files" is the name
> used by meson for basically "config files".
> 
> Also it's not very clear which build directories will be impacted when
> `meson setup --native-file my-machine-file` is run.

As `meson setup` sets up a new build directory it is that particular
directory. I've reworded this a bit.

> > +# Subproject wrappers
> > +# ===================
> > +#
> > +# Subproject wrappers are a feature provided by Meson that allow the automatic
> 
> s/allow/allows/
> 
> > +# fallback to a "wrapped" dependency in case the dependency is not provided by
> > +# the system. For example if the system is lacking curl, then Meson will use
> > +# "subprojects/curl.wrap" to set up curl as a subproject and compile and link
> > +# the dependency into Git itself. This is especially helpful on systems like
> > +# Windows, where you typically don't have such dependencies installed.
> > +#
> > +# The use of subproject wrappers can be disabled by executing `meson setup
> > +# --wrap-mode nofallback`.
> 
> It's not very clear which build directories will be impacted by this command.

Reformulated slightly.

Thanks for your feedback!

Patrick