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

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

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

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

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

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

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

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