#1472 Hare: First draft for packaging guidelines
Opened by dridi. Modified
dridi/packaging-committee hare_guidelines  into  master

Download 1472.patch

These guidelines are based on the initial Hare packaging targeted at Fedora 43. Most aspects are covered, only the customization of build tags is missing, albeit being possible with the RPM macros provided by the candidate package.


I'm submitting this with the intention to add the ChangeReadyForWrangler category to the self-contained change. I have been dog-fooding this for a while now, and all the patches I wrote to support all the Fedora packaging use cases were merged upstream, making the latest release usable out of the box for mostly-automated RPM packaging.

I think it'd be better if hare itself or a hare-filesystem package owned the parent directory instead and then packages would explicitly state the subdirectories that they include and then depend on the package that owns the directories.

Adding the HAREFLAGS definition to %set_build_flags is probably preferable so the HAREFLAGS environment variable gets set automatically for all packages.

Should hare depend on gcc if it's needed to compile hare programs instead of requiring that each package depend on it explicitly?

%forgeautosetup -p1 or %autosetup -p1 %{forgesetupargs} is preferable so that any patches get applied automatically.

Is there a mixture of tabs and spaces here? This line and then one after don't look correctly aligned.

Thanks for the quick turnaround, I will address each point here.

The hare package owns /usr/src/hare and /usr/src/hare/third-party where other packages can drop their own directories. Hare modules don't strictly need to pull the hare package, and owning a couple directories has much less overhead than a filesystem package.

My take here is that a filesystem package would add more moving parts, while co-owning two directories is much simple. If it's an absolute requirement, I will do it, but making the module maintainers change one line in the %file section seemed like a better compromise than adding a hare-filesystem package, especially with an off-the-shelf %hare_srcdir macro.

Adding the HAREFLAGS definition to %set_build_flags is probably preferable so the HAREFLAGS environment variable gets set automatically for all packages.

I agree this creates a better out-of-the-box experience, but I also believe this is out of my direct control. I can submit a pull request after hare lands on f43, like I did for the %hare_arches macro in f42.

Should hare depend on gcc if it's needed to compile hare programs instead of requiring that each package depend on it explicitly?

No, the hare package will behave as Hare developers would expect and statically link programs by default.

I opted to dynamically link Hare programs in Fedora by default, and package maintainers can opt out. But as a result they need a C compiler by default, and I picked gcc in the guidelines because that's the compiler the hare package will invoke by default, but I'm also leaving the door open to choosing clang.

%forgeautosetup -p1 or %autosetup -p1 %{forgesetupargs} is preferable so that any patches get applied automatically.

I was not aware of that, I have yet to apply patches to a package relying on forge macros.

Is there a mixture of tabs and spaces here? This line and then one after don't look correctly aligned.

Probably a vim accident, I will push a commit to fix this.

Should I squash it in the main commit now? Later? Not at all?

First time contributor here.

3 new commits added

  • Hare: Use %forgeautosetup in RPM spec examples
  • Hare: Remove accidental TAB
  • Hare: The tool chain does NOT manage projects

Thanks for the quick turnaround, I will address each point here.

Sure. Note that I'm not a member of the FPC, so consider this "drive-by feedback."

The hare package owns /usr/src/hare and /usr/src/hare/third-party where other packages can drop their own directories. Hare modules don't strictly need to pull the hare package, and owning a couple directories has much less overhead than a filesystem package.

My take here is that a filesystem package would add more moving parts, while co-owning two directories is much simple. If it's an absolute requirement, I will do it, but making the module maintainers change one line in the %file section seemed like a better compromise than adding a hare-filesystem package, especially with an off-the-shelf %hare_srcdir macro.

It's generally it's preferable for cases like this for packages to specifically state the directories they own to avoid conflicts (e.g., one package unexpectedly starts installing an additional module that conflicts with another package), but then it would get installed anyways because %{hare_srcdir} includes anything and everything under that directory. See https://docs.fedoraproject.org/en-US/packaging-guidelines/#_explicit_lists and https://docs.fedoraproject.org/en-US/packaging-guidelines/Python/#_explicit_lists that are in a similar vain. You could require something like

%files
%dir %{hare_srcdir}
%{hare_srcdir}/NAME/

for each package, but at that point, it's cleaner for the dependency generator to generate a dependency on hare-filesystem for anything that installs files under %{hare_srcdir} and avoid the need for each package to have that additional line (or risk forgetting it). Then you are also aligned with other language ecosystems in Fedora that have shared directory ownership.

I forgot about these guidelines.

I should probably take inspiration from python guidelines to amend the hare guidelines, and I can probably make the hare-filesystem dependency transparent thanks to the dependency generators already implemented.

I worked on adding a filesystem sub-package and it creates an interesting problem. The shared root directory for Hare modules is used by two dependency generators. But because one invocation is enough to collect all Hare modules, the setup looks like this:

$ cat hare.attr
%__hare_provides    %__hare_gen prov %{version}-%{release}
%__hare_requires    %__hare_gen req
%__hare_path        ^%{hare_moddir}$

The ^%{hare_moddir}$ ensures the single execution.

I could change it to something like this:

%__hare_provides    %__hare_gen prov %{hare_moddir} %{version}-%{release}
%__hare_requires    %__hare_gen req %{hare_moddir}
%__hare_path        ^%{hare_moddir}

This way the generator would query modules inside %{hare_moddir} once per file or directory in the tree (I could of course limit that to top-level directories with a finer-grained regular expression but that could still incur several calls for the same result every time). I'd also need to revisit the build requires generator to align with the new calling convention, and the special case for Hare's standard library that is handled differently, but relying on the same generator.

Not a ground-breaking problem, but I'll try to see whether it is possible to consolidate dependency generation for the (potentially multiple) files under %{hare_moddir} with one call to the dependency generator.

5 new commits added

  • Hare: Add a section on build tags
  • Hare: Mention a buildrequires generator limitation
  • Hare: Add missing word "macro"
  • Hare: Cover the hare-filesystem packaging rules
  • Hare: Expand on the tool chain and static linking

1 new commit added

  • Hare: Mention file listing in the share moddir

I amended my packaging to add a hare-filesystem sub-package with the unfortunate effect described above. I also updated the guidelines to reflect this change, and took the opportunity to add a section on build tags.

Unfortunately, I ran out of spare time and will resume later this week.

1 new commit added

  • Hare: Update module spec example as per guidelines
Metadata