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