path: root/README.MinGW

    Copyright (C) 2003-2020 Free Software Foundation, Inc.

    Copying and distribution of this file, with or without modification,
    are permitted in any medium without royalty provided the copyright
    notice and this notice are preserved.

  README.MinGW
  ============

  Contributed by Keith Marshall (keith.d.marshall@ntlworld.com)


  INTRODUCTION
  ------------

  This file provides recommendations for building a Win32 implementation
  of GNU Groff, using the MinGW port of GCC for Microsoft (TM)
  Windows-32 platforms.  It is intended to supplement the standard
  installation instructions (see file INSTALL); it does not replace
  them.

  You require both the MinGW implementation of GCC and its supporting
  MSYS toolkit, which provides a Win-32 implementation of the GNU bash
  shell, and a few other essential utilities; these may be obtained from

    http://sourceforge.net/projects/mingw

  by following the appropriate download links, where they are available
  as self-extracting executable installation packages.  If installing
  both from scratch, it is recommended that MinGW is installed first, as
  the MSYS installer can then automatically set up the proper
  environment for running MinGW.

  Additionally, if you wish to compile groff with support for its HTML
  (and XHTML) output capability, some additional tools are required as
  described in the section PREREQUISITES FOR HTML OUTPUT later in this
  file.


  BUILDING GROFF WITH MINGW
  -------------------------

  *** WARNING ***

  Before commencing this procedure, you should ensure that you are
  running the MSYS shell in a *native* Win32 console window, and not in
  any window managed by the rxvt emulator provided with MSYS; (this
  emulator suffers from various known defects, which will prevent
  successful completion of a groff build).

  ******

  Assuming that you have obtained the appropriate groff distribution,
  and that you are already running an MSYS shell, then the
  configuration, compilation, and installation of groff, using MinGW, is
  performed in much the same way as it is described in the INSTALL file,
  which is provided with the groff distribution.  The installation steps
  are summarised below:

  1. Change working directory to any suitable location where you may
     unpack the groff distribution; you must be authorized for write
     access.  Approximately 30MB of free disk space are needed.

  2. Unpack the groff distribution:

       tar xzf <download-path>/groff-<version>.tar.gz

     This creates a new sub-directory, groff-<version>, containing an
     image of the groff source tree.  You should now change directory,
     to make this ./groff-<version> your working directory.

  3. If you are intending to build groff with support for HTML (and
     XHTML) output, then you must now ensure that the prerequisites
     described in the later section PREREQUISITES FOR HTML OUTPUT are
     satisfied, before proceeding to build groff; in particular, please
     ensure that all required support programs are installed in the
     current PATH.

  4. You are now ready to configure, build, and install groff.  This is
     accomplished using the conventional procedure, as described in the
     file INSTALL, i.e.

       ./configure --prefix=<win32-install-path> ...
       make
       make install

     Please observe the syntax for the configure command, indicated
     above; the default value for --prefix is not suitable for use with
     MinGW, so the --prefix=<win32-install-path> option must be
     specified, where <win32-install-path> is the chosen MS-Windows
     directory in which the groff application files are to be installed
     (see the later section entitled CHOOSING AN INSTALLATION PATH).
     Any other desired configuration options may also be specified, as
     described in the standard groff installation instructions.

  5. After completing the above, groff should be successfully installed;
     the build directory is no longer required; it may be simply deleted
     in its entirety.  Alternatively, you may choose to keep it, but to
     remove all files which can be reproduced later, by repeating the
     configure, make and make install steps; this is readily
     accomplished by the command

       make distclean


  This completes the installation of groff; please read the final
  sections of this file, GROFF RUNTIME ENVIRONMENT and CAVEATS AND BUGS,
  for advice on setting up the runtime environment, and avoiding known
  runtime problems, before running groff.


  CHOOSING AN INSTALLATION PATH
  -----------------------------

  It may be noted that the above instructions indicate that the
  ./configure command must be invoked with an argument specifying a
  preference for --prefix=<win32-install-path>, whereas the standard
  groff installation instructions indicate that this may be omitted, in
  which case it defaults to --prefix=/usr/local.

  In the case of building with MinGW, the default behaviour of configure
  is not appropriate for the following reasons.

  o The MSYS environment creates a virtual Unix-like file system, with
    its root mapped to the actual MS-Windows directory where MSYS itself
    is installed; /usr is also mapped to this MSYS installation
    directory.

  o All of the MSYS tools, and the MinGW implementation of GCC, refer to
    files via this virtual file system representation; thus, if the
    --prefix=<win32-install-path> is not specified when groff is
    configured, `make install' causes groff to be installed in
    <MSYS-install-path>/local.

  o groff needs to know its own installation path, so that it can locate
    its own installed components.  This information is compiled in,
    using the exact form specified with the
    --prefix=<win32-install-path> option to configure.

  o Knowledge of the MSYS virtual file system is not imparted to groff;
    it expects the compiled-in path to its components to be a fully
    qualified MS-Windows path name (although Unix-style slashes are
    permitted, and preferred to the MS-Windows style backslashes, to
    demarcate the directory hierarchy).  Thus, when configuring groff,
    if --prefix=<win32-install-path> is not correctly specified, then
    the installed groff application looks for its components in
    /usr/local, and most likely doesn't find them, because they are
    actually installed in <MSYS-install-path>/local.

  It is actually convenient, but by no means a requirement, to have
  groff installed in the /usr/local directory of the MSYS virtual file
  system; this makes it easy to invoke groff from the MSYS shell, since
  the virtual /usr/local/bin is normally added automatically to the PATH
  (the default PATH, as set in MSYS's /etc/profile), when MSYS is
  started.

  In order to install groff into MSYS's /usr/local directory, it is
  necessary to specify the fully qualified absolute MS-Windows path to
  this directory, when configuring groff, i.e.

    ./configure --prefix=<MSYS-install-path>/local ...

  For example, on a system where MSYS is installed in the MS-Windows
  directory D:\MSYS\1.0, the MSYS virtual path /usr/local resolves to
  the absolute MS-Windows native path D:\MSYS\1.0\local (the /usr
  component of the MSYS virtual path does not appear in the resolved
  absolute native path name since MSYS maps this directly to the root of
  the MSYS virtual file system).  Thus, the --prefix option should be
  specified to configure as

    ./configure --prefix=D:/MSYS/1.0/local ...

  Note that the backslash characters, which appear in the native
  MS-Windows form of the path name, are replaced by Unix-style slashes
  in the argument to configure; this is the preferred syntax.

  Also note that the MS-Windows device designator (D: in this instance)
  is prepended to the specified path, in the normal MS-Windows format,
  and that, since upper and lower case distinctions are ignored in
  MS-Windows path names, any combination of upper and lower case is
  acceptable.


  PREREQUISITES FOR HTML OUTPUT
  -----------------------------

  If you intend to use groff for production of HTML or XHTML output,
  then there are a few dependencies which must be satisfied.  Ideally,
  these should be resolved before attempting to configure and build
  groff, since the configuration script does check them.

  In order to produce HTML or XHTML output, you first require a working
  implementation of Ghostscript; either the AFPL Ghostscript or the GNU
  Ghostscript implementation for MS-Windows should be suitable,
  depending on your licensing preference.  It is highly recommended to
  use version 8.11 or higher due to bugs in older versions.  These may
  be obtained, in the form of self-installing binary packages, by
  following the download links for the chosen licensing option, from
  http://sourceforge.net/projects/ghostscript.

  Please note that these packages install the Ghostscript interpreter
  required by groff in the ./bin subdirectory of the Ghostscript
  installation directory, with the name gswin32c.exe.  However, groff
  expects this interpreter to be located in the system PATH, with the
  name gs.exe.  Thus, to ensure that groff can correctly locate the
  Ghostscript interpreter, it is recommended that the file gswin32c.exe
  should be copied from the Ghostscript installation directory to the
  MSYS /usr/local/bin directory, where it should be renamed to gs.exe.

  In addition to a working Ghostscript interpreter, you also require
  several image manipulation utilities, all of which may be scavenged
  from various packages available from
  http://sourceforge.net/projects/gnuwin32, and which should be
  installed in the MSYS /usr/local/bin directory, or any other suitable
  directory which is specified in the PATH.  These additional
  prerequisites are

    1. from the netpbm-<version>-bin.zip package:

         netpbm.dll
         pnmcrop.exe
         pnmcut.exe
         pnmtopng.exe
         pnmtops.exe

    2. from the libpng-<version>-bin.zip package:

         libpng.dll

    3. from the zlib-<version>-bin.zip package:

         zlib-1.dll, which must be renamed to zlib.dll

    4. from the psutils-<version>-bin.zip package:

         psselect.exe

  Note that it is not necessary to install the above four packages in
  their entirety; of course, you may do so if you wish.

  Further note that you are advised to avoid the netpbm-10.27 release
  from the GnuWin32 download repository, as its pnmtopng.exe has been
  reported to fail on even simple conversions, resulting in failure of
  the groff build process; the earlier netpbm-10.18.4 has been found to
  work successfully.  Also, you may find it necessary to use
  libpng-1.2.7, rather than libpng-1.2.8, in conjunction with this
  earlier release of netpbm.


  GROFF RUNTIME ENVIRONMENT
  -------------------------

  The runtime environment, provided to groff by MSYS, is essentially the
  same as would be provided under a Unix or GNU/Linux operating system;
  thus, any environment variables which may be used to customize the
  groff runtime environment have similar effects under MSYS, as they
  would in Unix or GNU/Linux, with the exception that any variable
  specifying a path should adopt the same syntax as a native MS-Windows
  PATH specification.

  There is, however, one known problem which is associated with the
  implementation of the MS-Windows file system, and the manner in which
  the Microsoft runtime library (which is used by the MinGW
  implementation of GCC) generates names for temporary files.  This
  known problem arises when groff is invoked with a current working
  directory which refers to a network share, for which the user does not
  have write access in the root directory, and there is no environment
  variable set to define a writeable location for creating temporary
  files.  When these conditions arise, groff fails with a `permission
  denied' error, as soon as it tries to create any temporary file.

  To specify the location for creating temporary files, the standard
  Unix or GNU/Linux implementation of groff provides the GROFF_TMPDIR or
  TMPDIR environment variables, whereas MS-Windows applications
  generally use TMP or TEMP; furthermore, the MS-Windows implementations
  of Ghostscript apparently support the use of only TEMP or TMPDIR.

  To avoid problems with creation of temporary files, it is recommended
  that you ensure that both TMP and TEMP are defined, with identical
  values, to point to a suitable location for creating temporary files;
  many MS-Windows boxes have them set already, and groff has been
  adapted to honour them, when built in accordance with the preceding
  instructions, using MinGW.


  CAVEATS AND BUGS
  ----------------

  There are two known issues, observed when running groff in the
  MinGW/MSYS environment, which would not affect groff in its native
  Unix environment:

  o Running groff with the working directory set to a subdirectory of a
    network share, where the user does not have write permission in the
    root directory of the share, causes groff to fail with a `permission
    denied' exception, if the TMP environment variable is not
    appropriately defined; it may also be necessary to define the TEMP
    environment variable, to avoid a similar failure mode, when using
    the -Thtml or -Txhtml output mode of groff.  This problem is more
    fully discussed in the preceding section, GROFF RUNTIME ENVIRONMENT.

  o When running groff (or nroff) to process standard input, where the
    standard input stream is obtained directly from the RXVT console
    provided with MSYS, groff cannot detect the end-of-file condition
    for the standard input stream, and hangs.  This appears to be caused
    by a fault in the MSYS implementation of RXVT; it may be worked
    around by either starting MSYS without RXVT (see the comments in the
    MSYS.BAT startup script); in this case standard input is terminated
    by typing <Ctrl-Z> followed by <RETURN>, on a new input line.
    Alternatively, if you prefer to use MSYS with RXVT, you can enter
    the interactive groff command in the form

      cat | groff ...

    in which case <Ctrl-D> terminates the standard input stream, in just
    the same way it does on a Unix system; the cat executable provided
    with MSYS does seem to trap the end-of-file condition, and properly
    signals groff that the input stream has terminated.


##### Editor settings
Local Variables:
fill-column: 72
mode: text
End:
vim: set textwidth=72: