How to run Gitit from a Cabal sandbox?

by Michał Antkiewicz

Some Haskell projects, such as Gitit, dynamically load Haskell modules which implement plugins. ClaferWiki is one such a plugin for Gitit. To have Gitit load the ClaferWiki plugin, one must specify the following in the gitit.cnf file

plugins: Network.Gitit.Plugin.ClaferWiki

Gitit will then search for the module ClaferWiki in the user and global package registries. However, when the plugin is installed in a Cabal sandbox, it will not be found.

UPDATE (Feb 10, 2015): the claferwiki.sh script now provides an option --sandbox.

Gitit is normally run using the command

gitit -f gitit.cnf

In order to make the cabal sandbox visible to Gitit, it must be started in the sandbox environment using the command cabal exec (you'll need cabal install >= 1.20) as follows:

cabal exec gitit -- -f gitit.cnf

This command must be executed in a directory (or a child of thereof) which contains the file cabal.sandbox.config, which points to the location of the sandbox. The -- delimiter indicates the beginning of the target command arguments. Any arguments for cabal exec itself must be provided before the -- delimiter.

NOTE: The examples below show a simplified process for Linux only. For instructions for other platforms and about installing the dependencies (GLPK, etc.), see the README.

Example: installing ClaferWiki from Hackage and running it from a Cabal sandbox

This shows the fully manual process. In some folder of your choice, e.g., mywiki, execute the following:

cd mywiki
cabal update
cabal sandbox init
cabal install claferwiki

Then create a default Gitit configuration file:

gitit --print-default-config > gitit.cnf

In the config file modify the port number and specify the plugins as follows:

port: 8091
plugins: Network.Gitit.Plugin.ClaferWiki

Finally run the wiki:

cabal exec gitit -- -f gitit.cnf

Note: to use the CSS for clafer, you must add the following line to the file static/css/custom.css:

@import url("clafer.css"); /* for syntax highlighting for Clafer */

Example: building ClaferWiki from source and running it from a Cabal sandbox

Using this process you'll get a customized Gitit with the Clafer logo and the help page such as the Clafer Model Wiki.

git clone http://github.com/gsdlab/claferwiki
cd claferwiki
make init
cabal install

Here, make init creates a sandbox in ../.clafertools-cabal-sandbox/ and installs all dependencies, including Clafer, from Hackage.
At this point, we're ready to create a live ClaferWiki instance, for example, in a folder mywiki:

make install to=mywiki

This command copies the preconfigured gitit.cnf file, Clafer logo, and preloads the wiki with some initial content, including the help page. We can then run it as described before:

cd mywiki
cabal exec gitit -- -f gitit.cnf 

If the wiki starts up correctly (see http://localhost:8091), it can be run it in background under nohup as follows:

nohup "cabal exec gitit -- -f gitit.cnf" &

Note: The above assumes that the folder mywiki is a child of the claferwiki and because of that the sandbox will be found. Otherwise, when installing to a different location, e.g., a folder ~/mywiki, the sandbox must be initialized to point to the existing sandbox where gitit and ClaferWiki (e.g., assume folder ~/.clafertools-cabal-sandbox/) were installed as follows:

cd mywiki
cabal sandbox init --sandbox=~/.clafertools-cabal-sandbox
cabal exec gitit -- -f gitit.cnf