/contrib/groff/README.MinGW
Unknown | 277 lines | 211 code | 66 blank | 0 comment | 0 complexity | 8acf04633947a7cffbf83f20d0207688 MD5 | raw file
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.