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 and use the Haskell Cabal package system. So currently these guidelines mostly 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 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).
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 name of Haskell Lib packages built for ghc are prefixed by "ghc-". For example the zlib library 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.
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.
Bin packages should be dynamically linked to shared libraries. Due to current Cabal limitations, BinLib packages cannot currently provide both profiling libraries and dynamically linked programs.
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 their devel package to be present to allow user configuration.
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 rpm macros to assist with packaging Haskell Cabal packages.
The main commonly used macros are:
- %ghc_bin_build
- %ghc_lib_build
- %ghc_bin_install
- %ghc_lib_install
- %ghc_lib_package
- %ghc_binlib_package
- %ghc_pkg_recache
- %ghc_reindex_haddock
They are used in the templates and explained in more detail below.
Bin packages
Bin packages should set %bcond_without dynamic to enable dynamic linking of executables.
%ghc_bin_buildis 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_installis 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_buildis 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.
%ghc_lib_installis 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 should be installed under %pkg_libdir:
%global ghc_pkg_libdir %{_libdir}/ghc-%{ghc_version}/%{pkg_name}-%{version}
Library documentation lives under:
%global ghc_pkg_docdir %{_docdir}/ghc/libraries/%{pkg_name}
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] [version]
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.
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.
References
- http://fedorahosted.org/cabal2spec
- http://pkg-haskell.alioth.debian.org/haskell-policy/ - Debian Haskell packaging policy
- Fedora OCaml Packaging Guidelines
- Fedora Haskell SIG