README.MinGW

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