DOC: draft for meson-args.rst

This is a draft for the (how to) meson-args
documentation

Author: peter-urban

docs/how-to-guides/meson-args.rst

@@ -8,7 +8,6 @@
 Passing arguments to Meson_
 ***************************
 
-
 .. todo::
 
    - Explain how you can add extra Meson arguments via ``pyproject.toml``
@@ -17,5 +16,104 @@ Passing arguments to Meson_
    - Mention the order in which Meson arguments are added, and how it affect
      Meson
 
+Advanced meson options can be accessed by specifying extra arguments to the individual meson comands:
+
+   - meson dist: https://mesonbuild.com/Commands.html#dist
+   - meson setup: https://mesonbuild.com/Commands.html#setup
+   - meson compile: https://mesonbuild.com/Commands.html#compile
+   - meson install: https://mesonbuild.com/Commands.html#install
+
+These arguments can be added to the project via the project's ``pyproject.toml``:
+
+.. code-block::
+
+   [tool.meson-python.args]
+   dist    = ['dist-argument_1', 'dist-argument_2', '...']
+   setup   = ['setup-argument_1', 'setup-argument_2', '...']
+   compile = ['compile-argument_1', 'compile-argument_2', '...']
+   install = ['install-argument_1', 'install-argument_2', '...']
+
+.. admonition:: All four categories must exist
+   :class: attention
+
+   Currently all four option categories (``dist``, ``setup``, ``compile`` and ``install``) must be present in the [tool.meson-python.args] section, even if no arguments are supplied (empty list: [])
+
+Using the build config settings (with pypa/build):
+
+.. code-block:: console
+
+   $ python -m build -Cdist-args="args"    \
+                     -Csetup-args="args"   \
+                     -Ccompile-args="args" \
+                     -Cinstall-args="args" .
+
+Or using pip:
+
+.. code-block:: console
+
+   $ python -m pip --config-settings=dist-args="args"    \
+                   --config-settings=setup-args="args"   \
+                   --config-settings=compile-args="args" \
+                   --config-settings=install-args="args" .
+
+
+Example 1: set the default libraries to *static*
+================================================
+
+Set the target default libraries to "static" in the pyproject.toml
+
+.. code-block:: console
+
+   [tool.meson-python.args]
+   dist = []
+   setup = ['--default-library=static']
+   compile = []
+   install = []
+
+Using the build config settings (with pypa/build):
+
+.. code-block:: console
+
+   python -m build -Csetup-args="--default-library=static" .
+
+Or using pip:
+
+.. code-block:: console
+
+   python -m pip --config-settings=setup-args="--default-library=static" .
+
+
+Example 2: use meson install_tags for selective installs
+========================================================
+
+It is now (``meson-python`` >= 0.13) possible to use meson install_tags to select which targets are installed into the binary wheels.
+
+.. admonition:: Meson installation tags
+   :class: seealso
+
+   Each meson target has a default install_tag (e.g. ``runtime`` for shared libraries and ``devel`` for headers.). Using ``meson install --tags=tag1,tag2,...`` will cause meson to only install the targets tagges with any of the specified tags. The default tag of each target can be overwritten using the target's "install_tag" option. For more information refer mesons documentation in installation-tags: https://mesonbuild.com/Installing.html#installation-tags
+
+The following code (in pyproject.toml) causes meson-python to only install targets tagged with ``runtime`` or ``python-runtime``) into the binary wheel (ignoring e.g. C++ headers):
+
+.. code-block:: console
+
+   [tool.meson-python.args]
+   dist = []
+   setup = []
+   compile = []
+   install = ['--tags=runtime,python-runtime']
+
+Using the build config settings (with pypa/build):
+
+.. code-block:: console
+
+   $ python -m build -install-args="--tags=runtime,python-runtime" .
+
+Or using pip:
+
+.. code-block:: console
+
+   $ python -m pip --config-settings=install-args="--tags=runtime,python-runtime" .
+
 
 .. _Meson: https://github.com/mesonbuild/meson