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