git.iko.soy/typeable/pandoc
on 1.12.2 help sign in
typeable/pandoc/INSTALL
208 lines 6.8 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 are also binary installers for Windows and Mac OS X.
8If you are installing the development version from github, see also:
9https://github.com/jgm/pandoc/wiki/Installing-the-development-version-of-pandoc
11Quick install
12-------------
141. Install the [Haskell platform]. This will give you [GHC] and
15 the [cabal-install] build tool, as well as `alex` and `happy`.
16 If you do not use the Haskell platform, you'll need to install
17 `alex` and `happy` separately:
19 cabal install alex happy
212. Update your package database:
23 cabal update
253. Use `cabal` to install pandoc and its dependencies:
27 cabal install pandoc
29 This procedure will install the released version of pandoc,
30 which will be downloaded automatically from HackageDB.
31 If you want to install a modified or development version
32 of pandoc instead, switch to the source directory and do
33 as above, but without the 'pandoc':
35 cabal install
37 Note: If you obtained the source from the git repository (rather
38 than a release tarball), you'll need to do
40 git submodule update --init
42 to fetch the contents of `data/templates` before `cabal install`.
444. Make sure the `$CABALDIR/bin` directory is in your path. You should
45 now be able to run `pandoc`:
47 pandoc --help
49 [Not sure where `$CABALDIR` is?](http://www.haskell.org/haskellwiki/Cabal-Install#The_cabal-install_configuration_file)
515. Make sure the `$CABALDIR/share/man/man1` directory is in your `MANPATH`.
52 You should now be able to access the `pandoc` man page:
54 man pandoc
566. If you want to process citations with pandoc, you will also need to
57 install a separate package, `pandoc-citeproc`. This can be installed
58 using cabal:
60 cabal install pandoc-citeproc
62 By default `pandoc-citeproc` uses the "i;unicode-casemap" method
63 to sort bibliography entries (RFC 5051). If you would like to
64 use the locale-sensitive unicode collation algorithm instead,
65 specify the `unicode_collation` flag:
67 cabal install pandoc-citeproc -funicode_collation
69 Note that this requires the `text-icu` library, which in turn
70 depends on the C library `icu4c`. Installation directions
71 vary by platform. Here is how it might work on OSX with homebrew:
73 brew install icu4c
74 cabal install --extra-lib-dirs=/usr/local/Cellar/icu4c/51.1/lib \
75 --extra-include-dirs=/usr/local/Cellar/icu4c/51.1/include \
76 -funicode_collation text-icu pandoc-citeproc
78[GHC]: http://www.haskell.org/ghc/
79[Haskell platform]: http://hackage.haskell.org/platform/
80[cabal-install]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall
82Custom install
83--------------
85This is a step-by-step procedure that offers maximal control
86over the build and installation. Most users should use the
87quick install, but this information may be of use to packagers.
88For more details, see the [Cabal User's Guide]. These instructions
89assume that the pandoc source directory is your working directory.
911. Install dependencies: in addition to the [Haskell platform],
92 you will need a number of additional libraries. You can install
93 them all with
95 cabal update
96 cabal install --only-dependencies
982. Configure:
100 cabal configure --prefix=DIR --bindir=DIR --libdir=DIR \
101 --datadir=DIR --libsubdir=DIR --datasubdir=DIR --docdir=DIR \
102 --htmldir=DIR --program-prefix=PREFIX --program-suffix=SUFFIX \
103 --mandir=DIR --flags=FLAGSPEC
105 All of the options have sensible defaults that can be overridden
106 as needed.
108 `FLAGSPEC` is a list of Cabal configuration flags, optionally
109 preceded by a `-` (to force the flag to `false`), and separated
110 by spaces. Pandoc's flags include:
112 - `embed_data_files`: embed all data files into the binary (default no).
113 This is helpful if you want to create a relocatable binary.
114 Note: if this option is selected, you need to install the
115 `hsb2hs` preprocessor:
117 cabal install hsb2hs
119 - `http-conduit`: use the `http-conduit` library to fetch external
120 resources (default yes -- without this, pandoc cannot make SSL
121 connections)
1233. Build:
125 cabal build
1274. Build API documentation:
129 cabal haddock --html-location=URL --hyperlink-source
1315. Copy the files:
133 cabal copy --destdir=PATH
135 The default destdir is `/`.
1376. Register pandoc as a GHC package:
139 cabal register
141 Package managers may want to use the `--gen-script` option to
142 generate a script that can be run to register the package at
143 install time.
145Creating a relocatable binary
146-----------------------------
148It is possible to compile pandoc such that the data files
149pandoc uses are embedded in the binary. The resulting binary
150can be run from any directory and is completely self-contained.
152 cabal install hsb2hs # a required build tool
153 cabal install --flags="embed_data_files" citeproc-hs
154 cabal configure --flags="embed_data_files"
155 cabal build
157You can find the pandoc executable in `dist/build/pandoc`. Copy this wherever
158you please.
160[zip-archive]: http://hackage.haskell.org/package/zip-archive
161[highlighting-kate]: http://hackage.haskell.org/package/highlighting-kate
162[blaze-html]: http://hackage.haskell.org/package/blaze-html
163[Cabal User's Guide]: http://www.haskell.org/cabal/release/latest/doc/users-guide/builders.html#setup-configure-paths
165Running tests
166-------------
168Pandoc comes with an automated test suite integrated to cabal.
169To build the tests:
171 cabal configure --enable-tests && cabal build
173To run the tests:
175 cabal test
177To run particular tests (pattern-matching on their names), use
178the `-t` option:
180 cabal test --test-options='-t markdown'
182If you add a new feature to pandoc, please add tests as well, following
183the pattern of the existing tests. The test suite code is in
184`tests/test-pandoc.hs`. If you are adding a new reader or writer, it is
185probably easiest to add some data files to the `tests` directory, and
186modify `tests/Tests/Old.hs`. Otherwise, it is better to modify the module
187under the `tests/Tests` hierarchy corresponding to the pandoc module you
188are changing.
190Running benchmarks
191------------------
193To build the benchmarks:
195 cabal configure --enable-benchmarks && cabal build
197To run the benchmarks:
199 cabal bench
201To use a smaller sample size so the benchmarks run faster:
203 cabal bench --benchmark-options='-s 20'
205To run just the markdown benchmarks:
207 cabal bench --benchmark-options='markdown'