git.iko.soy/typeable/pandoc
on 1.13.1 help sign in
typeable/pandoc/INSTALL
203 lines 6.6 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.
27 If you want to install a modified or development version
28 of pandoc instead, switch to the source directory and do
29 as above, but without the 'pandoc':
31 cabal install
33 Note: If you obtained the source from the git repository (rather
34 than a release tarball), you'll need to do
36 git submodule update --init
38 to fetch the contents of `data/templates` before `cabal install`.
404. Make sure the `$CABALDIR/bin` directory is in your path. You should
41 now be able to run `pandoc`:
43 pandoc --help
45 [Not sure where `$CABALDIR` is?](http://www.haskell.org/haskellwiki/Cabal-Install#The_cabal-install_configuration_file)
475. Make sure the `$CABALDIR/share/man/man1` directory is in your `MANPATH`.
48 You should now be able to access the `pandoc` man page:
50 man pandoc
526. If you want to process citations with pandoc, you will also need to
53 install a separate package, `pandoc-citeproc`. This can be installed
54 using cabal:
56 cabal install pandoc-citeproc
58 By default `pandoc-citeproc` uses the "i;unicode-casemap" method
59 to sort bibliography entries (RFC 5051). If you would like to
60 use the locale-sensitive unicode collation algorithm instead,
61 specify the `unicode_collation` flag:
63 cabal install pandoc-citeproc -funicode_collation
65 Note that this requires the `text-icu` library, which in turn
66 depends on the C library `icu4c`. Installation directions
67 vary by platform. Here is how it might work on OSX with homebrew:
69 brew install icu4c
70 cabal install --extra-lib-dirs=/usr/local/Cellar/icu4c/51.1/lib \
71 --extra-include-dirs=/usr/local/Cellar/icu4c/51.1/include \
72 -funicode_collation text-icu pandoc-citeproc
74[GHC]: http://www.haskell.org/ghc/
75[Haskell platform]: http://hackage.haskell.org/platform/
76[cabal-install]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall
78Custom install
79--------------
81This is a step-by-step procedure that offers maximal control
82over the build and installation. Most users should use the
83quick install, but this information may be of use to packagers.
84For more details, see the [Cabal User's Guide]. These instructions
85assume that the pandoc source directory is your working directory.
871. Install dependencies: in addition to the [Haskell platform],
88 you will need a number of additional libraries. You can install
89 them all with
91 cabal update
92 cabal install --only-dependencies
942. Configure:
96 cabal configure --prefix=DIR --bindir=DIR --libdir=DIR \
97 --datadir=DIR --libsubdir=DIR --datasubdir=DIR --docdir=DIR \
98 --htmldir=DIR --program-prefix=PREFIX --program-suffix=SUFFIX \
99 --mandir=DIR --flags=FLAGSPEC
101 All of the options have sensible defaults that can be overridden
102 as needed.
104 `FLAGSPEC` is a list of Cabal configuration flags, optionally
105 preceded by a `-` (to force the flag to `false`), and separated
106 by spaces. Pandoc's flags include:
108 - `embed_data_files`: embed all data files into the binary (default no).
109 This is helpful if you want to create a relocatable binary.
110 Note: if this option is selected, you need to install the
111 `hsb2hs` preprocessor:
113 cabal install hsb2hs
115 - `https`: enable support for downloading resources over https
116 (using the `http-client` and `http-client-tls` libraries).
1183. Build:
120 cabal build
1224. Build API documentation:
124 cabal haddock --html-location=URL --hyperlink-source
1265. Copy the files:
128 cabal copy --destdir=PATH
130 The default destdir is `/`.
1326. Register pandoc as a GHC package:
134 cabal register
136 Package managers may want to use the `--gen-script` option to
137 generate a script that can be run to register the package at
138 install time.
140Creating a relocatable binary
141-----------------------------
143It is possible to compile pandoc such that the data files
144pandoc uses are embedded in the binary. The resulting binary
145can be run from any directory and is completely self-contained.
147 cabal install hsb2hs # a required build tool
148 cabal install --flags="embed_data_files" citeproc-hs
149 cabal configure --flags="embed_data_files"
150 cabal build
152You can find the pandoc executable in `dist/build/pandoc`. Copy this wherever
153you please.
155[zip-archive]: http://hackage.haskell.org/package/zip-archive
156[highlighting-kate]: http://hackage.haskell.org/package/highlighting-kate
157[blaze-html]: http://hackage.haskell.org/package/blaze-html
158[Cabal User's Guide]: http://www.haskell.org/cabal/release/latest/doc/users-guide/builders.html#setup-configure-paths
160Running tests
161-------------
163Pandoc comes with an automated test suite integrated to cabal.
164To build the tests:
166 cabal configure --enable-tests && cabal build
168To run the tests:
170 cabal test
172To run particular tests (pattern-matching on their names), use
173the `-t` option:
175 cabal test --test-options='-t markdown'
177If you add a new feature to pandoc, please add tests as well, following
178the pattern of the existing tests. The test suite code is in
179`tests/test-pandoc.hs`. If you are adding a new reader or writer, it is
180probably easiest to add some data files to the `tests` directory, and
181modify `tests/Tests/Old.hs`. Otherwise, it is better to modify the module
182under the `tests/Tests` hierarchy corresponding to the pandoc module you
183are changing.
185Running benchmarks
186------------------
188To build the benchmarks:
190 cabal configure --enable-benchmarks && cabal build
192To run the benchmarks:
194 cabal bench
196To use a smaller sample size so the benchmarks run faster:
198 cabal bench --benchmark-options='-s 20'
200To run just the markdown benchmarks:
202 cabal bench --benchmark-options='markdown'