summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorfiddlosopher <fiddlosopher@788f1e2b-df1e-0410-8736-df70ead52e1b>2010-02-03 08:27:31 +0000
committerfiddlosopher <fiddlosopher@788f1e2b-df1e-0410-8736-df70ead52e1b>2010-02-03 08:27:31 +0000
commit012c569f06b004af17b58cfa88d190e8761cc4a5 (patch)
tree3761f0815fa73d6bc471c0750ca3d701869cc423
parentd6642c322c5316c7613cadd9e7716376f321a08c (diff)
Updated INSTALL instructions.
git-svn-id: https://pandoc.googlecode.com/svn/trunk@1832 788f1e2b-df1e-0410-8736-df70ead52e1b
-rw-r--r--INSTALL342
1 files changed, 66 insertions, 276 deletions
diff --git a/INSTALL b/INSTALL
index b4f7d2a7b..a0ad11431 100644
--- a/INSTALL
+++ b/INSTALL
@@ -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
-