git.iko.soy/typeable/pandoc
on 0.10 help sign in
typeable/pandoc/INSTALL
160 lines 4.9 kB history raw
1% Installing pandoc
3These instructions explain how to install pandoc from source.
4Binary packages or ports of pandoc are available for freebsd
5and several linux distributions, so check your package manager.
6There is also a Windows installer.
8Quick install
9-------------
111. Install the [Haskell platform]. This will give you [GHC] and
12the [cabal-install] build tool.
142. Use `cabal` to install pandoc and its dependencies:
16 cabal install pandoc
18 This procedure will install the released version of pandoc,
19 which will be downloaded automatically from HackageDB.
20 If you want to install a modified or development version
21 of pandoc instead, switch to the source directory and do
22 as above, but without the 'pandoc':
24 cabal install
263. Make sure the `$CABALDIR/bin` directory is in your path. You should
27now be able to run `pandoc`:
29 pandoc --help
314. Make sure the `$CABALDIR/share/man/man1` directory is in your `MANPATH`.
32You should now be able to access the `pandoc` man page:
34 man pandoc
36[GHC]: http://www.haskell.org/ghc/
37[Haskell platform]: http://hackage.haskell.org/platform/
38[cabal-install]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall
40Custom install
41--------------
43This is a step-by-step procedure that offers maximal control
44over the build and installation. Most users should use the
45quick install, but this information may be of use to packagers.
46For more details, see the [Cabal User's Guide].
481. Install dependencies: in addition to the [Haskell platform],
49you will need [zip-archive], [blaze-html], and [highlighting-kate].
512. Configure:
53 runghc Setup.hs configure --prefix=DIR --bindir=DIR --libdir=DIR \
54 --datadir=DIR --libsubdir=DIR --datasubdir=DIR --docdir=DIR \
55 --htmldir=DIR --program-prefix=PREFIX --program-suffix=SUFFIX \
56 --mandir=DIR --flags=FLAGSPEC
58 All of the options have sensible defaults that can be overridden
59 as needed.
61 `FLAGSPEC` is a list of Cabal configuration flags, optionally
62 preceded by a `-` (to force the flag to `false`), and separated
63 by spaces. Pandoc's flags include:
65 - `blaze_html_0_5`: Use blaze-html >= 0.5 (default yes)
66 - `embed_data_files`: embed all data files into the binary (default no)
683. Build:
70 runghc Setup.hs build
724. Build API documentation:
74 runghc Setup.hs haddock --html-location=URL --hyperlink-source
765. Copy the files:
78 runghc Setup.hs copy --destdir=PATH
80 The default destdir is `/`.
826. Register pandoc as a GHC package:
84 runghc Setup.hs register
86 Package managers may want to use the `--gen-script` option to
87 generate a script that can be run to register the package at
88 install time.
90Creating a relocatable binary
91-----------------------------
93It is possible to compile pandoc such that the data files
94pandoc uses are embedded in the binary. The resulting binary
95can be run from any directory and is completely self-contained.
97 cabal install --flags="embed_data_files" citeproc-hs
98 cabal configure --flags="embed_data_files"
99 cabal build
101You can find the pandoc executable in `dist/build/pandoc`. Copy this wherever
102you please.
104[zip-archive]: http://hackage.haskell.org/package/zip-archive
105[highlighting-kate]: http://hackage.haskell.org/package/highlighting-kate
106[blaze-html]: http://hackage.haskell.org/package/blaze-html
107[Cabal User's Guide]: http://www.haskell.org/cabal/release/latest/doc/users-guide/builders.html#setup-configure-paths
110Running tests
111-------------
113Pandoc comes with an automated test suite integrated to cabal.
114To build the tests:
116 cabal configure --enable-tests && cabal build
118Note: If you obtained the source via git, you should first do
120 git submodule update --init templates
122to populate the templates subdirectory. (You can skip this step
123if you obtained the source from a release tarball.)
125To run the tests:
127 cabal test
129To run particular tests (pattern-matching on their names), use
130the `-t` option:
132 cabal test --test-options='-t markdown'
134If you add a new feature to pandoc, please add tests as well, following
135the pattern of the existing tests. The test suite code is in
136`tests/test-pandoc.hs`. If you are adding a new reader or writer, it is
137probably easiest to add some data files to the `tests` directory, and
138modify `tests/Tests/Old.hs`. Otherwise, it is better to modify the module
139under the `tests/Tests` hierarchy corresponding to the pandoc module you
140are changing.
142Running benchmarks
143------------------
145To build the benchmarks:
147 cabal configure --enable-benchmarks && cabal build
149To run the benchmarks:
151 cabal bench
153To use a smaller sample size so the benchmarks run faster:
155 cabal bench --benchmark-options='-s 20'
157To run just the markdown benchmarks:
159 cabal bench --benchmark-options='markdown'