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