lix/doc/manual
Qyriad b913a939b0 meson: flip the switch!!
This commit makes Meson the default buildsystem for Lix.
The Make buildsystem is now deprecated and will be removed soon, but has
not yet, which will be done in a later commit when all seems good. The
mesonBuild jobs have been removed, and have not been replaced with
equivalent jobs to ensure the Make buildsystem still works.

The full, new commands in a development shell are:

$ meson setup ./build "--prefix=$out" $mesonFlags

(A simple `meson setup ./build` will also build, but will do a different
thing, not having the settings from package.nix applied.)

$ meson compile -C build
$ meson test -C build --suite=check
$ meson install -C build
$ meson test -C build --suite=installcheck

(Check and installcheck may both be done after install, allowing you to
omit the --suite argument entirely, but this is the order package.nix
runs them in.)

If tests fail and Meson helpfully has no output for why, use the
`--print-error-logs` option to `meson test`. Why this is not the default
I cannot explain.

If you change a setting in the buildsystem, most cases will
automatically regenerate the Meson configuration, but some cases, like
trying to build a specific target whose name is new to the buildsystem
(e.g. `meson compile -C build src/libmelt/libmelt.dylib`, when
`libmelt.dylib` did not exist as a target the last time the buildsystem
was generated), then you can reconfigure using new settings but
existing options, and only recompiling stuff affected by the changes:

$ meson setup --reconfigure build

Note that changes to the default values in `meson.options` or in the
`default_options :` argument to project() are NOT propagated with
`--reconfigure`.

If you want a totally clean build, you can use:

$ meson setup --wipe build

That will work regardless of if `./build` exists or not.

Specific, named targets may be addressed in
`meson build -C build <target>` with the "target ID" if there is one,
which is the first string argument passed to target functions that
have one, and unrelated to the variable name, e.g.:

libexpr_dylib = library('nixexpr', …)

can be addressed with:

$ meson compile -C build nixexpr

All targets may be addressed as their output, relative to the build
directory, e.g.:

$ meson compile -C build src/libexpr/libnixexpr.so

But Meson does not consider intermediate files like object files
targets. To build a specific object file, use Ninja directly and
specify the output file relative to the build directory:

$ ninja -C build src/libexpr/libnixexpr.so.p/nixexpr.cc.o

To inspect the canonical source of truth on what the state of the
buildsystem configuration is, use:

$ meson introspect

Have fun!

Change-Id: Ia3e7b1e6fae26daf3162e655b4ded611a5cd57ad
2024-04-22 21:41:58 -06:00
..
rl-next Print top-level errors normally in nix repl 2024-04-09 08:34:40 -07:00
rl-next-dev Enable clang build timing analysis 2024-03-27 03:52:57 +00:00
src meson: flip the switch!! 2024-04-22 21:41:58 -06:00
theme Add pre-commit checks 2024-03-29 22:57:40 -07:00
anchors.jq Add pre-commit checks 2024-03-29 22:57:40 -07:00
book.toml docs: redo content generation for mdbook and manual 2024-04-11 13:32:06 +00:00
custom.css disallow selecting shell prompt in code samples 2022-12-05 11:01:46 +01:00
generate-builtin-constants.nix Format Nix code with nixfmt 2024-04-08 13:00:00 -07:00
generate-builtins.nix Format Nix code with nixfmt 2024-04-08 13:00:00 -07:00
generate-deps.py docs: redo content generation for mdbook and manual 2024-04-11 13:32:06 +00:00
generate-manpage.nix docs: don't compute SUMMARY.md during build 2024-04-09 02:09:36 +00:00
generate-xp-features-shortlist.nix Format Nix code with nixfmt 2024-04-08 13:00:00 -07:00
generate-xp-features.nix Format Nix code with nixfmt 2024-04-08 13:00:00 -07:00
json-to-tree.py docs: generalize manpage generation script as json-to-tree.py 2024-04-10 15:04:34 +02:00
local.mk docs: redo content generation for mdbook and manual 2024-04-11 13:32:06 +00:00
meson.build manual: build docs with dummy envs 2024-04-11 13:36:04 +00:00
process-includes.sh meson: add manpages for old cli and config files 2024-03-30 14:26:47 +00:00
quote-literals.xsl Generate release notes again 2014-03-12 14:24:29 +01:00
redirects.js fix an old lost direct (#9717) 2024-01-08 20:57:39 +01:00
render-manpage.sh docs: redo content generation for mdbook and manual 2024-04-11 13:32:06 +00:00
substitute.py docs: redo content generation for mdbook and manual 2024-04-11 13:32:06 +00:00
utils.nix Format Nix code with nixfmt 2024-04-08 13:00:00 -07:00