gh-40485: meson: explicitly configurable options
    
As discussed in various places over the past two years, it is useful to
be able to override the automagic detection of libraries to explicitly
enable or disable a feature. This commit adds `meson.options` at the top
level to do that, and to make the documentation optional as well.

Example:

```
$ meson setup -Dsirocco=disabled
```

will disable the cython module `sage.libs.sirocco`, even if I have
sirocco installed. This is nice for a few reasons:

* If you are building from source (or using a source-based distro), this
is the only way to achieve accurate dependency information.
* Now that we are adding meson subprojects, there is again a risk of
vendoring libraries that you already have installed if (say) its pkg-
config check is flaky. Specifying `-Dfoo=enabled` makes that an error
rather than quietly doing the wrong thing.
* It makes it possible to easily test the `# needs whatever` tags on
non-Windows systems (i.e. to test that the things we say are optional
are really optional).
* On a system where the corresponding libraries happen to be installed,
you can speed up the build by disabling the features you aren't
currently working on or using.

And of course, the defaults are all "auto," and should not change
anything for anyone else.

I was finally motivated to do this because the doc build fails on my
machine, and otherwise I have to edit out the line in `src/meson.build`
and be careful not to commit it to all of my PRs. This implementation is
the first thing I came up with after a few minutes of reading the docs,
but it works surprisingly well.
    
URL: #40485
Reported by: Michael Orlitzky
Reviewer(s): Antonio Rojas, Dima Pasechnik, Michael Orlitzky, Tobias Diez

Author: Release Manager

meson.options

@@ -7,3 +7,78 @@ option(
   value: '',
   description: 'Path to SAGE_LOCAL directory (only used for compatibility with the old Sage-the-Distro',
 )
+
+#
+# Boolean options
+#
+option(
+  'build-docs',
+  type: 'boolean',
+  description: 'Build the HTML / PDF documentation'
+)
+
+#
+# Features
+#
+option(
+  'bliss',
+  type: 'feature',
+  value: 'auto',
+  description: 'Bliss interface to graph isomorphisms'
+)
+
+option(
+  'brial',
+  type: 'feature',
+  value: 'auto',
+  description: 'BRiAl interface to polynomials over boolean rings'
+)
+
+option(
+  'coxeter3',
+  type: 'feature',
+  value: 'auto',
+  description: 'Coxeter 3.x interface to Coxeter groups'
+)
+
+option(
+  'eclib',
+  type: 'feature',
+  value: 'auto',
+  description: 'eclib interface to mwrank and elliptic curves over Q'
+)
+
+option(
+  'mcqd',
+  type: 'feature',
+  value: 'auto',
+  description: 'MCQD interface to the MaxCliqueDyn algorithm'
+)
+
+option(
+  'meataxe',
+  type: 'feature',
+  value: 'auto',
+  description: 'MeatAxe interface to matrix representations over finite fields'
+)
+
+option(
+  'rankwidth',
+  type: 'feature',
+  value: 'auto',
+  description: 'Interface to librw for rank-width decompositions'
+)
+
+option(
+  'sirocco',
+  type: 'feature',
+  value: 'auto',
+  description: 'Sirocco interface to certified root continuation'
+)
+
+option(
+  'tdlib',
+  type: 'feature',
+  value: 'auto',
+  description: 'Interface to tdlib for tree decompositions'
+)

pyproject.toml

@@ -129,11 +129,9 @@ host-requires = [
   "virtual:interface/blas",
   "virtual:compiler/fortran",
   "pkg:generic/boost",
-  "pkg:generic/brial",
   "pkg:generic/cddlib",
   "pkg:generic/cliquer",
   "pkg:generic/ecl",
-  "pkg:generic/eclib",
   "pkg:generic/ecm",
   "pkg:generic/fflas-ffpack",
   "pkg:generic/flint",
@@ -183,7 +181,9 @@ dependencies = [
 [external.optional-host-requires]
 extra = [
   "pkg:generic/bliss",
+  "pkg:generic/brial",
   "pkg:generic/coxeter3",
+  "pkg:generic/eclib",
   "pkg:generic/mcqd",
   "pkg:generic/meataxe",
   "pkg:generic/sirocco",

src/doc/en/installation/meson.rst

@@ -232,8 +232,24 @@ To configure the project, we need to run the following command:
 
     $ meson setup builddir
 
-This will create a build directory ``builddir`` that will hold the build
-artifacts.
+This will create a build directory ``builddir`` that will hold the
+build artifacts. Certain options are configurable at build time. The
+easiest way to obtain an overview of these options is by using ``meson
+configure``:
+
+.. code-block:: shell-session
+
+    $ meson configure builddir
+
+This command should display the available options and their associated
+values. The section titled "Project options" contains the options that
+are unique to SageMath. To change the value of an option, the flag
+``-Doption=value`` can be passed to ``meson setup``. For example, if
+you don't want to build the HTML documentation, you might use
+
+.. code-block:: shell-session
+
+    $ meson setup -Dbuild-docs=false builddir
 
 If pip is used as above with ``--editable``, ``builddir`` is set to be
 ``build/cp[Python major version][Python minor version]``, such as
@@ -298,6 +314,21 @@ Alternatively, we can still use pip to install:
         $ meson compile -C builddir
         $ DESTDIR=/path/to/staging/root meson install -C builddir
 
+    SageMath's automatic feature detection (based on the packages that
+    happen to be installed at build time) can be disabled in favor of
+    explicit configuration by passing ``-Dauto_features=disabled`` to
+    ``meson setup``. Afterwards, individual features must be enabled
+    explicitly. You can obtain a list of valid feature names through
+    ``meson configure``.
+
+    By default, meson may fall back to bundled versions of certain
+    subprojects known as `wrap dependencies
+    <https://mesonbuild.com/Wrap-dependency-system-manual.html>`_.
+    Maintainers will typically want to disable this behavior as well
+    to ensure that the system dependencies are used. This can be
+    achieved with the `--wrap-mode flag
+    <https://mesonbuild.com/Subprojects.html#commandline-options>`_
+
     With the `default <https://mesonbuild.com/Running-Meson.html#installing>`_ prefix
     being ``/usr/local``, it may then install to
     ``$DESTDIR/usr/local/lib/python3.12/site-packages/sage``.

src/doc/meson.build

@@ -1,3 +1,7 @@
+if not get_option('build-docs')
+  subdir_done()
+endif
+
 sphinx_check = py_module.find_installation(required: false, modules: ['sphinx'])
 if not sphinx_check.found()
   warning(
@@ -6,6 +10,7 @@ if not sphinx_check.found()
   subdir_done()
 endif
 
+
 doc_src = []
 subdir('en/reference/repl')
 # TODO: Migrate this completely to meson

src/meson.build

@@ -151,18 +151,18 @@ endif
 # Cannot be found via pkg-config
 mtx = cc.find_library(
   'mtx',
-  required: false,
+  required: get_option('meataxe'),
   disabler: true,
   has_headers: ['meataxe.h'],
 )
 png = dependency(['libpng', 'png', 'png16'], version: '>=1.2')
 zlib = dependency('zlib', version: '>=1.2.11')
-# We actually want >= 20231212, but the version number is not updated in the pkgconfig
-# https://github.com/conda-forge/eclib-feedstock/issues/48
-ec = dependency('eclib', version: '>=20231211', required: false, disabler: true)
-if not ec.found()
-  ec = cc.find_library('ec', required: false, disabler: true)
-endif
+ec = dependency(
+  'eclib',
+  version: '>=20250122',
+  required: get_option('eclib'),
+  disabler: true,
+)
 ecm = cc.find_library('ecm', required: not is_windows, disabler: true)
 gmpxx = dependency('gmpxx', required: not is_windows, disabler: true)
 fflas = dependency(

src/sage/graphs/graph_decompositions/meson.build

@@ -1,11 +1,10 @@
-# tdlib is a header-only library
-if cc.has_header('treedec/combinations.hpp')
+tdlib = disabler()
+if cc.has_header('treedec/combinations.hpp', required: get_option('tdlib'))
+  # tdlib is a header-only library
   tdlib = declare_dependency()
-else
-  tdlib = disabler()
 endif
 # Cannot be found via pkg-config
-rw = cc.find_library('rw', required: false, disabler: true)
+rw = cc.find_library('rw', required: get_option('rankwidth'), disabler: true)
 
 py.install_sources(
   '__init__.py',

src/sage/graphs/meson.build

@@ -1,9 +1,9 @@
-bliss = cc.find_library('bliss', required: false, disabler: true)
-# mcqd is a header-only library
-if cc.has_header('mcqd.h')
+bliss = cc.find_library('bliss', required: get_option('bliss'), disabler: true)
+
+mcqd = disabler()
+if cc.has_header('mcqd.h', required: get_option('mcqd'))
+  # mcqd is a header-only library
   mcqd = declare_dependency()
-else
-  mcqd = disabler()
 endif
 cliquer = cc.find_library('cliquer', required: not is_windows, disabler: true)
 

src/sage/libs/coxeter3/meson.build

@@ -1,4 +1,8 @@
-coxeter3 = cc.find_library('coxeter3', required: false, disabler: true)
+coxeter3 = cc.find_library(
+  'coxeter3',
+  required: get_option('coxeter3'),
+  disabler: true,
+)
 py.install_sources(
   '__init__.py',
   'all__sagemath_coxeter3.py',

src/sage/libs/meson.build

@@ -1,4 +1,8 @@
-sirocco = cc.find_library('sirocco', required: false, disabler: true)
+sirocco = cc.find_library(
+  'sirocco',
+  required: get_option('sirocco'),
+  disabler: true,
+)
 # cannot be found via pkg-config
 ecl = cc.find_library('ecl', required: false, disabler: true)
 if not ecl.found() and not is_windows

src/sage/rings/polynomial/pbori/meson.build

@@ -1,8 +1,8 @@
-brial = cc.find_library('brial', required: false, disabler: true)
+brial = cc.find_library('brial', required: get_option('brial'), disabler: true)
 # Cannot be found via pkg-config
 brial_groebner = cc.find_library(
   'brial_groebner',
-  required: false,
+  required: get_option('brial'),
   disabler: true,
 )