aboutsummaryrefslogtreecommitdiff
path: root/INSTALL
blob: bff5304e06568c3795e887c2af5e4121ba541ce6 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
% Installing pandoc

The following instructions are for installing pandoc from source. Binary
packages are also available for Windows, MacOS X, Linux (Debian and
derivatives), and FreeBSD. See the [pandoc home page] for more details.

[pandoc home page]: http://sophos.berkeley.edu/macfarlane/pandoc/

# Installing GHC

To compile Pandoc, you'll need [GHC] version 6.6 or greater.  If
you don't have GHC already, you can get it from the [GHC Download]
page. If you're running MacOS X, you can also install GHC using
[MacPorts] or [Fink].

[GHC]: http://www.haskell.org/ghc/
[GHC Download]: http://www.haskell.org/ghc/download.html
[MacPorts]: http://macports.org
[Fink]: http://finkproject.org

You'll also need standard build tools: [GNU `make`], `sed`, `bash`,
and `perl`.  These are standard on unix systems (including MacOS
X).  If you're using Windows, you can install [Cygwin].

[Cygwin]: http://www.cygwin.com/
[GNU `make`]: http://www.gnu.org/software/make/

# Installing Pandoc

1.  Change to the directory containing the Pandoc distribution.

2.  Compile:

        make

    If you get "Unknown modifier" errors, it is probably because `make`
    on your system is not [GNU `make`].  Try using `gmake` instead.

3.  See if it worked (optional, but recommended): 

        make test

    Note: if you see errors like the following, they're due to differences
    between different versions of the xhtml library, and can safely be
    disregarded:

        2c2
        < <html xmlns="http://www.w3.org/1999/xhtml"
        ---
        > <html

4.  Install:

        sudo make install

    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:

        PREFIX=/opt/local sudo make install

    If you don't have root privileges or would prefer to install
    `pandoc` and the associated wrappers into your `~/bin` directory,
    type this instead:

        PREFIX=~ make install-exec

5.  Build and install the Haskell libraries and library
    documentation (optional--for Haskell programmers only):

        make build-all
        sudo make install-all

    Note that building the library documentation requires [haddock].

[haddock]: http://www.haskell.org/haddock/ 

# Removing Pandoc

Each of the installation steps described above can be reversed:

    sudo make uninstall

    PREFIX=~ make uninstall-exec

    sudo make uninstall-all

# 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`:  Performs the needed preprocessing to create a proper
  Cabal package for Pandoc:
    - Builds `ASCIIMathML.hs`, `DefaultHeaders.hs`, and `S5.hs`
      from templates in `src/templates` and data in `src/ASCIIMathML.js`,
      `src/ui`, and `src/headers`.
    - 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) and creates the wrappers `html2markdown` and `markdown2pdf`
  from templates in `src/wrappers`.
* `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`.  (Three of the tests 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.
* `deb`:  Creates debian packages in `..` directory.
* `osx-pkg-prep`:  Prepares for building a MacOS X package.
* `osx-pkg`:  Builds a MacOS X package (must be run as root, and on OS X).
  You should make `osx-pkg-prep` first (not as root).
* `osx-dmg`:  Creates a compressed disk image containing Mac OS X package
  (must be run on OS X).  You should make `osx-pkg` first.
* `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.