Skip to content

DOC: minor tweak to docs on invoking pip/build #707

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

DOC: minor tweak to docs on invoking pip/build #707

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 22 additions & 21 deletions docs/how-to-guides/config-settings.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we assume pip 23.1 or later in the example, it would be nice to use the same configuration arguments for the build and pip examples. The only reason why these were different is that earlier pip did not allow to specify the same configuration key multiple times. I would also remove the note in the comment here and move it to the admonition block just below, that could be retitled "pip version 23.1 and earlier" or something like that, and explain the different command line argument and the limitation. These versions of pip are starting to be ancient history, anyway.

If we switch this example to use -C instead of --config-settings, I think we should do the same for every other example using pip too.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good idea, will make that change. pip 23.1 is old enough by now



Refer to the `build`_ and `pip`_ documentation for details. This
Expand Down Expand Up @@ -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``
Expand Down
8 changes: 4 additions & 4 deletions docs/how-to-guides/meson-args.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 .
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be nice to always use the same order of the argument in the examples, namely move --wheel before -C. Here and in all other instances too.


.. tab-item:: pip
:sync: key_pip
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
3 changes: 3 additions & 0 deletions docs/tutorials/introduction.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that this misses the main point. The issue in not the extra work for building an sdist that will not be used, but that doing so any uncommitted change in the repository is not reflected in the wheel.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah good point, will add that as the first point since it's indeed a footgun. I think both can be relevant; sdist creation for a large project can be really slow (a quick unscientific measurement says 40 seconds for scipy at the moment, and it might breaking caching on rebuilds as well).


.. admonition:: Building wheels for multiple platforms
:class: tip
Expand Down