From 1af4352db4ffd133155f5a18e0f68d28865f0240 Mon Sep 17 00:00:00 2001 From: Daniele Nicolodi Date: Fri, 31 Oct 2025 23:05:21 +0100 Subject: [PATCH 1/2] DOC: fix white space --- docs/how-to-guides/config-settings.rst | 16 +++---- docs/how-to-guides/meson-args.rst | 64 +++++++++++++------------- 2 files changed, 40 insertions(+), 40 deletions(-) diff --git a/docs/how-to-guides/config-settings.rst b/docs/how-to-guides/config-settings.rst index ee750fff2..c14fcff02 100644 --- a/docs/how-to-guides/config-settings.rst +++ b/docs/how-to-guides/config-settings.rst @@ -19,22 +19,22 @@ the ``-C`` short command line option: .. tab-set:: - .. tab-item:: pypa/build - :sync: key_pypa_build + .. tab-item:: pypa/build + :sync: key_pypa_build - .. code-block:: console + .. code-block:: console - $ python -m build \ + $ python -m build \ -Csetup-args="-Doption=true" \ -Csetup-args="-Dvalue=1" \ -Ccompile-args="-j6" - .. tab-item:: pip - :sync: key_pip + .. tab-item:: pip + :sync: key_pip - .. code-block:: console + .. code-block:: console - $ python -m pip wheel . \ + $ python -m pip wheel . \ --config-settings=setup-args="-Doption=disable" \ --config-settings=compile-args="-j6" diff --git a/docs/how-to-guides/meson-args.rst b/docs/how-to-guides/meson-args.rst index 87ee68e1d..6cb77e4d1 100644 --- a/docs/how-to-guides/meson-args.rst +++ b/docs/how-to-guides/meson-args.rst @@ -78,19 +78,19 @@ To set this option temporarily at build-time: .. tab-set:: - .. tab-item:: pypa/build - :sync: key_pypa_build + .. tab-item:: pypa/build + :sync: key_pypa_build - .. code-block:: console + .. code-block:: console - $ python -m build -Csetup-args="--default-library=static" . + $ python -m build -Csetup-args="--default-library=static" . - .. tab-item:: pip - :sync: key_pip + .. tab-item:: pip + :sync: key_pip - .. code-block:: console + .. code-block:: console - $ python -m pip wheel --config-settings=setup-args="--default-library=static" . + $ python -m pip wheel --config-settings=setup-args="--default-library=static" . Select the build targets to include in the wheel @@ -120,19 +120,19 @@ To set this option temporarily at build-time: .. tab-set:: - .. tab-item:: pypa/build - :sync: key_pypa_build + .. tab-item:: pypa/build + :sync: key_pypa_build - .. code-block:: console + .. code-block:: console - $ python -m build -Cinstall-args="--tags=runtime,python-runtime" . + $ python -m build -Cinstall-args="--tags=runtime,python-runtime" . - .. tab-item:: pip - :sync: key_pip + .. tab-item:: pip + :sync: key_pip - .. code-block:: console + .. code-block:: console - $ python -m pip wheel --config-settings=install-args="--tags=runtime,python-runtime" . + $ python -m pip wheel --config-settings=install-args="--tags=runtime,python-runtime" . Set the build optimization level @@ -153,19 +153,19 @@ To set this option temporarily at build-time: .. tab-set:: - .. tab-item:: pypa/build - :sync: key_pypa_build + .. tab-item:: pypa/build + :sync: key_pypa_build - .. code-block:: console + .. code-block:: console - $ python -m build -Csetup-args="-Doptimization=3" . + $ python -m build -Csetup-args="-Doptimization=3" . - .. tab-item:: pip - :sync: key_pip + .. tab-item:: pip + :sync: key_pip - .. code-block:: console + .. code-block:: console - $ python -m pip wheel --config-settings=setup-args="-Doptimization=3" . + $ python -m pip wheel --config-settings=setup-args="-Doptimization=3" . .. _vsenv-example: @@ -194,16 +194,16 @@ To set this option temporarily at build-time: .. tab-set:: - .. tab-item:: pypa/build - :sync: key_pypa_build + .. tab-item:: pypa/build + :sync: key_pypa_build - .. code-block:: console + .. code-block:: console - $ python -m build -Csetup-args="--vsenv" . + $ python -m build -Csetup-args="--vsenv" . - .. tab-item:: pip - :sync: key_pip + .. tab-item:: pip + :sync: key_pip - .. code-block:: console + .. code-block:: console - $ python -m pip wheel --config-settings=setup-args="--vsenv" . + $ python -m pip wheel --config-settings=setup-args="--vsenv" . From 9154e95c58c076327c3f78dc85d09632e1ec0b57 Mon Sep 17 00:00:00 2001 From: Daniele Nicolodi Date: Fri, 31 Oct 2025 23:11:09 +0100 Subject: [PATCH 2/2] DOC: assume pip 23.1 or later in examples Add a note about the command line syntax for older versions. --- docs/how-to-guides/config-settings.rst | 20 +++++++++++--------- docs/how-to-guides/editable-installs.rst | 2 +- docs/how-to-guides/meson-args.rst | 8 ++++---- 3 files changed, 16 insertions(+), 14 deletions(-) diff --git a/docs/how-to-guides/config-settings.rst b/docs/how-to-guides/config-settings.rst index c14fcff02..715f93aef 100644 --- a/docs/how-to-guides/config-settings.rst +++ b/docs/how-to-guides/config-settings.rst @@ -35,8 +35,9 @@ the ``-C`` short command line option: .. code-block:: console $ python -m pip wheel . \ - --config-settings=setup-args="-Doption=disable" \ - --config-settings=compile-args="-j6" + -Csetup-args="-Doption=true" \ + -Csetup-args="-Dvalue=1" \ + -Ccompile-args="-j6" Refer to the `build`_ and `pip`_ documentation for details. This @@ -46,15 +47,16 @@ immediately install it, replace ``wheel`` with ``install``. See the :ref:`how-to-guides-meson-args` guide for more examples. -.. admonition:: Passing multiple settings +.. admonition:: Older pip versions :class: caution - Please note that ``pip`` prior to 23.1 did not offer a way to set a - build config setting to a list of strings: later values for the - same key passed to ``--config-settings`` override earlier ones, - effectively limiting the number of options that can be passed to - each command invoked in the build process to one. This limitation - has been lifted in ``pip`` release 23.1. + Please note that prior to version 23.1 ``pip`` did not support the ``-C`` + short command line switch for the ``--config-settings`` options and did not + offer a way to set a build config setting to a list of strings: later + values for the same key passed to ``--config-settings`` override earlier + ones, effectively limiting the number of options that can be passed to each + command invoked in the build process to one. This limitation has been + lifted in ``pip`` release 23.1. .. _build: https://pypa-build.readthedocs.io/en/stable/ diff --git a/docs/how-to-guides/editable-installs.rst b/docs/how-to-guides/editable-installs.rst index 54bfb3645..12cc8a4c1 100644 --- a/docs/how-to-guides/editable-installs.rst +++ b/docs/how-to-guides/editable-installs.rst @@ -178,4 +178,4 @@ set to a non-null value when installing the package: .. code-block:: console - $ python -m pip install --no-build-isolation --config-settings=editable-verbose=true --editable . + $ python -m pip install --no-build-isolation -Ceditable-verbose=true --editable . diff --git a/docs/how-to-guides/meson-args.rst b/docs/how-to-guides/meson-args.rst index 6cb77e4d1..901002fba 100644 --- a/docs/how-to-guides/meson-args.rst +++ b/docs/how-to-guides/meson-args.rst @@ -90,7 +90,7 @@ To set this option temporarily at build-time: .. code-block:: console - $ python -m pip wheel --config-settings=setup-args="--default-library=static" . + $ python -m pip wheel -Csetup-args="--default-library=static" . Select the build targets to include in the wheel @@ -132,7 +132,7 @@ To set this option temporarily at build-time: .. code-block:: console - $ python -m pip wheel --config-settings=install-args="--tags=runtime,python-runtime" . + $ python -m pip wheel -Cinstall-args="--tags=runtime,python-runtime" . Set the build optimization level @@ -165,7 +165,7 @@ To set this option temporarily at build-time: .. code-block:: console - $ python -m pip wheel --config-settings=setup-args="-Doptimization=3" . + $ python -m pip wheel -Csetup-args="-Doptimization=3" . .. _vsenv-example: @@ -206,4 +206,4 @@ To set this option temporarily at build-time: .. code-block:: console - $ python -m pip wheel --config-settings=setup-args="--vsenv" . + $ python -m pip wheel -Csetup-args="--vsenv" .