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,125 @@ 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 a section
+to the project's ``pyproject.toml``, or as arguments when building
+the package using the :ref:`build config settings<how-to-guides-config-settings>`
+
+.. tab-set::
+
+    .. tab-item:: pyproject.toml
+        :sync: key_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', '...']
+
+    .. tab-item:: pypa/buid
+        :sync: key_pypa_build
+
+		.. code-block:: console
+
+			$ python -m build -Cdist-args="args"    \
+					  -Csetup-args="args"   \
+					  -Ccompile-args="args" \
+					  -Cinstall-args="args" .
+
+    .. tab-item:: pip
+        :sync: key_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: key_pyproject_toml
+
+        .. code-block:: console
+
+			 [tool.meson-python.args]
+			 dist = []
+			 setup = ['--default-library=static']
+			 compile = []
+			 install = []
+
+    .. tab-item:: pypa/build
+        :sync: key_pypa_build
+
+        .. code-block:: console
+
+			 $ python -m build -Csetup-args="--default-library=static" .
+
+    .. tab-item:: pip
+        :sync: key_pip
+
+        .. code-block:: console
+
+			 $ python -m pip --config-settings=setup-args="--default-library=static" .
+
+
+Example 2: use meson install_tags for selective installs
+========================================================
+
+Meson install_tags can be used (since ``meson-python`` >= 0.13) to select which
+targets are installed into the binary wheels. 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: key_pyproject_toml
+
+		.. code-block:: console
+
+			 [tool.meson-python.args]
+			 dist = []
+			 setup = []
+			 compile = []
+			 install = ['--tags=runtime,python-runtime']
+
+    .. tab-item:: pypa/build
+        :sync: key_pypa_build
+
+        .. code-block:: console
+
+			 $ python -m build -install-args="--tags=runtime,python-runtime" .
+
+    .. tab-item:: pip
+        :sync: key_pip
+
+        .. code-block:: console
+
+			$ python -m pip --config-settings=install-args="--tags=runtime,python-runtime" .
+
+
+.. admonition:: Meson installation tags
+	:class: seealso
+
+	Each meson target has a default install_tag (e.g. ``runtime`` for shared libraries and ``devel`` for headers.). Calling ``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
+
 
 .. _Meson: https://github.com/mesonbuild/meson