PackagingDrafts/Haskell

Haskell Packaging Guidelines

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

What is Haskell?

(from http://haskell.org/)

Haskell is an advanced purely functional programming language. The product of more than twenty years of cutting edge research, it allows rapid development of robust, concise, correct software. With strong support for integration with other languages, built-in concurrency, debuggers, profilers, rich libraries and an active community, Haskell makes it easier to produce flexible, maintainable high-quality software.

GHC, or the Glasgow Haskell Compiler, is the most popular and widely used Haskell compiler. It complies with Haskell 98, the latest official language specification, and also includes numerous experimental language ideas. It represents a good picture of what the future of Haskell will look like, so it is a good choice for development. Many Haskell programs work better or only with GHC. So currently these guidelines mainly focus on packaging for GHC. At some later stage if the need arises they may be extended to cover other implementation in more detail.

Base package naming

Libraries

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, hug98-X11, etc.

Rationale: The Fedora Project tries to follow upstream as closely as possible. Upstream maintains very consistent naming schemes, and mixed case names are tracked very well.

Programs

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.

Rationale: Binaries are not dependant on the compiler they were compiled with anymore than a C program is dependant on whether it's been compiled with gcc or icc.

Description

When packaging things out of Hackage or other sources, you may find that the description is incomplete or improperly labeled. Please double check all parts of the package description so that it meets Fedora's standards for writing quality.

Build and Install

%build and %install can be done through a series of macros that ensure correctness.

%build
%ghc_autotools -l -p enable
%ghc_build
%ghc_haddock

%ghc_autotools takes three paramaters.

1. -l is to be used if there are libraries packaged
2. -p takes either 'enable' or 'disable' to enable or disable library profiling files.
3. -f applies flags to the --flags paramater of Setup.hs --flags.

Note: Please include profiling libraries where possible or include a justification for not doing so.

%ghc_build will build a package without installing it

%ghc_haddock builds haddock files

%install
rm -rf ${RPM_BUILD_ROOT}
%ghc_install

%ghc_install will install the package without including the registration scripts for ghc's library management. For libraries, see below how to achieve this.

Packaging libraries

GHC libraries are installed under libdir/ghc by cabal.

Using Cabal

If you use Cabal to build and install the packages, you can use the following snippet in your %install section to define filelists, rather than doing it by hand:

%ghc_gen_filelists %{name}

This macro takes one parameter, which is just a name 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
%doc dist/doc/html
%doc LICENSE TODO README


%files -n %{name}-prof -f %{name}-files.prof
%doc LICENSE

Install scripts

Libraries must be registered with the installed ghc.

To generate registration scripts that can be embedded in the package, include the following in %build. (This requires that you also follow the following steps)

%ghc_gen_scripts

To separate the copying phase from the registration phase of installation, include the following in %install

%ghc_install_scripts

To register packages at install time, make sure to include the following bits:

%pre -n %{hsc_namever}-%{f_pkg_name}
%ghc_preinst_script


%post -n %{hsc_namever}-%{f_pkg_name}
%ghc_postinst_script


%preun -n %{hsc_namever}-%{f_pkg_name}
%ghc_preun_script


%postun -n %{hsc_namever}-%{f_pkg_name}
%ghc_postun_script

Packaging programs

Programs are packaged in their simple name, eg xmonad would remain xmonad. Libraries should go into separate subpackage: eg the spec file for xmonad would generate two rpms, both of which are required for runtime, xmonad and ghc-xmonad. 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.

Binary packages should be compiled with GHC when possible. Some Haskell packages might require some compiler extension not provided in GHC. Alternate compilers may be used so long as they are packaged for Fedora. Please make it clear what feature is needed when submitting that package for review, and leave an appropriate comment in the spec file.

If a compiler is not available in Fedora, please submit it for package review as well. We can block your review request on the compiler, and if they pass review, they can be accepted simultaneously. Please note that your compiler must follow Fedora's guidelines for packaging and package submission.

Rationale: Binaries are recognized on their name alone. Furthermore, they do not require a compiler to run. Therefore the name provided should simply be the upstream name. GHC is the best supported compiler in Fedora currently. Therefore, if something goes wrong, we have a larger skill base to ask for help.

Documentation

Packages should try to make sure Haddock document links correctly to other dependent packages.

Debug Information

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

Rationale: GHC does not emit DWARF debug data.

Macros

A number of macros are defined for cabal packages, per compiler. They have names like %ghc_build and %ghc_install. Similar macros can be defined for other compilers. Please stick to this API when implementing macros for other compilers.

• %ghc_autotools(lf:p:)
• %ghc_build
• %ghc_haddock
• %ghc_gen_scripts
• %ghc_install
• %ghc_install_scripts
• %ghc_gen_filelists()
• %ghc_preinst_script
• %ghc_postinst_script
• %ghc_preun_script
• %ghc_postun_script

Definitions

Definitions per compiler go here

• Definitions for GHC Macros

Spec Templates

There are three types of packages: Library only, Library and Binary, and Binary only. The program cabal-rpm can generate a SPEC file suited to all three cases. The following templates are the output from cabal-rpm with a few minor changes. These templates should build under mock, and any failure is a bug against these guidelines.

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

Static vs. Dynamic Linking

Currently GHC performs only static linking with other Haskell libraries, partly due to a significant amount of optimizations done when inlining functions from other libraries. Therefore, when recompiling any library, all packages that depend on it will also need to be recompiled, and in the event of a security advisory, one needs to be applied to all dependencies.

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

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

Keep in mind though, this does not mean that you can just put all dependencies in the BuildRequires list and be done with it. Some packages, such as xmonad, perform lots of run time code generation, and may require certain libraries to be present to work.

Using cabal-rpm

If you use cabal-rpm to generate spec files, there are a few gotchas. These items are the difference between Yaakov Nemoy's working cabal-rpm and the guidelines. Since there is little variety in spec files, it might be easier to copy one of the templates from above and make the changes needed.

• The file name of the spec file will be the name of the package. Make sure to prepend 'ghc-' or the appropriate name for another compiler to the spec file before submitting it for review. This is necessary for libraries only. (For example, there would be a collision between ghc-zlib and zlib, but there is only one haddock or darcs.)
• cabal-rpm is currently only aware of haskell libraries installed by default with GHC. It will need alot more work to provide automagic dependency detection.
• cabal-rpm isn't always so intelligent about runtime dependencies for libraries. For example, it may specify the devel version of a library where the non-devel version is required. (This is important for binaries only. Libraries require devel versions, of course.)
• BuildRequires probably needs to be filled out by hand. One suitable method is to keep testing it in mock until it compiles cleanly.
• If the source package requires steps besides cabal, report it to upstream, and make sure to include them in the %build and %install sections.

Double check the following:

• License
• Group
• URL - this can be the Hackage page
• Source URL - this can be from Hackage
• Summary
• Description
• Files section includes all documentation and LICENSES. If not, please patch it according to the Fedora Packaging Guidelines

Finally, make sure to include changelog entries to specify what has been changed from the original cabal-rpm output.

References

• http://urchin.earth.li/~ian/haskell-policy/ - Debian Haskell packaging policy
• Fedora OCaml Packaging Guidelines
• Fedora Haskell SIG
• Ynemoy's macros and cabal-rpm tree