aboutsummaryrefslogtreecommitdiff
path: root/INSTALL
diff options
context:
space:
mode:
Diffstat (limited to 'INSTALL')
-rw-r--r--INSTALL263
1 files changed, 0 insertions, 263 deletions
diff --git a/INSTALL b/INSTALL
deleted file mode 100644
index 9a582784d..000000000
--- a/INSTALL
+++ /dev/null
@@ -1,263 +0,0 @@
-% Installing pandoc
-
-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 are also binary installers for Windows and Mac OS X.
-
-If you are installing the development version from github, see also:
-https://github.com/jgm/pandoc/wiki/Installing-the-development-version-of-pandoc
-
-Please note that pandoc only supports [GHC] versions 7.8 and
-above. The easiest way to get GHC is by installing the [Haskell platform]
-
-How to get the source
----------------------
-
-Source tarballs can be found at
-<https://hackage.haskell.org/package/pandoc>. The tarball
-for a particular version `VERSION` can be found at
-
- https://hackage.haskell.org/package/pandoc-VERSION/pandoc-VERSION.tar.gz
-
-**Do not use the automatically generated tarball that can be
-downloaded from pandoc's GitHub releases page.** It does not
-include some essential template files, which come from a GitHub
-submodule.
-
-If you want the latest development code, you can fetch it
-by cloning the repository:
-
- git clone https://github.com/jgm/pandoc
- cd pandoc
- git submodule update --init # to fetch the templates
-
-Note: there may be times when the development code is broken
-or depends on other libraries which must be installed
-separately. Unless you really know what you're doing, install
-the last released version.
-
-Quick install with stack
-------------------------
-
-1. Install [stack](http://docs.haskellstack.org/en/stable/install_and_upgrade.html).
-
-2. If you used git to get the pandoc source (as opposed to unpacking
- a release tarball), do
-
- git submodule update --init
-
-3. In the pandoc source directory,
-
- stack install
-
- You may be prompted to run `stack setup`, which will automatically
- download the ghc compiler if needed.
-
-
-Quick install with cabal
-------------------------
-
-1. Install the [Haskell platform]. This will give you [GHC] and
- the [cabal-install] build tool.
-
-2. Update your package database:
-
- cabal update
-
-3. Use `cabal` to install pandoc and its dependencies:
-
- cabal install pandoc
-
- This procedure will install the released version of pandoc,
- which will be downloaded automatically from HackageDB.
-
- If this step fails, and you are using an older version
- of the Haskell Platform, e.g. on Debian stable, you may need to
- upgrade your version of cabal:
-
- cabal install cabal-install
- ~/.cabal/bin/cabal update
- ~/.cabal/bin/cabal install pandoc
-
- If you want to install a modified or development version
- of pandoc instead, switch to the source directory and do
- as above, but without the 'pandoc':
-
- cabal install
-
- Note: If you obtained the source from the git repository (rather
- than a release tarball), you'll need to do
-
- git submodule update --init
-
- to fetch the contents of `data/templates` before `cabal install`.
-
-4. Make sure the `$CABALDIR/bin` directory is in your path. You should
- now be able to run `pandoc`:
-
- pandoc --help
-
- [Not sure where `$CABALDIR` is?](http://www.haskell.org/haskellwiki/Cabal-Install#The_cabal-install_configuration_file)
-
-5. If you want to process citations with pandoc, you will also need to
- install a separate package, `pandoc-citeproc`. This can be installed
- using cabal:
-
- cabal install pandoc-citeproc
-
- By default `pandoc-citeproc` uses the "i;unicode-casemap" method
- to sort bibliography entries (RFC 5051). If you would like to
- use the locale-sensitive unicode collation algorithm instead,
- specify the `unicode_collation` flag:
-
- cabal install pandoc-citeproc -funicode_collation
-
- Note that this requires the `text-icu` library, which in turn
- depends on the C library `icu4c`. Installation directions
- vary by platform. Here is how it might work on OSX with homebrew:
-
- brew install icu4c
- cabal install --extra-lib-dirs=/usr/local/Cellar/icu4c/51.1/lib \
- --extra-include-dirs=/usr/local/Cellar/icu4c/51.1/include \
- -funicode_collation text-icu pandoc-citeproc
-
-The `pandoc.1` man page will be installed automatically. cabal shows
-you where it is installed: you may need to set your `MANPATH`
-accordingly. If `MANUAL.txt` has been modified, the man page can be
-rebuilt: `make man/pandoc.1`.
-
-The `pandoc-citeproc.1` man page will also be installed automatically.
-
-[GHC]: http://www.haskell.org/ghc/
-[Haskell platform]: http://hackage.haskell.org/platform/
-[cabal-install]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall
-
-Custom 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]. These instructions
-assume that the pandoc source directory is your working directory.
-
-1. Install dependencies: in addition to the [Haskell platform],
- you will need a number of additional libraries. You can install
- them all with
-
- cabal update
- cabal install --only-dependencies
-
-2. Configure:
-
- cabal 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
-
- All of the options have sensible defaults that can be overridden
- as needed.
-
- `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:
-
- - `embed_data_files`: embed all data files into the binary (default no).
- This is helpful if you want to create a relocatable binary.
- Note: if this option is selected, you need to install the
- `hsb2hs` preprocessor: `cabal install hsb2hs` (version 0.3.1 or
- higher is required).
-
- - `https`: enable support for downloading resources over https
- (using the `http-client` and `http-client-tls` libraries).
-
-3. Build:
-
- cabal build
-
-4. Build API documentation:
-
- cabal haddock --html-location=URL --hyperlink-source
-
-5. Copy the files:
-
- cabal copy --destdir=PATH
-
- The default destdir is `/`.
-
-6. Register pandoc as a GHC package:
-
- cabal register
-
- 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.
-
-Creating a relocatable binary
------------------------------
-
-It is possible to compile pandoc such that the data files
-pandoc uses are embedded in the binary. The resulting binary
-can be run from any directory and is completely self-contained.
-
- cabal install hsb2hs # a required build tool
- cabal install --flags="embed_data_files" citeproc-hs
- cabal configure --flags="embed_data_files"
- cabal build
-
-You can find the pandoc executable in `dist/build/pandoc`. Copy this wherever
-you please.
-
-Or alternatively with `stack`:
-
- stack install pandoc --flag pandoc:embed_data_files
-
-[zip-archive]: http://hackage.haskell.org/package/zip-archive
-[highlighting-kate]: http://hackage.haskell.org/package/highlighting-kate
-[blaze-html]: http://hackage.haskell.org/package/blaze-html
-[Cabal User's Guide]: http://www.haskell.org/cabal/release/latest/doc/users-guide/builders.html#setup-configure-paths
-
-Running tests
--------------
-
-Pandoc comes with an automated test suite integrated to cabal.
-To build the tests:
-
- cabal configure --enable-tests && cabal build
-
-To run the tests:
-
- cabal test
-
-To run particular tests (pattern-matching on their names), use
-the `-t` option:
-
- cabal test --test-options='-t markdown'
-
-If you add a new feature to pandoc, please add tests as well, following
-the pattern of the existing tests. The test suite code is in
-`tests/test-pandoc.hs`. If you are adding a new reader or writer, it is
-probably easiest to add some data files to the `tests` directory, and
-modify `tests/Tests/Old.hs`. Otherwise, it is better to modify the module
-under the `tests/Tests` hierarchy corresponding to the pandoc module you
-are changing.
-
-Running benchmarks
-------------------
-
-To build the benchmarks:
-
- cabal configure --enable-benchmarks && cabal build
-
-To run the benchmarks:
-
- cabal bench
-
-To use a smaller sample size so the benchmarks run faster:
-
- cabal bench --benchmark-options='-s 20'
-
-To run just the markdown benchmarks:
-
- cabal bench --benchmark-options='markdown'