/contrib/groff/README.MinGW

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 277 lines · 211 code · 66 blank · 0 comment · 0 complexity · 8acf04633947a7cffbf83f20d0207688 MD5 · raw file

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