PackagingDrafts/Haskell

Haskell Packaging Guidelines

This 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 and use the Haskell Cabal package system. So currently these guidelines mostly focus on packaging for GHC using Cabal.

Spec Templates

There are three types of 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:

• Binary Only Template
• Library Only Template
• Library and Binary Template.

It is strongly 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. With minor 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).

RPM Macros

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

• %cabal
• %cabal_configure
• %ghc_bin_build
• %ghc_lib_build
• %ghc_binlib_build
• %cabal_install
• %cabal_pkg_conf
• %ghc_gen_filelists()
• %ghc_lib_package
• %ghc_binlib_package
• %ghc_bin_package
• %ghc_pkg_recache
• %ghc_reindex_haddock

and use them following the templates above as explained below.

%ghc_bin_build

%ghc_bin_build is used to configure and build bin packages.

It runs:

%cabal_configure --ghc
%cabal build

Bin packages should set %bcond_without dynamic to enable dynamic linking of executables.

%ghc_lib_build

%ghc_lib_build is used to configure, build and generate documentation for lib and binlib packages in the standard way.

It runs:

%cabal_configure --ghc -p
%cabal build
%cabal haddock

%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 builds HTML Haddock documentation files from the source code.

Install

%install
rm -rf ${RPM_BUILD_ROOT}
%cabal_install

%cabal_install will install the package without including the registration scripts for ghc's library management. For libraries there are additional macros for generating the install scripts and filelists: see below.

Packaging libraries

Naming

The names of Haskell library packages should be prefixed with the compiler or interpreter they are intended for. Package names should follow the upstream naming and preserve case. For example, the bzlib library from Hackage packaged for GHC would be named ghc-bzlib in Fedora, and the QuickCheck library would be 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.

Rationale: The Fedora Project tries to follow upstream as closely as possible. Haskell upstream packages maintain consistent naming schemes across tarball, cabal and ghc package names, and mixed case names are tracked well.

Static vs. Dynamic Linking

Current releases of GHC do not yet support generating shared libraries, so all ghc libraries are static and library packages of them should provide themselves as a -devel package also to allow migrating parts of them to -devel subpackages in the future when shared libraries become the norm:

Provides: ghc-%{pkg_name}-devel = %{version}-%{release}

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 special packages may still do code generation at runtime in which case they may need Requires as well as BuildRequires for their dependencies: examples include xmonad and yi which may require certain libraries to be present to work.

Package directory

GHC libraries should be installed under %pkg_libdir as done by Cabal.

%global pkg_libdir %{_libdir}/ghc-%{ghc_version}/%{pkg_name}-%{version}

File lists

You can generate filelists for libraries and profiling library subpackages using the following macro, rather than doing it by hand:

%ghc_gen_filelists %{name}

This macro takes one parameter, which is just a name prefix to be used for the file lists. This same parameter must be used later in the files section.

The files section would then look something like this:

%files -f %{name}.files
%defattr(-,root,root,-)
%doc LICENSE README
%{pkg_docdir}

%files -n %{name}-prof -f %{name}-prof.files
%defattr(-,root,root,-)

Install scripts

Libraries must be registered with the installed ghc package.

To generate registration scripts that can be embedded in the package first include the following in %build:

%ghc_gen_scripts

and then in %install install them with:

%ghc_install_scripts

Finally the actual registering of packages must be done at install and uninstall time with the following scriplets:

%post -n ghc-%{pkg_name}
%ghc_register_pkg

%preun -n ghc-%{pkg_name}
if [ "$1" -eq 0 ] ; then
  %ghc_unregister_pkg
fi

Documentation

Normal doc files for a package should live in the usual place. Haskell supports inline API docs using the haddock tool (bundled in the ghc package as of 6.10), for which the situation is somewhat different. The master directory for Haddock files is %{_docdir}/ghc/libraries, with one directory per package under there. The index.html file for this directory should be regenerated every time a package is installed, upgraded, or removed. Since %{_docdir}/ghc/libraries is owned by ghc-doc it is recommended to subpackage haddock documentation in a doc subpackage, which can require ghc-doc.

If a package comes with meaningful Haddock documentation, your spec file should define

%global pkg_docdir %{_docdir}/ghc/libraries/%{pkg_name}

and the %build section should contain the following:

%cabal haddock

This will cause the HTML version of the Haddock documentation to be generated. If built, it will automatically be installed to the correct location by %cabal_install without any further intervention.

To automatically update the master index of all Haddock documentation in /usr/share/doc/ghc/libraries, add the following to your %post and %postun scriptlets:

%post 
%ghc_reindex_haddock

%postun
if [ "$1" -eq 0 ] ; then
  %ghc_reindex_haddock
fi

The ghc haddock docs index will then be updated after installation, update, or removal of the package.

Finally, you'll want to add the following to your %files section, so that the Haddock docs will be picked up correctly.

%{pkg_docdir}

Packaging programs

Naming

For packages of Haskell programs the usual Fedora Package Naming Guidelines must be followed: ie in they should follow the upstream name. Examples include projects like darcs, haddock, and xmonad. If the package also generates libraries, then the libraries SHOULD be subpackaged as a Haskell library package named after the compiler or interpreter as above.

Any libraries provided should go into a separate subpackage: eg the spec file for xmonad would generate three rpm packages: xmonad, ghc-xmonad, and ghc-xmonad-prof. xmonad would require ghc-xmonad, but not visa versa. ghc-xmonad would contain a line in its description explaining that these are the libraries necessary for xmonad to run.

Rationale: Program packages should be easy to find by their upstream name. Binaries are recognized on their name alone. Furthermore, they generally do not require a compiler to run. Therefore the name provided should simply be the upstream name.

Debug Information

Debuginfo packages should not be built for GHC binaries, since they will be empty anyway.

%global debug_package %{nil}

Rationale: GHC does not emit DWARF debug data.

References

• http://fedorahosted.org/cabal2spec
• http://pkg-haskell.alioth.debian.org/haskell-policy/ - Debian Haskell packaging policy
• Fedora OCaml Packaging Guidelines
• Fedora Haskell SIG