From 98f0c48fd901dd014832a4d16d352d7de5a6cf73 Mon Sep 17 00:00:00 2001 From: "sapunyangkut 302607731+sapunyangkut@users.noreply.github.com[0]" Date: Tue, 14 Jul 2026 11:03:32 +0800 Subject: [PATCH] DOC: clarify handling of install arguments --- docs/how-to-guides/meson-args.rst | 46 ++++++++++++++++++++------ docs/reference/config-settings.rst | 4 ++- docs/reference/meson-compatibility.rst | 6 ++-- docs/reference/pyproject-settings.rst | 4 ++- 4 files changed, 44 insertions(+), 16 deletions(-) diff --git a/docs/how-to-guides/meson-args.rst b/docs/how-to-guides/meson-args.rst index e543e5a6b..d7f4305cb 100644 --- a/docs/how-to-guides/meson-args.rst +++ b/docs/how-to-guides/meson-args.rst @@ -8,18 +8,20 @@ Passing arguments to Meson ************************** -``meson-python`` invokes the ``meson setup``, ``ninja``, and ``meson -install`` commands to build the files that will be included in the +``meson-python`` invokes ``meson setup`` and either ``ninja`` or +``meson compile`` to build the files that will be included in the Python wheel, and ``meson dist`` to collect the files that will be -included in the Python sdist. Arguments can be passed to these -commands to modify their behavior. Refer to the `Meson documentation`_ -and to the `ninja documentation`_ for details. +included in the Python sdist. It does not invoke ``meson install``; +instead, it reads Meson's install plan and maps the files listed there +into the wheel. Arguments can be passed to the invoked commands or +used to filter the install plan, as described below. Refer to the +`Meson documentation`_ and to the `ninja documentation`_ for details. .. _Meson documentation: https://mesonbuild.com/Commands.html .. _ninja documentation: https://ninja-build.org/manual.html#_running_ninja -Command line arguments for ``meson`` and ``ninja`` can be specified -via tool specific settings in ``pyproject.toml`` as lists of strings +Arguments can be specified via tool specific settings in +``pyproject.toml`` as lists of strings for the ``setup``, ``compile``, ``install``, and ``dist`` keys in the ``tool.meson-python.args`` table. For example: @@ -59,6 +61,29 @@ documentation`__ for more details. __ https://mesonbuild.com/Commands.html#backend-specific-arguments +.. _how-to-guides-meson-args-install: + +Install arguments +================= + +The ``install`` project setting and ``install-args`` build config +setting do not pass arguments to a ``meson install`` command. +``meson-python`` recognizes these options while filtering Meson's +install plan: + +``--tags=TAG,...`` + Include only files whose install tag is listed. + +``--skip-subprojects[=NAME,...]`` + Exclude files installed by every subproject when no name is given, + or by the named subprojects otherwise. This requires Meson 1.2.0 + or later. + +All other ``meson install`` options are ignored with a warning. +Because the command is not run, scripts registered with +``meson.add_install_script()`` are not executed when building a wheel. + + Examples ======== @@ -97,10 +122,9 @@ Select the build targets to include in the wheel ------------------------------------------------ It is possible to include in the Python wheel only a subset of the -installable files using Meson `installation tags`_ via the ``meson -install``'s ``--tags`` command line option. When ``--tags`` is -specified, only files that have one of the specified the tags are -going to be installed. +installable files using Meson `installation tags`_ and the ``--tags`` +install argument. When ``--tags`` is specified, only files with one of +the specified tags are included in the wheel. Meson sets predefined tags on some files. Custom installation tags can be set using the ``install_tag`` keyword argument passed to the target diff --git a/docs/reference/config-settings.rst b/docs/reference/config-settings.rst index 4749b8fef..3f8f22ff0 100644 --- a/docs/reference/config-settings.rst +++ b/docs/reference/config-settings.rst @@ -40,7 +40,9 @@ them. .. option:: install-args - Extra arguments to be passed to the ``meson install`` command. + Options interpreted by ``meson-python`` when filtering Meson's + install plan. See :ref:`how-to-guides-meson-args-install` for the + supported options. .. option:: editable-verbose diff --git a/docs/reference/meson-compatibility.rst b/docs/reference/meson-compatibility.rst index 73258e73a..2e34a8156 100644 --- a/docs/reference/meson-compatibility.rst +++ b/docs/reference/meson-compatibility.rst @@ -28,9 +28,9 @@ versions. .. option:: 1.2.0 - Meson 1.2.0 or later is required to support the ``--skip-subprojects`` - option that can be passed to ``meson install`` to not include files - installed by some or all subprojects in the Python wheel. + Meson 1.2.0 or later is required for ``meson-python`` to honor the + ``--skip-subprojects`` option when filtering files for the Python + wheel. .. option:: 1.2.3 diff --git a/docs/reference/pyproject-settings.rst b/docs/reference/pyproject-settings.rst index 0dab117b9..ceb5a0e9f 100644 --- a/docs/reference/pyproject-settings.rst +++ b/docs/reference/pyproject-settings.rst @@ -68,7 +68,9 @@ use them and examples. .. option:: tool.meson-python.args.install - Extra arguments to be passed to the ``meson install`` command. + Options interpreted by ``meson-python`` when filtering Meson's + install plan. See :ref:`how-to-guides-meson-args-install` for the + supported options. .. option:: tool.meson-python.wheel.exclude