DOC: add details on default build options used by meson-python

This follows up on the `n_debug` default added in gh-325,
documents all other default options and they are used, as well
as improves the page on using `pyproject.toml` settings.

docs/explanations/default-options.rst

@@ -0,0 +1,63 @@
+.. SPDX-FileCopyrightText: 2023 The meson-python developers
+..
+.. SPDX-License-Identifier: MIT
+
+.. _explanations-default-options:
+
+*********************
+Default build options
+*********************
+
+Meson offers many `built-in options <https://mesonbuild.com/Builtin-options.html>`__,
+and in the vast majority of cases those have good defaults. There are a couple
+of cases however where ``meson-python`` either is forced or chooses to override
+those with its own defaults. To view what those are for the version of
+``meson-python`` you have installed, look at the *User defined options* section
+of the output during the configure stage of the build (e.g., by running
+``python -m build --wheel``). This will look something like:
+
+.. code-block:: text
+
+    User defined options
+      Native files     : /home/username/code/project/.mesonpy-native-file.ini
+      debug            : false
+      optimization     : 2
+      prefix           : /home/username/mambaforge/envs/project-dev
+      python.platlibdir: /home/username/mambaforge/envs/project-dev/lib/python3.10/site-packages
+      python.purelibdir: /home/username/mambaforge/envs/project-dev/lib/python3.10/site-packages
+      b_ndebug         : if-release
+
+Let's go through each option and why they are used:
+
+- meson-python uses a native file, named ``.mesonpy-native-file.ini`` in order
+  to point Meson at the correct ``python`` interpreter to use (the same one for
+  which ``meson-python`` was installed). This is necessary, because Meson may
+  otherwise look for the first Python interpreter on the PATH (usually the same
+  one, but not always the case).
+- The ``prefix`` and ``platlibdir``/``purelibdir`` options also point Meson at
+  that same interpreter and the environment in which it is installed.
+- The ``debug``, ``optimization`` and ``b_ndebug`` options are overridden,
+  because Meson defaults to values that are appropriate for development, while
+  the main purpose of meson-python is to build release artifacts.
+
+It is possible to override these defaults, either permanently in your project
+or at build time. For example, to build a wheel with debug symbols, use:
+
+.. code-block:: bash
+
+   $ python -m build -Csetup-args=-Ddebug=true
+
+And to override all debug and optimization settings permanently, add this to
+your ``pyproject.toml`` file:
+
+.. code-block:: toml
+
+   [tool.meson-python.args]
+   setup = ['-Ddebug=true', '-Doptimization=0', '-Db_ndebug=false']
+   dist = []
+   compile = []
+   install = []
+
+For more details on overriding build options at build time see
+:ref:`here <reference-config-settings>`, and in ``pyproject.toml`` see
+:ref:`here <reference-pyproject-settings>`.

docs/index.rst

@@ -135,6 +135,7 @@ Contributors
    :hidden:
 
    explanations/design
+   explanations/default-options
    explanations/internal-dependencies
    explanations/editable-installs
 

docs/reference/pyproject-settings.rst

@@ -31,3 +31,19 @@ This page lists the configuration settings supported by ``meson-python`` in the
 
    * - ``tool.meson-python.args.install``
      - Extra arguments to be passed to the ``meson install`` command.
+
+Usage example:
+
+.. code-block:: toml
+
+   [tool.meson-python.args]
+   setup = ['-Dwarning_level=2', '-Db_pie=true']
+   dist = ['--include-subprojects']
+   compile = ['-j4']
+   install = ['--quiet']
+
+.. note::
+
+   At the moment it is necessary to specify all four arguments (``dist``,
+   ``setup```, ``compile`` and ``install``). This limitation will go away in a
+   future version.