Mac OS X Common Installation Paths

The default layout for installed Haskell components follows the conventions of most unix-like systems. On Mac OS X, this layout isn't optimal, and a different layout is used. The layout presented here has several advantages:

• Follows Apple's Guidelines for file system layout
• Makes it easy for a user to locate all the Haskell components, especially user installed packages
• Enables easy removal of a user installed package, whether they have installed it --user or --global.
• Facilitate creation of unified, hyper-linked Haddock documentation, optionally with source

Haskell Platform 2011.2.0.0 (March 2011) and later uses this layout and sets up cabal to use it for built packages. On new installs, if you didn't already have a ~/.cabal/config file, then it is set up by default. Otherwise, the config file for this layout is placed in ~/.cabal/config.platform and you can manually move it over, or incorporate it into your existing config file.

Implementations

Haskell implementations are generally installed for use by all accounts on the system. They consist of large collections of executables, libraries, and other files. These are packaged using Apple's framework, versioning, and bundling techniques and installed in:

 /Library/Frameworks

For example, GHC 7.0.2 is installed in:

 /Library/Frameworks/GHC.framework/Versions/7.0.2-i386

Executables intended for use from the command line, are be symlink'd into:

 /usr/bin

[Q: Would /usr/local/bin be more appropriate? ]

Packages that come with the implementation, are be located within the Framework bundle.

If the implementation has any GUI applications, these are installed in:

 /Applications

NB: These guidelines allow for multiple implementations and multiple versions to co-exist. (With the exception of multiple versions of GUI applications which can only be done by distinct naming, and the symlinks in /usr/bin which can achieved in the normal way: Append the version number to the executable and then symlink the 'bare' name to the most recent.

If implementations want to be able to be installed "per user", then the above paths should be:

 ~/Library/Frameworks
 ~/bin
 ~/Applications

Not all software for Mac OS X offers a "per user" option on installation, and while nice, it is by no means universal.

User Installed Packages

User installed packages are placed under a "prefix" that depends on if the user choose to install for all users (--global) for just their own use (--user):

 /Library/Haskell  --global
 ~/Library/Haskell --user

Package Component Layout

Cabal offers a large amount of flexibility in where the various pieces of a package are installed. The GHC package system is rather agnostic about where these pieces are, and insulates the implementation from such differences. These combine to enable the choice of package layout to be largely to serve the user.

For both --global and --user installs, this is the recommended package layout on Mac OS X:

{prefix}
  {compiler}
    lib
      {pkgid}
        bin         -- binaries ($bindir)
        lib         -- libraries & .hi files ($libdir, $libdir/$libsubdir, $dynlibdir)
          include   -- include files ($includedir)
        libexec     -- private binaries ($libexecdir)
        share       -- data files ($datadir, $datadir/$datasubdir)    
        doc         -- documentation ($docdir)
          html      -- html doc ($htmldir, $haddockdir)
          man       -- man pages ($mandir)

This can be achieved with the following cabal configuration defaults:

 install-dirs user
   prefix:     ~/Library/Haskell/$compiler/lib/$pkgid
   bindir:     $prefix/bin
   libdir:     $prefix/lib
   libsubdir:  
   libexecdir: $prefix/libexec
   datadir:    $prefix/share
   datasubdir:
   docdir:     $datadir/doc
   htmldir:    $docdir/html
   haddockdir: $htmldir
 
 install-dirs global
   prefix:     /Library/Haskell/$compiler/lib/$pkgid
   bindir:     $prefix/bin
   libdir:     $prefix/lib
   libsubdir:  
   libexecdir: $prefix/libexec
   datadir:    $prefix/share
   datasubdir:
   docdir:     $datadir/doc
   htmldir:    $docdir/html
   haddockdir: $htmldir
 

N.B.:

• Cabal configuration files don't actually support ~. You must replace that with /Users/xxx where xxx is your account name.
• All packages for a given compiler are under a single directory. When an old compiler is removed, all the packages compiled for it can be easily removed too.
• All components for a package are under a single directory. This facilitates easy location and removal of a single package, for either a single compiler, or all installed versions.
• If a package generates different doc for different compilers (it may have different APIs available), then this structure preserves each.
• Executables are also per compilation, which is sometimes important (for Haddock, for example).

Executables

Packages that build executables to be run from the command line present a difficultly. They are built into a per-package bin directory, and then should be symlink'd somewhere on the user's PATH. For global installs, the logical place is one of:

/usr/bin
/usr/local/bin

For user installs, since ~/bin is not on the PATH by default on Mac OS X and may not exist, binaries are symlink'd into:

~/Library/Haskell/bin

Alas, cabal only supports one location for both kinds of build, and so it is set to be the later.

---

References

1. Apple guidelines for the /Library and ~/Library files
2. MtnViewMark's original e-mail on this topic.