From Fedora Project Wiki

(%define => %global)
No edit summary
Line 1: Line 1:
= Haskell Packaging Guidelines =
= Haskell Packaging Guidelines =
This documents the guidelines and conventions for packaging Haskell projects in Fedora.
This documents the guidelines and conventions for packaging Haskell projects in Fedora.


== What is Haskell? ==
== What is Haskell? ==
''"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."'' -- (from http://haskell.org/)


(from http://haskell.org/)
=== GHC ===
[http://haskell.org/ghc GHC], 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 various 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.  Most Haskell programs work better or only with GHC.  So currently these guidelines mostly focus on packaging for GHC.  At some later stage if the need arises they may be extended to cover other implementations in more detail.


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.
Packages should normally be compiled with GHC where possible.  Some Haskell packages might require some other compiler extension not available in GHC but in another compiler implementation in which case that compiler would have to be included in Fedora first before the package can get added to Fedora.  If a package needs special language features they should be mentioned in the review and documented in comments in the spec file.


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.
''Rationale: GHC is the best supported compiler in Fedora currently.  Therefore, if something goes wrong, we have a larger skill base to ask for help.''


== Base package naming ==
=== Cabal ===
''"Cabal is a system for building and packaging Haskell libraries and programs. It defines a common interface for package authors and distributors to easily build their applications in a portable way. Cabal is part of a larger infrastructure for distributing, organizing, and cataloging Haskell libraries and programs.''


=== Libraries ===
''Specifically, the Cabal describes what a Haskell package is, how these packages interact with the language, and what Haskell implementations must do to support packages. The Cabal also specifies some infrastructure (code) that makes it easy for tool authors to build and distribute conforming packages.''
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 <code>bzlib</code> library from [http://hackage.haskell.org/ Hackage] packaged for GHC would be named <code>ghc-bzlib</code> in Fedora, and the <code>QuickCheck</code> library would be named <code>ghc-QuickCheck</code>.


If a library is packaged for more than one Haskell compiler or interpreter, the base name should instead be prefixed with <code>haskell</code>, e.g. <code>haskell-X11</code>.  Such a package would then have subpackages for each compiler and/or interpreter it is built for (e.g. <code>ghc-X11</code>, <code>hug98-X11</code>, etc.
''The Cabal is only one contribution to the larger goal. In particular, the Cabal says nothing about more global issues such as how authors decide where in the module name space their library should live; how users can find a package they want; how orphan packages find new owners; and so on."''


''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.''
(from http://haskell.org/cabal)


=== Programs ===
== Summary and Description ==
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 <code>darcs</code>, <code>haddock</code>, and <code>xmonad</code>.  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.
When packaging things out of [http://hackage.haskell.org Hackage]  or other sources, you may find that the summary or description is incomplete or lacks detail.  Please try to include an appropriate summary and adequate description for Fedora of the library or program in the package so users will know what it does.
 
''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 [http://hackage.haskell.org 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 ==
<code>%build</code> and <code>%install</code> can be done through a series of macros that ensure correctness.
<code>%build</code> and <code>%install</code> can be done through a series of macros that ensure correctness.


<pre>
<pre>
%build
%build
%cabal_configure
%cabal_configure --ghc -p
%cabal_build
%cabal build
%cabal_haddock
%cabal haddock
</pre>
</pre>


''Note: Please include profiling libraries where possible or include a justification for not doing so.''
<code>%cabal_configure --ghc -p</code> configures the package for building with ghc and profiling.  ''Note: library packages should include profiling libraries where possible or include a justification for not doing so.'' If you omit profiling libraries (the <code>-p</code> option above), anyone wanting to install a profiling version of a dependent library or application will be unable to do so, which is generally considered bad form.  There is no need to provide profiling for non-library packages.


%cabal_build will build a package without installing it
<code>%cabal build</code> will build a package without installing it.


%cabal_haddock builds haddock files
<code>%cabal haddock</code> builds HTML Haddock documentation files.


<pre>
<pre>
Line 53: Line 46:
</pre>
</pre>


%cabal_install will install the package without including the registration scripts for ghc's library management.  For libraries, see below how to achieve this.
<code>%cabal_install</code> 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 ==
== Packaging libraries ==
GHC libraries should be installed under libdir/ghc as done by Cabal.
=== 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 <code>bzlib</code> library from [http://hackage.haskell.org/ Hackage] packaged for GHC would be named <code>ghc-bzlib</code> in Fedora, and the <code>QuickCheck</code> library would be named <code>ghc-QuickCheck</code>.
 
If a library is packaged for more than one Haskell compiler or interpreter, the base name should instead be prefixed with <code>haskell</code>, e.g. <code>haskell-X11</code>.  Such a package would then have subpackages for each compiler and/or interpreter it is built for (e.g. <code>ghc-X11</code>, <code>hugs98-X11</code>, 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:
 
<pre>
Provides: ghc-%{pkg_name}-devel = %{version}-%{release}
</pre>
 
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 <code>%pkg_libdir</code> as done by Cabal.


<pre>
<pre>
Line 63: Line 79:


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


<pre>
<pre>
Line 69: Line 85:
</pre>
</pre>


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.
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:
The files section would then look something like this:
Line 76: Line 92:
%files -f %{name}.files
%files -f %{name}.files
%defattr(-,root,root,-)
%defattr(-,root,root,-)
%doc dist/doc/html
%doc LICENSE README
%doc LICENSE TODO README
%{pkg_docdir}
 


%files -n %{name}-prof -f %{name}-prof.files
%files -n %{name}-prof -f %{name}-prof.files
%defattr(-,root,root,-)
%defattr(-,root,root,-)
%doc LICENSE
</pre>
</pre>


=== Install scripts ===
=== Install scripts ===
Libraries must be registered with the installed GHC.
Libraries must be registered with the installed ghc package.


To generate registration scripts that can be embedded in the package, include the following in %build, and include the following install script macros.
To generate registration scripts that can be embedded in the package first include the following in %build:
<pre>
<pre>
%ghc_gen_scripts
%ghc_gen_scripts
</pre>
</pre>
 
and then in %install install them with:
To separate the copying phase from the registration phase of installation, include the following in %install
<pre>
<pre>
%ghc_install_scripts
%ghc_install_scripts
</pre>
</pre>


To register packages at install time, make sure to include the following bits:
Finally the actual registering of packages must be done at install and uninstall time with the following scriplets:
<pre>
<pre>
%pre -n ghc-%{pkg_name}
%post -n ghc-%{pkg_name}
%ghc_preinst_script
%ghc_register_pkg
 
%preun -n ghc-%{pkg_name}
if [ "$1" -eq 0 ] ; then
  %ghc_unregister_pkg
fi
</pre>


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


%post -n ghc-%{pkg_name}
If a package comes with meaningful Haddock documentation, your spec file should define
%ghc_postinst_script
 
<pre>%global pkg_docdir %{_docdir}/ghc/libraries/%{pkg_name}</pre>
 
and the <code>%build</code> section should contain the following:
 
<pre>%cabal haddock</pre>


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 <code>%cabal_install</code> without any further intervention.


%preun -n ghc-%{pkg_name}
To automatically update the master index of all Haddock documentation in <code>/usr/share/doc/ghc/libraries</code>, add the following to your <code>%post</code> and <code>%postun</code> scriptlets:
%ghc_preun_script


<pre>
%post
%ghc_reindex_haddock


%postun -n ghc-%{pkg_name}
%postun
%ghc_postun_script
if [ "$1" -eq 0 ] ; then
  %ghc_reindex_haddock
fi
</pre>
</pre>
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 <code>%files</code> section, so that the Haddock docs will be picked up correctly.
<pre>%{pkg_docdir}</pre>


== Packaging programs ==
== Packaging programs ==
Programs are packaged in their simple name, eg <code>xmonad</code> would remain <code>xmonad</code>.  Any libraries should go into a 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.
=== 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 <code>darcs</code>, <code>haddock</code>, and <code>xmonad</code>.  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.


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


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: 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.


''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 ==
== Debug Information ==
Debuginfo packages should not be built for GHC binaries, since they will be empty anyway.
Debuginfo packages should not be built for GHC binaries, since they will be empty anyway.
<pre>
%global debug_package %{nil}
</pre>


''Rationale: GHC does not emit DWARF debug data.''
''Rationale: GHC does not emit DWARF debug data.''


== Macros ==
== Macros ==
 
A number of macros are defined for convenince for packaging cabal packages and libraries for ghc.  Similar macros could also be defined for other compilers.  It would be good to follow this scheme as far as possible also when implementing macros for other Haskell compilers or interpreters to keep portability.
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.


* %cabal
* %cabal
* %cabal_configure
* %cabal_configure
* %cabal_build
* %cabal_makefile
* %cabal_makefile
* %cabal_haddock
* %ghc_gen_scripts
* %cabal_install
* %cabal_install
* %ghc_install_scripts
* %ghc_install_scripts
* %ghc_gen_filelists()
* %ghc_gen_filelists()
* %ghc_preinst_script
* %ghc_register_pkg
* %ghc_postinst_script
* %ghc_unregister_pkg
* %ghc_preun_script
* %ghc_reindex_haddock
* %ghc_postun_script
 
=== Definitions ===
 
Definitions per compiler go here


* [[PackagingDrafts/Haskell/GHCMacroDefs | Definitions for GHC Macros ]]
You can find the current [http://cvs.fedoraproject.org/viewvc/devel/ghc/ghc-rpm-macros.ghc?view=co <code>ghc.macros</code>] definitions in the ghc package.


== Spec Templates ==
== 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.
There are three types of packages: Library only, Library and Binary, and Binary only.  Templates are provided for all three cases since they are slightly different:
 
* [[PackagingDrafts/Haskell/LibraryOnlyTemplate|  Library Only Template]]
* [[PackagingDrafts/Haskell/BinaryOnlyTemplate|  Binary Only Template]]
* [[PackagingDrafts/Haskell/LibraryAndBinaryTemplate|  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
* [http://git.fedorahosted.org/git/cabal2spec.git?p=cabal2spec.git;a=blob_plain;f=spectemplate-ghc-lib.spec;hb=HEAD Library Only Template]
* Group
* [http://git.fedorahosted.org/git/cabal2spec.git?p=cabal2spec.git;a=blob_plain;f=spectemplate-ghc-bin.spec;hb=HEAD Binary Only Template]
* URL - this can be the Hackage page
* [http://git.fedorahosted.org/git/cabal2spec.git?p=cabal2spec.git;a=blob_plain;f=spectemplate-ghc-binlib.spec;hb=HEAD Library and Binary Template].
* 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.
<code>cabal2spec</code> provides a simple script which can generate .spec files using these templates directly out of a Cabal package or .cabal file for any of the three cases.  The .spec files should build for most general Cabal hackage packages with minimal changes: for example you might need to specify BuildRequires for other build dependencies and possibly Requires for any runtime or linking dependencies.  Please report any problems in [https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora&component=cabal2spec bugzilla (in the cabal2spec component of the Fedora product)].


== References ==
== References ==
* http://petersen.fedorapeople.org/cabal2spec
* http://urchin.earth.li/~ian/haskell-policy/ - Debian Haskell packaging policy
* http://urchin.earth.li/~ian/haskell-policy/ - Debian Haskell packaging policy
* [[Packaging/OCaml|Fedora OCaml Packaging Guidelines]]
* [[Packaging/OCaml|Fedora OCaml Packaging Guidelines]]
* [[SIGs/Haskell|Fedora Haskell SIG]]
* [[SIGs/Haskell|Fedora Haskell SIG]]
* [http://ynemoy.fedorapeople.org/haskell Ynemoy's macros and cabal-rpm tree]

Revision as of 14:58, 14 April 2009

Haskell Packaging Guidelines

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

What is Haskell?

"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." -- (from http://haskell.org/)

GHC

GHC, 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 various 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. Most Haskell programs work better or only with GHC. So currently these guidelines mostly focus on packaging for GHC. At some later stage if the need arises they may be extended to cover other implementations in more detail.

Packages should normally be compiled with GHC where possible. Some Haskell packages might require some other compiler extension not available in GHC but in another compiler implementation in which case that compiler would have to be included in Fedora first before the package can get added to Fedora. If a package needs special language features they should be mentioned in the review and documented in comments in the spec file.

Rationale: GHC is the best supported compiler in Fedora currently. Therefore, if something goes wrong, we have a larger skill base to ask for help.

Cabal

"Cabal is a system for building and packaging Haskell libraries and programs. It defines a common interface for package authors and distributors to easily build their applications in a portable way. Cabal is part of a larger infrastructure for distributing, organizing, and cataloging Haskell libraries and programs.

Specifically, the Cabal describes what a Haskell package is, how these packages interact with the language, and what Haskell implementations must do to support packages. The Cabal also specifies some infrastructure (code) that makes it easy for tool authors to build and distribute conforming packages.

The Cabal is only one contribution to the larger goal. In particular, the Cabal says nothing about more global issues such as how authors decide where in the module name space their library should live; how users can find a package they want; how orphan packages find new owners; and so on."

(from http://haskell.org/cabal)

Summary and Description

When packaging things out of Hackage or other sources, you may find that the summary or description is incomplete or lacks detail. Please try to include an appropriate summary and adequate description for Fedora of the library or program in the package so users will know what it does.

Build and Install

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

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

%cabal_configure --ghc -p configures the package for building with ghc and profiling. Note: library packages should include profiling libraries where possible or include a justification for not doing so. If you omit profiling libraries (the -p option above), anyone wanting to install a profiling version of a dependent library or application will be unable to do so, which is generally considered bad form. There is no need to provide profiling for non-library packages.

%cabal build will build a package without installing it.

%cabal haddock builds HTML Haddock documentation files. 

%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.

Macros

A number of macros are defined for convenince for packaging cabal packages and libraries for ghc. Similar macros could also be defined for other compilers. It would be good to follow this scheme as far as possible also when implementing macros for other Haskell compilers or interpreters to keep portability.

  • %cabal
  • %cabal_configure
  • %cabal_makefile
  • %ghc_gen_scripts
  • %cabal_install
  • %ghc_install_scripts
  • %ghc_gen_filelists()
  • %ghc_register_pkg
  • %ghc_unregister_pkg
  • %ghc_reindex_haddock

You can find the current ghc.macros definitions in the ghc package.

Spec Templates

There are three types of packages: Library only, Library and Binary, and Binary only. Templates are provided for all three cases since they are slightly different:

cabal2spec provides a simple script which can generate .spec files using these templates directly out of a Cabal package or .cabal file for any of the three cases. The .spec files should build for most general Cabal hackage packages with minimal changes: for example you might need to specify BuildRequires for other build dependencies and possibly Requires for any runtime or linking dependencies. Please report any problems in bugzilla (in the cabal2spec component of the Fedora product).

References

Retrieved from "https://fedoraproject.org/w/index.php?title=Packaging:Haskell&oldid=96915"