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,98 @@ 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:: console
+
+   [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: [])
+
+Or using the build config settings:
+
+.. code-block:: console
+
+   # with pypa/build
+   python -m build -Cdist-args="args"    \
+                   -Csetup-args="args"   \
+                   -Ccompile-args="args" \
+                   -Cinstall-args="args" .
+
+   # with pip
+   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 = []
+
+Or using build config settings:
+
+.. code-block:: console
+
+   # with pypa/build
+   python -m build -Csetup-args="--default-library=static" .
+
+   # with pip
+   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. Ffor 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']
+
+Or using build config settings:
+
+.. code-block:: console
+
+   # with pypa/build
+   python -m build -install-args="--tags=runtime,python-runtime" .
+
+   # with pip
+   python -m pip --config-settings=install-args="--tags=runtime,python-runtime" .
+
 
 .. _Meson: https://github.com/mesonbuild/meson