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 released on Hackage and use the 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:
cabal2spec
can create .spec files based on these templates directly from a Cabal package tarball or .cabal file for any of the three cases. Using these 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 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 against the cabal2spec component.
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
BinLib package has library subpackages
ghc-xmonad
for the shared library,ghc-xmonad-devel
for devel files and the static library, andghc-xmonad-prof
for the profiling development files.
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>
GHC uses static libraries by default, but now also supports shared libraries. Lib and BinLib packages should provide static, shared, and profiling libraries:
- the shared library lives in the base library package,
- the static library and header files in the -devel subpackage, and
- the profiling library and headers in the -prof subpackage.
Because GHC always assumes static versions of libraries are installed they need to be in the devel subpackage and it doesn't make sense to subpackage them yet.
Executables in Bin and BinLib packages should be dynamically linked to shared libraries.
Note that executables in BinLib packages are currently staticly linked against the library contained in the package, but will be dynamically linked against other dependent libraries.
Some particular packages may do user compilation during runtime in which case they will 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.
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 used 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 expansion and then tweaked in order to get a package to build for Fedora.
Bin packages
Bin package executables are dynamically linked to shared Haskell libraries when available, but this can be overridden if necessary by defining the ghc_without_dynamic
macro.
%ghc_bin_build
is used to configure and build bin packages. It runs:%global debug_package %{nil}
: debuginfo is disabled since ghc's output is not in DWARF format.%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
BinLib package executables are dynamically linked to other shared Haskell libraries when available, but this can be overridden if necessary by defining the ghc_without_dynamic
macro.
%ghc_lib_build
is used to configure, build and generate documentation for Lib and BinLib packages. It runs:%global debug_package %{nil}
: debuginfo is disabled since ghc's output is not in DWARF format.%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
. - Additionally links to colored html sourcecode are also generated with
hscolour
, which can be disabled by definingwithout_hscolour
.
- If necessary (if e.g. documentation is failing to build for some reason) this can be skipped by defining
%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 .conf metadata file for package installation time%ghc_gen_filelists
: generates rpm filelists.%ghc_strip_dynlinked
: strips dynamically linked objects.
%ghc_lib_package
: Boilerplate macro that defines the files list forghc-%{pkg_name}
, and its devel and prof subpackages using:%ghc_package_devel
: defines the devel subpackage, files list, and install scripts:- The install scripts run
%ghc_pkg_recache
to refresh the ghc package cache database with .conf file data. - For older versions of ghc
%ghc_reindex_haddock
regenerates the library documentation indices at install time.
- The install scripts run
%ghc_package_prof
: defines the prof subpackage and file list.
%ghc_binlib_package
: BinLib equivalent of%ghc_lib_package
which additionally definesghc-%{pkg_name}
as a subpackage.
Directories
GHC libraries are installed under %ghcpkgdir/%{pkg_name}-%{version}
:
Library documentation lives under %ghclibdocdir/%{pkg_name}-%{version}
.
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.
ghc-%{pkg_name}: W: spelling-error Summary(en_US) Haskell -> Gaskell, Gaitskell, Skellum
This is fixed in Fedora 15 hunspell-en.