Added INSTALL.md, incorporating INSTALL + installing page from website.
This commit is contained in:
John MacFarlane
parent
b4fbe226a5
commit
bb20f919c3
4 changed files with 342 additions and 265 deletions
1
.gitignore
vendored
1
.gitignore
vendored
|
|
@ -2,7 +2,6 @@
|
||||||
dist/*
|
dist/*
|
||||||
MANUAL.*
|
MANUAL.*
|
||||||
!MANUAL.txt
|
!MANUAL.txt
|
||||||
INSTALL.*
|
|
||||||
.configure-stamp
|
.configure-stamp
|
||||||
.cabal-sandbox
|
.cabal-sandbox
|
||||||
cabal.sandbox.config
|
cabal.sandbox.config
|
||||||
|
|
|
||||||
263
INSTALL
263
INSTALL
|
|
@ -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'
|
|
||||||
341
INSTALL.md
Normal file
341
INSTALL.md
Normal file
|
|
@ -0,0 +1,341 @@
|
||||||
|
# Installing pandoc
|
||||||
|
|
||||||
|
## Windows
|
||||||
|
|
||||||
|
- There is a package installer at pandoc's [download page].
|
||||||
|
|
||||||
|
- For PDF output, you'll also need to install LaTeX.
|
||||||
|
We recommend [MiKTeX](http://miktex.org/).
|
||||||
|
|
||||||
|
## Mac OS X
|
||||||
|
|
||||||
|
- There is a package installer at pandoc's [download page].
|
||||||
|
If you later want to uninstall the package, you can do so
|
||||||
|
by downloading [this script][uninstaller]
|
||||||
|
and running it with `perl uninstall-pandoc.pl`.
|
||||||
|
|
||||||
|
- You can also install pandoc using
|
||||||
|
[homebrew](http://brew.sh): `brew install pandoc`.
|
||||||
|
|
||||||
|
- For PDF output, you'll also need LaTeX. Because a full [MacTeX]
|
||||||
|
installation takes more than a gigabyte of disk space, we recommend
|
||||||
|
installing [BasicTeX](http://www.tug.org/mactex/morepackages.html)
|
||||||
|
(64M) and using the `tlmgr` tool to install additional packages
|
||||||
|
as needed. If you get errors warning of fonts not found, try
|
||||||
|
|
||||||
|
tlmgr install collection-fontsrecommended
|
||||||
|
|
||||||
|
## Linux
|
||||||
|
|
||||||
|
- First, try your package manager.
|
||||||
|
Pandoc is in the [Debian], [Ubuntu], [Slackware],
|
||||||
|
[Arch], [Fedora], [NiXOS], [openSUSE], and [gentoo] repositories.
|
||||||
|
Note, however, that versions in the repositories are often
|
||||||
|
old.
|
||||||
|
|
||||||
|
- For 64-bit [Debian] and [Ubuntu], we provide a debian package
|
||||||
|
on the [download page].
|
||||||
|
|
||||||
|
sudo dpkg -i $DEB
|
||||||
|
|
||||||
|
where `$DEB` is the path to the downloaded deb, will
|
||||||
|
will install the `pandoc` and `pandoc-citeproc` executables
|
||||||
|
and man pages. If you use an RPM-based distro, you may be
|
||||||
|
able to install this deb using `alien`, or try
|
||||||
|
|
||||||
|
ar p $DEB data.tar.gz | sudo tar xvz --strip-components 2 -C /usr/local
|
||||||
|
|
||||||
|
- If you'd rather install pandoc in your home directory, say
|
||||||
|
in `$HOME/.local`, then you can extract the files manually
|
||||||
|
from the deb:
|
||||||
|
|
||||||
|
ar p $DEB data.tar.gz | tar xvz --strip-components 2 -C $HOME/.local/
|
||||||
|
|
||||||
|
where, again, `$DEB` is the path to the downloaded deb.
|
||||||
|
|
||||||
|
- If the version in your repository is too old and you cannot
|
||||||
|
use the deb we provide, you can install from source, using the
|
||||||
|
instructions below under [Installing from source].
|
||||||
|
Note that most distros have the Haskell platform in their
|
||||||
|
package repositories. For example, on Debian/Ubuntu,
|
||||||
|
you can install it with `apt-get install haskell-platform`.
|
||||||
|
|
||||||
|
- For PDF output, you'll need LaTeX. We recommend installing
|
||||||
|
[TeX Live](http://www.tug.org/texlive/) via your package
|
||||||
|
manager. (On Debian/Ubuntu, `apt-get install texlive`.)
|
||||||
|
|
||||||
|
## BSD
|
||||||
|
|
||||||
|
- Pandoc is in the [NetBSD] and [FreeBSD ports] repositories.
|
||||||
|
|
||||||
|
## Compiling from source
|
||||||
|
|
||||||
|
If for some reason a binary package is not available for your
|
||||||
|
platform, or if you want to hack on pandoc or use a non-released
|
||||||
|
version, you can install from source.
|
||||||
|
|
||||||
|
### Getting the pandoc source code
|
||||||
|
|
||||||
|
Source tarballs can be found at
|
||||||
|
<https://hackage.haskell.org/package/pandoc>. For example, to
|
||||||
|
fetch the source for version 1.17.0.3:
|
||||||
|
|
||||||
|
wget https://hackage.haskell.org/package/pandoc-1.17.0.3/pandoc-1.17.0.3.tar.gz
|
||||||
|
tar xvzf pandoc-1.17.0.3.tar.gz
|
||||||
|
cd pandoc-1.17.0.3
|
||||||
|
|
||||||
|
Or you can fetch the development code 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 stack method
|
||||||
|
|
||||||
|
The easiest way to build pandoc from source is to use [stack]:
|
||||||
|
|
||||||
|
1. Install [stack].
|
||||||
|
|
||||||
|
2. Change to the pandoc source directory and issue the following commands:
|
||||||
|
|
||||||
|
stack setup
|
||||||
|
stack install --test
|
||||||
|
|
||||||
|
`stack setup` will automatically download the ghc compiler
|
||||||
|
if you don't have it. `stack install` will install the
|
||||||
|
`pandoc` executable into `~/.local/bin`, which you should
|
||||||
|
add to your `PATH`. This process will take a while, and
|
||||||
|
will consume a considerable amount of disk space.
|
||||||
|
|
||||||
|
### Quick cabal method
|
||||||
|
|
||||||
|
1. Install the [Haskell platform]. This will give you [GHC] and
|
||||||
|
the [cabal-install] build tool. Note that pandoc requires
|
||||||
|
GHC >= 7.8.
|
||||||
|
|
||||||
|
2. Update your package database:
|
||||||
|
|
||||||
|
cabal update
|
||||||
|
|
||||||
|
3. Use `cabal` to install pandoc and its dependencies:
|
||||||
|
|
||||||
|
cabal install pandoc --enable-tests
|
||||||
|
|
||||||
|
This procedure will install the released version of pandoc,
|
||||||
|
which will be downloaded automatically from HackageDB.
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
6. 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 cabal method
|
||||||
|
|
||||||
|
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 --enable-tests
|
||||||
|
|
||||||
|
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
|
||||||
|
cabal test
|
||||||
|
|
||||||
|
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.
|
||||||
|
With cabal, add `-fembed_data_files` to the `cabal configure`
|
||||||
|
or `cabal install` commands.
|
||||||
|
|
||||||
|
With stack, use `--flag pandoc:embed_data_files`.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
### Running tests
|
||||||
|
|
||||||
|
Pandoc comes with an automated test suite.
|
||||||
|
To run with cabal, `cabal test`; to run with stack, `stack
|
||||||
|
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 and run the benchmarks:
|
||||||
|
|
||||||
|
cabal configure --enable-benchmarks && cabal build
|
||||||
|
cabal bench
|
||||||
|
|
||||||
|
or with stack:
|
||||||
|
|
||||||
|
stack 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'
|
||||||
|
|
||||||
|
### Building the whole pandoc ecosystem
|
||||||
|
|
||||||
|
Sometimes pandoc's development code depends on unreleased versions
|
||||||
|
of dependent libraries. You'll need to build these as well. A
|
||||||
|
maximal build method would be
|
||||||
|
|
||||||
|
mkdir pandoc-build
|
||||||
|
cd pandoc-build
|
||||||
|
git clone https://github.com/jgm/pandoc-types
|
||||||
|
git clone https://github.com/jgm/texmath
|
||||||
|
git clone https://github.com/jgm/pandoc-citeproc
|
||||||
|
git clone https://github.com/jgm/pandoc
|
||||||
|
git clone https://github.com/jgm/cmark-hs
|
||||||
|
git clone https://github.com/jgm/zip-archive
|
||||||
|
cd pandoc
|
||||||
|
git submodule update --init
|
||||||
|
stack install --test --install-ghc --stack-yaml stack.full.yaml
|
||||||
|
|
||||||
|
To pull in the latest changes, after you've done this and there have been
|
||||||
|
changes in the repositories: Visit each repository in pandoc-build
|
||||||
|
(pandoc-types, texmath, pandoc-citeproc, pandoc, zip-archive, cmark-hs) and do
|
||||||
|
`git pull`. In the pandoc repo, also do `git submodule update` and `stack
|
||||||
|
install --test --stack-yaml stack.full.yaml`.
|
||||||
|
|
||||||
|
|
||||||
|
[Arch]: https://www.archlinux.org/packages/community/x86_64/pandoc/
|
||||||
|
[Cabal User's Guide]: http://www.haskell.org/cabal/release/latest/doc/users-guide/builders.html#setup-configure-paths
|
||||||
|
[Debian]: http://packages.debian.org/lenny/pandoc
|
||||||
|
[Fedora]: https://apps.fedoraproject.org/packages/pandoc
|
||||||
|
[FreeBSD ports]: http://www.freshports.org/textproc/pandoc/
|
||||||
|
[GHC]: http://www.haskell.org/ghc/
|
||||||
|
[GPL]: http://www.gnu.org/copyleft/gpl.html
|
||||||
|
[Haskell platform]: http://hackage.haskell.org/platform/
|
||||||
|
[MacPorts]: http://trac.macports.org/browser/trunk/dports/textproc/pandoc/Portfile
|
||||||
|
[MacTeX]: https://tug.org/mactex/
|
||||||
|
[NetBSD]: http://pkgsrc.se/wip/pandoc
|
||||||
|
[NixOS]: http://nixos.org/nixos/
|
||||||
|
[Slackware]: http://www.linuxpackages.net/search_view.php?by=name&name=pandoc&ver=
|
||||||
|
[Ubuntu]: http://www.ubuntu.com
|
||||||
|
[download page]: https://github.com/jgm/pandoc/releases/latest
|
||||||
|
[gentoo]: http://packages.gentoo.org/package/app-text/pandoc
|
||||||
|
[haskell repository]: https://wiki.archlinux.org/index.php/Haskell_Package_Guidelines#.5Bhaskell.5D
|
||||||
|
[openSUSE]: https://software.opensuse.org/package/pandoc
|
||||||
|
[source tarball]: http://hackage.haskell.org/package/pandoc
|
||||||
|
[stack]: http://docs.haskellstack.org/en/stable/install_and_upgrade.html
|
||||||
|
[uninstaller]: https://raw.githubusercontent.com/jgm/pandoc/master/osx/uninstall-pandoc.pl
|
||||||
|
|
@ -108,7 +108,7 @@ Data-Files:
|
||||||
MANUAL.txt, COPYRIGHT
|
MANUAL.txt, COPYRIGHT
|
||||||
Extra-Source-Files:
|
Extra-Source-Files:
|
||||||
-- documentation
|
-- documentation
|
||||||
INSTALL, BUGS, README.md, CONTRIBUTING.md, changelog
|
INSTALL.md, BUGS, README.md, CONTRIBUTING.md, changelog
|
||||||
man/pandoc.1
|
man/pandoc.1
|
||||||
-- stack build plan
|
-- stack build plan
|
||||||
stack.yaml
|
stack.yaml
|
||||||
|
|
|
||||||
Loading…
Add table
Reference in a new issue