git.iko.soy/typeable/pandoc
on 1.15.0.5 help sign in
typeable/pandoc/INSTALL
212 lines 7.1 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.
172. Update your package database:
19 cabal update
213. Use `cabal` to install pandoc and its dependencies:
23 cabal install pandoc
25 This procedure will install the released version of pandoc,
26 which will be downloaded automatically from HackageDB.
28 If this step fails, and you are using an older version
29 of the Haskell Platform, e.g. on Debian stable, you may need to
30 upgrade your version of cabal:
32 cabal install cabal-install
33 ~/.cabal/bin/cabal update
34 ~/.cabal/bin/cabal install pandoc
36 If you want to install a modified or development version
37 of pandoc instead, switch to the source directory and do
38 as above, but without the 'pandoc':
40 cabal install
42 Note: If you obtained the source from the git repository (rather
43 than a release tarball), you'll need to do
45 git submodule update --init
47 to fetch the contents of `data/templates` before `cabal install`.
494. Make sure the `$CABALDIR/bin` directory is in your path. You should
50 now be able to run `pandoc`:
52 pandoc --help
54 [Not sure where `$CABALDIR` is?](http://www.haskell.org/haskellwiki/Cabal-Install#The_cabal-install_configuration_file)
565. 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
78The `pandoc.1` man page will be installed automatically. cabal shows
79you where it is installed: you may need to set your `MANPATH`
80accordingly. If `README` has been modified, the man page can be
81rebuilt: `make man/pandoc.1`.
83The `pandoc-citeproc.1` man page will also be installed automatically.
85[GHC]: http://www.haskell.org/ghc/
86[Haskell platform]: http://hackage.haskell.org/platform/
87[cabal-install]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall
89Custom install
90--------------
92This is a step-by-step procedure that offers maximal control
93over the build and installation. Most users should use the
94quick install, but this information may be of use to packagers.
95For more details, see the [Cabal User's Guide]. These instructions
96assume that the pandoc source directory is your working directory.
981. Install dependencies: in addition to the [Haskell platform],
99 you will need a number of additional libraries. You can install
100 them all with
102 cabal update
103 cabal install --only-dependencies
1052. Configure:
107 cabal configure --prefix=DIR --bindir=DIR --libdir=DIR \
108 --datadir=DIR --libsubdir=DIR --datasubdir=DIR --docdir=DIR \
109 --htmldir=DIR --program-prefix=PREFIX --program-suffix=SUFFIX \
110 --mandir=DIR --flags=FLAGSPEC
112 All of the options have sensible defaults that can be overridden
113 as needed.
115 `FLAGSPEC` is a list of Cabal configuration flags, optionally
116 preceded by a `-` (to force the flag to `false`), and separated
117 by spaces. Pandoc's flags include:
119 - `embed_data_files`: embed all data files into the binary (default no).
120 This is helpful if you want to create a relocatable binary.
121 Note: if this option is selected, you need to install the
122 `hsb2hs` preprocessor: `cabal install hsb2hs` (version 0.3.1 or
123 higher is required).
125 - `https`: enable support for downloading resources over https
126 (using the `http-client` and `http-client-tls` libraries).
1283. Build:
130 cabal build
1324. Build API documentation:
134 cabal haddock --html-location=URL --hyperlink-source
1365. Copy the files:
138 cabal copy --destdir=PATH
140 The default destdir is `/`.
1426. Register pandoc as a GHC package:
144 cabal register
146 Package managers may want to use the `--gen-script` option to
147 generate a script that can be run to register the package at
148 install time.
150Creating a relocatable binary
151-----------------------------
153It is possible to compile pandoc such that the data files
154pandoc uses are embedded in the binary. The resulting binary
155can be run from any directory and is completely self-contained.
157 cabal install hsb2hs # a required build tool
158 cabal install --flags="embed_data_files" citeproc-hs
159 cabal configure --flags="embed_data_files"
160 cabal build
162You can find the pandoc executable in `dist/build/pandoc`. Copy this wherever
163you please.
165[zip-archive]: http://hackage.haskell.org/package/zip-archive
166[highlighting-kate]: http://hackage.haskell.org/package/highlighting-kate
167[blaze-html]: http://hackage.haskell.org/package/blaze-html
168[Cabal User's Guide]: http://www.haskell.org/cabal/release/latest/doc/users-guide/builders.html#setup-configure-paths
170Running tests
171-------------
173Pandoc comes with an automated test suite integrated to cabal.
174To build the tests:
176 cabal configure --enable-tests && cabal build
178To run the tests:
180 cabal test
182To run particular tests (pattern-matching on their names), use
183the `-t` option:
185 cabal test --test-options='-t markdown'
187If you add a new feature to pandoc, please add tests as well, following
188the pattern of the existing tests. The test suite code is in
189`tests/test-pandoc.hs`. If you are adding a new reader or writer, it is
190probably easiest to add some data files to the `tests` directory, and
191modify `tests/Tests/Old.hs`. Otherwise, it is better to modify the module
192under the `tests/Tests` hierarchy corresponding to the pandoc module you
193are changing.
195Running benchmarks
196------------------
198To build the benchmarks:
200 cabal configure --enable-benchmarks && cabal build
202To run the benchmarks:
204 cabal bench
206To use a smaller sample size so the benchmarks run faster:
208 cabal bench --benchmark-options='-s 20'
210To run just the markdown benchmarks:
212 cabal bench --benchmark-options='markdown'