#194 revision to Haskell Packaging Guidelines
Closed: Fixed None Opened 11 years ago by petersen.

https://fedoraproject.org/wiki/PackagingDrafts/Haskell contains a rewrite of the Haskell Packaging Guidelines, which has been in draft form for quite a while now.

Please review it.


An initial review lead us to request the following:

  1. a summary of changes/diffs from https://fedoraproject.org/wiki/Packaging/Haskell
  2. some justification for the additional rpm macros (specifically, the %description, %package, and %*post macros.

Please provide this and we will revisit this.

Any updates on this in response to spot's comment? If you need more time, that's ok, but if not we'll close this out in 1 week.

Sorry for being too slow to respond to the earlier comments.

I have reworked https://fedoraproject.org/wiki/PackagingDrafts/Haskell a little more to reflect the new cabal-rpm packaging tool we are now using which replaced cabal2spec and a few other minor updates, improvements, and cleanups.

Replying to [comment:1 spot]:

  1. a summary of changes/diffs from https://fedoraproject.org/wiki/Packaging/Haskell

The actual diff is here: https://fedoraproject.org/w/index.php?title=PackagingDrafts/Haskell&diff=321552&oldid=81838

The page has been simplified and rewritten quite a lot but here is a summary of the main changes:

  • replaced introductory sections on Haskell, GHC and Cabal with a few short summarizing sentences.
  • moved Spec File Templates to beginning (fixed/updated urls)
  • consolidated naming to new Package Naming section (no actual Naming changes)
  • new Headers section describes header definitions for %pkg_name and common_summary/description
  • added a short section added on handling of Cabal Flags and a new small section explaining Dependency Generation
  • cleaned up description of Shared and Static Libraries
  • macros list updated to those currently used in templates and explained for Bin and !Lib/BinLib packages (updated link to macros.ghc source file), replacing the old long section on Packaging Libraries and Packaging Programs
  • updated Files Lists section to describe current macros that generate filelists boilerplate.
  • short section added on non-Cabal Haskell
  1. some justification for the additional rpm macros (specifically, the %description, %package, and %*post macros.

The %ghc_devel_package, %ghc_devel_description, %ghc_package, and %ghc_description macros
replace earlier %ghc_lib_package and %ghc_binlib_package macros we used for a while,
now making it possible to add fields like Requires to subpackages easily while still
benefitting from not having to repeat all the same standard subpackaging boilerplate.
Using them simplifies package maintenance when updating packages and makes it easy
to spot differences for individual packages. I can explain them in more detail if
necessary.

They are also very helpful for handling secondary arch builds where there are no Haskell shared libraries available
and hence no ghc-<pkgname> binary library base packages. I suppose we could have dummy base library packages there but that seems kind of silly. So these macros simplify this handling automatically whether there is a base package for the arch or not, preventing having a lot
of extra %if's etc in the spec file for that.

%ghc_devel_post_postun basically just covers the old Install Scripts subsection
(which wrongly mentions ghc-%{pkg_name} not ghc-%{pkg_name}-devel).
It could be dropped but it is a convenience and again stops boilerplate repetition
across all spec files.

More details of the template changes can be found in:
http://git.fedorahosted.org/cgit/cabal2spec.git/log/spectemplate-ghc-lib.spec
http://git.fedorahosted.org/cgit/cabal2spec.git/log/spectemplate-ghc-binlib.spec
* http://git.fedorahosted.org/cgit/cabal2spec.git/log/spectemplate-ghc-bin.spec
which largely cover the period since the last approved revision.

The templates and macros have become a lot more stable now over time but going forward I will try to post any draft updates to the Guidelines earlier and more often to FPC. :)

Commenting here - just to make clear that this ticket is still open!

Any suggestions for helping this move forward?

action Haskell Draft Guidelines approved (+1:6, 0:0, -1:0)

We also will move copies of the templates into the Packaging namespace rather than linking to git.

One minor change requirement which we caught after voting:

%ghc_devel_post_postun => needs to be broken into two macros

Each scriptlet section should have its own "header" in the spec files and then you can use a macro within that section, so you need a %ghc_devel_post and %ghc_devel_postun invoked like this:

%post[[BR]]
%ghc_devel_post

%postun[[BR]]
%ghc_devel_postun

Otherwise, you can't leverage the macro and customize those scriptlets.

Please make that change to the draft and we'll roll it live.

Upon even further discussion, there were serious concerns about how the macros operate, and several FPC members changed their votes to reject this draft as is. Toshio will be on the ticket shortly to elaborate.

This draft reverts to a "pending" state as a result. Many apologies.

Replying to [comment:9 spot]:

%ghc_devel_post_postun => needs to be broken into two macros

Each scriptlet section should have its own "header" in the spec files and then you can use a macro within that section, so you need a %ghc_devel_post and %ghc_devel_postun invoked like this:

%post[[BR]]
%ghc_devel_post

%postun[[BR]]
%ghc_devel_postun

So basically you are saying don't use %ghc_devel_post_postun but just use %ghc_pkg_recache.

Okay I suppose we can do that (but actually in the 200+ packages we have there are no examples
of needing to customize the devel scripts, so %ghc_devel_post_postun actually seems to be optimal).

The rest is fine, but I would really appreciate being allowed to keep %ghc_files for now
as I tried also to explain indirectly in the above paragraph:

for handling secondary arch builds where there are no Haskell shared libraries available and hence no ghc-<pkgname> binary library base packages. I suppose we could have dummy base library packages there but that seems kind of silly. So these macros simplify this handling automatically whether there is a base package for the arch or not, preventing having a lot of extra %if's etc in the spec file for that.

since the presence of a "%files" even if empty will automatically induce rpmbuild to create a ghc-PKG base library package, it can't really be handled in the way you suggest.

At the risk of preempting Toshio's comments, I went ahead and updated the new Lib and !BinLib templates in git:

http://git.fedorahosted.org/cgit/haskell-sig.git/tree/packaging-templates

expanding out %ghc_devel_package, %ghc_devel_description, %ghc_devel_post_postun,
and %ghc_package, %ghc_description, as you suggested.

The simple Bin package template remains unchanged since I think FPC basically approved that one. :) ;)

If this looks more acceptable then I can go head and update the draft page to reflect this cleaner
more standard approach. The previous comment still holds though - I explain with an example:

if I drop %ghc_files usage then in all packages I will need to make the following change (for many .spec files):

{{{
-%ghc_files LICENSE
+%global base_doc_files LICENSE
+
+%if %{undefined ghc_without_shared}
+%files -n ghc-%{pkg_name} -f ghc-%{pkg_name}.files
+%doc %base_doc_files
+%endif
+
+%files -n ghc-%{pkg_name}-devel -f ghc-%{pkg_name}-devel.files\
+%if %{defined ghc_without_shared}\
+%doc %base_doc_files
+%endif
}}}

I think the %ghc_files boilerplate macro is much nicer and cleaner than having to doing this,
resulting in better maintainability.

I also note in passing that OpenSUSE has been using my ghc-rpm-macros, cabal2spec, and now cabal-rpm for quite a while. But I don't think/hope the changes should impact them negatively but I will try to give them aheadsup about the impending changes.

Well, shoot -- I submitted this after a new comment was made so it didn't save... luckily I still had the tab open...

There seem to be a few issues but they all boil down to macro usage. To some extent, macros are a blessing to packagers since they encapsulate boilerplate into a small, easy to remember name. At some point, however, macros can degrade the readability of a spec file, make it hard to modify, or require special knowledge of what the macros do in order to avoid tripping over special cases. The use of macros in the proposed guidelines crosses over into that territory as seen by FPC initially thinking the macros were okay but discovering multiple ways that the macros didn't operate as they expected upon looking deeper.

First, two general rules: macros must never include headers ("%files", "%post", "%package", etc) for two different sections. Doing so prevents packagers from modifying the first of those sections (because the section is ended when the rpm parser encounters the header for the second section).

Macros should never include "header" type values at all, certainly not macros that enter into the Guidelines. Instead, macros should be designed to work within one of these sections and the header be explicitly written into the spec file by the packager. This greatly aids in readability and prevents mistakes by packagers unfamiliar with the macros' implementations putting in duplicate sections.

With those in mind, these are the macros we spotted with issues, if you know of more, please fix them as well:

  • %ghc_devel_post_postun -- should be broken up into two macros as spot mentioned in comment:9
  • %ghc_files -- should instead create the file list and let the packager specify the %files header themselves.
  • %ghc_devel_package and %ghc_package -- let the packager specify %package and %package -n %{name}-devel themselves
  • FPC is a little worried by the use of %common_description. Descriptions are meant to be multiline with each line no more than 80 chars to format nicely on terminals. How is this handled with the %common_description macro? We haven't tested but speculate that it will need multiple escape sequences... perhaps:

{{{
%global common_description \
line1\n\
line2\n\
}}}

Could you either get rid of the common_description portion (my preference if this is going to require adding explicit \n as that's sure to be forgotten by packagers) or test what needs to be done and add a section with the proper formatting of common_description?

Other things:

  • The package sections should be brought up above the %prep step to be consistent with other Fedora guidelines.

After some more discussion with Toshio on irc, we concluded that if secondary archs also
have ghc-%{pkg_name} packages, the macros can be simplified and %ghc_files is no longer a hurdle.

I made further changes to the draft templates in git to reflect this:
http://git.fedorahosted.org/cgit/haskell-sig.git/tree/packaging-templates
which I think should now be more acceptable, and I agree about the readability.

No "\n"'s are needed in %common_description but I am also pondering
possibly even dropping it and/or maybe more likely %common_summary.

I think I will open a new ticket when the reworked revision is ready since it will be a "rebase" to the new templates, which will be closer to the current old Guidelines and this ticket was originally filed 9 months ago, but until then I will leave this ticket open.

(Ignore the last comment - looking more it was pretty easy just to remove the unwanted macros from the current draft.)

Okay I think I have finished updating the templates - they now moved to:

http://git.fedorahosted.org/cgit/haskell-sig.git/tree/templates

and reworked the draft guidelines following the feedback from FPC:

https://fedoraproject.org/wiki/PackagingDrafts/Haskell

So the changes are mostly just removals but I added a few minor new details.

In the end I even dropped %common_summary, %common_description, and %ghc_devel_requires.
So I think the templates should be pretty clean and readable now,
and more acceptable.

Haskell Draft (with templates merged into guidelines) approved : (+1:6, 0:0, -1:0)

I made one more trivial change to the draft: just dropping %ghc_compiler from the macros.

https://fedoraproject.org/w/index.php?title=PackagingDrafts/Haskell&diff=337658&oldid=333956

Anything I can do to help land this in the wiki?

Perhaps putting the templates into Draft pages?

Just for the record I have now updated all the fedora haskell packages' master branches to the new packaging templates which are also implemented in cabal-rpm-0.8.0

Written into the Guidelines and ready for announcement.

Announcement text:

After an unintentional delay, the Haskell Guideline revision approved four months ago has been officially written into the Guidelines. A profound apology to everyone who wanted to point people at the new guidelines and couldn't find them in the meantime. The updated guidelines can be read here: https://fedoraproject.org/wiki/Packaging:Haskell

Metadata Update from @petersen:
- Issue assigned to spot

7 years ago

Login to comment on this ticket.

Metadata