1151497Sru README.MinGW 2151497Sru ============ 3151497Sru 4151497Sru Contributed by Keith Marshall (keith.d.marshall@ntlworld.com) 5151497Sru 6151497Sru 7151497Sru INTRODUCTION 8151497Sru ------------ 9151497Sru 10151497Sru This file provides recommendations for building a Win32 implementation of 11151497Sru GNU Groff, using the MinGW port of GCC for Microsoft (TM) Windows-32 12151497Sru platforms. It is intended to supplement the standard installation 13151497Sru instructions (see file INSTALL); it does not replace them. 14151497Sru 15151497Sru You require both the MinGW implementation of GCC and its supporting MSYS 16151497Sru toolkit, which provides a Win-32 implementation of the GNU bash shell, and a 17151497Sru few other essential utilities; these may be obtained from 18151497Sru 19151497Sru http://sourceforge.net/projects/mingw 20151497Sru 21151497Sru by following the appropriate download links, where they are available as 22151497Sru self-extracting executable installation packages. If installing both from 23151497Sru scratch, it is recommended that MinGW is installed first, as the MSYS 24151497Sru installer can then automatically set up the proper environment for running 25151497Sru MinGW. 26151497Sru 27151497Sru Additionally, if you wish to compile groff with support for its HTML output 28151497Sru capability, some additional tools are required as decribed in the section 29151497Sru PREREQUISITES FOR HTML OUTPUT later in this file. 30151497Sru 31151497Sru 32151497Sru BUILDING GROFF WITH MINGW 33151497Sru ------------------------- 34151497Sru 35151497Sru Assuming that you have obtained the appropriate groff distribution, and that 36151497Sru you are already running an MSYS shell, then the configuration, compilation, 37151497Sru and installation of groff, using MinGW, is performed in much the same way as 38151497Sru it is described in the INSTALL file, which is provided with the groff 39151497Sru distribution. The installation steps are summarised below: 40151497Sru 41151497Sru 1. Change working directory to any suitable location where you may unpack 42151497Sru the groff distribution; you must be authorized for write access. 43151497Sru Approximately 30MB of free disk space are needed. 44151497Sru 45151497Sru 2. Unpack the groff distribution: 46151497Sru 47151497Sru tar xzf <download-path>/groff-<version>.tar.gz 48151497Sru 49151497Sru This creates a new sub-directory, groff-<version>, containing an image of 50151497Sru the groff source tree. You should now change directory, to make this 51151497Sru ./groff-<version> your working directory. 52151497Sru 53151497Sru 3. If you are intending to build groff with support for HTML output, then 54151497Sru you must now ensure that the prerequisites described in the later section 55151497Sru PREREQUISITES FOR HTML OUTPUT are satisfied, before proceeding to build 56151497Sru groff; in particular, please ensure that all required support programs 57151497Sru are installed in the current PATH. 58151497Sru 59151497Sru 4. You are now ready to configure, build, and install groff. This is 60151497Sru accomplished using the conventional procedure, as described in the file 61151497Sru INSTALL, i.e. 62151497Sru 63151497Sru ./configure --prefix=<win32-install-path> ... 64151497Sru make 65151497Sru make install 66151497Sru 67151497Sru Please observe the syntax for the configure command, indicated above; the 68151497Sru default value for --prefix is not suitable for use with MinGW, so the 69151497Sru --prefix=<win32-install-path> option must be specified, where 70151497Sru <win32-install-path> is the chosen MS-Windows directory in which the 71151497Sru groff application files are to be installed (see the later section 72151497Sru entitled CHOOSING AN INSTALLATION PATH). Any other desired configuration 73151497Sru options may also be specified, as described in the standard groff 74151497Sru installation instructions. 75151497Sru 76151497Sru 5. After completing the above, groff should be successfully installed; the 77151497Sru build directory is no longer required; it may be simply deleted in its 78151497Sru entirety. Alternatively, you may choose to keep it, but to remove all 79151497Sru files which can be reproduced later, by repeating the configure, make and 80151497Sru make install steps; this is readily accomplished by the command 81151497Sru 82151497Sru make distclean 83151497Sru 84151497Sru 85151497Sru This completes the installation of groff; please read the final sections of 86151497Sru this file, GROFF RUNTIME ENVIRONMENT and CAVEATS AND BUGS, for advice on 87151497Sru setting up the runtime environment, and avoiding known runtime problems, 88151497Sru before running groff. 89151497Sru 90151497Sru 91151497Sru CHOOSING AN INSTALLATION PATH 92151497Sru ----------------------------- 93151497Sru 94151497Sru It may be noted that the above instructions indicate that the ./configure 95151497Sru command must be invoked with an argument specifying a preference for 96151497Sru --prefix=<win32-install-path>, whereas the standard groff installation 97151497Sru instructions indicate that this may be omitted, in which case it defaults to 98151497Sru --prefix=/usr/local. 99151497Sru 100151497Sru In the case of building with MinGW, the default behaviour of configure is 101151497Sru not appropriate for the following reasons. 102151497Sru 103151497Sru o The MSYS environment creates a virtual UNIX-like file system, with its 104151497Sru root mapped to the actual MS-Windows directory where MSYS itself is 105151497Sru installed; /usr is also mapped to this MSYS installation directory. 106151497Sru 107151497Sru o All of the MSYS tools, and the MinGW implementation of GCC, refer to files 108151497Sru via this virtual file system representation; thus, if the 109151497Sru --prefix=<win32-install-path> is not specified when groff is configured, 110151497Sru `make install' causes groff to be installed in <MSYS-install-path>/local. 111151497Sru 112151497Sru o groff needs to know its own installation path, so that it can locate its 113151497Sru own installed components. This information is compiled in, using the 114151497Sru exact form specified with the --prefix=<win32-install-path> option to 115151497Sru configure. 116151497Sru 117151497Sru o Knowledge of the MSYS virtual file system is not imparted to groff; it 118151497Sru expects the compiled-in path to its components to be a fully qualified 119151497Sru MS-Windows path name (although UNIX-style slashes are permitted, and 120151497Sru preferred to the MS-Windows style backslashes, to demarcate the directory 121151497Sru hierarchy). Thus, when configuring groff, if 122151497Sru --prefix=<win32-install-path> is not correctly specified, then the 123151497Sru installed groff application looks for its components in /usr/local, and 124151497Sru most likely doesn't find them, because they are actually installed in 125151497Sru <MSYS-install-path>/local. 126151497Sru 127151497Sru It is actually convenient, but by no means a requirement, to have groff 128151497Sru installed in the /usr/local directory of the MSYS virtual file system; this 129151497Sru makes it easy to invoke groff from the MSYS shell, since the virtual 130151497Sru /usr/local/bin is normally added automatically to the PATH (the default 131151497Sru PATH, as set in MSYS's /etc/profile), when MSYS is started. 132151497Sru 133151497Sru In order to install groff into MSYS's /usr/local directory, it is necessary 134151497Sru to specify the fully qualified absolute MS-Windows path to this directory, 135151497Sru when configuring groff, i.e. 136151497Sru 137151497Sru ./configure --prefix=<MSYS-install-path>/local ... 138151497Sru 139151497Sru For example, on a system where MSYS is installed in the MS-Windows directory 140151497Sru D:\MSYS\1.0, the MSYS virtual path /usr/local resolves to the absolute 141151497Sru MS-Windows native path D:\MSYS\1.0\local (the /usr component of the MSYS 142151497Sru virtual path does not appear in the resolved absolute native path name since 143151497Sru MSYS maps this directly to the root of the MSYS virtual file system). Thus, 144151497Sru the --prefix option should be specified to configure as 145151497Sru 146151497Sru ./configure --prefix=D:/MSYS/1.0/local ... 147151497Sru 148151497Sru Note that the backslash characters, which appear in the native MS-Windows 149151497Sru form of the path name, are replaced by UNIX-style slashes in the argument to 150151497Sru configure; this is the preferred syntax. 151151497Sru 152151497Sru Also note that the MS-Windows device designator (D: in this instance) is 153151497Sru prepended to the specified path, in the normal MS-Windows format, and that, 154151497Sru since upper and lower case distinctions are ignored in MS-Windows path 155151497Sru names, any combination of upper and lower case is acceptable. 156151497Sru 157151497Sru 158151497Sru PREREQUISITES FOR HTML OUTPUT 159151497Sru ----------------------------- 160151497Sru 161151497Sru If you intend to use groff for production of HTML output, then there are a 162151497Sru few dependencies which must be satisfied. Ideally, these should be resolved 163151497Sru before attempting to configure and build groff, since the configuration 164151497Sru script does check them. 165151497Sru 166151497Sru In order to produce HTML output, you first require a working implementation 167151497Sru of Ghostscript; either the AFPL Ghostscript or the GNU Ghostscript 168151497Sru implementation for MS-Windows should be suitable, depending on your 169151497Sru licensing preference. It is highly recommended to use version 8.11 or 170151497Sru higher due to bugs in older versions. These may be obtained, in the form of 171151497Sru self-installing binary packages, by following the download links for the 172151497Sru chosen licensing option, from http://sourceforge.net/projects/ghostscript. 173151497Sru 174151497Sru Please note that these packages install the Ghostscript interpreter required 175151497Sru by groff in the ./bin subdirectory of the Ghostscript installation 176151497Sru directory, with the name gswin32c.exe. However, groff expects this 177151497Sru interpreter to be located in the system PATH, with the name gs.exe. Thus, 178151497Sru to ensure that groff can correctly locate the Ghostscript interpreter, it is 179151497Sru recommended that the file gswin32c.exe should be copied from the Ghostscript 180151497Sru installation directory to the MSYS /usr/local/bin directory, where it should 181151497Sru be renamed to gs.exe. 182151497Sru 183151497Sru In addition to a working Ghostscript interpreter, you also require several 184151497Sru image manipulation utilities, all of which may be scavenged from various 185151497Sru packages available from http://sourceforge.net/projects/gnuwin32, and which 186151497Sru should be installed in the MSYS /usr/local/bin directory, or any other 187151497Sru suitable directory which is specified in the PATH. These additional 188151497Sru prerequisites are 189151497Sru 190151497Sru 1. from the netpbm-<version>-bin.zip package: 191151497Sru 192151497Sru netpbm.dll 193151497Sru pnmcrop.exe 194151497Sru pnmcut.exe 195151497Sru pnmtopng.exe 196151497Sru pnmtops.exe 197151497Sru 198151497Sru 2. from the libpng-<version>-bin.zip package: 199151497Sru 200151497Sru libpng.dll 201151497Sru 202151497Sru 3. from the zlib-<version>-bin.zip package: 203151497Sru 204151497Sru zlib-1.dll, which must be renamed to zlib.dll 205151497Sru 206151497Sru 4. from the psutils-<version>-bin.zip package: 207151497Sru 208151497Sru psselect.exe 209151497Sru 210151497Sru Note that it is not necessary to install the above four packages in their 211151497Sru entirety; of course, you may do so if you wish. 212151497Sru 213151497Sru 214151497Sru GROFF RUNTIME ENVIRONMENT 215151497Sru ------------------------- 216151497Sru 217151497Sru The runtime environment, provided to groff by MSYS, is essentially the same 218151497Sru as would be provided under a UNIX or GNU/Linux operating system; thus, any 219151497Sru environment variables which may be used to customize the groff runtime 220151497Sru environment have similar effects under MSYS, as they would in UNIX or 221151497Sru GNU/Linux, with the exception that any variable specifying a path should 222151497Sru adopt the same syntax as a native MS-Windows PATH specification. 223151497Sru 224151497Sru There is, however, one known problem which is associated with the 225151497Sru implementation of the MS-Windows file system, and the manner in which the 226151497Sru Microsoft runtime library (which is used by the MinGW implementation of GCC) 227151497Sru generates names for temporary files. This known problem arises when groff 228151497Sru is invoked with a current working directory which refers to a network share, 229151497Sru for which the user does not have write access in the root directory, and 230151497Sru there is no environment variable set to define a writeable location for 231151497Sru creating temporary files. When these conditions arise, groff fails with a 232151497Sru `permission denied' error, as soon as it tries to create any temporary file. 233151497Sru 234151497Sru To specify the location for creating temporary files, the standard UNIX or 235151497Sru GNU/Linux implementation of groff provides the GROFF_TMPDIR or TMPDIR 236151497Sru environment variables, whereas MS-Windows applications generally use TMP or 237151497Sru TEMP; furthermore, the MS-Windows implementations of Ghostscript apparently 238151497Sru support the use of only TEMP or TMPDIR. 239151497Sru 240151497Sru To avoid problems with creation of temporary files, it is recommended that 241151497Sru you ensure that both TMP and TEMP are defined, with identical values, to 242151497Sru point to a suitable location for creating temporary files; many MS-Windows 243151497Sru boxes have them set already, and groff has been adapted to honour them, when 244151497Sru built in accordance with the preceding instructions, using MinGW. 245151497Sru 246151497Sru 247151497Sru CAVEATS AND BUGS 248151497Sru ---------------- 249151497Sru 250151497Sru There are two known issues, observed when running groff in the MinGW/MSYS 251151497Sru environment, which would not affect groff in its native UNIX environment: 252151497Sru 253151497Sru o Running groff with the working directory set to a subdirectory of a 254151497Sru network share, where the user does not have write permission in the root 255151497Sru directory of the share, causes groff to fail with a `permission denied' 256151497Sru exception, if the TMP environment variable is not appropriately defined; 257151497Sru it may also be necessary to define the TEMP environment variable, to avoid 258151497Sru a similar failure mode, when using the -Thtml output mode of groff. This 259151497Sru problem is more fully discussed in the preceding section, GROFF RUNTIME 260151497Sru ENVIRONMENT. 261151497Sru 262151497Sru o When running groff (or nroff) to process standard input, where the 263151497Sru standard input stream is obtained directly from the RXVT console provided 264151497Sru with MSYS, groff cannot detect the end-of-file condition for the standard 265151497Sru input stream, and hangs. This appears to be caused by a fault in the MSYS 266151497Sru implementation of RXVT; it may be worked around by either starting MSYS 267151497Sru without RXVT (see the comments in the MSYS.BAT startup script); in this 268151497Sru case standard input is terminated by typing <Ctrl-Z> followed by <RETURN>, 269151497Sru on a new input line. Alternatively, if you prefer to use MSYS with RXVT, 270151497Sru you can enter the interactive groff command in the form 271151497Sru 272151497Sru cat | groff ... 273151497Sru 274151497Sru in which case <Ctrl-D> terminates the standard input stream, in just the 275151497Sru same way it does on a UNIX system; the cat executable provided with MSYS 276151497Sru does seem to trap the end-of-file condition, and properly signals groff 277151497Sru that the input stream has terminated. 278