Permalink
Browse files

Improved INSTALL instructions.

  • Loading branch information...
1 parent 2677e84 commit b0143bfad6ebc3b2ae1ced2fb3a9bed989c41000 @jgm committed Aug 8, 2013
Showing with 43 additions and 23 deletions.
  1. +43 −23 INSTALL
View
@@ -9,9 +9,17 @@ Quick install
-------------
1. Install the [Haskell platform]. This will give you [GHC] and
-the [cabal-install] build tool.
+ the [cabal-install] build tool, as well as `alex` and `happy`.
+ If you do not use the Haskell platform, you'll need to install
+ `alex` and `happy` separately:
-2. Use `cabal` to install pandoc and its dependencies:
+ cabal install alex happy
+
+2. Update your package database:
+
+ cabal update
+
+3. Use `cabal` to install pandoc and its dependencies:
cabal install pandoc
@@ -23,15 +31,22 @@ the [cabal-install] build tool.
cabal install
-3. Make sure the `$CABALDIR/bin` directory is in your path. You should
-now be able to run `pandoc`:
+ Note: If you obtained the source from the git repository (rather
+ than a release tarball), you'll need to do
+
+ git submodule update --init
+
+ to fetch the contents of `data/templates` before `cabal install`.
+
+4. Make sure the `$CABALDIR/bin` directory is in your path. You should
+ now be able to run `pandoc`:
pandoc --help
[Not sure where `$CABALDIR` is?](http://www.haskell.org/haskellwiki/Cabal-Install#The_cabal-install_configuration_file)
-4. Make sure the `$CABALDIR/share/man/man1` directory is in your `MANPATH`.
-You should now be able to access the `pandoc` man page:
+5. Make sure the `$CABALDIR/share/man/man1` directory is in your `MANPATH`.
+ You should now be able to access the `pandoc` man page:
man pandoc
@@ -45,14 +60,19 @@ Custom install
This is a step-by-step procedure that offers maximal control
over the build and installation. Most users should use the
quick install, but this information may be of use to packagers.
-For more details, see the [Cabal User's Guide].
+For more details, see the [Cabal User's Guide]. These instructions
+assume that the pandoc source directory is your working directory.
1. Install dependencies: in addition to the [Haskell platform],
-you will need [zip-archive], [blaze-html], and [highlighting-kate].
+ you will need a number of additional libraries. You can install
+ them all with
+
+ cabal update
+ cabal install --only-dependencies
2. Configure:
- runghc Setup.hs configure --prefix=DIR --bindir=DIR --libdir=DIR \
+ cabal configure --prefix=DIR --bindir=DIR --libdir=DIR \
--datadir=DIR --libsubdir=DIR --datasubdir=DIR --docdir=DIR \
--htmldir=DIR --program-prefix=PREFIX --program-suffix=SUFFIX \
--mandir=DIR --flags=FLAGSPEC
@@ -64,26 +84,34 @@ you will need [zip-archive], [blaze-html], and [highlighting-kate].
preceded by a `-` (to force the flag to `false`), and separated
by spaces. Pandoc's flags include:
- - `blaze_html_0_5`: Use blaze-html >= 0.5 (default yes)
- - `embed_data_files`: embed all data files into the binary (default no)
+ - `embed_data_files`: embed all data files into the binary (default no).
+ This is helpful if you want to create a relocatable binary.
+ Note: if this option is selected, you need to install the
+ `hsb2hs` preprocessor:
+
+ cabal install hsb2hs
+
+ - `http-conduit`: use the `http-conduit` library to fetch external
+ resources (default yes -- without this, pandoc cannot make SSL
+ connections)
3. Build:
- runghc Setup.hs build
+ cabal build
4. Build API documentation:
- runghc Setup.hs haddock --html-location=URL --hyperlink-source
+ cabal haddock --html-location=URL --hyperlink-source
5. Copy the files:
- runghc Setup.hs copy --destdir=PATH
+ cabal copy --destdir=PATH
The default destdir is `/`.
6. Register pandoc as a GHC package:
- runghc Setup.hs register
+ cabal register
Package managers may want to use the `--gen-script` option to
generate a script that can be run to register the package at
@@ -109,7 +137,6 @@ you please.
[blaze-html]: http://hackage.haskell.org/package/blaze-html
[Cabal User's Guide]: http://www.haskell.org/cabal/release/latest/doc/users-guide/builders.html#setup-configure-paths
-
Running tests
-------------
@@ -118,13 +145,6 @@ To build the tests:
cabal configure --enable-tests && cabal build
-Note: If you obtained the source via git, you should first do
-
- git submodule update --init data/templates
-
-to populate the templates subdirectory. (You can skip this step
-if you obtained the source from a release tarball.)
-
To run the tests:
cabal test

0 comments on commit b0143bf

Please sign in to comment.