path: root/INSTALL.extra

    Copyright 1997-2022 Free Software Foundation, Inc.

    Copying and distribution of this file, with or without modification,
    are permitted in any medium without royalty provided the copyright
    notice and this notice are preserved.

This file contains information that supplements the generic
installation instructions in file 'INSTALL'.


Building and Installing from within the Source Tree
===================================================

A simple method of building and installing groff is as follows.

  1. 'cd' to the directory containing groff's source code and type
     './configure' to configure groff for your system.  If you are
     using 'csh' on an old version of AT&T Unix System V, you might need
     to type 'sh ./configure' instead to prevent 'csh' from trying to
     execute 'configure' itself.

     While 'configure' runs, it reports properties of the host system
     that determine how the build is to be performed.

  2. Type 'make' to compile groff.  You may wish to add the '-j' option
     to accelerate the build on multicore systems.

  3. Optionally, check the build for sound operation as described under
     "Evaluation" below.

  4. Type 'sudo make install install-doc' to install groff's programs,
     data files, and documentation.  This is the only step for which you
     need 'root' access; 'sudo' obtains this access.

  5. You can remove the groff executables and other generated files from
     the source code directory by typing 'make clean'.  To also remove
     the files that 'configure' created (so you can compile groff for a
     different kind of computer or with different options to
     'configure'), type 'make distclean'.


Building and Installing from outside the Source Tree
====================================================

It is also possible to perform the build and installation procedure
outside the source code directory.  In this case an external build
directory structure is created without changing any parts of the source
tree.  This practice is useful if the source code is read-only or if
several different installations, such as for multiple architectures,
should be constructed.

As an example, we will imagine that groff's source code is in
'/usr/local/src/groff' and that the build should happen within the
directory '/home/my/groff-build'.  These directory names can be anything
valid on the operating system.

  0. Create '/home/my/groff-build' and 'cd' to that directory.

  1. Type '/usr/local/src/groff/configure' to configure groff for your
     system.  If you are using 'csh' on an old version of AT&T System V
     Unix, you might need to type 'sh /usr/local/src/groff/configure'
     instead.

  2. Type 'make' to compile groff.  You may wish to add the '-j' option
     to accelerate the build on multicore systems.

  3. Optionally, check the build for sound operation as described under
     "Evaluation" below.

  4. Type 'sudo make install install-doc' to install groff's programs,
     data files, and documentation.  This is the only step for which you
     need 'root' access; 'sudo' obtains this access.

  5. You can remove the groff executables and other generated files from
     the source code directory by typing 'make clean'.  To also remove
     the files that 'configure' created (so you can compile groff for a
     different kind of computer or with different options to
     'configure'), type 'make distclean'.


Unprivileged Installation
=========================

The use of 'sudo' is only necessary if one or more destination
directories used by the 'make install' command are in locations that
require administrative access for writing.  You can 'configure' groff
with options like '--prefix' that select an alternative directory that
is writable by the user conducting the build.  Type './configure --help'
from the groff source tree for documentation of relevant options.
Running groff commands from such a directory may require you to set the
'GROFF_BIN_PATH', 'GROFF_FONT_PATH', and 'GROFF_TMAC_PATH' environment
variables.  See the groff(1) man page.  See "Evaluation" below for
instructions on viewing this man page without having groff installed.


Non-POSIX Platforms
===================

For instructions how to build groff with DJGPP tools for MS-DOS and
MS-Windows, see the file arch/djgpp/README.

For instructions how to build groff with the MinGW tools for
MS-Windows, see the file README.MinGW.


Dependencies
============

groff is predominantly written in ISO C++98, so you need a C++ compiler
capable of handling this standardized version of the language.  The C++
source files use a suffix of '.cpp'; your C++ compiler must be able to
handle this.  A C/C++ preprocessor that conforms to ISO C90 is also
required.  If you don't already have a C++ compiler, we suggest GCC 9.4
or later.  To override the 'configure' script's choice of C++ compiler,
you can set the CXX environment variable to the name of its executable.

A few components of groff are written in ISO C99.  Features later made
optional by ISO C11 (the 'complex' primitive data type and
variable-length arrays) are not used.

Several programs distributed with GNU roff are written in the Perl
language.  Version 5.6.1 (1 April 2001) or later is required.

The 'uchardet' library is an optional dependency of the 'preconv'
program: if this library is found by 'configure', it will be
automatically used by 'preconv'.  Discovery of the 'uchardet' library
requires the 'pkg-config' program to be installed on your system, as
well as the library's C header files--on a package-based host system,
this can mean installing uchardet's '-dev' or '-devel' package.

URW fonts
---------

The 'configure' script searches for PostScript Type 1 fonts originating
with the URW foundry; these are metrically compatible replacements for
the Adobe PostScript Level 2 base 35 fonts required by that standard.
These URW fonts are packaged with Ghostscript and in various derivative
versions.  The Adobe fonts are not free software, but the replacements,
often named "Nimbus Roman", "Nimbus Sans", and "Nimbus Mono", and so
forth, are.  The PostScript and early PDF standards assumed that these
base fonts would be supplied by the rendering device (a printer or PDF
viewer).  Nowadays the PDF standard expects all fonts to be embedded in
the document; if groff's gropdf(1) output driver knows where to find
these fonts, you can use its "-e" option for this purpose.

The build process populates "Foundry" and "download" files that tell
gropdf where to find their groff font descriptions and the font files
themselves, respectively.  If you have multiple versions of the URW
fonts available on your system, or the 'configure' script cannot locate
them on its own, use its "--with-urw-fonts-dir" option to tell the
script where to find them.  If you never use groff to generate
PostScript or PDF documents, you can ignore any output from the
'configure' script about URW fonts.


Miscellaneous
=============

If you want A4 or U.S. letter paper format and the 'configure' script
produces an incorrect guess, say

  PAGE=xxx ./configure

where 'xxx' should be either 'A4' or 'letter'.  This affects only the
media size used by some groff output drivers, like grops (which can
still be overridden on the command line).  For compatibility with AT&T
troff, GNU troff's default page length is always 11 inches.  The page
length can be changed with the 'pl' request or with the "papersize"
macro package; see section "Paper format" in groff(1).


Evaluation
==========

Once groff is built, you can check it for correct operation without
having to install it.  groff comes with a test suite; use 'make check'
to run it.

You can also try it out from the directory you used to build it.  A
script called 'test-groff' is supplied for this purpose.  It sets up
environment variables to allow groff to run without being installed.
For example, from the directory where you built groff, the command

  ./test-groff -t -man -Tascii src/roff/groff/groff.1 | less -R

displays the groff(1) man page with the 'less' pager.  (You might prefer
either the '-Tlatin1' or '-Tutf8' option to '-Tascii' depending on the
character set you're using.)


Documentation
=============

The groff Texinfo manual can be viewed in several formats.  Versions
corresponding to the source document 'doc/groff.texi' are supplied with
the source distribution archive.  You can browse it in GNU info format.

  info doc/groff.info

It can be viewed as text encoded in ISO Latin-1 as well.

  iconv -f latin1 -t utf8 doc/groff.txt | less # for UTF-8 users
  less doc/groff.txt # for Latin-1 users

Renderings in HTML, TeX DVI, and PDF are also available.

  lynx doc/groff.html
  xdvi doc/groff.dvi
  evince doc/groff.pdf

A compilation of groff's man pages is available in text (with ISO 6429
escape sequences) and PDF.

  less -R doc/groff-man-pages.utf8.txt
  evince doc/groff-man-pages.pdf


In Case of Trouble
==================

If a test fails, gather its log file from the build directory.  For
instance, the test "tmac/tests/localization-works.sh" (in the source
directory) will have a log file called
"tmac/tests/localization-works.sh.log" in the build directory.

To re-run a test, change to the top of the build directory (if
necessary) and run the test by name from the shell prompt.

For example, to rerun the test mentioned above from a "build" directory
I created as a subdirectory in the source tree, I would do this.

  (cd build && ../tmac/tests/localization-works.sh)

I can view the test log as follows.

  cat build/tmac/tests/localization-works.sh.log

Many known issues are documented in the 'PROBLEMS' file; some apply to
historical systems.  You can also browse groff bug reports via the GNU
Savannah issue tracker to see if your issue has already been reported.

  https://savannah.gnu.org/bugs/?group=groff

If that doesn't help and you need support, please contact the groff
mailing list at groff@gnu.org.  If you think that you have found a bug,
please submit a ticket using the 'BUG-REPORT' file as a template.

  https://savannah.gnu.org/bugs/?group=groff&func=additem


Uninstalling
============

If you are dissatisfied with groff, or to prepare for a new installation
from source, you can uninstall it to ensure that no stale files persist
on the system.  Run the command 'sudo make uninstall'.  (If you
successfully used 'make install', simply run 'make uninstall'.)  At a
minimum, some directories not particular to groff, like 'bin' and
(depending on configuration) an X11 'app-defaults' directory will
remain, as will one plain file called 'dir', created by GNU Texinfo's
'install-info' command.  (As of this writing, 'install-info' offers no
provision for removing an effectively empty 'dir' file, and groff does
not attempt to parse this file to determine whether it can be safely
removed.)  All other groff artifacts will be deleted from the
installation hierarchy.


##### Editor settings
Local Variables:
fill-column: 72
mode: text
End:
vim: set autoindent textwidth=72: