% Installing pandoc Installing pandoc from Source ============================= This method will work on all architectures for which the GHC compiler is available. Installing GHC -------------- To compile Pandoc, you'll need [GHC] version 6.8 or greater. If you don't have GHC already, you can get it from the [GHC Download] page. If you're compiling GHC from source, be sure to get the `extralibs` in addition to the base tarball. Pandoc requires Cabal version 1.2 or greater. If your GHC comes with an older version of Cabal, you'll need to to [install Cabal] separately. You can check your Cabal version using `ghc-pkg list`. If you're running MacOS X, you can also install GHC using [MacPorts] or [Fink]. If you're on a [debian]-based linux system (such as [Ubuntu]), you can get GHC and some required libraries using `apt-get`: sudo apt-get install ghc6 libghc6-xhtml-dev libghc6-mtl-dev libghc6-network-dev [GHC]: http://www.haskell.org/ghc/ [GHC Download]: http://www.haskell.org/ghc/download.html [Cabal]: http://www.haskell.org/cabal/ [install Cabal]: http://www.haskell.org/cabal/download.html [MacPorts]: http://macports.org [Fink]: http://finkproject.org [Ubuntu]: http://www.ubuntu.com [debian]: http://www.debian.org/ Installing prerequisites ------------------------ Pandoc needs the `utf8-string` and `zip-archive` to compile. Check your packaging system to see if they are included. If not, you will need to compile them from source. On \*nix systems, the easiest way to do this is to install the [cabal-install] tool. See the section [Quick Installation on Unix] for instructions. If you use [MacPorts], you can just install the `hs-cabal` port. [cabal-install]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall [Quick Installation on Unix]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall#QuickInstallationonUnix Once you've got `cabal-install` installed, you can install the needed libraries by doing cabal install utf8-string cabal install zip-archive Alternatively, you can install these libraries using the [standard Cabal method], but you will have to install their dependencies manually. [standard Cabal method]: http://haskell.org/haskellwiki/Cabal/How_to_install_a_Cabal_package Getting the source ------------------ Download the source tarball from [pandoc's google code site]. Extract the contents into a subdirectory: tar xvzf pandoc-x.y.tar.gz [pandoc's google code site]: http://pandoc.googlecode.com Now choose one of the following methods for compiling and installing pandoc. If you are on a linux or unix-based system, you can [install pandoc using Make]. If not, you should [install pandoc using Cabal]. [install pandoc using Make]: #installing-pandoc-using-make [install pandoc using Cabal]: #installing-pandoc-using-cabal [build options]: #build-options Installing Pandoc using Make ---------------------------- 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. If you get a message saying that the `zip-archive` or `utf8-string` libraries cannot be found, and you have installed these using `cabal-install`, it is probably because by default `cabal-install` installs libraries to the user's directory rather than globally. Try again with CABALOPTS=--user make 3. See if it worked (optional, but recommended): make test 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]. 6. If you decide you don't want pandoc on your system, each of the installation steps described above can be reversed: sudo make uninstall PREFIX=~ make uninstall-exec sudo make uninstall-all [haddock]: http://www.haskell.org/haddock/ Installing pandoc using Cabal ----------------------------- Change to the directory containing the pandoc source, and type: runhaskell Setup configure # add --user if you have installed prerequisites # locally using cabal-install runhaskell Setup build runhaskell Setup haddock # optional, to build library documentation runhaskell Setup test # optional, to run test suite runhaskell Setup install # this one as root or sudo, or add --user This will install the pandoc executable and the Haskell libraries, but not the shell scripts, man pages, or other documentation. You may just want the executable, or just the libraries. This can be controlled with configuration flags (the `-` negates the flag): runhaskell Setup configure -f-library # just the executable runhaskell Setup configure -f-executable # just the libraries You can also specify the directory tree into which pandoc will be installed using the `--prefix=` option to `configure`. For more details, see the [Cabal User's Guide]. [Cabal User's Guide]: http://www.haskell.org/cabal/release/latest/doc/users-guide/builders.html#setup-configure-paths Optional syntax highlighting support ------------------------------------ Pandoc can optionally be compiled with support for syntax highlighting of delimited code blocks. This feature requires the [`highlighting-kate` library]. If you are using Cabal to compile pandoc, specify the `highlighting` flag in the configure step: runhaskell Setup configure -fhighlighting If you are using the Makefile: CABALOPTS=-fhighlighting make If you have already built pandoc, you may need to do a `make clean` or `runhaskell Setup clean` first. [`highlighting-kate` library]: http://johnmacfarlane.net/highlighting-kate Optional citeproc support ------------------------- Pandoc can optionally be compiled with support for bibliographic citations using Andrea Rossato's [`citeproc-hs` library]. This allows you to specify citations in markdown using an intuitive syntax (for example, `[jones2005@p. 3; smith2006]`). These are automatically changed into appropriately styled citations in the output, and a bibliography is added. The bibliography data and style information are taken from XML files that must be specified on the command line. (Note: `citeproc-hs` support is experimental, and the interface may change in the future.) If you are using Cabal to compile pandoc, specify the `citeproc` flag in the configure step: runhaskell Setup configure -fciteproc If you are using the Makefile: CABALOPTS=-fciteproc make If you have already built pandoc, you may need to do a `make clean` or `runhaskell Setup clean` first. [`citeproc-hs` library]: http://code.haskell.org/citeproc-hs/ 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`: - 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). * `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`. (One test 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. * `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). 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. Note that the version of pandoc in MacPorts may not be the most recent. To get the most recent version, you can use `cabal-install`: sudo port install hs-cabal cabal install pandoc --user # optionally: -fciteproc -fhighlighting This will install the `pandoc` executable into `~/.cabal/bin`. This method will not install the wrapper scripts or man pages; if you want those, follow the instructions above for compiling from source. Installing the Windows binary ============================= Simply download the Windows installer [pandoc's google code site] and run it. It will install `pandoc.exe` and ensure that it is in your system PATH. Note that the Windows binary distribution does not include the shell scripts `markdown2pdf`, `html2markdown`, or `hsmarkdown`. Installing pandoc on Debian =========================== Pandoc is now in the debian archives, 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. Note that the version of pandoc in Debian may not be the most recent. 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. Installing pandoc on Arch linux =============================== There are two `pandoc` packages in the Arch AUR repositories, `pandoc` (contributed by Abhishek Dasgupta) and `haskell-pandoc` (contributed by Dons Stewart). `haskell-pandoc` is more up-to-date, but does not install the man pages or wrapper scripts. pacman -Sy pandoc pacman -Sy haskell-pandoc