Skip to content

DOC: minor tweak to docs on invoking pypa/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

Merged
merged 1 commit into from
Nov 1, 2025
Merged

DOC: minor tweak to docs on invoking pypa/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
17 changes: 8 additions & 9 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 @@ -24,7 +24,7 @@ the ``-C`` short command line option:

.. code-block:: console

$ python -m build \
$ python -m build --wheel \
-Csetup-args="-Doption=true" \
-Csetup-args="-Dvalue=1" \
-Ccompile-args="-j6"
Expand All @@ -34,12 +34,11 @@ the ``-C`` short command line option:

.. code-block:: console

$ python -m pip wheel . \
$ python -m pip wheel . \
-Csetup-args="-Doption=true" \
-Csetup-args="-Dvalue=1" \
-Ccompile-args="-j6"


Refer to the `build`_ and `pip`_ documentation for details. This
example uses the ``python -m pip wheel`` command to build a Python wheel
that can be later installed or distributed. To build a package and
Expand Down Expand Up @@ -76,18 +75,18 @@ For example:
.. tab-set::

.. tab-item:: pypa/build
:sync: key_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
: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
10 changes: 5 additions & 5 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 --wheel -Csetup-args="--default-library=static" .

.. 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 --wheel -Cinstall-args="--tags=runtime,python-runtime" .

.. 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 --wheel -Csetup-args="-Doptimization=3" .

.. tab-item:: pip
:sync: key_pip
Expand Down Expand Up @@ -207,11 +207,11 @@ To set this option temporarily at build-time:

.. code-block:: console

$ python -m build -Csetup-args="--vsenv" .
$ python -m build --wheel -Csetup-args="--vsenv" .

.. tab-item:: pip
:sync: key_pip

.. code-block:: console

$ python -m pip wheel -Csetup-args="--vsenv" .
$ python -m pip wheel -Csetup-args="--vsenv" .
6 changes: 5 additions & 1 deletion docs/tutorials/introduction.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -228,7 +228,8 @@ Building the project

Before continuing, ensure you have committed the three files we created so far
to your Git repository - ``meson-python`` will only take into account the files
that Git knows about.
that Git knows about, and an sdist is created from the most recent commit -
uncommitted changes are ignored.
Copy link
Member

Choose a reason for hiding this comment

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

This paragraph is very confusing. What is committed only affects what gets into an sdist, but this section is actually about building a wheel. I think this paragraph needs to be removed and the note about uncommitted changes moved below.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

It's about both sdist and wheels. It's part of the "Creating your first release" section, and clearly does talk about both.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I'm happy to change it to an admonition while we're at it, but I really just want to get this PR in - it was about adding the --wheel flag and not related to the commit status of files at all.

Copy link
Member

Choose a reason for hiding this comment

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

This does not make this paragraph worse, so we can merge this PR and fix this part of the documentation later.


To generate the distribution artifacts we will use the `pypa/build`_ tool. It
will create a temporary virtual environment, install all the required build
Expand All @@ -240,6 +241,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).

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Added a note on uncommitted changes two paragraphs up, where it already talks about Git.


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