INSTALL.extra

   1     Copyright 1997-2018 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'.
   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 Dependencies
  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 In order to build the documentation you would need `makeinfo' from the
 101 'texinfo' package, in fact `configure' will fail if this program is
 102 not found unless you pass the option `with-doc=no'.
 103
 104 The `uchardet' library is an optional dependency of the `preconv'
 105 program: if this library is found by `configure' it will be
 106 automatically used by `preconv'.  In order to discover the presence of
 107 the `uchardet' library you would also need to have the `pkg-config'
 108 program installed on your system.
 109
 110
 111 Miscellaneous
 112 =============
 113
 114 If you want A4 or letter paper format and the configure script produces
 115 an incorrect guess, say
 116
 117   PAGE=xxx ./configure
 118
 119 where `xxx' should be either `A4' or `letter'.  Note that this only
 120 affects the paper selection of some device drivers like grops (which
 121 can be still overridden on the command line).  For compatibility with
 122 ditroff, the default page length in gtroff is always 11 inches.  The
 123 page length can be changed with the `pl' request.
 124
 125 When you have built groff but not installed yet, you can use the
 126 test-groff script to try groff out on one of the man pages.  (Use the
 127 .n files not the .man files.)  The test-groff script sets up environment
 128 variables to allow groff to run without being installed.  For example,
 129 you could do
 130
 131   ./test-groff -man -Tascii src/roff/groff/groff.n | less
 132
 133 to display the groff(1) man page with the `less' pager.
 134
 135 To get a DVI, PDF, or HTML version of the groff texinfo manual, say
 136 `make groff.dvi', `make groff.pdf', or `make groff.html', respectively,
 137 in the `doc' subdirectory (after configuring the groff package).  Note
 138 that you need texinfo version 4.8 as a prerequisite.
 139
 140 If you have problems, read the PROBLEMS file.  If this doesn't help
 141 and you need support, please contact the `groff' mailing list.  If you
 142 think that you have found a bug, please submit a report in our bug
 143 tracker at
 144
 145   https://savannah.gnu.org/projects/groff
 146
 147 ##### Emacs settings
 148 Local Variables:
 149 mode: text
 150 End: