Understanding of the Declarative builds, Python edition

[hroncok]

Hello. I've just located #1087 in https://fedoraproject.org/wiki/Changes/RPM-4.20 and I've read https://rpm-software-management.github.io/rpm/manual/buildsystem.html

I am trying to understand how to use this, so let's dive in.

Suppose I currently have this specfile simplified from https://docs.fedoraproject.org/en-US/packaging-guidelines/Python/#_example_spec_file

Name:                 python-pello
Version:              1.0.4
Release:              1%{?dist}
Summary:              Example Python library

License:              MIT-0
URL:                  https://github.com/fedora-python/Pello
Source:               %{url}/archive/v%{version}/Pello-%{version}.tar.gz

BuildArch:            noarch

%description
...

%package -n python3-pello
Summary:              %{summary}
Recommends:           python3-pello+color

%description -n python3-pello
...


%pyproject_extras_subpkg -n python3-pello color

%prep
%autosetup -p1 -n Pello-%{version}


%generate_buildrequires
%pyproject_buildrequires -t


%build
%pyproject_wheel


%install
%pyproject_install
%pyproject_save_files -l pello


%check
%pyproject_check_import
%tox


%files -n python3-pello -f %{pyproject_files}
%doc README.md
%{_bindir}/pello_greeting


%changelog

---

If I defined the following macros (in any macro file?):

%buildsystem_pyproject_generate_buildrequires(rRxtNwe:C:) %pyproject_buildrequires %**
%buildsystem_pyproject_build(C:) %pyproject_wheel %**
%buildsystem_pyproject_install(l) %pyproject_install %["%**" == "" ? "" : "\
%pyproject_save_files %**"]
%buildsystem_pyproject_check(e:t) %pyproject_check_import %**

The spec could be simplified as such:

Name:                 python-pello
Version:              1.0.4
Release:              1%{?dist}
Summary:              Example Python library

License:              MIT-0
URL:                  https://github.com/fedora-python/Pello
Source:               %{url}/archive/v%{version}/Pello-%{version}.tar.gz

BuildArch:            noarch

BuildSystem:          pyproject
BuildOption(prep):    -n Pello-%{version}
BuildOption(generate_buildrequires): -t
BuildOption(install): -l pello

%description
...

%package -n python3-pello
Summary:              %{summary}
Recommends:           python3-pello+color

%description -n python3-pello
...

%pyproject_extras_subpkg -n python3-pello color


%check -a
%tox


%files -n python3-pello -f %{pyproject_files}
%doc README.md
%{_bindir}/pello_greeting


%changelog

Is that assumption correct?

(And as a side question, with #2859 we would not even need to set BuildOption(prep), right?)

[pmatilai]

That's the essence of it, yes.

There might be something else in the details I missed, but one thing that did catch my eye:
the %buildsystem_foo_install() and such macros do not take options currently because they'd be shared across all buildsystems. So eg %buildsystem_pyproject_check(e:t) will not do what you intend, there's no way to pass options to the buildsystem macro itself. What you pass to BuildOption(): will get passed as an argument (ie after --) to this macro, which you just pass along to the thing actually implementing it - such as %pyproject_* here.

As for #2859, the new -C flag is not automatically enabled anywhere just now, it probably should be in %buildsystem_default_prep() though, that's a good point.

[hroncok]

As long as it won't tell me Unknown option l in buildsystem_pyproject_install but let me pass any option further down via %**, good (even better, so I won't have to duplicate the option list).

[hroncok]

Should I open an issue for -C to be the default for BuildOption(prep)?

[pmatilai]

That would be good so it wont go forgotten, yeah.

[hroncok]

#2998

[pmatilai]

On that note, don't hesitate to point out shortcomings or other new related ideas. I'm too close to the source (in both meanings 😄 ) to see clearly, as the -C example points out.

[pmatilai]

FWIW, I revived my rpm-snapshot repository where you can get Fedora compatible builds from rpm so if folks want to try this out before the soon-to-be-released 4.20 alpha, there goes: git: https://copr.fedorainfracloud.org/coprs/pmatilai/rpm-snapshot/

[pmatilai]

FWIW, turns out this stuff is pretty crippled in the alpha release due to these two issues:
#3024
#2204

They don't prevent one from developing buildsystems but pretty much prevent using them in real-world packages where local tweaks are needed 😞

[hroncok]

If you are interested, here is my first draft implementation of this: https://src.fedoraproject.org/rpms/pyproject-rpm-macros/pull-request/455

[dreua]

I just stumbled over this as five package already use this new "BuildSystem: pyproject" approach but I can't find any official documentation. If this is already in use and accepted for Fedora packaging it should be mentioned in the packaging guidelines imho. (Maybe I just need to be more patient? 🤔 )

Edit: It is actually 12 packages, I just stumbled over those 5 which don't have an %install section.

[hroncok]

The documentation is at pyproject-rpm-macros README -- see the Provisional: Declarative Buildsystem (RPM 4.20+) section (sorry, no anchor).

I generally don't put provisional stuff into the Python guidelines. PAckagers are free to use it, but we don't encourage them to do so unless they know what they are doing.

To lift the provisional status, I was waiting for this to happen:

• copr updates builds to Fedora 41+ Upgrade Fedora Copr builders to Fedora 41 fedora-copr/copr#3270
• Zuul to use Fedora 41+ (no ticket yet)
• early adopters actually usethis (already happens, as you mention) and report issues
• Fedora 40 to go end of life (optional: if this is the last option, it can be omitted)

[hroncok]

Alas, for your use case, you wanted documentation for Declarative Buildsystems generally, which is available in https://rpm-software-management.github.io/rpm/manual/buildsystem.html

[dreua]

Thanks, I was searching for the meaning of "BuildSystem: pyproject" and didn't see anything from the Fedora domains so this discussion here looked the most interesting on the search results. Your first link is what I was looking for at the moment, saying that it is new, provisional and able to replace the install section (among others). That helped a lot 👍

[pmatilai]

If you are interested, here is my first draft implementation of this: https://src.fedoraproject.org/rpms/pyproject-rpm-macros/pull-request/455

This is of course several months late, missed originally due to vacation, but most certainly have been looking forward to real-world uses, lab testing only gets you so far.

From a quick look, my takeaways are:

• Spec backwards compatibility is a bit of a pain point, there might be some value in teaching rpm 4.19 to parse (but not build) specs utilitizing buildsystem constructs, considering 4.19 will live for a long long time in RHEL 10
• having a generic way to declare mandatory options could be handy

Anything else that's not so immediately obvious?

[hroncok]

Having a way to pass arbitrary options not named after the sections would be great.

1. I'd declare my build backend supports e.g. BuildOption(modules) and say it's mandatory/optional
2. I can read the value from a well known macro, in any section