Difference between revisions of "Haskell package guidelines"

From ArchWiki
Jump to: navigation, search
([haskell-web]: Changed [haskell] to [haskell-core])
(48 intermediate revisions by 17 users not shown)
Line 1: Line 1:
[[Category:Guidelines (English)]][[Category:Package development (English)]]
+
[[Category:Package development]]
'''Haskell on Arch Linux'''
+
[[it:Haskell Package Guidelines]]
 +
{{Package Guidelines}}
  
Haskell is well supported on Arch Linux, with GHC and other key tools available via pacman, and 87% percent of [http://hackage.haskell.org hackage.haskell.org] library database [http://aur.archlinux.org/packages.php?O=0&L=0&C=0&K=arch-haskell&SeB=m&SB=n&SO=a&PP=100&do_Search=Go available via AUR].
+
[[Wikipedia:Haskell|Haskell]] is well supported on Arch Linux.
Not all the haskell packages work all the time, though. Try installing haskell-platform and see it fail.
+
GHC and a few core packages are available in the [[Official Repositories|official repositories]].
 +
For more serious Haskellers, the [[ArchHaskell]] community project provides many packages from [http://hackage.haskell.org Hackage], and the number is growing.
  
'''[http://code.haskell.org/arch/arch-haskell-status.html The status of all Haskell packages in Arch Linux]'''
+
See the [[ArchHaskell]] community page for contact details and ways to help.
 
+
The community around Haskell on Arch is also active and well organized.
+
 
+
== Community ==
+
 
+
The main resources for the Arch/Haskell community to interact and discuss are:
+
 
+
* [http://www.gogloom.com/FreeNode/arch-haskell <nowiki>#arch-haskell</nowiki>] irc channel @ freenode.org
+
** Good for quick discussion and planning
+
* [http://haskell.org/mailman/listinfo/arch-haskell arch-haskell@haskell.org] mailing list
+
** Broader announcements, and automated updates
+
* [http://archhaskell.wordpress.com/ Arch Haskell Weekly News]
+
** A blog announcing our progress to the outside world.
+
  
 
== Haskell Packages ==
 
== Haskell Packages ==
 +
To use Haskell on Arch Linux, you have two mutually exclusive options:
 +
# Use packages from the official Arch Linux repositories. These are a well maintained small subset of all Haskell packages. Just install them the way you would install anything else on Arch Linux. Examples of what is available: in the [https://www.archlinux.org/packages/?arch=x86_64&repo=Extra&q=haskell&last_update=&limit=50 extra] and [https://www.archlinux.org/packages/?arch=x86_64&repo=Community&q=haskell&last_update=&limit=50 community] repositories. The packages here should satisfy people who just want to use the Haskell Platform. You may also combine this option with other packages from unofficial sources like the AUR.
 +
# Use the ArchHaskell project's unofficial repositories. These contain a much larger subset of what's available on Hackage. As a community effort, we often need volunteers to help maintain and add more packages to these repositories. Read on for information about using them.
  
The core Haskell tools are available in the core system (extra):
+
=== [haskell-core] ===
 
+
The [haskell-core] repository is the base repository of packages maintained by the ArchHaskell team.
==== <nowiki>[Extra]</nowiki> ====
+
[haskell-core] can be accessed by adding the following entry to {{ic|/etc/pacman.conf}} (above [extra]):
* [http://www.archlinux.org/packages/?arch=x86_64&repo=Extra&q=haskell&last_update=&limit=50 Haskell packages in the core system]
+
 
+
Our [http://haskell.org/haskellwiki/Arch_Linux/Policy policy] is for [extra] to provide the Haskell platform, and popular Haskell applications.
+
 
+
==== <nowiki>AUR</nowiki> ====
+
 
+
* [http://aur.archlinux.org/packages.php?O=0&L=0&C=0&K=arch-haskell&SeB=m&SB=n&SO=a&PP=100&do_Search=Go Haskell packages in AUR]
+
 
+
A huge number (almost 2000) packages built from http://hackage.haskell.org
+
 
+
These generally improve on installing directly from Hackage as they resolve required C libraries. They can be installed as, for example:
+
 
+
    sudo paktahn -S haskell-csv
+
 
+
Anything not found here can be installed via [http://aur.archlinux.org/packages.php?ID=17411 cabal-install] direct from Hackage.
+
 
+
== Direction and strategy ==
+
 
+
The strategy for Haskell on Arch Linux is to support the Haskell platform suite in [extra], and to track Hackage via AUR. This has been adopted as an [http://haskell.org/haskellwiki/Arch_Linux/Policy official policy document].
+
 
+
== Guidelines ==
+
 
+
In almost all cases cabalised Haskell packages can be automatically translated into Arch packages, via the cabal2arch tool.
+
 
+
* [http://aur.archlinux.org/packages.php?ID=17471 Get the latest cabal2arch]
+
 
+
It is strongly recommended that you use this tool, as it implements the packaging policy for Haskell packages.
+
These packages are primarily managed by Don Stewart.
+
 
+
Development version:
+
 
+
* darcs get http://code.haskell.org/~dons/code/cabal2arch
+
 
+
Or:
+
 
+
* cabal install cabal2arch
+
 
+
Most things on http://hackage.haskell.org that are packageable, are already in AUR.
+
 
+
If not, download and build cabal2arch, as below, and use that to create
+
the package. This will ensure it follows standard naming, dependency and installation conventions. Drop by #arch-haskell to let us know what is going on.
+
 
+
===cabal2arch: an example===
+
 
+
This example illustrates how to create a new package with cabal2arch. We'll make a
+
new package for the delimited continuations library, CC-delcont:
+
 
+
First, find [http://hackage.haskell.org/cgi-bin/hackage-scripts/package/CC-delcont the hackage page for CC-delcont], then identify the link to the .cabal file. Use this link
+
as an argument to cabal2arch:
+
 
+
$ cd /tmp
+
$ cabal2arch http://hackage.haskell.org/packages/archive/CC-delcont/0.2/CC-delcont.cabal
+
Using /tmp/tmp.Ig0H8jCOyO/CC-delcont.cabal
+
Fetching http://hackage.haskell.org/packages/archive/CC-delcont/0.2/CC-delcont-0.2.tar.gz
+
Created /tmp/haskell-cc-delcont.tar.gz
+
 
+
Checking what was created:
+
 
+
$ ls
+
haskell-cc-delcont  haskell-cc-delcont.tar.gz
+
 
+
The .tar.gz is a zipped PKGBUILD ready to upload to AUR.
+
You can now inspect the PKGBUILD and install script for the library:
+
 
+
    # Contributor: Arch Haskell Team <arch-haskell@haskell.org>
+
    # Package generated by cabal2arch 0.6.1
+
    pkgname=haskell-cc-delcont
+
    pkgrel=1
+
    pkgver=0.2
+
    pkgdesc="Delimited continuations and dynamically scoped variables"
+
    url="http://hackage.haskell.org/package/CC-delcont"
+
    license=('custom:OtherLicense')
+
    arch=('i686' 'x86_64')
+
    makedepends=()
+
    depends=('ghc' 'haskell-cabal')
+
    options=('strip')
+
    source=(http://hackage.haskell.org/packages/archive/CC-delcont/0.2/CC-delcont-0.2.tar.gz)
+
    install=haskell-cc-delcont.install
+
    md5sums=('e52149fca9bf76330a7c159917152790')
+
    build() {
+
        cd ${srcdir}/CC-delcont-0.2
+
        runhaskell Setup configure --prefix=/usr --docdir=/usr/share/doc/${pkgname} || return 1
+
        runhaskell Setup build                  || return 1
+
        runhaskell Setup haddock || return 1
+
        runhaskell Setup register  --gen-script || return 1
+
        runhaskell Setup unregister --gen-script || return 1
+
        install -D -m744 register.sh  ${pkgdir}/usr/share/haskell/$pkgname/register.sh
+
        install    -m744 unregister.sh ${pkgdir}/usr/share/haskell/$pkgname/unregister.sh
+
        install -d -m755 $pkgdir/usr/share/doc/ghc/libraries
+
        ln -s /usr/share/doc/${pkgname}/html ${pkgdir}/usr/share/doc/ghc/libraries/CC-delcont
+
        runhaskell Setup copy --destdir=${pkgdir} || return 1
+
        install -D -m644 LICENSE ${pkgdir}/usr/share/licenses/$pkgname/LICENSE || return 1
+
        rm -f ${pkgdir}/usr/share/doc/${pkgname}/LICENSE
+
    }
+
 
+
It follows the conventions for Haskell packages:
+
 
+
* Maintainer is by default the Arch Haskell team.
+
* Libraries are prefixed with "haskell-"
+
* "core" and "extra" Haskell libraries are not included as explicit dependencies, since ghc provides them
+
* It uses cabal to generate a post-install register/unregister script, with a standard name.
+
* We use haddock to build the documentation.
+
* Profiling versions of the library aren't currently installed (''TODO'')
+
 
+
All Haskell libraries should follow these naming conventions, and using the cabal2arch tool
+
will ensure this is the case.
+
 
+
Inspect the bundle, and confirm you can build and install it:
+
 
+
    $ makepkg -s
+
    $ makepkg -i
+
 
+
And we're ready to go. Now your .tar.gz is ready to upload to AUR.
+
 
+
=== "Provides" ===
+
 
+
[http://haskell.org/haskellwiki/Arch_Linux/Preferred_Package_Tools See the discussion on the use of "provides" here].
+
 
+
===Uploading the the Haskell repository ===
+
 
+
'''This section is out of date'''
+
 
+
The following (ad hoc) script is currently used to upload packages after running cabal2arch to the respository, and keep it in sync:
+
+
#!/bin/sh
+
set -e
+
makepkg -i
+
scp *-x86_64.pkg.tar.gz code.haskell.org:/srv/code/arch/x86_64/
+
repo-add /home/dons/haskell.db.tar.gz *.pkg.tar.gz
+
rm -rf *.tar.gz pkg src
+
pwd=`pwd`
+
dir=`basename $pwd`
+
cd ..
+
scp -r $dir code.haskell.org:/srv/code/arch/x86_64/
+
scp $HOME/haskell.db.tar.gz code.haskell.org:/srv/code/arch/x86_64/
+
 
+
This is to be used by those with arch-haskell repository write permissions.
+
 
+
===Guidelines for Libraries===
+
 
+
In general, each .cabal file should map to one PKGBUILD. The following conventions hold:
+
 
+
* libraries have their cabal names prefixed with "haskell-"
+
* all haskell dependencies are statically linked, so can go in the makedepends field.
+
* all libraries have a dependency on 'ghc'
+
* libraries don't need to have explicit dependencies on core Haskell packages -- these come in the 'ghc' package. (e.g. array, base, containers, random,  process etc).
+
* be careful about dependencies from gtk2hs: cairo, svg, glib, gtk. These are all provided by the 'gtk2hs' package, not , e.g. "haskell-cairo"
+
* we want to resolve dependencies with a fixed constraint to base>=3.0
+
* be careful about dependencies on the libraries provided by the basic 'ghc' package, which include:
+
 
+
ALUT-2.1.0.0        cgi-3001.1.5.1      network-2.1.0.0      regex-base-0.72.0.1
+
Cabal-1.2.3.0      containers-0.1.0.1  old-locale-1.0.0.0    regex-compat-0.71.0.1
+
GLUT-2.1.1.1        directory-1.0.0.0    old-time-1.0.0.0      regex-posix-0.72.0.2
+
HUnit-1.2.0.0      fgl-5.4.1.1          packedstring-0.1.0.0  stm-2.1.1.0
+
OpenAL-1.3.1.1      filepath-1.1.0.0    parallel-1.0.0.0      template-haskell-2.2.0.0
+
OpenGL-2.2.1.1      haskell-src-1.0.1.1  parsec-2.1.0.0        time-1.1.2.0
+
QuickCheck-1.1.0.0  haskell98-1.0.1.0    pretty-1.0.0.0        unix-2.3.0.0
+
array-0.1.0.0      hpc-0.5.0.0          process-1.0.0.0      xhtml-3000.0.2.1
+
base-3.0.1.0        html-1.0.1.1        random-1.0.0.0
+
bytestring-0.9.0.1  mtl-1.1.0.0          readline-1.0.1.0
+
  
These libraries don't need explicit dependencies to be set. cabal2arch solves all these constraints for us.
+
  [haskell-core]
 +
Server = http://xsounds.org/~haskell/core/$arch
  
Registering Haskell libraries is done via a register hook:
+
or
  
  build() {
+
  [haskell-core]
    cd ${srcdir}/cabal2arch-0.1
+
Server = http://www.kiwilight.com/haskell/core/$arch
    runhaskell Setup configure --prefix=/usr || return 1
+
    runhaskell Setup build                  || return 1
+
    -- generate register scripts
+
    runhaskell Setup register  --gen-script || return 1
+
    runhaskell Setup unregister --gen-script || return 1
+
    install -D -m744 register.sh    ${pkgdir}/usr/share/haskell/$pkgname/register.sh
+
    install    -m744 unregister.sh ${pkgdir}/usr/share/haskell/$pkgname/unregister.sh
+
    runhaskell Setup copy --destdir=${pkgdir} || return 1
+
    -- usual Haskell BSD3 license isnt' official
+
    install -D -m644 LICENSE ${pkgdir}/usr/share/licenses/$pkgname/LICENSE || return 1
+
}
+
  
* Examples:
+
The set of packages in the [haskell-core] repository is derived from the '''habs''' tree officially located [https://github.com/archhaskell/habs here]. A tool called [https://github.com/magthe/cblrepo cblrepo] is used to keep the '''habs''' tree synchronized with the official Haskell packages from [http://hackage.haskell.org/packages/hackage.html Hackage].
haskell-zlib, haskell-mersenne-random
+
  
===Guidelines for Programs ===
+
Putting [haskell-core] above [extra] will ensure that the packages from [haskell-core] take precedence, in case of duplicate packages in the two repositories.
  
* Have their normal name. Examples:
+
The repositories provide both file listings (by using {{ic|repo-add --files}}), package deltas ({{ic|repo-add --delta}}), and both packages and the database are signed.  The fingerprint of the key used for signing is:
hmp3, xmonad, ghc, cabal-install
+
  
* Be careful about dynamically linked runtime dependencies on C. For example, all GHC-produced binaries
+
  pub  2048D/4209170B 2012-12-26
have a runtime dependency on 'gmp'. OpenGL or GtT-based binaries will have additional 'depends'. cabal2arch will attempt to work out the C dependencies, but there may be others implied by Haskell dependencies that are missed.
+
        Key fingerprint = F310 4992 EBF2 4EB8 72B9  7B9C 32B0 B453 4209 170B
 +
  uid                  ArchHaskell (Magnus Therning) <magnus@therning.org>
 +
  sub  2048D/A418C0FE 2012-12-26
  
* Use executable stripping, --enable-executable-stripping. cabal2arch will do this automatically.
+
=== [haskell-web] ===
 +
The [haskell-web] repository builds on [haskell-core], providing several more packages, especially those useful for web applications.
  
== Haskell on Arch: current state ==
+
[haskell-web]
 +
Server = http://archhaskell.mynerdside.com/$repo/$arch
  
* http://www.galois.com/~dons/arch-haskell-status.html
+
Add it after [haskell-core].
  
===AUR===
+
=== Last resorts ===
 +
* [https://aur.archlinux.org/packages.php?O=0&K=haskell- Haskell packages in the AUR]
 +
* cabal-install directly
  
There's another [http://aur.archlinux.org/packages.php?O=0&L=0&C=0&K=haskell&SB=v&SO=d&PP=100&SeB=nd&do_Orphans= > 550 Haskell packages] in AUR.
+
Unfortunately, many of the packages in the AUR are outdated due to a lack of resources.
 +
If you have the time, it is recommended to use cblrepo and create something like [haskell-web], which can then be added to the collection of haskell-providing repositories.
  
== Building all of Hackage ==
+
== Improving ArchHaskell ==
  
The following simple script, with cabal-install and cabal2arch installed,
+
=== Community ===
will do a simple run over all the Haskell packages on haskell.org,
+
See the [[ArchHaskell]] community page and get in touch via the mailing list or the IRC channel.
creating arch packages for them. Before you start it is worthwhile removing all haskell packages, and reinstalling them. And then editing your unpacked haskell package directory to remove base libraries -- you probably don't want to install them.
+
  
 +
=== Overview ===
 +
The plan is to have one user-facing repository, [haskell], which merges the packages available in various satellite repositories (like [haskell-web]), thereby distributing the maintenance load.
 +
One satellite repo is special, the [haskell-core] repository, which provides packages that are dependencies of all the other satellites.
  
    #!/bin/sh
+
=== [haskell-core] maintenance ===
    cabal update
+
Ensure:
    tmpdir=`mktemp -d`
+
* [haskell-core] is an Arch repo hosted at kiwilight and xsounds.
    finaldir=`mktemp -d`
+
* [haskell-core] is in sync with the [https://github.com/archhaskell/habs habs] cblrepo database.
    cd $tmpdir
+
    tar xzf $HOME/.cabal/packages/hackage.haskell.org/00-index.tar.gz
+
    for dir in * ; do
+
        if [ ! -d $dir ] ; then
+
            continue
+
        fi
+
        cd $dir
+
        lib=`ls --color=never -1 | tail -1`
+
        echo "************** Building package for $dir-$lib"
+
        cd $lib
+
        cabal2arch *.cabal > $dir.log 2>&1
+
        cd `find . -type d -a ! -name '.'`
+
        if makepkg -sm > ../$dir.log 2>&1 ; then
+
            echo "OK: " $dir-$lib
+
            cp *.pkg.tar.gz $finaldir/
+
            sudo pacman -A *.pkg.tar.gz
+
            rm *.pkg.tar.gz
+
            rm -rf pkg src *.tar.gz
+
            cd ..
+
            cp -R `find . -type d -a ! -name '.'` $finaldir/
+
            cp *.tar.gz $finaldir/
+
        else
+
            echo "Failed"
+
        fi
+
        cd $tmpdir
+
    done
+
    echo `ls $finaldir/*pkg* | wc -l` "build packages in $finaldir"
+
    echo "Now: scp -r $finaldir/* code.haskell.org:/srv/code/arch/$MACHTYPE/"
+
  
== Automatic local building of Hackage Packages with cabal2arch using Bauerbill ==
+
=== Other repo maintenance ===
Although there are a number of haskell packages on AUR, there will always be outdated packages on AUR. If this happens and you want to create a fully updated package you would normally use cabal2arch. This however can become painful/time consuming if you have numerous packages with different dependencies (some of which may/may not be updated). Instead you can automatic this process by using [[Bauerbill]] which has the --hackage flag, allowing you to create AUR packages from Hackage locally. Below is an example of some common commands
+
For example, for haskell-foo, ensure:
 +
* haskell-foo is a cblrepo database, possibly using packages from [haskell-core] as DistroPkgs.
 +
* Whenever [haskell-core] is updated, haskell-foo's database is updated to match within a reasonable time.
  
    bauerbill -S --hackage [pkgs] : build [pkgs] directly from Hackage*
+
=== Creating another repo ===
    bauerbill -Si --hackage [pkgs] : look up information about [pkgs]
+
    bauerbill -Ss --hackage [args] : search for [args]
+
    bauerbill -Qu --hackage : list upgradable Hackage packages
+
  
Syncing packages with the --hackage flag will interactively download all dependencies of the package from Hackage, convert them using cabal2arch and then build/install them (while checking dependencies). You can combine this with the --aur flag to give precedence to Hackage packages that are on AUR
+
=== List of satellite repos ===

Revision as of 22:37, 5 February 2013

Template:Package Guidelines

Haskell is well supported on Arch Linux. GHC and a few core packages are available in the official repositories. For more serious Haskellers, the ArchHaskell community project provides many packages from Hackage, and the number is growing.

See the ArchHaskell community page for contact details and ways to help.

Haskell Packages

To use Haskell on Arch Linux, you have two mutually exclusive options:

  1. Use packages from the official Arch Linux repositories. These are a well maintained small subset of all Haskell packages. Just install them the way you would install anything else on Arch Linux. Examples of what is available: in the extra and community repositories. The packages here should satisfy people who just want to use the Haskell Platform. You may also combine this option with other packages from unofficial sources like the AUR.
  2. Use the ArchHaskell project's unofficial repositories. These contain a much larger subset of what's available on Hackage. As a community effort, we often need volunteers to help maintain and add more packages to these repositories. Read on for information about using them.

[haskell-core]

The [haskell-core] repository is the base repository of packages maintained by the ArchHaskell team. [haskell-core] can be accessed by adding the following entry to /etc/pacman.conf (above [extra]):

[haskell-core]
Server = http://xsounds.org/~haskell/core/$arch

or

[haskell-core]
Server = http://www.kiwilight.com/haskell/core/$arch

The set of packages in the [haskell-core] repository is derived from the habs tree officially located here. A tool called cblrepo is used to keep the habs tree synchronized with the official Haskell packages from Hackage.

Putting [haskell-core] above [extra] will ensure that the packages from [haskell-core] take precedence, in case of duplicate packages in the two repositories.

The repositories provide both file listings (by using repo-add --files), package deltas (repo-add --delta), and both packages and the database are signed. The fingerprint of the key used for signing is:

 pub   2048D/4209170B 2012-12-26
       Key fingerprint = F310 4992 EBF2 4EB8 72B9  7B9C 32B0 B453 4209 170B
 uid                  ArchHaskell (Magnus Therning) <magnus@therning.org>
 sub   2048D/A418C0FE 2012-12-26

[haskell-web]

The [haskell-web] repository builds on [haskell-core], providing several more packages, especially those useful for web applications.

[haskell-web]
Server = http://archhaskell.mynerdside.com/$repo/$arch

Add it after [haskell-core].

Last resorts

Unfortunately, many of the packages in the AUR are outdated due to a lack of resources. If you have the time, it is recommended to use cblrepo and create something like [haskell-web], which can then be added to the collection of haskell-providing repositories.

Improving ArchHaskell

Community

See the ArchHaskell community page and get in touch via the mailing list or the IRC channel.

Overview

The plan is to have one user-facing repository, [haskell], which merges the packages available in various satellite repositories (like [haskell-web]), thereby distributing the maintenance load. One satellite repo is special, the [haskell-core] repository, which provides packages that are dependencies of all the other satellites.

[haskell-core] maintenance

Ensure:

  • [haskell-core] is an Arch repo hosted at kiwilight and xsounds.
  • [haskell-core] is in sync with the habs cblrepo database.

Other repo maintenance

For example, for haskell-foo, ensure:

  • haskell-foo is a cblrepo database, possibly using packages from [haskell-core] as DistroPkgs.
  • Whenever [haskell-core] is updated, haskell-foo's database is updated to match within a reasonable time.

Creating another repo

List of satellite repos