From Fedora Project Wiki
(→‎Lib and BinLib packages: expand %ghc_compiler to avoid koji srpm problems)
 
(45 intermediate revisions by the same user not shown)
Line 6: Line 6:


== Spec file templates ==
== Spec file templates ==
There are three types of Haskell Cabal packages: binary only (Bin), library only (Lib), and binary and library (BinLib):
Spec files in line with these templates are generated automatically by the [https://apps.fedoraproject.org/packages/cabal-rpm cabal-rpm] packaging tool
which also adds dependencies listed in the package's <code>.cabal</code> configuration file.
Most packages should then build, though for some packages
it may be necessary to specify some additional BuildRequires and/or Requires, and to check non-Haskell devel dependencies.
 
There are three types of Haskell Cabal packages: library only (Lib), binary only (Bin), and binary and library (BinLib):


* [http://git.fedorahosted.org/cgit/haskell-sig.git/plain/packaging-templates/Bin-pkg.spec Bin Template]
* [http://git.fedorahosted.org/cgit/haskell-sig.git/tree/templates/ghc-Lib-pkg.spec Lib Template] ([http://git.fedorahosted.org/cgit/haskell-sig.git/plain/templates/ghc-Lib-pkg.spec plain])
* [http://git.fedorahosted.org/cgit/haskell-sig.git/plain/packaging-templates/ghc-Lib-pkg.spec Lib Template]
* [http://git.fedorahosted.org/cgit/haskell-sig.git/tree/templates/Bin-pkg.spec Bin Template] ([http://git.fedorahosted.org/cgit/haskell-sig.git/plain/templates/Bin-pkg.spec plain])
* [http://git.fedorahosted.org/cgit/haskell-sig.git/plain/packaging-templates/BinLib-pkg.spec BinLib Template].
* [http://git.fedorahosted.org/cgit/haskell-sig.git/tree/templates/BinLib-pkg.spec BinLib Template] ([http://git.fedorahosted.org/cgit/haskell-sig.git/plain/templates/BinLib-pkg.spec plain]).


Standardizing the packaging lowers the maintenance burden considerably across Fedora's Haskell packages.
Standardizing the packaging helps to lower the maintenance burden across Fedora's Haskell packages.
Spec files in line with these templates can be generated automatically by the [https://apps.fedoraproject.org/packages/cabal-rpm cabal-rpm] packaging tool which also adds dependencies listed in the package's cabal configuration file.
Most packages should then build, though for some Cabal packages
it may be necessary to specify some additional BuildRequires and/or Requires, and to check non-Haskell devel dependencies.


== Package Naming ==
== Package 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 <code>darcs</code> and <code>xmonad</code>.
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 <code>darcs</code> and <code>xmonad</code>.
However there may be cases where a Haskell BinLib package is really a Lib package with a minor or unimportant executable: in this case it is better to treat the package a Lib package, optionally with a executable subpackage if appropriate.


The names of Haskell Lib packages, packaged for <code>ghc</code>, are prefixed by "ghc-".  For example the zlib library package is named <code>ghc-zlib</code>, and the QuickCheck library is named <code>ghc-QuickCheck</code>, etc.
The names of Haskell Lib packages, packaged for <code>ghc</code>, are prefixed by "ghc-".  For example the Haskell X11 library package is named <code>ghc-X11</code>, and the Haskell mmap library package is named <code>ghc-mmap</code>, etc.
 
Note that having different Haskell source packages named "ghc-xyz" and "xyz" is not allowed since they would both correspond to the same upstream package named "xyz" on Hackage.


BinLib packages should subpackage their libraries with naming following Lib packages.
BinLib packages should subpackage their libraries with naming following Lib packages.
For example the <code>xmonad</code> BinLib package has library subpackages
For example the <code>xmonad</code> BinLib package has library subpackages
* <code>ghc-xmonad</code> for the shared library, and
* <code>ghc-xmonad</code> for the shared library, and
Line 39: Line 43:
  %global pkg_name <package>
  %global pkg_name <package>


The macros <code>common_summary</code> and <code>common_description</code> are used as the basis
== Cabal Flags ==
for Summary and Description respectively for the Lib and BinLib base and subpackages.
Cabal flags for build options should be set by changing the package's <code>.cabal</code> file: this can be done with the <code>cabal-tweak-flag</code> script to avoid having to carry and maintain patches for this.
It is recommended to define them otherwise simple generic text based on <code>pkg_name</code> will be used for the subpackages.
<code>%cabal_configure_options</code> can be set to pass other options to Cabal.
 
Modifying the <code>.cabal</code> file flags defaults allows packagers and tools like <code>cabal-rpm</code> to track actual package dependencies correctly.
 
== Dependency Generation ==
Spec file build dependencies are generated by the <code>cabal-rpm</code> packaging tool.
 
RPM dependencies for Haskell libraries are automatically generated at build-time by the <code>ghc-deps.sh</code> script.
 
The <code>cabal-tweak-dep-ver</code> script can be used to bump versions of dependencies in the package .cabal file.


== Shared and static library linking ==
== Shared and static library linking ==
GHC uses static libraries by default, but now also supports shared libraries on some platforms.  Lib and BinLib packages should provide static, shared, and profiling libraries:
GHC uses static libraries by default, but supports shared libraries on some architectures: currently i686 and x86_64.  Lib and BinLib packages should provide static, shared, and profiling libraries:
* the shared library lives in the base library package, and
* the shared library lives in the base library package, and
* the static and profiling library and header files in the -devel subpackage.
* the static and profiling library and header files in the -devel subpackage.
Line 52: Line 65:
Executables in Bin and BinLib packages should be dynamically linked to shared libraries.
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 in their own package, but will be dynamically linked against other dependent libraries.
Note that executables in most BinLib packages are currently staticly linked against the library in their own package (unless the .cabal file explicitly lists it as a dependency), but dynamically linked against other dependent libraries. BinLib executables that do link dynamically against their own library should use <code>%ghc_fix_dynamic_rpath</code> to fix its RPATH.


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.
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 ==
== RPM Macros ==
The templates all have buildrequires for ghc-rpm-macros, which provides [http://pkgs.fedoraproject.org/gitweb/?p=ghc-rpm-macros.git;a=blob;f=ghc-rpm-macros.ghc macros.ghc] to assist with packaging Haskell Cabal packages.
The templates all have buildrequires for ghc-rpm-macros, which provides [http://pkgs.fedoraproject.org/cgit/ghc-rpm-macros.git/tree/ghc-rpm-macros.ghc macros.ghc] to assist with packaging Haskell Cabal packages.
 
<pre>
BuildRequires:  ghc-rpm-macros
</pre>


The main commonly used macros are:
The main commonly used macros are:


* %ghc_bin_build, %ghc_lib_build
* %ghc_bin_build
* %ghc_bin_install, %ghc_lib_install
* %ghc_lib_build
* %ghc_devel_package, %ghc_devel_description
* %ghc_bin_install
* %ghc_package, %ghc_description
* %ghc_lib_install
* %ghc_devel_post_postun
* %ghc_files


They are used in the templates and explained in more detail below.
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
== Bin packages ==
a macro can be replaced by its expansion
 
and then tweaked in order to get a package to build for Fedora.
Bin package executables should be dynamically linked to shared Haskell libraries when available, but this can be overridden if necessary by defining the <code>ghc_without_dynamic</code> macro.
 
<pre>
%build
%ghc_bin_build


== Bin packages ==


Bin package executables are dynamically linked to shared Haskell libraries when available, but this can be overridden if necessary by defining the <code>ghc_without_dynamic</code> macro.
%install
%ghc_bin_install
</pre>


* <code>%ghc_bin_build</code> is used to configure and build bin packages. It runs:
<code>%ghc_bin_build</code> is used to configure and build bin packages. It runs:
** <code>%global debug_package %{nil}</code>: debuginfo is disabled since ghc's output is not in DWARF format.
* <code>%global debug_package %{nil}</code>: debuginfo is disabled since ghc's output is not in GDB format.
** <code>%cabal_configure</code>: configure the package for building and dynamic linking.
* <code>%cabal_configure</code>: configure the package for building and dynamic linking.
** <code>%cabal build</code>: builds the package.
* <code>%cabal build</code>: builds the package.


* <code>%ghc_bin_install</code> is used to install bin packages.  It runs:
<code>%ghc_bin_install</code> is used to install bin packages.  It runs:
** <code>%cabal_install</code>: installs the package.
* <code>%cabal_install</code>: installs the package.
** <code>%ghc_strip_dynlinked</code>: strips the dynamically linked binary.
* <code>%ghc_strip_dynlinked</code>: strips the dynamically linked binary.


== Lib and BinLib packages ==
== 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 <code>ghc_without_dynamic</code> macro.
BinLib package executables should be dynamically linked to other shared Haskell libraries when available, but this can be overridden if necessary by defining the <code>ghc_without_dynamic</code> macro.
 
Devel subpackages need to setup some Requires:
 
<pre>
%package -n ghc-%{pkg_name}-devel
Summary:        Haskell %{pkg_name} library development files
Requires:      ghc-compiler = %{ghc_version}
Requires(post): ghc-compiler = %{ghc_version}
Requires(postun): ghc-compiler = %{ghc_version}
Requires:      ghc-%{pkg_name} = %{version}-%{release}
</pre>
 
Lib packages need to use <code>%setup -n</code>:
 
<pre>
%prep
%setup -q -n %{pkg_name}-%{version}
</pre>
 
Both Lib and BinLib have:
 
<pre>
%build
%ghc_lib_build
 
 
%install
%ghc_lib_install
 


* <code>%ghc_lib_build</code> is used to configure, build and generate documentation for Lib and BinLib packages.  It runs:
%post devel
** <code>%global debug_package %{nil}</code>: debuginfo is disabled since ghc's output is not in DWARF format.
%ghc_pkg_recache
** <code>%cabal_configure --ghc -p</code>: configures the package for building with ghc and profiling.  Libraries should build profiling versions of their static libraries.
** <code>%cabal build</code>: builds the package.
** <code>%cabal haddock</code>: 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 <code>without_haddock</code>.
*** Additionally links to colored html sourcecode are also generated with <code>hscolour</code>, which can be disabled by defining <code>without_hscolour</code>.


* <code>%ghc_lib_install</code> is used to install Lib and BinLib packages.  It runs:
** <code>%cabal_install</code>: installs the package without registering it in ghc-pkg.
** <code>%cabal_pkg_conf</code>: creates ghc-pkg .conf metadata file for package installation time
** <code>%ghc_gen_filelists</code>: generates rpm filelists.
** <code>%ghc_strip_dynlinked</code>: strips dynamically linked objects.


* <code>%ghc_devel_package</code>: Boilerplate to define devel subpackages.
%postun devel
* <code>%ghc_devel_description</code>: Boilerplate for devel subpackage description.
%ghc_pkg_recache
</pre>


* <code>%ghc_package</code>: BinLib boilerplate to define base library subpackage.
<code>%ghc_lib_build</code> is used to configure, build and generate documentation for Lib and BinLib packages.  It runs:
* <code>%ghc_description</code>: BinLib boilerplate for base library subpackage description.
* <code>%global debug_package %{nil}</code>: debuginfo is disabled since ghc's output is not in DWARF format.
* <code>%cabal_configure --ghc -p</code>: configures the package for building with ghc and profiling.  Libraries should build profiling versions of their static libraries.
* <code>%cabal build</code>: builds the package.
* <code>%cabal haddock</code>: 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 <code>without_haddock</code>.
** Additionally links to colored html sourcecode are also generated with <code>hscolour</code>, which can be disabled by defining <code>without_hscolour</code>.


* <code>%ghc_devel_post_postun</code>: post and postun boilerplate for devel subpackage.
<code>%ghc_lib_install</code> is used to install Lib and BinLib packages.  It runs:
** The install scripts run <code>%ghc_pkg_recache</code> to refresh the ghc package cache database with .conf file data.
* <code>%cabal_install</code>: installs the package without registering it in ghc-pkg.
* <code>%cabal_pkg_conf</code>: creates ghc-pkg .conf metadata file for package installation time
* <code>%ghc_gen_filelists</code>: generates rpm filelists.
* <code>%ghc_strip_dynlinked</code>: strips dynamically linked objects.


* <code>%ghc_files</code>: Helper macro for %files lists for base library and devel subpackages (see below).
<code>%ghc_pkg_recache</code>: used in %post and %postun for devel subpackage - refreshes the ghc package cache database with .conf file data.


== Directories ==
== Directories ==
Line 124: Line 172:
Filelists for shared and devel library subpackages are generated through <code>%ghc_lib_install</code> using the macro <code>%ghc_gen_filelists</code>.
Filelists for shared and devel library subpackages are generated through <code>%ghc_lib_install</code> using the macro <code>%ghc_gen_filelists</code>.


It generates the filelists: <code>ghc-%{pkg_name}.files</code> and <code>ghc-%{pkg_name}-devel.files</code>.
It generates the filelists <code>ghc-%{pkg_name}.files</code> and <code>ghc-%{pkg_name}-devel.files</code>.
 
The files sections are boilerplate generated by the <code>%ghc_files</code>.
 
If you need to add additional %doc files to the base library package they can pass them as arguments to <code>%ghc_files</code>.
Additionally files to the devel subpackage can be appended below <code>%ghc_files</code>.
 
For example:
 
    %ghc_files COPYING
    %doc README
 
adds a license file to the base library package and a README file to the devel subpackage.


== Compiling non-Cabal packages ==
== Compiling non-Cabal packages ==

Latest revision as of 07:44, 17 May 2013

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 the current guidelines mostly focus on packaging for GHC using Cabal.

Spec file templates

Spec files in line with these templates are generated automatically by the cabal-rpm packaging tool which also adds dependencies listed in the package's .cabal configuration file. Most packages should then build, though for some packages it may be necessary to specify some additional BuildRequires and/or Requires, and to check non-Haskell devel dependencies.

There are three types of Haskell Cabal packages: library only (Lib), binary only (Bin), and binary and library (BinLib):

Standardizing the packaging helps to lower the maintenance burden across Fedora's Haskell packages.

Package 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. However there may be cases where a Haskell BinLib package is really a Lib package with a minor or unimportant executable: in this case it is better to treat the package a Lib package, optionally with a executable subpackage if appropriate.

The names of Haskell Lib packages, packaged for ghc, are prefixed by "ghc-". For example the Haskell X11 library package is named ghc-X11, and the Haskell mmap library package is named ghc-mmap, etc.

Note that having different Haskell source packages named "ghc-xyz" and "xyz" is not allowed since they would both correspond to the same upstream package named "xyz" on Hackage.

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, and
  • ghc-xmonad-devel for devel files and the static library.

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.

Headers

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>

Cabal Flags

Cabal flags for build options should be set by changing the package's .cabal file: this can be done with the cabal-tweak-flag script to avoid having to carry and maintain patches for this. %cabal_configure_options can be set to pass other options to Cabal.

Modifying the .cabal file flags defaults allows packagers and tools like cabal-rpm to track actual package dependencies correctly.

Dependency Generation

Spec file build dependencies are generated by the cabal-rpm packaging tool.

RPM dependencies for Haskell libraries are automatically generated at build-time by the ghc-deps.sh script.

The cabal-tweak-dep-ver script can be used to bump versions of dependencies in the package .cabal file.

Shared and static library linking

GHC uses static libraries by default, but supports shared libraries on some architectures: currently i686 and x86_64. Lib and BinLib packages should provide static, shared, and profiling libraries:

  • the shared library lives in the base library package, and
  • the static and profiling library and header files in the -devel subpackage.

Because GHC still 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 most BinLib packages are currently staticly linked against the library in their own package (unless the .cabal file explicitly lists it as a dependency), but dynamically linked against other dependent libraries. BinLib executables that do link dynamically against their own library should use %ghc_fix_dynamic_rpath to fix its RPATH.

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.

BuildRequires:  ghc-rpm-macros

The main commonly used macros are:

  • %ghc_bin_build
  • %ghc_lib_build
  • %ghc_bin_install
  • %ghc_lib_install

They are used in the templates and explained in more detail below.

Bin packages

Bin package executables should be dynamically linked to shared Haskell libraries when available, but this can be overridden if necessary by defining the ghc_without_dynamic macro.

%build
%ghc_bin_build


%install
%ghc_bin_install

%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 GDB 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 should be dynamically linked to other shared Haskell libraries when available, but this can be overridden if necessary by defining the ghc_without_dynamic macro.

Devel subpackages need to setup some Requires:

%package -n ghc-%{pkg_name}-devel
Summary:        Haskell %{pkg_name} library development files
Requires:       ghc-compiler = %{ghc_version}
Requires(post): ghc-compiler = %{ghc_version}
Requires(postun): ghc-compiler = %{ghc_version}
Requires:       ghc-%{pkg_name} = %{version}-%{release}

Lib packages need to use %setup -n:

%prep
%setup -q -n %{pkg_name}-%{version}

Both Lib and BinLib have:

%build
%ghc_lib_build


%install
%ghc_lib_install


%post devel
%ghc_pkg_recache


%postun devel
%ghc_pkg_recache

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

%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_pkg_recache: used in %post and %postun for devel subpackage - refreshes the ghc package cache database with .conf file data.

Directories

GHC libraries are installed under %ghcpkgdir/%{pkg_name}-%{version}:

Library documentation lives under %ghclibdocdir/%{pkg_name}-%{version}.

File lists

Filelists for shared and devel library subpackages are generated through %ghc_lib_install using the macro %ghc_gen_filelists.

It generates the filelists ghc-%{pkg_name}.files and ghc-%{pkg_name}-devel.files.

Compiling non-Cabal packages

Packages compiling Haskell code without Cabal, ie directly with ghc or ghc --make, should use -O1 optimization, like Cabal does by default.

References