git.iko.soy/typeable/pandoc
on 1.12 help sign in
typeable/pandoc/INSTALL
192 lines 6.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, 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[GHC]: http://www.haskell.org/ghc/
63[Haskell platform]: http://hackage.haskell.org/platform/
64[cabal-install]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall
66Custom install
67--------------
69This is a step-by-step procedure that offers maximal control
70over the build and installation. Most users should use the
71quick install, but this information may be of use to packagers.
72For more details, see the [Cabal User's Guide]. These instructions
73assume that the pandoc source directory is your working directory.
751. Install dependencies: in addition to the [Haskell platform],
76 you will need a number of additional libraries. You can install
77 them all with
79 cabal update
80 cabal install --only-dependencies
822. Configure:
84 cabal configure --prefix=DIR --bindir=DIR --libdir=DIR \
85 --datadir=DIR --libsubdir=DIR --datasubdir=DIR --docdir=DIR \
86 --htmldir=DIR --program-prefix=PREFIX --program-suffix=SUFFIX \
87 --mandir=DIR --flags=FLAGSPEC
89 All of the options have sensible defaults that can be overridden
90 as needed.
92 `FLAGSPEC` is a list of Cabal configuration flags, optionally
93 preceded by a `-` (to force the flag to `false`), and separated
94 by spaces. Pandoc's flags include:
96 - `embed_data_files`: embed all data files into the binary (default no).
97 This is helpful if you want to create a relocatable binary.
98 Note: if this option is selected, you need to install the
99 `hsb2hs` preprocessor:
101 cabal install hsb2hs
103 - `http-conduit`: use the `http-conduit` library to fetch external
104 resources (default yes -- without this, pandoc cannot make SSL
105 connections)
1073. Build:
109 cabal build
1114. Build API documentation:
113 cabal haddock --html-location=URL --hyperlink-source
1155. Copy the files:
117 cabal copy --destdir=PATH
119 The default destdir is `/`.
1216. Register pandoc as a GHC package:
123 cabal register
125 Package managers may want to use the `--gen-script` option to
126 generate a script that can be run to register the package at
127 install time.
129Creating a relocatable binary
130-----------------------------
132It is possible to compile pandoc such that the data files
133pandoc uses are embedded in the binary. The resulting binary
134can be run from any directory and is completely self-contained.
136 cabal install hsb2hs # a required build tool
137 cabal install --flags="embed_data_files" citeproc-hs
138 cabal configure --flags="embed_data_files"
139 cabal build
141You can find the pandoc executable in `dist/build/pandoc`. Copy this wherever
142you please.
144[zip-archive]: http://hackage.haskell.org/package/zip-archive
145[highlighting-kate]: http://hackage.haskell.org/package/highlighting-kate
146[blaze-html]: http://hackage.haskell.org/package/blaze-html
147[Cabal User's Guide]: http://www.haskell.org/cabal/release/latest/doc/users-guide/builders.html#setup-configure-paths
149Running tests
150-------------
152Pandoc comes with an automated test suite integrated to cabal.
153To build the tests:
155 cabal configure --enable-tests && cabal build
157To run the tests:
159 cabal test
161To run particular tests (pattern-matching on their names), use
162the `-t` option:
164 cabal test --test-options='-t markdown'
166If you add a new feature to pandoc, please add tests as well, following
167the pattern of the existing tests. The test suite code is in
168`tests/test-pandoc.hs`. If you are adding a new reader or writer, it is
169probably easiest to add some data files to the `tests` directory, and
170modify `tests/Tests/Old.hs`. Otherwise, it is better to modify the module
171under the `tests/Tests` hierarchy corresponding to the pandoc module you
172are changing.
174Running benchmarks
175------------------
177To build the benchmarks:
179 cabal configure --enable-benchmarks && cabal build
181To run the benchmarks:
183 cabal bench
185To use a smaller sample size so the benchmarks run faster:
187 cabal bench --benchmark-options='-s 20'
189To run just the markdown benchmarks:
191 cabal bench --benchmark-options='markdown'