On Fri, Nov 15, 2024 at 8:21 AM Patrick Steinhardt <ps@xxxxxx> 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.
If the above commands use ccache or can use it, or similar tools, it
could be interesting to say so too.
> +#
> +# 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.
> +# 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.
> +# 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/".
> +# # 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?
> +# # 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?
> +# 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.
> +# 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.
Thanks.
