diff options
| -rw-r--r-- | INSTALL | 342 |
1 files changed, 66 insertions, 276 deletions
@@ -1,189 +1,105 @@ % Installing pandoc -Installing pandoc from Source -============================= +These instructions explain how to install pandoc from source. +Binary packages or ports of pandoc are available for freebsd +and several linux distributions, so check your package manager. +There is also a Windows installer. -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]. +Quick install +------------- -[install pandoc using Make]: #installing-pandoc-using-make -[install pandoc using Cabal]: #installing-pandoc-using-cabal -[build options]: #build-options +1. Install the [Haskell platform]. This will give you [GHC] and +the [cabal-install] build tool. -Installing Pandoc using Make ----------------------------- +2. Use `cabal` to install pandoc and its dependencies: -1. Change to the directory containing the Pandoc distribution. + cabal install pandoc -2. Compile: + If you want support for source code syntax highlighting, set + the `highlighting` flag: - make + cabal install -fhighlighting pandoc - If you get "Unknown modifier" errors, it is probably because `make` - on your system is not [GNU `make`]. Try using `gmake` instead. +3. Make sure the `$CABALDIR/bin` directory is in your path. You should +now be able to run `pandoc`: - 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 + pandoc --help - CABALOPTS=--user make +4. Make sure the `$CABALDIR/share/man/man1` directory is in your `MANPATH`. +You should now be able to access the `pandoc` man page: -3. See if it worked (optional, but recommended): + man pandoc - make test +[GHC]: http://www.haskell.org/ghc/ +[Haskell platform]: http://hackage.haskell.org/platform/ +[cabal-install]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall -4. Install: +Custom install +-------------- - sudo make install +This is a step-by-step procedure that offers maximal control +over the build and installation. Most users should use the +quick install, but this information may be of use to packagers. +For more details, see the [Cabal User's Guide]. - 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: +1. Install dependencies: in addition to the [Haskell platform], +you will need [zip-archive] and (if you want syntax highlighting) +[highlighting-kate]. - PREFIX=/opt/local sudo make install +2. Configure: - If you don't have root privileges or would prefer to install - `pandoc` and the associated wrappers into your `~/bin` directory, - type this instead: + runghc Setup.hs configure --prefix=DIR --bindir=DIR --libdir=DIR \ + --datadir=DIR --libsubdir=DIR --datasubdir=DIR --docdir=DIR \ + --htmldir=DIR --program-prefix=PREFIX --program-suffix=SUFFIX \ + --mandir=DIR --flags=FLAGSPEC - PREFIX=~ make install-exec + All of the options have sensible defaults that can be overridden + as needed. -5. Build and install the Haskell libraries and library - documentation (optional--for Haskell programmers only): + `FLAGSPEC` is a list of Cabal configuration flags, optionally + preceded by a `-` (to force the flag to `false`), and separated + by spaces. Pandoc's flags include: - make build-all - sudo make install-all + - `library`: build the library (default yes) + - `executable`: build the pandoc executable (default yes) + - `wrappers`: build the wrappers `markdown2pdf` and `hsmarkdown` + (default yes) + - `highlighting`: compile with syntax highlighting support (increases + the size of the executable) (default no) - Note that building the library documentation requires [haddock]. + So, for example, -6. If you decide you don't want pandoc on your system, each of the - installation steps described above can be reversed: + --flags="-library highlighting" - sudo make uninstall + tells Cabal to build the executable but not the library, and to + compile with syntax highlighting support. - PREFIX=~ make uninstall-exec +3. Build: - sudo make uninstall-all + runghc Setup.hs build -[haddock]: http://www.haskell.org/haddock/ +4. Build API documentation: -Installing pandoc using Cabal ------------------------------ + runghc Setup.hs haddock --html-location=URL --hyperlink-source -Change to the directory containing the pandoc source, and type: +5. Copy the files: - 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 + runghc Setup.hs copy --destdir=PATH -This will install the pandoc executable and the Haskell libraries, -but not the shell scripts, man pages, or other documentation. + The default destdir is `/`. -You may just want the executable, or just the libraries. This -can be controlled with configuration flags (the `-` negates the -flag): +6. Register pandoc as a GHC package: - runhaskell Setup configure -f-library # just the executable - runhaskell Setup configure -f-executable # just the libraries + runghc Setup.hs register -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]. + Package managers may want to use the `--gen-script` option to + generate a script that can be run to register the package at + install time. +[zip-archive]: http://hackage.haskell.org/package/zip-archive +[highlighting-kate]: http://hackage.haskell.org/package/highlighting-kate [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 ------------------------- @@ -199,133 +115,7 @@ 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. + runhaskell Setup configure --flags="citeproc" [`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 - |