1 Copyright (C) 2003, 2004, 2007, 2008
2 Free Software Foundation, Inc.
4 Copying and distribution of this file, with or without modification,
5 are permitted in any medium without royalty provided the copyright
6 notice and this notice are preserved.
11 Contributed by Keith Marshall (keith.d.marshall@ntlworld.com)
17 This file provides recommendations for building a Win32 implementation of
18 GNU Groff, using the MinGW port of GCC for Microsoft (TM) Windows-32
19 platforms. It is intended to supplement the standard installation
20 instructions (see file INSTALL); it does not replace them.
22 You require both the MinGW implementation of GCC and its supporting MSYS
23 toolkit, which provides a Win-32 implementation of the GNU bash shell, and a
24 few other essential utilities; these may be obtained from
26 http://sourceforge.net/projects/mingw
28 by following the appropriate download links, where they are available as
29 self-extracting executable installation packages. If installing both from
30 scratch, it is recommended that MinGW is installed first, as the MSYS
31 installer can then automatically set up the proper environment for running
34 Additionally, if you wish to compile groff with support for its HTML (and
35 XHTML) output capability, some additional tools are required as decribed in
36 the section PREREQUISITES FOR HTML OUTPUT later in this file.
39 BUILDING GROFF WITH MINGW
40 -------------------------
44 Before commencing this procedure, you should ensure that you are running the
45 MSYS shell in a *native* Win32 console window, and not in any window managed
46 by the rxvt emulator provided with MSYS; (this emulator suffers from various
47 known defects, which will prevent successful completion of a groff build).
51 Assuming that you have obtained the appropriate groff distribution, and that
52 you are already running an MSYS shell, then the configuration, compilation,
53 and installation of groff, using MinGW, is performed in much the same way as
54 it is described in the INSTALL file, which is provided with the groff
55 distribution. The installation steps are summarised below:
57 1. Change working directory to any suitable location where you may unpack
58 the groff distribution; you must be authorized for write access.
59 Approximately 30MB of free disk space are needed.
61 2. Unpack the groff distribution:
63 tar xzf <download-path>/groff-<version>.tar.gz
65 This creates a new sub-directory, groff-<version>, containing an image of
66 the groff source tree. You should now change directory, to make this
67 ./groff-<version> your working directory.
69 3. If you are intending to build groff with support for HTML (and XHTML)
70 output, then you must now ensure that the prerequisites described in the
71 later section PREREQUISITES FOR HTML OUTPUT are satisfied, before
72 proceeding to build groff; in particular, please ensure that all required
73 support programs are installed in the current PATH.
75 4. You are now ready to configure, build, and install groff. This is
76 accomplished using the conventional procedure, as described in the file
79 ./configure --prefix=<win32-install-path> ...
83 Please observe the syntax for the configure command, indicated above; the
84 default value for --prefix is not suitable for use with MinGW, so the
85 --prefix=<win32-install-path> option must be specified, where
86 <win32-install-path> is the chosen MS-Windows directory in which the
87 groff application files are to be installed (see the later section
88 entitled CHOOSING AN INSTALLATION PATH). Any other desired configuration
89 options may also be specified, as described in the standard groff
90 installation instructions.
92 5. After completing the above, groff should be successfully installed; the
93 build directory is no longer required; it may be simply deleted in its
94 entirety. Alternatively, you may choose to keep it, but to remove all
95 files which can be reproduced later, by repeating the configure, make and
96 make install steps; this is readily accomplished by the command
101 This completes the installation of groff; please read the final sections of
102 this file, GROFF RUNTIME ENVIRONMENT and CAVEATS AND BUGS, for advice on
103 setting up the runtime environment, and avoiding known runtime problems,
104 before running groff.
107 CHOOSING AN INSTALLATION PATH
108 -----------------------------
110 It may be noted that the above instructions indicate that the ./configure
111 command must be invoked with an argument specifying a preference for
112 --prefix=<win32-install-path>, whereas the standard groff installation
113 instructions indicate that this may be omitted, in which case it defaults to
116 In the case of building with MinGW, the default behaviour of configure is
117 not appropriate for the following reasons.
119 o The MSYS environment creates a virtual UNIX-like file system, with its
120 root mapped to the actual MS-Windows directory where MSYS itself is
121 installed; /usr is also mapped to this MSYS installation directory.
123 o All of the MSYS tools, and the MinGW implementation of GCC, refer to files
124 via this virtual file system representation; thus, if the
125 --prefix=<win32-install-path> is not specified when groff is configured,
126 `make install' causes groff to be installed in <MSYS-install-path>/local.
128 o groff needs to know its own installation path, so that it can locate its
129 own installed components. This information is compiled in, using the
130 exact form specified with the --prefix=<win32-install-path> option to
133 o Knowledge of the MSYS virtual file system is not imparted to groff; it
134 expects the compiled-in path to its components to be a fully qualified
135 MS-Windows path name (although UNIX-style slashes are permitted, and
136 preferred to the MS-Windows style backslashes, to demarcate the directory
137 hierarchy). Thus, when configuring groff, if
138 --prefix=<win32-install-path> is not correctly specified, then the
139 installed groff application looks for its components in /usr/local, and
140 most likely doesn't find them, because they are actually installed in
141 <MSYS-install-path>/local.
143 It is actually convenient, but by no means a requirement, to have groff
144 installed in the /usr/local directory of the MSYS virtual file system; this
145 makes it easy to invoke groff from the MSYS shell, since the virtual
146 /usr/local/bin is normally added automatically to the PATH (the default
147 PATH, as set in MSYS's /etc/profile), when MSYS is started.
149 In order to install groff into MSYS's /usr/local directory, it is necessary
150 to specify the fully qualified absolute MS-Windows path to this directory,
151 when configuring groff, i.e.
153 ./configure --prefix=<MSYS-install-path>/local ...
155 For example, on a system where MSYS is installed in the MS-Windows directory
156 D:\MSYS\1.0, the MSYS virtual path /usr/local resolves to the absolute
157 MS-Windows native path D:\MSYS\1.0\local (the /usr component of the MSYS
158 virtual path does not appear in the resolved absolute native path name since
159 MSYS maps this directly to the root of the MSYS virtual file system). Thus,
160 the --prefix option should be specified to configure as
162 ./configure --prefix=D:/MSYS/1.0/local ...
164 Note that the backslash characters, which appear in the native MS-Windows
165 form of the path name, are replaced by UNIX-style slashes in the argument to
166 configure; this is the preferred syntax.
168 Also note that the MS-Windows device designator (D: in this instance) is
169 prepended to the specified path, in the normal MS-Windows format, and that,
170 since upper and lower case distinctions are ignored in MS-Windows path
171 names, any combination of upper and lower case is acceptable.
174 PREREQUISITES FOR HTML OUTPUT
175 -----------------------------
177 If you intend to use groff for production of HTML or XHTML output, then
178 there are a few dependencies which must be satisfied. Ideally, these should
179 be resolved before attempting to configure and build groff, since the
180 configuration script does check them.
182 In order to produce HTML or XHTML output, you first require a working
183 implementation of Ghostscript; either the AFPL Ghostscript or the GNU
184 Ghostscript implementation for MS-Windows should be suitable, depending on
185 your licensing preference. It is highly recommended to use version 8.11
186 or higher due to bugs in older versions. These may be obtained, in the
187 form of self-installing binary packages, by following the download links
188 for the chosen licensing option, from
189 http://sourceforge.net/projects/ghostscript.
191 Please note that these packages install the Ghostscript interpreter required
192 by groff in the ./bin subdirectory of the Ghostscript installation
193 directory, with the name gswin32c.exe. However, groff expects this
194 interpreter to be located in the system PATH, with the name gs.exe. Thus,
195 to ensure that groff can correctly locate the Ghostscript interpreter, it is
196 recommended that the file gswin32c.exe should be copied from the Ghostscript
197 installation directory to the MSYS /usr/local/bin directory, where it should
198 be renamed to gs.exe.
200 In addition to a working Ghostscript interpreter, you also require several
201 image manipulation utilities, all of which may be scavenged from various
202 packages available from http://sourceforge.net/projects/gnuwin32, and which
203 should be installed in the MSYS /usr/local/bin directory, or any other
204 suitable directory which is specified in the PATH. These additional
207 1. from the netpbm-<version>-bin.zip package:
215 2. from the libpng-<version>-bin.zip package:
219 3. from the zlib-<version>-bin.zip package:
221 zlib-1.dll, which must be renamed to zlib.dll
223 4. from the psutils-<version>-bin.zip package:
227 Note that it is not necessary to install the above four packages in their
228 entirety; of course, you may do so if you wish.
230 Further note that you are advised to avoid the netpbm-10.27 release from the
231 GnuWin32 download repository, as its pnmtopng.exe has been reported to fail
232 on even simple conversions, resulting in failure of the groff build process;
233 the earlier netpbm-10.18.4 has been found to work successfully. Also, you
234 may find it necessary to use libpng-1.2.7, rather than libpng-1.2.8, in
235 conjunction with this earlier release of netpbm.
238 GROFF RUNTIME ENVIRONMENT
239 -------------------------
241 The runtime environment, provided to groff by MSYS, is essentially the same
242 as would be provided under a UNIX or GNU/Linux operating system; thus, any
243 environment variables which may be used to customize the groff runtime
244 environment have similar effects under MSYS, as they would in UNIX or
245 GNU/Linux, with the exception that any variable specifying a path should
246 adopt the same syntax as a native MS-Windows PATH specification.
248 There is, however, one known problem which is associated with the
249 implementation of the MS-Windows file system, and the manner in which the
250 Microsoft runtime library (which is used by the MinGW implementation of GCC)
251 generates names for temporary files. This known problem arises when groff
252 is invoked with a current working directory which refers to a network share,
253 for which the user does not have write access in the root directory, and
254 there is no environment variable set to define a writeable location for
255 creating temporary files. When these conditions arise, groff fails with a
256 `permission denied' error, as soon as it tries to create any temporary file.
258 To specify the location for creating temporary files, the standard UNIX or
259 GNU/Linux implementation of groff provides the GROFF_TMPDIR or TMPDIR
260 environment variables, whereas MS-Windows applications generally use TMP or
261 TEMP; furthermore, the MS-Windows implementations of Ghostscript apparently
262 support the use of only TEMP or TMPDIR.
264 To avoid problems with creation of temporary files, it is recommended that
265 you ensure that both TMP and TEMP are defined, with identical values, to
266 point to a suitable location for creating temporary files; many MS-Windows
267 boxes have them set already, and groff has been adapted to honour them, when
268 built in accordance with the preceding instructions, using MinGW.
274 There are two known issues, observed when running groff in the MinGW/MSYS
275 environment, which would not affect groff in its native UNIX environment:
277 o Running groff with the working directory set to a subdirectory of a
278 network share, where the user does not have write permission in the root
279 directory of the share, causes groff to fail with a `permission denied'
280 exception, if the TMP environment variable is not appropriately defined;
281 it may also be necessary to define the TEMP environment variable, to
282 avoid a similar failure mode, when using the -Thtml or -Txhtml output
283 mode of groff. This problem is more fully discussed in the preceding
284 section, GROFF RUNTIME ENVIRONMENT.
286 o When running groff (or nroff) to process standard input, where the
287 standard input stream is obtained directly from the RXVT console provided
288 with MSYS, groff cannot detect the end-of-file condition for the standard
289 input stream, and hangs. This appears to be caused by a fault in the MSYS
290 implementation of RXVT; it may be worked around by either starting MSYS
291 without RXVT (see the comments in the MSYS.BAT startup script); in this
292 case standard input is terminated by typing <Ctrl-Z> followed by <RETURN>,
293 on a new input line. Alternatively, if you prefer to use MSYS with RXVT,
294 you can enter the interactive groff command in the form
298 in which case <Ctrl-D> terminates the standard input stream, in just the
299 same way it does on a UNIX system; the cat executable provided with MSYS
300 does seem to trap the end-of-file condition, and properly signals groff
301 that the input stream has terminated.