From 04aaa4d5aaf644a7b5ed941f57212b08e7bd3c92 Mon Sep 17 00:00:00 2001 From: Matt Jolly Date: Sat, 6 Apr 2024 01:28:42 +1000 Subject: [PATCH] dev-docs: update build system info Discuss the meson build path, provide guidance about maintaining feature parity in both build systems. Update install instructions to include a meson build example. --- dev-docs/BUILD-SYSTEMS.md | 119 ++++++++++++++++++++++++++++++++++++++ dev-docs/INSTALL.md | 47 +++++++++++++-- fvwm/Makefile.am | 2 +- 3 files changed, 163 insertions(+), 5 deletions(-) create mode 100644 dev-docs/BUILD-SYSTEMS.md diff --git a/dev-docs/BUILD-SYSTEMS.md b/dev-docs/BUILD-SYSTEMS.md new file mode 100644 index 000000000..9010764c3 --- /dev/null +++ b/dev-docs/BUILD-SYSTEMS.md @@ -0,0 +1,119 @@ +# Build Systems + +FVWM3 supports both autotools and Meson as its build systems. + +Why? + +- Autotools is the traditional build system for FVWM, and is still used by non-Linux systems. + It is retained for compatibility with systems that do not support Meson. +- Meson is a modern build system that is faster and easier to use than autotools. + +When adding new files to the source tree, or changing dependencies or configuration options +you will need to update both build systems to include the new files. + +This is done by adding the new files to the appropriate build system file (`meson.build`, `Makefile.am`), +or for configuration changes, by updating the appropriate configuration file (`configure.ac`, `meson.build`, `meson.options`). + +## Meson + +## Options: Booleans vs Features + +Meson has a selection of options that can be set by the user when configuring the build. + +Often, these are used to enable or disable features (i.e. are set to `true` or `false`). + +These can be directly queried for truthiness in the `meson.build` file. + +```meson.build +if get_option('bar') + # do something +endif +``` + +There also exists a `features` system in Meson, which is a more advanced way to handle options. +Features are defined in the `meson.options` file, and can be set to `auto`, `enabled`, or `disabled`. + +These are envisioned to be used for dependencies, where the developer can use a feature to +set the 'required' property of a dependency. + + - `enabled` is the same as passing `required : true`. + - `auto` is the same as passing `required : false`. + - `disabled` do not look for the dependency and always return 'not-found'. + +```meson.build +dep = dependency('foo', required : get_option('bar')) +``` + +See the [Reference Manual](https://mesonbuild.com/Reference-manual_returned_feature.html) for more information +on the feature system and the more complex ways it can be used. + +When building the software, the user can specify which features to enable or disable, like with booleans, +however the `auto_features` option controls the default value of all features set to `auto`. By default it +is set to `auto`, but can be set (by the user) to `enabled` or `disabled` to +override the default value of all features set to `auto`. + +The user can still override `auto_features` by specifying the feature directly. + +```bash +user@host:~/$ meson build -Dauto_features=enabled -Dfeature_name=disabled +``` + +### What's the difference? + +You can do a lot of the same things with both options and features, but features are more +flexible and can be used to control multiple options at once, or toggled within the build system +without needing to change the user's configuration. + +Features can also take advantage of convenient helpers like `enable_if` and `disable_if` to avoid +tons of boilerplate code. + +```meson.build +dep = dependency('foo', required : get_option('bar')) +if dep.found() + foobar = executable('foobar', 'foobar.c', dependencies : dep) +endif + +if get_option('baz').allowed() + # feature is enabled or 'auto' +endif + +cool_feature = get_option('qux') \ + .disable_if(host_machine.system() == 'darwin', error_message : 'this cool fvwm feature not supported on MacOS') +dep_cool_feature = dependency('cool_feature', required: cool_feature) + +build_docs = get_option( + 'docs', +).enable_if(get_option('htmldoc')).enable_if(get_option('mandoc')) +asciidoc = find_program('asciidoctor', required: build_docs) + +if asciidoc.found() + subdir('doc') +endif +``` + +Using features also enables the user to easily control all +of the feature options at once (a distribution packager may +disable all `auto` features and selectively enable only a few, for example). + +TL;DR: + +Use a boolean option: + + - When the option has only two states: enabled or disabled (e.g., enable_debugging). + - When the option simply controls the presence or absence of a functionality (e.g., build_tests). + - For simple on/off toggles that don't require additional configuration. + +Use a Meson Feature: + + - When the option triggers additional configuration or dependency logic based on its state (e.g., a database feature with choices like sqlite, mysql, or none). + - To provide informative messages or warnings depending on the chosen feature state. + +# Distribution Packagers + +You should probably prefer Meson on systems that support it, as it is faster and more modern than autotools. + +The Ninja backend is faster than make, and Meson's configuration is straightforward. +Meson also has better support for cross-compilation, and the input files are more readable / auditable. + +If you are packaging FVWM3 for a system that does not support Meson, you can use Muon C99 implementation, +however this receives less testing and is not recommended for general use. diff --git a/dev-docs/INSTALL.md b/dev-docs/INSTALL.md index 50bb8aace..3ee9f56a2 100644 --- a/dev-docs/INSTALL.md +++ b/dev-docs/INSTALL.md @@ -60,22 +60,61 @@ To generate `fvwm3`'s documentation: Installing From Git =================== +## Autotools + FVWM3 has a bootstrap script to generate `configure` and associated files. Run the following command chain to generate the `configure` script and build the project: +```console +user@host:~/fvwm3$ ./autogen.sh +user@host:~/fvwm3$ ./configure +user@host:~/fvwm3$ make +user@host:~/fvwm3$ sudo make install ``` -./autogen.sh && ./configure && make + +## Meson + +FVWM3 supports the Meson build system. To build with Meson first configure the build then use the 'Ninja' tool to compile and install: + +```console +user@host:~/fvwm3$ meson setup build +user@host:~/fvwm3/builddir$ ninja -C build +user@host:~/fvwm3/builddir$ ninja -C build install +``` + +Ninja also has an `uninstall` target: + +```console +user@host:~/fvwm3/builddir$ ninja -C build uninstall ``` +To configure the build, pass options to `meson setup` (or `meson configure «builddir»` if the project has already been setup): + +```console +user@host:~/fvwm3$ meson setup build --prefix=/usr --buildtype=release -Dmandoc=true +``` + +For a full list of flags and possible values, see `meson configure meson.build` or point `meson configure` at an existing builddir with no arguments. + Installing From Release Tarball =============================== Release tarballs will come bundled with `./configure` already, hence: +```console +user@host:~/fvwm3-1.2.3$ ./configure +user@host:~/fvwm3-1.2.3$ make +user@host:~/fvwm3-1.2.3$ sudo make install ``` -./configure && make + +or + +```console +user@host:~/fvwm3$ meson setup build +user@host:~/fvwm3/builddir$ ninja -C build +user@host:~/fvwm3/builddir$ meson install -C build ``` -As with most things, if the default options `./configure` chooses isn't -appropriate for your needs, see `./configure --help` for appropriate options. +As with most things, if the default options aren't appropriate for your needs, +see `./configure --help` or `meson configure meson.build` for appropriate options. diff --git a/fvwm/Makefile.am b/fvwm/Makefile.am index 0f794f429..7f4ea0b94 100644 --- a/fvwm/Makefile.am +++ b/fvwm/Makefile.am @@ -49,4 +49,4 @@ AM_CFLAGS = \ -DFVWM_MODULEDIR=\"$(FVWM_MODULEDIR)\" \ -DFVWM_DATADIR=\"$(FVWM_DATADIR)\" \ -DFVWM_CONFDIR=\"$(FVWM_CONFDIR)\" \ - -DLOCALEDIR=\"$(LOCALEDIR)\" \ No newline at end of file + -DLOCALEDIR=\"$(LOCALEDIR)\"