% 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 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).
Note that you'll need OSX 10.4 and the latest version of XCode Tools.
Once you've installed MacPorts, you'll need to create a local ports
repository and copy the [pandoc `Portfile`](Portfile) into it:
mkdir -p ~/ports/textproc/pandoc
cp Portfile ~/ports/textproc/pandoc/
Then (as root) open `/opt/local/etc/macports/sources.conf` in an editor
and insert the line
file:///Users/yourusername/ports
before the line beginning `rsync:`, so MacPorts will know about your
local repository.
Now you should be able to install pandoc by typing
sudo port install pandoc
Since pandoc requires GHC to build, 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
===========================
This method will work on Debian linux and derivatives (including Ubuntu).
Download the latest debian package from the [pandoc home page].
To install it, just type
sudo dpkg -i pandoc_0.xx_i386.deb
where `pandoc_0.xx_i386.deb` is the filename of the debian package.
To uninstall later, use
sudo apt-get remove pandoc
[pandoc home page]: http://sophos.berkeley.edu/macfarlane/pandoc/
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.