git.iko.soy/typeable/pandoc
on issue771 help sign in
typeable/pandoc/INSTALL
163 lines 5.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 is also a Windows installer.
8Quick install
9-------------
111. Install the [Haskell platform]. This will give you [GHC] and
12the [cabal-install] build tool.
142. Use `cabal` to install pandoc and its dependencies:
16 cabal install pandoc
18 This procedure will install the released version of pandoc,
19 which will be downloaded automatically from HackageDB.
20 If you want to install a modified or development version
21 of pandoc instead, switch to the source directory and do
22 as above, but without the 'pandoc':
24 cabal install
263. Make sure the `$CABALDIR/bin` directory is in your path. You should
27now be able to run `pandoc`:
29 pandoc --help
31 [Not sure where `$CABALDIR` is?](http://www.haskell.org/haskellwiki/Cabal-Install#The_cabal-install_configuration_file)
334. Make sure the `$CABALDIR/share/man/man1` directory is in your `MANPATH`.
34You should now be able to access the `pandoc` man page:
36 man pandoc
38[GHC]: http://www.haskell.org/ghc/
39[Haskell platform]: http://hackage.haskell.org/platform/
40[cabal-install]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall
42Custom install
43--------------
45This is a step-by-step procedure that offers maximal control
46over the build and installation. Most users should use the
47quick install, but this information may be of use to packagers.
48For more details, see the [Cabal User's Guide].
501. Install dependencies: in addition to the [Haskell platform],
51you will need [zip-archive], [blaze-html], and [highlighting-kate].
532. Configure:
55 runghc Setup.hs configure --prefix=DIR --bindir=DIR --libdir=DIR \
56 --datadir=DIR --libsubdir=DIR --datasubdir=DIR --docdir=DIR \
57 --htmldir=DIR --program-prefix=PREFIX --program-suffix=SUFFIX \
58 --mandir=DIR --flags=FLAGSPEC
60 All of the options have sensible defaults that can be overridden
61 as needed.
63 `FLAGSPEC` is a list of Cabal configuration flags, optionally
64 preceded by a `-` (to force the flag to `false`), and separated
65 by spaces. Pandoc's flags include:
67 - `blaze_html_0_5`: Use blaze-html >= 0.5 (default yes)
68 - `embed_data_files`: embed all data files into the binary (default no)
703. Build:
72 runghc Setup.hs build
744. Build API documentation:
76 runghc Setup.hs haddock --html-location=URL --hyperlink-source
785. Copy the files:
80 runghc Setup.hs copy --destdir=PATH
82 The default destdir is `/`.
846. Register pandoc as a GHC package:
86 runghc Setup.hs register
88 Package managers may want to use the `--gen-script` option to
89 generate a script that can be run to register the package at
90 install time.
92Creating a relocatable binary
93-----------------------------
95It is possible to compile pandoc such that the data files
96pandoc uses are embedded in the binary. The resulting binary
97can be run from any directory and is completely self-contained.
99 cabal install hsb2hs # a required build tool
100 cabal install --flags="embed_data_files" citeproc-hs
101 cabal configure --flags="embed_data_files"
102 cabal build
104You can find the pandoc executable in `dist/build/pandoc`. Copy this wherever
105you please.
107[zip-archive]: http://hackage.haskell.org/package/zip-archive
108[highlighting-kate]: http://hackage.haskell.org/package/highlighting-kate
109[blaze-html]: http://hackage.haskell.org/package/blaze-html
110[Cabal User's Guide]: http://www.haskell.org/cabal/release/latest/doc/users-guide/builders.html#setup-configure-paths
113Running tests
114-------------
116Pandoc comes with an automated test suite integrated to cabal.
117To build the tests:
119 cabal configure --enable-tests && cabal build
121Note: If you obtained the source via git, you should first do
123 git submodule update --init data/templates
125to populate the templates subdirectory. (You can skip this step
126if you obtained the source from a release tarball.)
128To run the tests:
130 cabal test
132To run particular tests (pattern-matching on their names), use
133the `-t` option:
135 cabal test --test-options='-t markdown'
137If you add a new feature to pandoc, please add tests as well, following
138the pattern of the existing tests. The test suite code is in
139`tests/test-pandoc.hs`. If you are adding a new reader or writer, it is
140probably easiest to add some data files to the `tests` directory, and
141modify `tests/Tests/Old.hs`. Otherwise, it is better to modify the module
142under the `tests/Tests` hierarchy corresponding to the pandoc module you
143are changing.
145Running benchmarks
146------------------
148To build the benchmarks:
150 cabal configure --enable-benchmarks && cabal build
152To run the benchmarks:
154 cabal bench
156To use a smaller sample size so the benchmarks run faster:
158 cabal bench --benchmark-options='-s 20'
160To run just the markdown benchmarks:
162 cabal bench --benchmark-options='markdown'