Copyright 1997-2021 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'. Normal Installation =================== The simplest way to compile groff is: 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 System V, you might need to type `sh ./configure' instead to prevent `csh' from trying to execute `configure' itself. Running `configure' takes awhile. While running, it prints some messages telling which features it is checking for. 2. Type `make' to compile groff. 3. Type `sudo make install' to install the groff programs and any data files and documentation. `make install' is the only step for which you need `root' access; this is done by `sudo'. 4. You can remove the groff binaries and object 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), type `make distclean'. External Installation ===================== It is also possible to perform the whole installation process outside of the source code directory. In this case a whole external build directory structure is created without changing any parts of the source code tree. This 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 assume that the source code of the `groff' code is in `/usr/local/src/groff', and that the build process should be done within the directory `/home/my/groff.compile'. 0. Create `/home/my/groff.compile' and change to that directory. 1. Call `/usr/local/src/groff/configure' in that directory to configure groff for your system. If you are using `csh' on an old version of System V, you might need to type `sh /usr/local/src/groff/configure' instead. 2. Type `make' to compile groff in that directory. 3. Type `sudo make install' to install the groff programs and any data files and documentation. 4. You can remove the groff binaries and object files from the build directory by typing `make clean'. To also remove the files that `configure' created (so you can compile the package for a different kind of computer), type `make distclean'. Special 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 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. Several programs distributed with GNU roff are written in the Perl language. Version 5.6.1 or later is required. In order to build the documentation, you need 'makeinfo' from the 'texinfo' package; in fact 'configure' will fail if this program is not found unless you pass the option '--with-doc=no'. 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'. In order to discover the presence of the 'uchardet' library, you will also need to have the 'pkg-config' program installed on your system, and the library's C header files will need to be present on the system--on a package-based host system, this can mean installing uchardet's '-dev' or '-devel' package. Miscellaneous ============= If you want A4 or letter paper format and the configure script produces an incorrect guess, say PAGE=xxx ./configure where `xxx' should be either `A4' or `letter'. Note that this only affects the paper selection of some device drivers like grops (which can be still overridden on the command line). For compatibility with ditroff, the default page length in gtroff is always 11 inches. The page length can be changed with the `pl' request. 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, the command ./test-groff -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.) The groff Texinfo manual can be previewed as an info document. info ./doc/groff.info It can be viewed as text as well (albeit text encoded in ISO Latin-1). iconv -f latin1 -t utf8 doc/groff.txt | less # for UTF-8 users less doc/groff.txt # for Latin-1 users To get a DVI, PDF, or HTML version of the groff texinfo manual, say 'make groff.dvi', 'make groff.pdf', or 'make groff.html', respectively, in the 'doc' subdirectory (after configuring the groff package). Texinfo version 5.0 or later is a prerequisite for generation of these formats. Here are some ways you might view the documents produced. xdvi doc/groff.dvi evince doc/groff.pdf lynx doc/groff.html In Case of Trouble ================== If you have problems, read the PROBLEMS file. If this doesn't help and you need support, please contact the `groff' mailing list. If you think that you have found a bug, please submit a report to our bug tracker. https://savannah.gnu.org/bugs/?group=groff&func=additem ##### Editor settings Local Variables: fill-column: 72 mode: text End: vim: set textwidth=72: