summaryrefslogtreecommitdiff
path: root/Build/source/texk/web2c/INSTALL
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/texk/web2c/INSTALL')
-rw-r--r--Build/source/texk/web2c/INSTALL262
1 files changed, 262 insertions, 0 deletions
diff --git a/Build/source/texk/web2c/INSTALL b/Build/source/texk/web2c/INSTALL
new file mode 100644
index 00000000000..8a26c522b76
--- /dev/null
+++ b/Build/source/texk/web2c/INSTALL
@@ -0,0 +1,262 @@
+Contents:
+
+Installation
+ `configure' options
+ Compile-time options
+ Additional targets
+ Trip, trap, and mptrap: Torture tests
+ Runtime options
+
+
+Installation
+************
+
+ Installing Web2c is mostly the same as installing any other
+Kpathsea-using program. Therefore, for the basic steps involved, *note
+Installation: (kpathsea)Installation.. (A copy is in the file
+`kpathsea/INSTALL'.)
+
+ One peculiarity to Web2c is that the source distribution comes in two
+files: `web.tar.gz' and `web2c.tar.gz'. You must retrieve and unpack
+them both. (We have two because the former archive contains the very
+large and seldom-changing original WEB source files.) *Note
+unixtex.ftp: (kpathsea)unixtex.ftp.
+
+ Another peculiarity is the MetaPost program. Although it has been
+installed previously as `mp', as of Web2c 7.0 the installed name is now
+`mpost', to avoid conflict with the `mp' program that does
+prettyprinting. This approach was recommended by the MetaPost author,
+John Hobby. If you as the TeX administrator wish to make it available
+under its shorter name as well, you will have to set up a link or some
+such yourself. And of course individual users can do the same.
+
+ For solutions to common installation problems and information on how
+to report a bug, see the file `kpathsea/BUGS' (*note Bugs:
+(kpathsea)Bugs.). See also the Web2c home page,
+`http://www.tug.org/web2c'.
+
+ Points worth repeating:
+
+ * Before starting the standard compilation and installation you must
+ install the basic fonts, macros, and other library files. *Note
+ Installation: (kpathsea)Installation.
+
+ * If you do not wish to use the standard file locations, see *Note
+ Changing search paths: (kpathsea)Changing search paths.
+
+ * Some Web2c features are enabled or disabled at `configure' time,
+ as described in the first section below.
+
+`configure' options
+===================
+
+ This section gives pointers to descriptions of the `--with' and
+`--enable' `configure' arguments that Web2c accepts. Some are specific
+to Web2c, others are generic to all Kpathsea-using programs.
+
+ For a list of all the options `configure' accepts, run `configure
+--help'. The generic options are listed first, and the
+package-specific options come last.
+
+ For a description of the generic options (which mainly allow you to
+specify installation directories) and basic `configure' usage, *note
+Running `configure' scripts: (autoconf)Invoking configure. (a copy is
+in the file `kpathsea/CONFIGURE').
+
+`--disable-dump-share'
+ Do not make fmt/base/mem files sharable across different endian
+ architectures. *Note Hardware and memory dumps::.
+
+`--without-maketexmf-default'
+`--without-maketexpk-default'
+`--without-maketextfm-default'
+`--with-maketextex-default'
+ Enable or disable the dynamic generation programs. *Note MakeTeX
+ configuration: (kpathsea)MakeTeX configuration. The defaults are
+ the inverse of the options, i.e., everything is enabled except
+ `MakeTeXTeX'.
+
+`--enable-auto-core'
+ Dump `core' if the input file is
+ `HackyInputFileNameForCoreDump.tex'. *Note Preloaded
+ executables::.
+
+`--enable-shared'
+ Build Kpathsea as a shared library. *Note Shared library:
+ (kpathsea)Shared library.
+
+`--with-editor=CMD'
+ Change the default editor invoked by the `e' interactive command.
+ *Note Editor invocation::.
+
+`--with-hp2627win'
+`--with-mftalkwin'
+`--with-nextwin'
+`--with-regiswin'
+`--with-suntoolswin'
+`--with-tektronixwin'
+`--with-unitermwin'
+`--with-x'
+`--with-x-toolkit=KIT'
+`--with-x11win'
+`--with-x11'
+ Define Metafont graphics support; by default, no graphics support
+ is enabled. *Note Online Metafont graphics::.
+
+`--x-includes=DIR'
+`--x-libraries=DIR'
+ Define the locations of the X11 include files and libraries; by
+ default, `configure' does its best to guess). *Note Optional
+ Features: (autoconf)Optional Features. A copy is in
+ `kpathsea/CONFIGURE'.
+
+Compile-time options
+====================
+
+ In addition to the `configure' options listed in the previous
+section, there are a few things that can be affected at compile-time
+with C definitions, rather than with `configure'. Using any of these
+is unusual.
+
+ To specify extra compiler flags (`-DNAME' in this case), the simplest
+thing to do is:
+ make XCFLAGS="CCOPTIONS"
+ You can also set the `CFLAGS' environment variable before running
+`configure'. *Note configure environment: (kpathsea)configure
+environment.
+
+Anyway, here are the possibilities:
+
+`-DFIXPT'
+`-DNO_MF_ASM'
+ Use the original WEB fixed-point routines for Metafont and MetaPost
+ arithmetic calculations regarding fractions. By default,
+ assembly-language routines are used on x86 hardware with GNU C
+ (unless `NO_MF_ASM' is defined), and floating-point routines are
+ used otherwise.
+
+`-DIPC_DEBUG'
+ Report on various interprocess communication activities. *Note
+ IPC and TeX: IPC and TeX.
+
+Additional targets
+==================
+
+ Web2c has several Make targets besides the standard ones. You can
+invoke these either in the top level directory of the source
+distribution (the one containing `kpathsea/' and `web2c/'), or in the
+`web2c/' directory.
+
+`c-sources'
+ Make only the C files, translated from the Web sources, presumably
+ because you want to take them to a non-Unix machine.
+
+`formats'
+`install-formats'
+ Make or install all the memory dumps (*note Memory dumps::.). By
+ default, the standard plain formats plus `latex.fmt' are made. You
+ can add other formats by redefining the `fmts', `bases', and
+ `mems' variables. See the top of `web2c/Makefile' for the
+ possibilities.
+
+`fmts'
+`install-fmts'
+ Make or install the TeX `.fmt' files. *Note initex invocation::.
+
+`bases'
+`install-bases'
+ Make or install the Metafont `.base' files. *Note inimf
+ invocation::.
+
+`mems'
+`install-mems'
+ Make or install the MetaPost `.mem' files. *Note inimpost
+ invocation::.
+
+`triptrap'
+`trip'
+`trap'
+`mptrap'
+ To run the torture tests for TeX, Metafont, and MetaPost
+ (respectively). See the next section.
+
+Trip, trap, and mptrap: Torture tests
+=====================================
+
+ To validate your TeX, Metafont, and MetaPost executables, run `make
+triptrap'. This runs the trip, trap, and mptrap "torture tests". See
+the files `triptrap/tripman.tex', `triptrap/trapman.tex', and
+`triptrap/mptrap.readme' for detailed information and background on the
+tests.
+
+ The differences between your executables' behavior and the standard
+values will show up on your terminal. The usual differences (these are
+all acceptable) are:
+
+ * string usage and table sizes;
+
+ * glue set ratios;
+
+ * `down4', `right4', and `y4' commands in DVItype output;
+
+ * dates and times.
+
+Any other differences are trouble. The most common culprit in the past
+has been compiler bugs, especially when optimizing. *Note TeX or
+Metafont failing: (kpathsea)TeX or Metafont failing.
+
+ The files `trip.diffs', `mftrap.diffs', and `mptrap.diffs' in the
+`triptrap' directory show the standard diffs against the original
+output. If you diff your diffs against these files, you should come up
+clean. For example
+ make trip >&mytrip.diffs
+ diff triptrap/trip.diffs mytrip.diffs
+
+ To run the tests separately, use the targets `trip', `trap', and
+`mptrap'.
+
+ To run simple tests for all the programs as well as the torture tests,
+run `make check'. You can compare the output to the distributed file
+`tests/check.log' if you like.
+
+Runtime options
+===============
+
+ Besides the configure- and compile-time options described in the
+previous sections, you can control a number of parameters (in
+particular, array sizes) in the `texmf.cnf' runtime file read by
+Kpathsea (*note Config files: (kpathsea)Config files.).
+
+ Rather than exhaustively listing them here, please see the last
+section of the distributed `kpathsea/texmf.cnf'. Some of the more
+interesting values:
+
+`main_memory'
+ Total words of memory available, for TeX, Metafont, and MetaPost.
+ Must remake the format file after changing.
+
+`extra_mem_bot'
+ Extra space for "large" TeX data structures: boxes, glue,
+ breakpoints, et al. If you use PiCTeX, you may well want to set
+ this.
+
+`font_mem_size'
+ Words of font info available for TeX; this is approximately the
+ total size of all TFM files read.
+
+`hash_extra'
+ Additional space for the hash table of control sequence names.
+ Approximately 10,000 control sequences can be stored in the main
+ hash table; if you have a large book with numerous
+ cross-references, this might not be enough, and thus you will want
+ to set `hash_extra'.
+
+ Of course, ideally all arrays would be dynamically expanded as
+necessary, so the only limiting factor would be the amount of swap space
+available. Unfortunately, implementing this is extremely difficult, as
+the fixed size of arrays is assumed in many places throughout the source
+code. These runtime limits are a practical compromise between the
+compile-time limits in previous versions, and truly dynamic arrays. (On
+the other hand, the Web2c BibTeX implementation does do dynamic
+reallocation of some arrays.)
+