DOC: add documentation 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,117 @@ 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 commands:
+
+   - 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 by adding the following section to 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', '...']
+
+Alternatively they can be added when building the package using the :ref:`build config settings<how-to-guides-config-settings>`:
+
+.. tab-set::
+
+    .. tab-item:: pypa/buid
+
+		.. code-block:: console
+
+			$ python -m build -Cdist-args="args"    \
+					  -Csetup-args="args"   \
+					  -Ccompile-args="args" \
+					  -Cinstall-args="args" .
+
+    .. tab-item:: 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"
+
+.. tab-set::
+
+    .. tab-item:: pyproject.toml
+        :sync: key1
+
+        .. code-block:: console
+
+			 [tool.meson-python.args]
+			 dist = []
+			 setup = ['--default-library=static']
+			 compile = []
+			 install = []
+
+    .. tab-item:: pypa/build
+        :sync: key2
+
+        .. code-block:: console
+
+			 $ python -m build -Csetup-args="--default-library=static" .
+
+    .. tab-item:: pip
+        :sync: key3
+
+        .. code-block:: console
+
+			 $ python -m pip --config-settings=setup-args="--default-library=static" .
+
+
+Example 2: use meson install_tags for selective installs
+========================================================
+
+Since ``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 tagged 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
+
+This example causes meson-python to only install targets tagged with ``runtime`` or ``python-runtime``) into the binary wheel (ignoring e.g. C++ headers):
+
+.. tab-set::
+
+    .. tab-item:: pyproject.toml
+        :sync: key1
+		
+		.. code-block:: console
+
+			 [tool.meson-python.args]
+			 dist = []
+			 setup = []
+			 compile = []
+			 install = ['--tags=runtime,python-runtime']
+
+    .. tab-item:: pypa/build
+        :sync: key2
+
+        .. code-block:: console
+
+			 $ python -m build -install-args="--tags=runtime,python-runtime" .
+
+    .. tab-item:: pip
+        :sync: key3
+
+        .. code-block:: console
+
+			$ python -m pip --config-settings=install-args="--tags=runtime,python-runtime" .
+
 
 .. _Meson: https://github.com/mesonbuild/meson