diff options
Diffstat (limited to 'INSTALL')
| -rw-r--r-- | INSTALL | 263 |
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' |