mirror of
https://https.git.savannah.gnu.org/git/groff.git
synced 2026-01-26 15:39:07 +00:00
621c75426e
[grohtml]: Migrate from psselect(1) to ps2ps(1). * src/preproc/html/pre-html.cpp (imageList::createPage): Do it. * src/devices/grohtml/grohtml.1.man (Dependencies): Document the changed runtime requirement. * m4/groff.m4 (GROFF_CHECK_GROHTML_PROGRAMS): * src/roff/groff/tests/html_works_with_grn_and_eqn.sh: * src/roff/groff/tests/smoke-test_html_device.sh: Check for existence of `ps2ps` command instead of `psselect`. * ANNOUNCE: * NEWS: * README: * README.MinGW: Document change in dependencies. Fixes <https://savannah.gnu.org/bugs/?65987>.
323 lines
14 KiB
Plaintext
323 lines
14 KiB
Plaintext
Copyright (C) 2003-2020 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.
|
|
|
|
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
|
|
(and XHTML) output capability, some additional tools are required as
|
|
described in the section PREREQUISITES FOR HTML OUTPUT later in this
|
|
file.
|
|
|
|
|
|
BUILDING GROFF WITH MINGW
|
|
-------------------------
|
|
|
|
*** WARNING ***
|
|
|
|
Before commencing this procedure, you should ensure that you are
|
|
running the MSYS shell in a *native* Win32 console window, and not in
|
|
any window managed by the rxvt emulator provided with MSYS; (this
|
|
emulator suffers from various known defects, which will prevent
|
|
successful completion of a groff build).
|
|
|
|
******
|
|
|
|
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 (and
|
|
XHTML) 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 or XHTML 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 or XHTML 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
|
|
pamcut.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
|
|
|
|
Note that it is not necessary to install the above four packages in
|
|
their entirety; of course, you may do so if you wish.
|
|
|
|
Further note that you are advised to avoid the netpbm-10.27 release
|
|
from the GnuWin32 download repository, as its pnmtopng.exe has been
|
|
reported to fail on even simple conversions, resulting in failure of
|
|
the groff build process; the earlier netpbm-10.18.4 has been found to
|
|
work successfully. Also, you may find it necessary to use
|
|
libpng-1.2.7, rather than libpng-1.2.8, in conjunction with this
|
|
earlier release of netpbm.
|
|
|
|
|
|
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 or -Txhtml 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.
|
|
|
|
|
|
##### Editor settings
|
|
Local Variables:
|
|
fill-column: 72
|
|
mode: text
|
|
End:
|
|
vim: set textwidth=72:
|