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.