From cf6e2a7b87c627e7e4d2963086c0ac48c98e63b0 Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Thu, 14 Nov 2024 12:05:54 +0100 Subject: [PATCH] DOC: minor tweak to docs on invoking pip/build Addresses a comment on issue 704, where a user got tripped up by `python -m build` building an sdist first (and that's typically not what you want). Also fix up stray tab characters in how-to-guides/config-settings.rst --- docs/how-to-guides/config-settings.rst | 43 +++++++++++++------------- docs/how-to-guides/meson-args.rst | 8 ++--- docs/tutorials/introduction.rst | 3 ++ 3 files changed, 29 insertions(+), 25 deletions(-) diff --git a/docs/how-to-guides/config-settings.rst b/docs/how-to-guides/config-settings.rst index 75b02a81b..b2249e846 100644 --- a/docs/how-to-guides/config-settings.rst +++ b/docs/how-to-guides/config-settings.rst @@ -19,24 +19,25 @@ 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 \ - -Csetup-args="-Doption=true" \ - -Csetup-args="-Dvalue=1" \ - -Ccompile-args="-j6" + $ python -m build --wheel \ + -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 . \ - --config-settings=setup-args="-Doption=disable" \ - --config-settings=compile-args="-j6" + $ # note: for Pip <23.1, use `--config-settings=` instead of `-C` + $ python -m pip wheel . \ + -Csetup-args="-Doption=disable" \ + -Ccompile-args="-j6" Refer to the `build`_ and `pip`_ documentation for details. This @@ -73,19 +74,19 @@ user-specified build directory which will not be deleted. For example: .. 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 -Cbuild-dir=build + $ python -m build --wheel -Cbuild-dir=build - .. tab-item:: pip - :sync: key_pip + .. tab-item:: pip + :sync: key_pip - .. code-block:: console + .. code-block:: console - $ python -m pip install . -Cbuild-dir=build + $ python -m pip install . -Cbuild-dir=build After running this command, the ``build`` directory will contain all the build artifacts and support files created by ``meson``, ``ninja`` diff --git a/docs/how-to-guides/meson-args.rst b/docs/how-to-guides/meson-args.rst index 87ee68e1d..6db0a3f33 100644 --- a/docs/how-to-guides/meson-args.rst +++ b/docs/how-to-guides/meson-args.rst @@ -83,7 +83,7 @@ To set this option temporarily at build-time: .. code-block:: console - $ python -m build -Csetup-args="--default-library=static" . + $ python -m build -Csetup-args="--default-library=static" --wheel . .. tab-item:: pip :sync: key_pip @@ -125,7 +125,7 @@ To set this option temporarily at build-time: .. code-block:: console - $ python -m build -Cinstall-args="--tags=runtime,python-runtime" . + $ python -m build -Cinstall-args="--tags=runtime,python-runtime" --wheel . .. tab-item:: pip :sync: key_pip @@ -158,7 +158,7 @@ To set this option temporarily at build-time: .. code-block:: console - $ python -m build -Csetup-args="-Doptimization=3" . + $ python -m build -Csetup-args="-Doptimization=3" --wheel . .. tab-item:: pip :sync: key_pip @@ -199,7 +199,7 @@ To set this option temporarily at build-time: .. code-block:: console - $ python -m build -Csetup-args="--vsenv" . + $ python -m build -Csetup-args="--vsenv" --wheel . .. tab-item:: pip :sync: key_pip diff --git a/docs/tutorials/introduction.rst b/docs/tutorials/introduction.rst index 0c98c8987..c1d7325fb 100644 --- a/docs/tutorials/introduction.rst +++ b/docs/tutorials/introduction.rst @@ -242,6 +242,9 @@ dependencies, and ask ``meson-python`` to build the artifacts. $ python -m build If the build succeeded, you'll have the binary artifacts in the ``dist`` folder. +Note that by default, ``python -m build`` builds an sdist first, and then a +wheel from the sdist. If you only want one artifact, add ``--sdist`` or +``--wheel`` to the invocation. .. admonition:: Building wheels for multiple platforms :class: tip