From Fedora Project Wiki

Haskell Packaging Guidelines

This page documents the guidelines and conventions for packaging Haskell projects in Fedora.

GHC (Glasgow Haskell Compiler) is the current mainstream Haskell compiler. Most Haskell packages are now released on Haskage, which all use the Haskell Cabal package system. So currently these guidelines focus on packaging for GHC using Cabal.

Spec file templates

There are three types of Haskell Cabal packages: binary only (Bin), library only (Lib), and binary and library (BinLib). Templates are provided for all three cases since they are slightly different:

It is recommended to use cabal2spec to create .spec files using these templates directly from a Cabal package or .cabal file for any of the three cases, since following the standard packaging templates lowers the maintenance burden considerably across Fedora's Haskell packages. With a little editing the .spec files should then build for most general Cabal packages: for example it may be necessary to specify BuildRequires for build dependencies and Requires for any runtime dependencies. Please report any problems in bugzilla (in the cabal2spec component of the Fedora product).

Naming

Haskell Bin and BinLib packages should follow the usual Fedora Package Naming Guidelines for base package naming: ie follow the upstream name. Examples include projects like darcs and xmonad. BinLib packages SHOULD subpackage their libraries with naming following Lib packages.

For example the xmonad package has library subpackages ghc-xmonad, ghc-xmonad-devel, and ghc-xmonad-prof.

The names of Haskell Lib packages built for ghc are prefixed by "ghc-". For example the zlib library package is named ghc-zlib, and the QuickCheck library is named ghc-QuickCheck.

If a library is packaged for more than one Haskell compiler or interpreter, the base name should instead be prefixed with haskell, e.g. haskell-X11. Such a package would then have subpackages for each compiler and/or interpreter it is built for (e.g. ghc-X11, hugs98-X11, etc).

Package naming preserves case to follow the upstream naming conventions as closely as possible.

The macro pkg_name is used to carry the name of the upstream library package (i.e. without the Fedora "ghc-" prefix). It should be defined at the top of Lib and BinLib packages:

%global pkg_name <package>

Shared and static library linking

GHC uses static libraries by default, but now supports shared libraries. Lib and BinLib packages should provide static, shared, and profiling libraries. The shared libraries live in the base library package, static library and header files in the -devel subpackage and profiling libraries in the -prof subpackage.

Executables in Bin and BinLib packages should be dynamically linked to shared libraries.

Static linking means that when updating any library, all packages that depend on it will also need to be rebuilt before they see any changes, and in the event of a security advisory, all of them need to be rebuilt also.

This is not true for linking to other languages using the Foreign Function Interface (FFI). When linking to these libraries, the standard dynamic linker is used.

Note: the situation is similar to OCaml, and the usual rules that apply there apply here as well.

Keep in mind though, that some particular packages may still do user compilation during runtime in which case they may need Requires as well as BuildRequires for their dependencies: examples include xmonad and yi which require their devel package to be present to allow users to relink their configuration or customization.

Debug Information

Objects compiled with ghc do not include useful debug info, so debuginfo packages should be disabled:

%global debug_package %{nil}

RPM Macros

The templates all have buildrequires for ghc-rpm-macros, which provides macros.ghc to assist with packaging Haskell Cabal packages.

The main commonly needed macros are:

  • %ghc_bin_build
  • %ghc_bin_install
  • %ghc_lib_build
  • %ghc_lib_install
  • %ghc_lib_package
  • %ghc_binlib_package

They are used in the templates and explained in more detail below.

Generally the macros should just work and do the right thing, but if necessary a macro can be replaced by its expansions of course and then tweaked in order to get a package to build for Fedora.

Bin packages

Bin packages use dynamic linking by default, but this can be disabled if necessary by defining the without_dynamic macro.

  • %ghc_bin_build is used to configure and build bin packages. It runs:
    • %cabal_configure: configure the package for building and dynamic linking.
    • %cabal build: builds the package.
  • %ghc_bin_install is used to install bin packages. It runs:
    • %cabal_install: installs the package.
    • %ghc_strip_dynlinked: strips the dynamically linked binary.

Lib and BinLib packages

  • %ghc_lib_build is used to configure, build and generate documentation for lib and binlib packages. It runs:
    • %cabal_configure --ghc -p: configures the package for building with ghc and profiling. Libraries should build profiling versions of their static libraries.
    • %cabal build: builds the package.
    • %cabal haddock: generates HTML library documentation from the source code. If necessary (if e.g. documentation is failing to build for some reason) this can be skipped by defining without_haddock.
  • %ghc_lib_install is used to install lib and binlib packages. It runs:
    • %cabal_install: installs the package without registering it in ghc-pkg.
    • %cabal_pkg_conf: creates ghc-pkg metadata for package installation time
    • %ghc_gen_filelists: generates rpm filelists.
    • %ghc_strip_dynlinked: strips dynamically linked objects.

Directories

GHC libraries are installed under %ghcpkgdir/%{pkg_name}-%{version}:

Library documentation lives under %ghclibdocdir/%{pkg_name}-%{version}.

Install scripts

Library devel packages include a ".conf" metadata file generated by %cabal_pkg_conf as part of %ghc_lib_install. The %post and %postun scripts regenerate ghc's package cache by running:

%ghc_pkg_recache

and can regenerate the Haddock documentation index with

%ghc_reindex_haddock

File lists

Filelists for shared, devel and profiling library subpackages are generated using the following macro:

%ghc_gen_filelists

It generates three filelists: ghc-%{pkg_name}.files, ghc-%{pkg_name}-devel.files, and ghc-%{pkg_name}-prof.files.

The files sections are boilerplate generated by %ghc_lib_package and %ghc_binlib_package.

If you need to add additional files (e.g. extra %doc files or datadir files say) they can simply be added by echo'ing to the appropriate ".files" list.

RPM Lint output

Because of the nature of packaging ghc libraries, there are some warning and errors generated by rpmlint that can be waived:

ghc-%{pkg_name}-prof: E: devel-dependency ghc-%{pkg_name}-devel
ghc-%{pkg_name}-prof: W: devel-file-in-non-devel-package
%{ghcpkgdir}/libHS%{pkg_name}-%{version}_p.a

ghc-%{pkg_name}-prof should be considered an extra devel package.

ghc-%{pkg_name}-prof: W: no-documentation

prof subpackages require the devel subpackage which contains devel documents and in turn require ghc-%{pkg_name} which carries the license file.

References