INSTALL

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