INSTALL

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