Update README

Fixes: https://bugzilla.redhat.com/show_bug.cgi?id=1868346

- Explain what "provisional" means
- Say what kinds of projects the macros handle
- Tell people to BuidRequire python*-devel
- Say %pyproject_buildrequires is needed for the other macros
- Note that %pyproject_buildrequires generates `exit 11` messages
- Note that most buildsystems have prepare-metadata-for-build-wheel
This commit is contained in:
Petr Viktorin 2020-08-20 11:48:35 +02:00
parent 09be4c117d
commit fb4066b150

View File

@ -1,27 +1,54 @@
pyproject RPM macros
====================
This is a provisional implementation of pyproject RPM macros for Fedora.
These macros allow projects that follow the Python [packaging specifications]
to be packaged as RPMs.
These macros are useful for packaging Python projects that use the [PEP 517] `pyproject.toml` file, which specifies the package's build dependencies (including the build system, such as setuptools, flit or poetry).
They are still *provisional*: we can make non-backwards-compatible changes to
the API.
Please subscribe to Fedora's [python-devel list] if you use the macros.
They work for:
* traditional Setuptools-based projects that use the `setup.py` file,
* newer Setuptools-based projects that have a `setup.cfg` file,
* general Python projects that use the [PEP 517] `pyproject.toml` file (which allows using any build system, such as setuptools, flit or poetry).
These macros replace `%py3_build` and `%py3_install`, which only work with `setup.py`.
[packaging specifications]: https://packaging.python.org/specifications/
[python-devel list]: https://lists.fedoraproject.org/archives/list/python-devel@lists.fedoraproject.org/
Usage
-----
If your upstream sources include `pyproject.toml` and you want to use these macros, BuildRequire them:
To use these macros, first BuildRequire them:
BuildRequires: pyproject-rpm-macros
This will bring in python3-devel, so you don't need to require python3-devel explicitly.
Also BuildRequire the devel package for the Python you are building against.
In Fedora, that's `python3-devel`.
(In the future, we plan to make `python3-devel` itself require
`pyproject-rpm-macros`.)
In order to get automatic build dependencies on Fedora 31+, run `%pyproject_buildrequires` in the `%generate_buildrequires` section:
Next, you need to generate more build dependencies (of your projects and
the macros themselves) by running `%pyproject_buildrequires` in the
`%generate_buildrequires` section:
%generate_buildrequires
%pyproject_buildrequires
Only build dependencies according to [PEP 517] and [PEP 518] will be added.
All other build dependencies (such as non-Python libraries or test dependencies) still need to be specified manually.
This will add build dependencies according to [PEP 517] and [PEP 518].
To also add run-time and test-time dependencies, see the section below.
If you need more dependencies, such as non-Python libraries, BuildRequire
them manually.
Note that `%generate_buildrequires` may produce error messages `(exit 11)` in
the build log. This is expected behavior of BuildRequires generators; see
[the Fedora change] for details.
[the Fedora change]: https://fedoraproject.org/wiki/Changes/DynamicBuildRequires
Then, build a wheel in `%build` with `%pyproject_wheel`:
@ -33,7 +60,8 @@ And install the wheel in `%install` with `%pyproject_install`:
%install
%pyproject_install
`%pyproject_install` installs all wheels in `$PWD/pyproject-wheeldir/`. If you would like to save wheels somewhere else redefine `%{_pyproject_wheeldir}`.
`%pyproject_install` installs all wheels in `$PWD/pyproject-wheeldir/`.
If you would like to save wheels somewhere else, redefine `%{_pyproject_wheeldir}`.
Adding run-time and test-time dependencies
@ -41,13 +69,15 @@ Adding run-time and test-time dependencies
To run tests in the `%check` section, the package's runtime dependencies
often need to also be included as build requirements.
If the project's build system supports the [`prepare-metadata-for-build-wheel`
hook](https://www.python.org/dev/peps/pep-0517/#prepare-metadata-for-build-wheel),
this can be done using the `-r` flag:
This can be done using the `-r` flag:
%generate_buildrequires
%pyproject_buildrequires -r
For this to work, the project's build system must support the
[`prepare-metadata-for-build-wheel` hook](https://www.python.org/dev/peps/pep-0517/#prepare-metadata-for-build-wheel).
The popular buildsystems (setuptools, flit, poetry) do support it.
For projects that specify test requirements using an [`extra`
provide](https://packaging.python.org/specifications/core-metadata/#provides-extra-multiple-use),
these can be added using the `-x` flag.
@ -93,7 +123,8 @@ Running tox based tests
-----------------------
In case you want to run the tests as specified in [tox] configuration,
you can use the `%tox` macro:
you must use `%pyproject_buildrequires` with `-t` or `-e` as explained above.
Then, use the `%tox` macro in `%check`:
%check
%tox
@ -126,10 +157,6 @@ Or (note the two sequential `--`s):
%tox -- -- --flag-for-posargs
**Warning:** This macro assumes you have used `%pyproject_buildrequires -t` or `-e`
in `%generate_buildrequires`. If not, you need to add:
BuildRequires: python3dist(tox-current-env)
Generating the %files section