git.iko.soy/typeable/pandoc
on 08fbfa3 help sign in
typeable/pandoc/INSTALL
218 lines 7.0 kB history raw
1% Installing pandoc
3Installing from Source
4======================
6This method will work on all architectures, but requires that you first
7install the GHC compiler and some build tools: [GNU `make`], `sed`,
8`bash`, and `perl`. These are standard on unix systems (including MacOS
9X). If you're using Windows, you can install [Cygwin].
11[Cygwin]: http://www.cygwin.com/
12[GNU `make`]: http://www.gnu.org/software/make/
14Installing GHC
15--------------
17To compile Pandoc, you'll need [GHC] version 6.6 or greater. If
18you don't have GHC already, you can get it from the [GHC Download]
19page. If you're running MacOS X, you can also install GHC using
20[MacPorts] or [Fink].
22[GHC]: http://www.haskell.org/ghc/
23[GHC Download]: http://www.haskell.org/ghc/download.html
24[MacPorts]: http://macports.org
25[Fink]: http://finkproject.org
27Getting the source
28------------------
30Download the source tarball from pandoc's [pandoc's google code site].
31Extract the contents into a subdirectory:
33 tar xvzf pandoc-0.xy.tar.gz
35[pandoc's google code site]: http://pandoc.googlecode.com
37Installing Pandoc
38-----------------
401. Change to the directory containing the Pandoc distribution.
422. Compile:
44 make
46 If you get "Unknown modifier" errors, it is probably because `make`
47 on your system is not [GNU `make`]. Try using `gmake` instead.
493. See if it worked (optional, but recommended):
51 make test
53 Note: if you see errors like the following, they're due to differences
54 between different versions of the xhtml library, and can safely be
55 disregarded:
57 2c2
58 < <html xmlns="http://www.w3.org/1999/xhtml"
59 ---
60 > <html
624. Install:
64 sudo make install
66 Note: This installs `pandoc`, together with its wrappers and
67 documentation, into the `/usr/local` directory. If you'd rather
68 install `pandoc` somewhere else--say, in `/opt/local`--you can
69 set the `PREFIX` environment variable:
71 PREFIX=/opt/local sudo make install
73 If you don't have root privileges or would prefer to install
74 `pandoc` and the associated wrappers into your `~/bin` directory,
75 type this instead:
77 PREFIX=~ make install-exec
795. Build and install the Haskell libraries and library
80 documentation (optional--for Haskell programmers only):
82 make build-all
83 sudo make install-all
85 Note that building the library documentation requires [haddock].
87[haddock]: http://www.haskell.org/haddock/
89Removing Pandoc
90---------------
92Each of the installation steps described above can be reversed:
94 sudo make uninstall
96 PREFIX=~ make uninstall-exec
98 sudo make uninstall-all
100Other targets
101-------------
103The following 'make' targets should not be needed by the average user,
104but are documented here for packagers and developers:
106### Building and installing
108* `configure`: Performs the needed preprocessing to create a proper
109 Cabal package for Pandoc:
110 - Builds `ASCIIMathML.hs`, `DefaultHeaders.hs`, and `S5.hs`
111 from templates in `src/templates` and data in `src/ASCIIMathML.js`,
112 `src/ui`, and `src/headers`.
113 - Stores values of relevant environment variables in `vars` for
114 persistence.
115 - Runs Cabal's "configure" command.
116* `build-exec`: Builds `pandoc` executable (using Cabal's "build"
117 command) and creates the wrappers `html2markdown` and `markdown2pdf`
118 from templates in `src/wrappers`.
119* `build-doc`: Builds program documentation (e.g. `README.html`).
120* `build-lib-doc`: Builds Haddock documentation for Pandoc libraries.
121* `install-doc`, `uninstall-doc`: Installs/uninstalls user documentation
122 and man pages.
123* `install-lib-doc`, `uninstall-lib-doc`: Installs/uninstalls library
124 documentation and man pages.
125* `install-exec`, `uninstall-exec`: Installs/uninstalls programs
126 (`pandoc` and wrappers).
128### Testing
130* `test`: Runs Pandoc's test suite. (All tests should pass.)
131* `test-markdown`: Runs the Markdown regression test suite, using
132 `pandoc --strict`. (Three of the tests will fail.)
134### Cleaning
136* `clean`: Restores directory to pre-build state, removing generated files.
137* `distclean`: Like clean, but also cleans up files created by `make deb`.
139### Packaging
141* `tarball`: Creates a source tarball for distribution.
142* `deb`: Creates debian packages in `..` directory.
143* `macport`: Creates MacPorts Portfile in `macports` directory.
144* `freebsd`: Creates freebsd Makefile and distinfo in `freebsd` directory.
145* `win-pkg`: Creates a Windows binary package (presupposes `pandoc.exe`,
146 which must be created by building Pandoc on a Windows machine).
147* `website`: Creates Pandoc's website in `web/pandoc` directory.
149Installing pandoc using Cabal
150=============================
152Pandoc can also be installed using the standard Haskell packaging tool,
153[Cabal](http://www.haskell.org/cabal/). You'll need GHC 6.6 or greater
154(see [Installing GHC](#installing-ghc), above). Just download the source
155tarball, unpack, and type:
157 runhaskell Setup.hs configure
158 runhaskell Setup.hs build
159 runhaskell Setup.hs install # this one as root
161This will install the pandoc executable and the Haskell libraries,
162but not the shell scripts, man pages, or other documentation.
164Installing pandoc using MacPorts
165================================
167This is an alternative to compiling from source on MacOS X.
168[MacPorts] is a system for building and maintaining \*nix software
169on MacOS X computers. If you don't already have MacPorts, follow
170[these instructions for installing
171it](http://trac.macosforge.org/projects/macports/wiki/InstallingMacPorts).
173Once you've installed MacPorts, you can install pandoc by typing:
175 sudo port sync # to get the most recent ports
176 sudo port install pandoc
178Since pandoc depends on GHC, the process may take a long time.
180Installing the Windows binary
181=============================
183Simply download the zip file from [pandoc's google code site].
184Extract the files from the archive, and put `pandoc.exe` somewhere
185in your PATH.
187Note that the Windows binary distribution does not include the shell
188scripts `markdown2pdf`, `html2markdown`, or `hsmarkdown`. If you need
189these, compile from source.
191Installing pandoc on Debian
192===========================
194Pandoc is now in the debian unstable archive, and can be installed
195using `apt-get` (as root):
197 apt-get install pandoc # the program, shell scripts, and docs
198 apt-get install libghc6-pandoc-dev # the libraries
199 apt-get install pandoc-doc # library documentation
201Thanks to Recai Oktaş for setting up the debian packages.
203Installing pandoc on FreeBSD
204============================
206Pandoc is in the FreeBSD ports repository (`textproc/pandoc`) and can be
207installed in the normal way:
209 cd /usr/ports/textproc/pandoc
210 make install clean # as root
212Alternatively, you can use `pkg_add`:
214 pkg_add -r pandoc
216Note that the version of pandoc in FreeBSD's official repository may be
217somewhat older than the most recent version.