git.iko.soy/typeable/pandoc
on 1.0 help sign in
typeable/pandoc/INSTALL
320 lines 11 kB history raw
1% Installing pandoc
3Installing pandoc from Source
4=============================
6This method will work on all architectures for which the GHC compiler
7is available.
9Installing GHC
10--------------
12To compile Pandoc, you'll need [GHC] version 6.8 or greater. If you
13don't have GHC already, you can get it from the [GHC Download] page.
14If you're compiling GHC from source, be sure to get the `extralibs`
15in addition to the base tarball. Pandoc requires Cabal version 1.2 or
16greater. If your GHC comes with an older version of Cabal, you'll need
17to to [install Cabal] separately. You can check your Cabal version using
18`ghc-pkg list`.
20If you're running MacOS X, you can also install GHC using [MacPorts] or [Fink].
22If you're on a [debian]-based linux system (such as [Ubuntu]), you can get
23GHC and some required libraries using `apt-get`:
25 sudo apt-get install ghc6 libghc6-xhtml-dev libghc6-mtl-dev libghc6-network-dev
27[GHC]: http://www.haskell.org/ghc/
28[GHC Download]: http://www.haskell.org/ghc/download.html
29[Cabal]: http://www.haskell.org/cabal/
30[install Cabal]: http://www.haskell.org/cabal/download.html
31[MacPorts]: http://macports.org
32[Fink]: http://finkproject.org
33[Ubuntu]: http://www.ubuntu.com
34[debian]: http://www.debian.org/
36Installing prerequisites
37------------------------
39Pandoc needs the `utf8-string` and `zip-archive` to compile.
40Check your packaging system to see if they are included.
41If not, you will need to compile them from source.
43On \*nix systems, the easiest way to do this is to install
44the [cabal-install] tool. See the section [Quick Installation
45on Unix] for instructions. If you use [MacPorts], you can
46just install the `hs-cabal` port.
48[cabal-install]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall
49[Quick Installation on Unix]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall#QuickInstallationonUnix
51Once you've got `cabal-install` installed, you can install the
52needed libraries by doing
54 cabal install utf8-string
55 cabal install zip-archive
57Alternatively, you can install these libraries using the [standard
58Cabal method], but you will have to install their dependencies manually.
60[standard Cabal method]: http://haskell.org/haskellwiki/Cabal/How_to_install_a_Cabal_package
62Getting the source
63------------------
65Download the source tarball from [pandoc's google code site].
66Extract the contents into a subdirectory:
68 tar xvzf pandoc-x.y.tar.gz
70[pandoc's google code site]: http://pandoc.googlecode.com
72Now choose one of the following methods for compiling and installing
73pandoc. If you are on a linux or unix-based system, you can [install
74pandoc using Make]. If not, you should [install pandoc using Cabal].
76[install pandoc using Make]: #installing-pandoc-using-make
77[install pandoc using Cabal]: #installing-pandoc-using-cabal
78[build options]: #build-options
80Installing Pandoc using Make
81----------------------------
831. Change to the directory containing the Pandoc distribution.
852. Compile:
87 make
89 If you get "Unknown modifier" errors, it is probably because `make`
90 on your system is not [GNU `make`]. Try using `gmake` instead.
92 If you get a message saying that the `zip-archive` or `utf8-string`
93 libraries cannot be found, and you have installed these using
94 `cabal-install`, it is probably because by default `cabal-install`
95 installs libraries to the user's directory rather than globally.
96 Try again with
98 CABALOPTS=--user make
1003. See if it worked (optional, but recommended):
102 make test
1044. Install:
106 sudo make install
108 Note: This installs `pandoc`, together with its wrappers and
109 documentation, into the `/usr/local` directory. If you'd rather
110 install `pandoc` somewhere else--say, in `/opt/local`--you can
111 set the `PREFIX` environment variable:
113 PREFIX=/opt/local sudo make install
115 If you don't have root privileges or would prefer to install
116 `pandoc` and the associated wrappers into your `~/bin` directory,
117 type this instead:
119 PREFIX=~ make install-exec
1215. Build and install the Haskell libraries and library
122 documentation (optional--for Haskell programmers only):
124 make build-all
125 sudo make install-all
127 Note that building the library documentation requires [haddock].
1296. If you decide you don't want pandoc on your system, each of the
130 installation steps described above can be reversed:
132 sudo make uninstall
134 PREFIX=~ make uninstall-exec
136 sudo make uninstall-all
138[haddock]: http://www.haskell.org/haddock/
140Installing pandoc using Cabal
141-----------------------------
143Change to the directory containing the pandoc source, and type:
145 runhaskell Setup configure # add --user if you have installed prerequisites
146 # locally using cabal-install
147 runhaskell Setup build
148 runhaskell Setup haddock # optional, to build library documentation
149 runhaskell Setup test # optional, to run test suite
150 runhaskell Setup install # this one as root or sudo, or add --user
152This will install the pandoc executable and the Haskell libraries,
153but not the shell scripts, man pages, or other documentation.
155You may just want the executable, or just the libraries. This
156can be controlled with configuration flags (the `-` negates the
157flag):
159 runhaskell Setup configure -f-library # just the executable
160 runhaskell Setup configure -f-executable # just the libraries
162You can also specify the directory tree into which pandoc will be
163installed using the `--prefix=` option to `configure`. For more details,
164see the [Cabal User's Guide].
166[Cabal User's Guide]: http://www.haskell.org/cabal/release/latest/doc/users-guide/builders.html#setup-configure-paths
168Optional syntax highlighting support
169------------------------------------
171Pandoc can optionally be compiled with support for syntax highlighting of
172delimited code blocks. This feature requires the [`highlighting-kate` library].
173If you are using Cabal to compile pandoc, specify the `highlighting` flag in
174the configure step:
176 runhaskell Setup configure -fhighlighting
178If you are using the Makefile:
180 CABALOPTS=-fhighlighting make
182If you have already built pandoc, you may need to do a `make clean` or
183`runhaskell Setup clean` first.
185[`highlighting-kate` library]: http://johnmacfarlane.net/highlighting-kate
187Optional citeproc support
188-------------------------
190Pandoc can optionally be compiled with support for bibliographic citations
191using Andrea Rossato's [`citeproc-hs` library]. This allows you
192to specify citations in markdown using an intuitive syntax (for example,
193`[jones2005@p. 3; smith2006]`). These are automatically changed into
194appropriately styled citations in the output, and a bibliography is
195added. The bibliography data and style information are taken from XML
196files that must be specified on the command line. (Note: `citeproc-hs`
197support is experimental, and the interface may change in the future.)
199If you are using Cabal to compile pandoc, specify the `citeproc` flag in
200the configure step:
202 runhaskell Setup configure -fciteproc
204If you are using the Makefile:
206 CABALOPTS=-fciteproc make
208If you have already built pandoc, you may need to do a `make clean` or
209`runhaskell Setup clean` first.
211[`citeproc-hs` library]: http://code.haskell.org/citeproc-hs/
213Other targets
214-------------
216The following 'make' targets should not be needed by the average user,
217but are documented here for packagers and developers:
219### Building and installing
221* `configure`:
222 - Stores values of relevant environment variables in `vars` for
223 persistence.
224 - Runs Cabal's "configure" command.
225* `build-exec`: Builds `pandoc` executable (using Cabal's "build"
226 command).
227* `build-doc`: Builds program documentation (e.g. `README.html`).
228* `build-lib-doc`: Builds Haddock documentation for Pandoc libraries.
229* `install-doc`, `uninstall-doc`: Installs/uninstalls user documentation
230 and man pages.
231* `install-lib-doc`, `uninstall-lib-doc`: Installs/uninstalls library
232 documentation and man pages.
233* `install-exec`, `uninstall-exec`: Installs/uninstalls programs
234 (`pandoc` and wrappers).
236### Testing
238* `test`: Runs Pandoc's test suite. (All tests should pass.)
239* `test-markdown`: Runs the Markdown regression test suite, using
240 `pandoc --strict`. (One test will fail.)
242### Cleaning
244* `clean`: Restores directory to pre-build state, removing generated files.
245* `distclean`: Like clean, but also cleans up files created by `make deb`.
247### Packaging
249* `tarball`: Creates a source tarball for distribution.
250* `macport`: Creates MacPorts Portfile in `macports` directory.
251* `freebsd`: Creates freebsd Makefile and distinfo in `freebsd` directory.
252* `win-pkg`: Creates a Windows binary package (presupposes `pandoc.exe`,
253 which must be created by building Pandoc on a Windows machine).
254* `website`: Creates Pandoc's website in `web/pandoc` directory.
256Installing pandoc using MacPorts
257================================
259This is an alternative to compiling from source on MacOS X.
260[MacPorts] is a system for building and maintaining \*nix software
261on MacOS X computers. If you don't already have MacPorts, follow
262[these instructions for installing
263it](http://trac.macosforge.org/projects/macports/wiki/InstallingMacPorts).
265Once you've installed MacPorts, you can install pandoc by typing:
267 sudo port sync # to get the most recent ports
268 sudo port install pandoc
270Since pandoc depends on GHC, the process may take a long time.
272Note that the version of pandoc in MacPorts may not be the most recent.
274Installing the Windows binary
275=============================
277Simply download the Windows installer [pandoc's google code site]
278and run it. It will install `pandoc.exe` and ensure that it is
279in your system PATH.
281Note that the Windows binary distribution does not include the shell
282scripts `markdown2pdf`, `html2markdown`, or `hsmarkdown`.
284Installing pandoc on Debian
285===========================
287Pandoc is now in the debian archives, and can be installed using `apt-get` (as root):
289 apt-get install pandoc # the program, shell scripts, and docs
290 apt-get install libghc6-pandoc-dev # the libraries
291 apt-get install pandoc-doc # library documentation
293Thanks to Recai Oktaş for setting up the debian packages.
295Note that the version of pandoc in Debian may not be the most recent.
297Installing pandoc on FreeBSD
298============================
300Pandoc is in the FreeBSD ports repository (`textproc/pandoc`) and can be
301installed in the normal way:
303 cd /usr/ports/textproc/pandoc
304 make install clean # as root
306Alternatively, you can use `pkg_add`:
308 pkg_add -r pandoc
310Note that the version of pandoc in FreeBSD's official repository may be
311somewhat older than the most recent version.
313Installing pandoc on Arch linux
314===============================
316Abhishek Dasgupta has created a binary package for `pandoc` in the
317Arch linux repository. Arch users can install `pandoc` by typing
319 pacman -Sy pandoc