% Installing pandoc
Installing from Source
======================
This method will work on all architectures, but requires that you first
install the GHC compiler and some build tools: [GNU `make`], `sed`,
`bash`, and `perl`. These are standard on unix systems (including MacOS
X). If you're using Windows, you can install [Cygwin].
[Cygwin]: http://www.cygwin.com/
[GNU `make`]: http://www.gnu.org/software/make/
Installing GHC
--------------
To compile Pandoc, you'll need [GHC] version 6.6 or greater. If
you don't have GHC already, you can get it from the [GHC Download]
page. If you're running MacOS X, you can also install GHC using
[MacPorts] or [Fink].
[GHC]: http://www.haskell.org/ghc/
[GHC Download]: http://www.haskell.org/ghc/download.html
[MacPorts]: http://macports.org
[Fink]: http://finkproject.org
Getting the source
------------------
Download the source tarball from pandoc's [pandoc's google code site].
Extract the contents into a subdirectory:
tar xvzf pandoc-0.xy.tar.gz
[pandoc's google code site]: http://pandoc.googlecode.com
Installing Pandoc
-----------------
1. Change to the directory containing the Pandoc distribution.
2. Compile:
make
If you get "Unknown modifier" errors, it is probably because `make`
on your system is not [GNU `make`]. Try using `gmake` instead.
3. See if it worked (optional, but recommended):
make test
Note: if you see errors like the following, they're due to differences
between different versions of the xhtml library, and can safely be
disregarded:
2c2
< <html xmlns="http://www.w3.org/1999/xhtml"
---
> <html
4. Install:
sudo make install
Note: This installs `pandoc`, together with its wrappers and
documentation, into the `/usr/local` directory. If you'd rather
install `pandoc` somewhere else--say, in `/opt/local`--you can
set the `PREFIX` environment variable:
PREFIX=/opt/local sudo make install
If you don't have root privileges or would prefer to install
`pandoc` and the associated wrappers into your `~/bin` directory,
type this instead:
PREFIX=~ make install-exec
5. Build and install the Haskell libraries and library
documentation (optional--for Haskell programmers only):
make build-all
sudo make install-all
Note that building the library documentation requires [haddock].
[haddock]: http://www.haskell.org/haddock/
Removing Pandoc
---------------
Each of the installation steps described above can be reversed:
sudo make uninstall
PREFIX=~ make uninstall-exec
sudo make uninstall-all
Other targets
-------------
The following 'make' targets should not be needed by the average user,
but are documented here for packagers and developers:
### Building and installing
* `configure`: Performs the needed preprocessing to create a proper
Cabal package for Pandoc:
- Builds `ASCIIMathML.hs`, `DefaultHeaders.hs`, and `S5.hs`
from templates in `src/templates` and data in `src/ASCIIMathML.js`,
`src/ui`, and `src/headers`.
- Stores values of relevant environment variables in `vars` for
persistence.
- Runs Cabal's "configure" command.
* `build-exec`: Builds `pandoc` executable (using Cabal's "build"
command) and creates the wrappers `html2markdown` and `markdown2pdf`
from templates in `src/wrappers`.
* `build-doc`: Builds program documentation (e.g. `README.html`).
* `build-lib-doc`: Builds Haddock documentation for Pandoc libraries.
* `install-doc`, `uninstall-doc`: Installs/uninstalls user documentation
and man pages.
* `install-lib-doc`, `uninstall-lib-doc`: Installs/uninstalls library
documentation and man pages.
* `install-exec`, `uninstall-exec`: Installs/uninstalls programs
(`pandoc` and wrappers).
### Testing
* `test`: Runs Pandoc's test suite. (All tests should pass.)
* `test-markdown`: Runs the Markdown regression test suite, using
`pandoc --strict`. (Three of the tests will fail.)
### Cleaning
* `clean`: Restores directory to pre-build state, removing generated files.
* `distclean`: Like clean, but also cleans up files created by `make deb`.
### Packaging
* `tarball`: Creates a source tarball for distribution.
* `deb`: Creates debian packages in `..` directory.
* `macport`: Creates MacPorts Portfile in `macports` directory.
* `freebsd`: Creates freebsd Makefile and distinfo in `freebsd` directory.
* `win-pkg`: Creates a Windows binary package (presupposes `pandoc.exe`,
which must be created by building Pandoc on a Windows machine).
* `website`: Creates Pandoc's website in `web/pandoc` directory.
Installing pandoc using Cabal
=============================
Pandoc can also be installed using the standard Haskell packaging tool,
[Cabal](http://www.haskell.org/cabal/). You'll need GHC 6.6 or greater
(see [Installing GHC](#installing-ghc), above). Just download the source
tarball, unpack, and type:
runhaskell Setup.hs configure
runhaskell Setup.hs build
runhaskell Setup.hs install # this one as root
This will install the pandoc executable and the Haskell libraries,
but not the shell scripts, man pages, or other documentation.
Note: If you are using GHC 6.6.*, you will need to start by
replacing `pandoc.cabal` with a version suitable for GHC 6.6:
cp pandoc.cabal pandoc.cabal.orig
cp pandoc.cabal.ghc66 pandoc.cabal
Installing pandoc using MacPorts
================================
This is an alternative to compiling from source on MacOS X.
[MacPorts] is a system for building and maintaining \*nix software
on MacOS X computers. If you don't already have MacPorts, follow
[these instructions for installing
it](http://trac.macosforge.org/projects/macports/wiki/InstallingMacPorts).
Once you've installed MacPorts, you can install pandoc by typing:
sudo port sync # to get the most recent ports
sudo port install pandoc
Since pandoc depends on GHC, the process may take a long time.
Installing the Windows binary
=============================
Simply download the zip file from [pandoc's google code site].
Extract the files from the archive, and put `pandoc.exe` somewhere
in your PATH.
Note that the Windows binary distribution does not include the shell
scripts `markdown2pdf`, `html2markdown`, or `hsmarkdown`. If you need
these, compile from source.
Installing pandoc on Debian
===========================
Pandoc is now in the debian unstable archive, and can be installed
using `apt-get` (as root):
apt-get install pandoc # the program, shell scripts, and docs
apt-get install libghc6-pandoc-dev # the libraries
apt-get install pandoc-doc # library documentation
Thanks to Recai Oktaş for setting up the debian packages.
Installing pandoc on FreeBSD
============================
Pandoc is in the FreeBSD ports repository (`textproc/pandoc`) and can be
installed in the normal way:
cd /usr/ports/textproc/pandoc
make install clean # as root
Alternatively, you can use `pkg_add`:
pkg_add -r pandoc
Note that the version of pandoc in FreeBSD's official repository may be
somewhat older than the most recent version.