Capri

Synopsis

Capri (abbreviation of CAbal PRIvate) is a wrapper program on top of cabal-install to operate it in project-private mode. In this mode, there is no global or user package databases; only one package database is defined, private to the project, located under the root directory of a project.

Capri is mainly intended for use with projects organized as Cabal packages targeting executables rather than just libraries. Capri is intended for use with Glasgow Haskell Compiler only as it depends on certain its features. It is also recommended to use cabal-install of recent versions (as of July 2010, the most recent version is 0.8.2).

Introduction

A situation is possible, when a local (global or user or both) Cabal packages database contains a package of the same name, but of several versions. Over time, other packages may be installed, depending on various versions of that package. Bad things happen when a new package is to be built, depending on other packages which in turn depend on different versions of the package mentioned first.

While such situation may be cured by careful tracing of dependencies, removal of old versions of packages, and rebuilding of new packages, there is a way to avoid it from the beginning. For each package, create a private database of packages it depends upon. This makes practical sense mainly for packages targeting statically linked executables, ensuring a clean build environment. Other than this, private building may be used for test builds of library packages as well, but it is not recommended to use libraries built privately together in other packages.

The Glasgow Haskell Compiler uses the GHC_PACKAGE_PATH environment variable to describe the location of Haskell packages database. A typical configuration of such database consists of global and user databases. Default locations of these databases are known to the compiler even when the variable is not set.

It is however possible to make GHC not to use any of these databases, and point it to an alternative location instead. In order to do this, the variable has to contain a single path, and not to be terminated with a path delimiter (colon or semicolon, depending on Unix/Windows platrorm). This is how project-private build is achieved at GHC level. Cabal-install in turn requires several options to be specified, to restrict itself to using only private packages database to look for installed packages, and the installation directory prefix which is also local to a project.

Source Location

Haskell source: http://hs-ogl-misc.googlecode.com/hg/capri/Main.hs

Hackage: TBD

Commands Summary

$ capri help
This program provides a wrapper over cabal-install to operate in project-private mode.

Usage: capri COMMAND [FLAGS]
   or: capri [GLOBAL FLAGS]

Global flags:
 -h --help            Show this help text
 -V --version         Print version information
    --numeric-version Print just the version number

Commands:
  bootstrap    Bootstrap private packages configuration
  list         List packages installed privately
  clone        Clone package(s) installed publicly into the private packages database
  ghc-pkg      Invoke the ghc-pkg program to run arbitrary action on private packages
  cabal        Invoke the cabal-install or Setup.{hs|lhs} program to run arbitrary action on private packages
  import       Build another package with respect to this package's private packages database and installation path
  install      Short-cut for cabal install command
  configure    Short-cut for cabal configure command
  build        Short-cut for cabal build command
  help         Help about commands

For more information about a command use
  capri COMMAND --help

Typical steps of building Haskell projects with Capri:
  capri bootstrap
  capri clone
  capri configure
  capri build
  capri install

Building Executables with Capri

This chapter covers the general scenario of building executables using Capri. We will call a Cabal package targeting one or more executables, containing its own private package database and build with use of Capri "the project". All other Cabal packages involved in building of the project will be referred to as just "packages".

Layout of Capri Files

Capri keeps its files under the .capri subdirectory of a project's root directory. Private packages database is located in .capri/packages, and compiled packages are installed in .capri/install subdirectories. Thus, typical location of executables built is .capri/install/bin.

Bootstrapping Private Packages Database

Building of a package cannot start with entirely empty packages database: several essential packages have to be installed in order to build any project:

   base
   ffi
   ghc-prim
   integer-gmp
   rts

It is assumed that some minimal GHC installation exists that contains at least these packages.

The capri bootstrap command created the private packages database and installation directory. Next, it clones the above mentioned packages into the private database. The capri list command may be used to verify that all packages have been installed properly, and the project is ready to build.

Building and Installation

The easiest way to build a project with Capri is just to type a shortcut command:

capri install

at the shell prompt once the private packages database has been bootstrapped. This results in running cabal install command within the project's top directory, with GHC_PACKAGE_PATH environment variable set properly, and --package-db and --prefix options supplied. If any custom options are needed, another (more flexible) form of this command may be issued:

capri cabal -- install <any options and parameters>

Note the double hyphen after cabal: anything following it will never be treated as options, and will be passed to the cabal-install program.

Although the install command covers package configuration and building, two more shortcut commands are available: capri configure and capri build.

Cloning Already Compiled Packages

Cloning was mentioned earlier in the Bootstrapping paragraph. Any of the packages installed in the global or user package database can be "cloned" into the private packages database of the project.

Technically cloning is equivalent to running the ghc-pkg describe <package-name> command piping its standard output to the ghc-pkg register command while the first command runs with GHC_PACKAGE_PATH set to access the global and user package databases, and the second runs with GHC_PACKAGE_PATH set to access the project private packages database.

Importing Local Source Packages

Cabal-install is capable of automatic chasing project dependencies, downloading, compiling, and installing their code. If however a package the project depends upon is not on Hackage or any other repository known to Cabal-install, the only way to bring it into the scope of the project's private package database is to manually compile it. this however should be done with respect to the project's private package configuration: all additional dependencies should be looked up in and installed into the project's packages database as well.

The capri import command serves this purpose. Its typical syntax is

capri import directory [-- command options]

The command is equivalent to running the cabal install in the other package's directory, but with GHC_PACKAGE_PATH set to the project's packages database, also supplying the --package-db and --prefix options as needed.

Simply typing capri install directory without any additional options results in execution of cabal install in directory.

Advanced Topics

Running ghc-pkg and cabal-install