From Fedora Project Wiki
Line 86: Line 86:


== Packaging binaries ==
== Packaging binaries ==
Binaries are packaged by their simple name<code>xmonad</code> would remain <code>xmonad</code>.  This does not apply to the libraries that are included in the cabal package.  A 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 the description explaining that these are the libraries necessary for xmonad to run.
Binaries are packaged by their simple name, eg <code>xmonad</code> would remain <code>xmonad</code>.  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.
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.

Revision as of 08:16, 25 June 2008

Haskell Packaging Guidelines

This document seeks to document 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 one of the more popular Haskell compilers. 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.

Base package naming

Libraries

Haskell library packages should be named after the compiler or interpreter they are used with. For example, if a Haskell library called trunks is only for GHC, the base package name in Fedora should be called ghc-trucks.

If a library supports multiple Haskell compilers or interpreters, the base name should instead be prefixed with haskell, e.g. haskell-trunks. Such a package would then have subpackages for each compiler and/or interpreter it is built for (e.g. ghc-trunks, hug98-trunks, etc.

Binaries

For Haskell packages for 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. For example, if compiled against GHC the library tubes's base name would be called ghc-tubes.

Summarizing: in CVS, library packages with no binaries are named like ghc-trucks. Program packages are named like tubes.

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.

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 to define filelists, rather than doing it by hand:

cd ${RPM_BUILD_ROOT}
echo '%defattr(-,root,root,-)' > %{_builddir}/%{?buildsubdir}/%{name}-files.prof
find .%{pkg_libdir} \( -name '*_p.a' -o -name '*.p_hi' \) | sed s/^.// >> %{_builddir}/%{?buildsubdir}/%{name}-files.prof
echo '%defattr(-,root,root,-)' > %{_builddir}/%{?buildsubdir}/%{name}-files.nonprof
find .%{pkg_libdir} -type d | sed 's/^./%dir /' >> %{_builddir}/%{?buildsubdir}/%{name}-files.nonprof
find .%{pkg_libdir} ! \( -type d -o -name '*_p.a' -o -name '*.p_hi' \) | sed s/^.// >> %{_builddir}/%{?buildsubdir}/%{name}-files.nonprof
sed 's,^/,%exclude /,' %{_builddir}/%{?buildsubdir}/%{name}-files.prof >> %{_builddir}/%{?buildsubdir}/%{name}-files.nonprof

cd ${RPM_BUILD_ROOT}/%{_datadir}/doc/%{hsc_namever}-%{f_pkg_name}-%{version}
rm -rf doc LICENSE README

Install scripts

Libraries must be registered with the installed ghc.

  • Not sure about using cabal for this --JensPetersen
  • What about security? As such the current system using ghc-pkg works ok and is safe.

To generate registration scripts that can be embedded in the package, include the following in %build

runghc Setup register --gen-script
runghc Setup unregister --gen-script

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

runghc Setup copy --destdir=${RPM_BUILD_ROOT}
install -m 755 register.sh unregister.sh ${RPM_BUILD_ROOT}%{pkg_libdir}

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

%pre -n %{hsc_namever}-%{f_pkg_name}
[ "$1" = 2 ]  && %{pkg_libdir}/unregister.sh >&/dev/null || :


%post -n %{hsc_namever}-%{f_pkg_name}
%{pkg_libdir}/register.sh >&/dev/null


%preun -n %{hsc_namever}-%{f_pkg_name}
%{pkg_libdir}/unregister.sh >&/dev/null


%postun -n %{hsc_namever}-%{f_pkg_name}
[ "$1" = 1 ]  && %{pkg_libdir}/register.sh >& /dev/null || :

Packaging binaries

Binaries are packaged by 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

Need to make sure Haddock interacts correctly with all the other included packages. The biggest challenge is making sure all packages are hyperlinked to each other correctly. (This may require an expensive post package install relinking phase for every Haskell library. I would like to avoid this, so it will involve some research. [I certainly hope not --JensPetersen] )

Debug Information

debuginfo packages shouldn't even be built. GHC doesn't emit DWARF debug data.

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.

  1. Library Only Template
  2. Library and Binary Template
  3. Binary Only Template

Comments

  • Some libraries (like X11 until ghc-6.8.1) included with GHC are not the newest version. Some packages like xmonad need a newer version. Do we break apart the GHC package into multiple libraries that other packages can also update from other sources?
  • I would love to do this. --YaakovNemoy
  • I'm not thrilled with the idea of splitting up ghc and the extralibs,

because it's a pain to have to install a dozen packages after ghc itself on systems that do the split, like Debian.

If we can come up with some scheme that does the split, but gets the whole lot installed in one go, then fine.

It's also perfectly reasonable, as far as GHC is concerned, to have multiple versions of a package installed at once. --BryanSullivan

  • Do we keep GHC installed libraries in one place, RPM installed libraries in another place, and pray that cabal keeps things organized?
  • GHC puts it's packaged libraries in /usr/lib/ghc/lib. There are no conflicts. --YaakovNemoy
  • Fedora is only concerned with rpm packages
  • users can install their own libraries locally in their homedir if they wish.
  • How do we handle Haddock data? Do we mandate haddock packages go in -doc? -haddock? should we enforce special build time requirements to make sure all haddock packages hyperlink to one another?
  • More research is needed here. This will not make it into Fedora 9 most likely. --YaakovNemoy
  • The standard for doc packages is a -doc suffix, so we're already doing the right thing. --BryanSullivan
  • Haddock should pick up links across packages properly by default. --BryanSullivan
  • Update: It's been pointed out that this probably already works. --YaakovNemoy
  • Some libraries take build time options via flags in cabal. Do we provide sane defaults? Both types? (This doesn't apply to trivial flags, like ones used to determine if they are compiled with the new/old versions of GHC.)
  • This decision should be made on a per package basis. If a sample RPM can be built that handles options, perhaps we can look at integrating it into cabal-rpm. --YaakovNemoy
  • Other than what cabal-rpm does already, are there any rules we need for profiling packages?
  • I would say no. -- YaakovNemoy
  • Do we need -devel sub-packages?
  • No. --BryanSullivan
  • Package names are entirely lower case. Hackage package names should be converted. cabal-rpm does this automatically. -- YaakovNemoy
  • I disagree with this: I think we should preserve case of names as usual -- JensPetersen
  • I pulled this from python's playbook. I believe that it is what is generally prefered by Fedora people, rather than having RidiculousNamingSCHeMES. --Yaakov
  • I agree with Yaakov's proposal to lowercase all names. The Haskell package naming capitalisation conventions are nonexistent and often ugly. -- BryanSullivan