/contrib/groff/README.MinGW

  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.