home *** CD-ROM | disk | FTP | other *** search
/ Geek Gadgets 1 / ADE-1.bin / ade-dist / octave-1.1.1p1-src.tgz / tar.out / fsf / octave / kpathsea / INSTALL < prev    next >
Text File  |  1996-09-28  |  11KB  |  244 lines
  1. Installation
  2. ************
  3.  
  4.   Here are the basic steps for configuration and installation:
  5.  
  6.   1. `configure'.  This automatically determines most system
  7.      dependencies.
  8.  
  9.   2. If necessary, edit the definitions in `Makefile' or `c-auto.h'.
  10.      *Note System dependencies::, below, for additional definitions you
  11.      may need to make.
  12.  
  13.   3. `make'.
  14.  
  15.   4. `make install'. This installs the library, header files, and
  16.      documentation.
  17.  
  18.   5. `make distclean'.  This removes all files created by the build.
  19.  
  20.  
  21.   Since I only distribute Kpathsea as part of another package, you will
  22. probably be doing the above in a top-level directory that contains a
  23. `Makefile', `kpathsea', and the other package.  But you can do the
  24. installation in `kpathsea' itself, if you only want to install the
  25. library, not the other package.
  26.  
  27. System dependencies
  28. ===================
  29.  
  30.   Although `configure' can reliably determine most aspects of your
  31. system, there are a few things you must help it out with.
  32.  
  33. Default paths
  34. -------------
  35.  
  36.   The directories into which files are installed are defined in the
  37. top-level `Makefile'. The default paths which programs use to search
  38. for inputs are defined in `kpathsea/paths.h'.  You will almost
  39. certainly want to change either or both of these to match your
  40. preferred local directory structure.  In particular, if you need to
  41. support only one output device, the rather deep structure of the default
  42. paths is unnecessary.
  43.  
  44.   Both of these files are automatically created: the `Makefile' at
  45. `configure' time, `kpathsea/paths.h' at `make' time. Thus, to change
  46. the default paths, the simplest thing to do is edit the template files
  47. `Makefile.in' and `paths.h.in' before running `configure'.
  48.  
  49.   The Make definitions are all repeated in several `Makefile''s; but
  50. changing the top-level `Makefile' should suffice, as it passes down all
  51. the variable definitions, thus overriding the submakes. (The
  52. definitions are repeated so you can potentially run Make in the
  53. subdirectories.)
  54.  
  55.   If you want to include the mode in a particular path, perhaps to
  56. distinguish two different devices with the same resolution, use
  57. `$MAKETEX_MODE', as in `/usr/local/lib/texmf/fonts//pk/$MAKETEX_MODE'.
  58. *Note `MakeTeX'... script arguments: MakeTeX... script arguments.
  59.  
  60.   The file `kpathsea/HIER' has some explanation of the default setup.
  61.  
  62.   A caveat: If you put `$HOME' or `~' in any of the paths, do not
  63. search that component recursively: when you run as root, you might wind
  64. up searching (say) `/zoneinfo/Brazil/tex/macros'. And of course it will
  65. take quite some time to look at every directory on the system.
  66.  
  67.   *Note Filename database::, for a description of an external database
  68. that can help speed searches.
  69.  
  70. `wchar_t'
  71. ---------
  72.  
  73.   The upshot of all the following is that if you get error messages
  74. regarding `wchar_t', try defining `NO_FOIL_X_WCHAR_T'. This is reported
  75. to be necessary on Linux.
  76.  
  77.   `wchar_t' has caused infinite trouble. None of my code ever uses
  78. `wchar_t'; all I want to do is include X header files and various
  79. system header files, compiling with GCC. This seems an impossible task.
  80.  
  81.   The X11R5 `<Xlib.h>' and GCC's `<stddef.h>' have conflicting
  82. definitions for wchar_t.
  83.  
  84.   The particulars: `<X11/Xlib.h>' from MIT X11R5 defines `wchar_t' if
  85. `X_WCHAR' is defined, which is defined if `X_NOT_STDC_ENV' is defined,
  86. and we define *that* if `STDC_HEADERS' is not defined (`configure'
  87. decides if STDC_HEADERS gets defined).  But when compiling with gcc on
  88. SunOS 4.1.x, `STDC_HEADERS' is not defined (`string.h' doesn't declare
  89. the `mem'* functions), so we do get X's `wchar_t'--and we also get
  90. gcc's `wchar_t' from its `<stddef.h>'.  Result: conflicting definitions.
  91.  
  92.   On the other hand, SunOS 4.1.1 with some other X configurations
  93. actually needs GCC to define `wchar_t', and fails otherwise.
  94.  
  95.   My current theory is to define `wchar_t' to a nonsense symbol before
  96. the X include files are read; that way its definition (if any) will be
  97. ignored by other system include files.  Going along with that, define
  98. `X_WCHAR' to tell X not to use `<stddef.h>', that we've already
  99. included, but instead to make its own definition.
  100.  
  101.   But this is not the end of the story. The X11 include files
  102. distributed with DG/UX 5.4.2 for the Aviion have been modified to
  103. include `<_int_wchar_t.h>' if `X_WCHAR', so our `#define' will not have
  104. any typedef to change--but the uses of `wchar_t' in the X include files
  105. will be changed to reference this undefined symbol. So there's nothing
  106. to foil in this case; I don't know how to detect this automatically, so
  107. it's up to you to define `NO_FOIL_X_WCHAR_T' yourself.
  108.  
  109. `putenv'
  110. --------
  111.  
  112.   If you are on a Net2/BSD or other system which has a `putenv' that
  113. knows how to avoid garbage when the same environment variable is set
  114. many times, define `SMART_PUTENV'. (And if you can write a test for
  115. this that could be incorporated into the `configure' script, please
  116. send it to the address given in *Note Bugs::.)
  117.  
  118. The `configure' script
  119. ======================
  120.  
  121.   (This section is largely from the Autoconf manual, by David MacKenzie.
  122. *Note Running `configure' scripts: (autoconf)Running configure Scripts.)
  123.  
  124.   The `configure' script that comes with this distribution was
  125. generated by the Autoconf program.  Thus, you can regenerate
  126. `configure' by rerunning Autoconf.  You might want to do this if a new
  127. version of Autoconf is released, for example.
  128.  
  129.   The purpose of `configure' is to adapt the present source to the
  130. particulars of your system.  For example, the name of the directory
  131. header file (`dirent.h' or `sys/dir.h'), whether the GNU C compiler
  132. `gcc' is available, and so on.
  133.  
  134.   Normally, you do not need to give any options to `configure'; just
  135. `cd' to the directory with the source code and type `configure'.
  136. Exceptions: if `.' is not in your `PATH', you must type `./configure';
  137. if you are using a non-Bourne compatible shell on systems that do not
  138. support `#!', you must type `sh configure'.
  139.  
  140.   Running `configure' takes a minute or two.  While it is running, it
  141. prints some messages that tell what it is doing.  If you don't want to
  142. see the messages, run `configure' with its standard output redirected
  143. to `/dev/null'; e.g., `configure >/dev/null'.  On the other hand, if
  144. you want to see even more messages, give `configure' the `-v' option.
  145.  
  146.   To compile the package in a different directory from the one
  147. containing the source code, you must use a variant of Make that
  148. supports the `VPATH' variable, such as GNU Make.  `cd' to the directory
  149. where you want the object files and executables to go and run
  150. `configure' with the option `--srcdir=DIR', where DIR is the directory
  151. that contains the source code.  Using this option is unnecessary if the
  152. source code is in the parent directory of the one in which you are
  153. compiling; `configure' automatically checks for the source code in `..'
  154. if it does not find it in `.'.
  155.  
  156.   `configure' (in the top-level directory) guesses the default
  157. installation prefix (we'll call it `$(prefix)', which is the
  158. corresponding Make variable) by looking for a directory which contains
  159. an executable named `tex', and using its parent.  In the package
  160. subdirectories, such as `kpathsea', `configure' doesn't try to guess
  161. the prefix (to avoid a conflict with the guess made at the top level);
  162. the default `/usr/local' is left.
  163.  
  164.   You can override this default guess for the installation prefix by
  165. giving `configure' the option `--prefix=PATH'.  You can also specify
  166. separate installation prefixes for architecture-specific files and
  167. architecture-independent files by giving `configure' the option
  168. `--exec-prefix=XPATH' (which substitutes for the Make variable
  169. `$(exec_prefix)').  Then XPATH will be the prefix for installing
  170. programs and libraries.  Data files and documentation will still use
  171. `$(prefix)'.
  172.  
  173.   You can tell `configure' to figure out the configuration for your
  174. system, and record it in a file `config.status', without actually
  175. configuring the package.  To do this, give `configure' the
  176. `--no-create' option.  Later, you can run `./config.status' to actually
  177. configure the package.  This option is useful mainly in `Makefile'
  178. rules for updating `config.status' and the `Makefile' itself.  You can
  179. also give `config.status' the `--recheck' option, which makes it rerun
  180. `configure' with the same arguments you used before.  This is useful if
  181. you change `configure'.
  182.  
  183.   `configure' ignores any other arguments that you give it.
  184.  
  185.   On systems that require unusual options for compilation or linking
  186. that the package's `configure' script does not know about, you can give
  187. `configure' initial values for variables by setting them in the
  188. environment.  In Bourne-compatible shells, you can do that on the
  189. command line like this:
  190.  
  191.      CC='gcc -traditional' LIBS=-lposix sh configure
  192.  
  193.   The Make variables that you might want to override with environment
  194. variables when running `configure' are:
  195.  
  196.   (For these variables, any value given in the environment overrides the
  197. value that `configure' would choose.)
  198.  
  199. `CC'
  200.      The C compiler program.  The default is `gcc' if that is in your
  201.      `PATH', `cc' otherwise.
  202.  
  203. `INSTALL'
  204.      The program to use to install files.  The default is `install' if
  205.      you have it, `cp' otherwise.
  206.  
  207.   (For these variables, any value given in the environment is added to
  208. the value that `configure' chooses.)
  209.  
  210. `DEFS'
  211.      Configuration options, in the form `-Dfoo -Dbar...'.
  212.  
  213. `LIBS'
  214.      Libraries to link with, in the form `-lfoo -lbar...'.
  215.  
  216.   Of course, problems requiring manual intervention (e.g., setting these
  217. variables) should ideally be fixed by updating either the Autoconf
  218. macros or the `configure.in' file for that package.
  219.  
  220. Reporting bugs
  221. ==============
  222.  
  223.   If you encounter problems, report them to `tex-k@cs.umb.edu'.
  224. Include the version number of the library, the system you are using, and
  225. enough information to reproduce the bug in your report.  To get on this
  226. mailing list yourself, email `tex-k-request@cs.umb.edu' with a message
  227. whose body contains a line
  228.      subscribe YOU@YOUR.PREFERRED.ADDRESS
  229.  
  230.   To avoid wasted effort and time (both mine and yours), I strongly
  231. advise applying the principles given in the GNU C manual (*note
  232. Reporting Bugs: (gcc)Bugs.) to your bug reports for any software.
  233.  
  234.   Please also report bugs in this documentation--not only factual
  235. errors, but unclear explanations, typos, wrong fonts, ....
  236.  
  237.   When compiling with old C compilers, you may get some warnings about
  238. "illegal pointer combinations".  These are spurious; ignore them.  I
  239. decline to clutter up the source with casts to get rid of them.  In
  240. general, if you have trouble with a system C compiler, I advise trying
  241. the GNU C compiler. (And vice versa, unfortunately; but in that case I
  242. also recommend reporting a bug to the GCC bug list.)
  243.  
  244.