diff options
Diffstat (limited to 'README.MinGW')
| -rw-r--r-- | README.MinGW | 326 |
1 files changed, 326 insertions, 0 deletions
diff --git a/README.MinGW b/README.MinGW new file mode 100644 index 0000000..412597a --- /dev/null +++ b/README.MinGW @@ -0,0 +1,326 @@ + 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: |