INSTALL

   1     Copyright 1997-2014 Free Software Foundation, Inc.
   2
   3     Copying and distribution of this file, with or without modification,
   4     are permitted in any medium without royalty provided the copyright
   5     notice and this notice are preserved.
   6
   7 This file contains information that supplements the generic
   8 installation instructions in file `INSTALL.gen'.
   9
  10
  11 Normal Installation
  12 ===================
  13
  14 The simplest way to compile groff is:
  15
  16   1. `cd' to the directory containing groff's source code and type
  17      `./configure' to configure groff for your system.  If you are
  18      using `csh' on an old version of System V, you might need to type
  19      `sh ./configure' instead to prevent `csh' from trying to execute
  20      `configure' itself.
  21
  22      Running `configure' takes awhile.  While running, it prints some
  23      messages telling which features it is checking for.
  24
  25   2. Type `make' to compile groff.
  26
  27   3. Type `sudo make install' to install the groff programs and any
  28      data files and documentation.  `make install' is the only step for
  29      which you need `root' access; this is done by `sudo'.
  30
  31   4. You can remove the groff binaries and object files from the
  32      source code directory by typing `make clean'.  To also remove the
  33      files that `configure' created (so you can compile groff for
  34      a different kind of computer), type `make distclean'.
  35
  36
  37 External Installation
  38 =====================
  39
  40 It is also possible to perform the whole installation process outside
  41 of the source code directory.  In this case a whole external build
  42 directory structure is created without changing any parts of the source
  43 code tree.  This is useful if the source code is read-only or if
  44 several different installations, such as for multiple architectures,
  45 should be constructed.
  46
  47 As an example we assume that the source code of the `groff' code is in
  48 `/usr/local/src/groff', and that the build process should be done
  49 within the directory `/home/my/groff.compile'.
  50
  51   0. Create `/home/my/groff.compile' and change to that directory.
  52
  53   1. Call `/usr/local/src/groff/configure' in that directory to
  54      configure groff for your system.  If you are using `csh' on an old
  55      version of System V, you might need to type `sh
  56      /usr/local/src/groff/configure' instead.
  57
  58   2. Type `make' to compile groff in that directory.
  59
  60   3. Type `sudo make install' to install the groff programs and any
  61      data files and documentation.
  62
  63   4. You can remove the groff binaries and object files from the
  64      build directory by typing `make clean'.  To also remove the
  65      files that `configure' created (so you can compile the package for
  66      a different kind of computer), type `make distclean'.
  67
  68
  69 Special Platforms
  70 =================
  71
  72 For instructions how to build groff with DJGPP tools for MS-DOS and
  73 MS-Windows, see the file arch/djgpp/README.
  74
  75 For instructions how to build groff with the MinGW tools for
  76 MS-Windows, see the file README.MinGW.
  77
  78
  79 Miscellaneous
  80 =============
  81
  82 groff is written in C++, so you need a C++ compiler.  The C++ source
  83 files use a suffix of `.cpp', so your C++ compiler must be able to
  84 handle this.  If you don't already have a C++ compiler, we suggest gcc
  85 2.7.1 or later (gcc version 2 includes GNU C++ as well as GNU C).  From
  86 gcc 2.5, it is no longer necessary to install libg++: the C++ header
  87 files needed by groff are created by the gcc installation process.  To
  88 override configure's choice of C++ compiler, you can set the CXX
  89 environment variable.
  90
  91 If you have a library that provides a faster malloc than your system's
  92 usual malloc, it is good idea to include it in LIBS.  For example,
  93 using the malloc that comes with GNU Emacs version 20 can give a
  94 worthwhile (and sometimes spectacular) performance improvement.
  95
  96 Many programs within the `groff' system are written in the Perl
  97 language.  So you need a `perl' program with the least version of
  98 `v5.6.1'.
  99
 100
 101 If you want A4 or letter paper format and the configure script produces
 102 an incorrect guess, say
 103
 104   PAGE=xxx ./configure
 105
 106 where `xxx' should be either `A4' or `letter'.  Note that this only
 107 affects the paper selection of some device drivers like grops (which
 108 can be still overridden on the command line).  For compatibility with
 109 ditroff, the default page length in gtroff is always 11 inches.  The
 110 page length can be changed with the `pl' request.
 111
 112 When you have built groff but not installed yet, you can use the
 113 test-groff script to try groff out on one of the man pages.  (Use the
 114 .n files not the .man files.)  The test-groff script sets up environment
 115 variables to allow groff to run without being installed.  For example,
 116 you could do
 117
 118   ./test-groff -man -Tascii src/roff/groff/groff.n | less
 119
 120 to display the groff(1) man page with the `less' pager.
 121
 122 To get a DVI, PDF, or HTML version of the groff texinfo manual, say
 123 `make groff.dvi', `make groff.pdf', or `make groff.html', respectively,
 124 in the `doc' subdirectory (after configuring the groff package).  Note
 125 that you need texinfo version 4.8 as a prerequisite.
 126
 127 If you have problems, read the PROBLEMS file.  If this doesn't help
 128 and you need support, please contact the `groff' mailing list.  If you
 129 think that you have found a bug, please submit a report in our bug
 130 tracker at
 131
 132   https://savannah.gnu.org/projects/groff
 133
 134 Alternative, but less preferable, you may send a bug report using the
 135 form in the file BUG-REPORT.
 136
 137 ##### Emacs settings
 138 Local Variables:
 139 mode: text
 140 End: