On Tue, Nov 12, 2024 at 9:42 PM Patrick Steinhardt <ps@xxxxxx> wrote:
> ++# 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 Git
> ++# directory.
Is it the "Git directory" or the "build directory"?
It might be helpful to repeat that this happens when `meson setup
build/` is run (as far as I understand it). Maybe something like:
"The exact configuration of Git is determined when setting up the
build directory, so when running `meson setup <build-dir>/`."
>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 build directory with optimized settings that will be
> ++# # installed into an alternative prefix.
> ++# $ meson setup --buildtype release --optimization 3 --strip --prefix=/home/$USER
It's not very clear if the above instruction should be run inside an
existing build directory to modify its configuration, or if it creates
a new build directory. If it creates one, it's also not clear what the
name of that directory would be. Maybe "build", but then what if an
existing build directory exists with that name?
> ++# # Set up a build directory with 'address' and 'undefined' sanitizers
> ++# # using Clang.
> ++# $ CC=clang meson setup -Db_sanitize=address,undefined
Same as above.
> ++# # Disable tests in a preexisting build directory.
> ++# $ meson configure -Dtests=false
As here the command is "configure" instead of "setup", I guess it
doesn't create a build directory and should be run inside a one.
> ++# # Disable features based on Python
> ++# $ meson configure -Dpython=disabled
> ++#
> ++# # Disable features based on Python
> ++# $ meson configure -Dpython=disabled
It looks like there is some duplication above.
> ++# 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.
It's not very clear what a "machine file" is. How is it different from
a config file?
> ++# 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`.
> ++#
> ++# Subproject wrappers
> ++# ===================
> ++#
> ++# Subproject wrappers are a feature provided by Meson that allow the automatic
> ++# 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`.
I guess this will make the build fail if the system doesn't provide curl then.
