278 lines
13 KiB
Plaintext
278 lines
13 KiB
Plaintext
README.MinGW
|
|
============
|
|
|
|
Contributed by Keith Marshall (keith.d.marshall@ntlworld.com)
|
|
|
|
|
|
INTRODUCTION
|
|
------------
|
|
|
|
This file provides recommendations for building a Win32 implementation of
|
|
GNU Groff, using the MinGW port of GCC for Microsoft (TM) Windows-32
|
|
platforms. It is intended to supplement the standard installation
|
|
instructions (see file INSTALL); it does not replace them.
|
|
|
|
You require both the MinGW implementation of GCC and its supporting MSYS
|
|
toolkit, which provides a Win-32 implementation of the GNU bash shell, and a
|
|
few other essential utilities; these may be obtained from
|
|
|
|
http://sourceforge.net/projects/mingw
|
|
|
|
by following the appropriate download links, where they are available as
|
|
self-extracting executable installation packages. If installing both from
|
|
scratch, it is recommended that MinGW is installed first, as the MSYS
|
|
installer can then automatically set up the proper environment for running
|
|
MinGW.
|
|
|
|
Additionally, if you wish to compile groff with support for its HTML output
|
|
capability, some additional tools are required as decribed in the section
|
|
PREREQUISITES FOR HTML OUTPUT later in this file.
|
|
|
|
|
|
BUILDING GROFF WITH MINGW
|
|
-------------------------
|
|
|
|
Assuming that you have obtained the appropriate groff distribution, and that
|
|
you are already running an MSYS shell, then the configuration, compilation,
|
|
and installation of groff, using MinGW, is performed in much the same way as
|
|
it is described in the INSTALL file, which is provided with the groff
|
|
distribution. The installation steps are summarised below:
|
|
|
|
1. Change working directory to any suitable location where you may unpack
|
|
the groff distribution; you must be authorized for write access.
|
|
Approximately 30MB of free disk space are needed.
|
|
|
|
2. Unpack the groff distribution:
|
|
|
|
tar xzf <download-path>/groff-<version>.tar.gz
|
|
|
|
This creates a new sub-directory, groff-<version>, containing an image of
|
|
the groff source tree. You should now change directory, to make this
|
|
./groff-<version> your working directory.
|
|
|
|
3. If you are intending to build groff with support for HTML output, then
|
|
you must now ensure that the prerequisites described in the later section
|
|
PREREQUISITES FOR HTML OUTPUT are satisfied, before proceeding to build
|
|
groff; in particular, please ensure that all required support programs
|
|
are installed in the current PATH.
|
|
|
|
4. You are now ready to configure, build, and install groff. This is
|
|
accomplished using the conventional procedure, as described in the file
|
|
INSTALL, i.e.
|
|
|
|
./configure --prefix=<win32-install-path> ...
|
|
make
|
|
make install
|
|
|
|
Please observe the syntax for the configure command, indicated above; the
|
|
default value for --prefix is not suitable for use with MinGW, so the
|
|
--prefix=<win32-install-path> option must be specified, where
|
|
<win32-install-path> is the chosen MS-Windows directory in which the
|
|
groff application files are to be installed (see the later section
|
|
entitled CHOOSING AN INSTALLATION PATH). Any other desired configuration
|
|
options may also be specified, as described in the standard groff
|
|
installation instructions.
|
|
|
|
5. After completing the above, groff should be successfully installed; the
|
|
build directory is no longer required; it may be simply deleted in its
|
|
entirety. Alternatively, you may choose to keep it, but to remove all
|
|
files which can be reproduced later, by repeating the configure, make and
|
|
make install steps; this is readily accomplished by the command
|
|
|
|
make distclean
|
|
|
|
|
|
This completes the installation of groff; please read the final sections of
|
|
this file, GROFF RUNTIME ENVIRONMENT and CAVEATS AND BUGS, for advice on
|
|
setting up the runtime environment, and avoiding known runtime problems,
|
|
before running groff.
|
|
|
|
|
|
CHOOSING AN INSTALLATION PATH
|
|
-----------------------------
|
|
|
|
It may be noted that the above instructions indicate that the ./configure
|
|
command must be invoked with an argument specifying a preference for
|
|
--prefix=<win32-install-path>, whereas the standard groff installation
|
|
instructions indicate that this may be omitted, in which case it defaults to
|
|
--prefix=/usr/local.
|
|
|
|
In the case of building with MinGW, the default behaviour of configure is
|
|
not appropriate for the following reasons.
|
|
|
|
o The MSYS environment creates a virtual UNIX-like file system, with its
|
|
root mapped to the actual MS-Windows directory where MSYS itself is
|
|
installed; /usr is also mapped to this MSYS installation directory.
|
|
|
|
o All of the MSYS tools, and the MinGW implementation of GCC, refer to files
|
|
via this virtual file system representation; thus, if the
|
|
--prefix=<win32-install-path> is not specified when groff is configured,
|
|
`make install' causes groff to be installed in <MSYS-install-path>/local.
|
|
|
|
o groff needs to know its own installation path, so that it can locate its
|
|
own installed components. This information is compiled in, using the
|
|
exact form specified with the --prefix=<win32-install-path> option to
|
|
configure.
|
|
|
|
o Knowledge of the MSYS virtual file system is not imparted to groff; it
|
|
expects the compiled-in path to its components to be a fully qualified
|
|
MS-Windows path name (although UNIX-style slashes are permitted, and
|
|
preferred to the MS-Windows style backslashes, to demarcate the directory
|
|
hierarchy). Thus, when configuring groff, if
|
|
--prefix=<win32-install-path> is not correctly specified, then the
|
|
installed groff application looks for its components in /usr/local, and
|
|
most likely doesn't find them, because they are actually installed in
|
|
<MSYS-install-path>/local.
|
|
|
|
It is actually convenient, but by no means a requirement, to have groff
|
|
installed in the /usr/local directory of the MSYS virtual file system; this
|
|
makes it easy to invoke groff from the MSYS shell, since the virtual
|
|
/usr/local/bin is normally added automatically to the PATH (the default
|
|
PATH, as set in MSYS's /etc/profile), when MSYS is started.
|
|
|
|
In order to install groff into MSYS's /usr/local directory, it is necessary
|
|
to specify the fully qualified absolute MS-Windows path to this directory,
|
|
when configuring groff, i.e.
|
|
|
|
./configure --prefix=<MSYS-install-path>/local ...
|
|
|
|
For example, on a system where MSYS is installed in the MS-Windows directory
|
|
D:\MSYS\1.0, the MSYS virtual path /usr/local resolves to the absolute
|
|
MS-Windows native path D:\MSYS\1.0\local (the /usr component of the MSYS
|
|
virtual path does not appear in the resolved absolute native path name since
|
|
MSYS maps this directly to the root of the MSYS virtual file system). Thus,
|
|
the --prefix option should be specified to configure as
|
|
|
|
./configure --prefix=D:/MSYS/1.0/local ...
|
|
|
|
Note that the backslash characters, which appear in the native MS-Windows
|
|
form of the path name, are replaced by UNIX-style slashes in the argument to
|
|
configure; this is the preferred syntax.
|
|
|
|
Also note that the MS-Windows device designator (D: in this instance) is
|
|
prepended to the specified path, in the normal MS-Windows format, and that,
|
|
since upper and lower case distinctions are ignored in MS-Windows path
|
|
names, any combination of upper and lower case is acceptable.
|
|
|
|
|
|
PREREQUISITES FOR HTML OUTPUT
|
|
-----------------------------
|
|
|
|
If you intend to use groff for production of HTML output, then there are a
|
|
few dependencies which must be satisfied. Ideally, these should be resolved
|
|
before attempting to configure and build groff, since the configuration
|
|
script does check them.
|
|
|
|
In order to produce HTML output, you first require a working implementation
|
|
of Ghostscript; either the AFPL Ghostscript or the GNU Ghostscript
|
|
implementation for MS-Windows should be suitable, depending on your
|
|
licensing preference. It is highly recommended to use version 8.11 or
|
|
higher due to bugs in older versions. These may be obtained, in the form of
|
|
self-installing binary packages, by following the download links for the
|
|
chosen licensing option, from http://sourceforge.net/projects/ghostscript.
|
|
|
|
Please note that these packages install the Ghostscript interpreter required
|
|
by groff in the ./bin subdirectory of the Ghostscript installation
|
|
directory, with the name gswin32c.exe. However, groff expects this
|
|
interpreter to be located in the system PATH, with the name gs.exe. Thus,
|
|
to ensure that groff can correctly locate the Ghostscript interpreter, it is
|
|
recommended that the file gswin32c.exe should be copied from the Ghostscript
|
|
installation directory to the MSYS /usr/local/bin directory, where it should
|
|
be renamed to gs.exe.
|
|
|
|
In addition to a working Ghostscript interpreter, you also require several
|
|
image manipulation utilities, all of which may be scavenged from various
|
|
packages available from http://sourceforge.net/projects/gnuwin32, and which
|
|
should be installed in the MSYS /usr/local/bin directory, or any other
|
|
suitable directory which is specified in the PATH. These additional
|
|
prerequisites are
|
|
|
|
1. from the netpbm-<version>-bin.zip package:
|
|
|
|
netpbm.dll
|
|
pnmcrop.exe
|
|
pnmcut.exe
|
|
pnmtopng.exe
|
|
pnmtops.exe
|
|
|
|
2. from the libpng-<version>-bin.zip package:
|
|
|
|
libpng.dll
|
|
|
|
3. from the zlib-<version>-bin.zip package:
|
|
|
|
zlib-1.dll, which must be renamed to zlib.dll
|
|
|
|
4. from the psutils-<version>-bin.zip package:
|
|
|
|
psselect.exe
|
|
|
|
Note that it is not necessary to install the above four packages in their
|
|
entirety; of course, you may do so if you wish.
|
|
|
|
|
|
GROFF RUNTIME ENVIRONMENT
|
|
-------------------------
|
|
|
|
The runtime environment, provided to groff by MSYS, is essentially the same
|
|
as would be provided under a UNIX or GNU/Linux operating system; thus, any
|
|
environment variables which may be used to customize the groff runtime
|
|
environment have similar effects under MSYS, as they would in UNIX or
|
|
GNU/Linux, with the exception that any variable specifying a path should
|
|
adopt the same syntax as a native MS-Windows PATH specification.
|
|
|
|
There is, however, one known problem which is associated with the
|
|
implementation of the MS-Windows file system, and the manner in which the
|
|
Microsoft runtime library (which is used by the MinGW implementation of GCC)
|
|
generates names for temporary files. This known problem arises when groff
|
|
is invoked with a current working directory which refers to a network share,
|
|
for which the user does not have write access in the root directory, and
|
|
there is no environment variable set to define a writeable location for
|
|
creating temporary files. When these conditions arise, groff fails with a
|
|
`permission denied' error, as soon as it tries to create any temporary file.
|
|
|
|
To specify the location for creating temporary files, the standard UNIX or
|
|
GNU/Linux implementation of groff provides the GROFF_TMPDIR or TMPDIR
|
|
environment variables, whereas MS-Windows applications generally use TMP or
|
|
TEMP; furthermore, the MS-Windows implementations of Ghostscript apparently
|
|
support the use of only TEMP or TMPDIR.
|
|
|
|
To avoid problems with creation of temporary files, it is recommended that
|
|
you ensure that both TMP and TEMP are defined, with identical values, to
|
|
point to a suitable location for creating temporary files; many MS-Windows
|
|
boxes have them set already, and groff has been adapted to honour them, when
|
|
built in accordance with the preceding instructions, using MinGW.
|
|
|
|
|
|
CAVEATS AND BUGS
|
|
----------------
|
|
|
|
There are two known issues, observed when running groff in the MinGW/MSYS
|
|
environment, which would not affect groff in its native UNIX environment:
|
|
|
|
o Running groff with the working directory set to a subdirectory of a
|
|
network share, where the user does not have write permission in the root
|
|
directory of the share, causes groff to fail with a `permission denied'
|
|
exception, if the TMP environment variable is not appropriately defined;
|
|
it may also be necessary to define the TEMP environment variable, to avoid
|
|
a similar failure mode, when using the -Thtml output mode of groff. This
|
|
problem is more fully discussed in the preceding section, GROFF RUNTIME
|
|
ENVIRONMENT.
|
|
|
|
o When running groff (or nroff) to process standard input, where the
|
|
standard input stream is obtained directly from the RXVT console provided
|
|
with MSYS, groff cannot detect the end-of-file condition for the standard
|
|
input stream, and hangs. This appears to be caused by a fault in the MSYS
|
|
implementation of RXVT; it may be worked around by either starting MSYS
|
|
without RXVT (see the comments in the MSYS.BAT startup script); in this
|
|
case standard input is terminated by typing <Ctrl-Z> followed by <RETURN>,
|
|
on a new input line. Alternatively, if you prefer to use MSYS with RXVT,
|
|
you can enter the interactive groff command in the form
|
|
|
|
cat | groff ...
|
|
|
|
in which case <Ctrl-D> terminates the standard input stream, in just the
|
|
same way it does on a UNIX system; the cat executable provided with MSYS
|
|
does seem to trap the end-of-file condition, and properly signals groff
|
|
that the input stream has terminated.
|