Installation
************

Installing Web2c is mostly the same as installing any other Kpathsea-using program.  Therefore, for the basic steps involved, see Installation (Kpathsea).  (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.) See unixtex.ftp (Kpathsea).

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 (see Bugs (Kpathsea)).  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. See Installation (Kpathsea).

  * If you do not wish to use the standard file locations, see Changing search paths (Kpathsea).

  * 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, see Running configure scripts (Autoconf) (a copy is in the file kpathsea/CONFIGURE).

--disable-dump-share
     Do not make fmt/base/mem files sharable across different endian architectures.  See Hardware and memory dumps.

--without-maketexmf-default
--without-maketexpk-default
--without-maketextfm-default
--with-maketextex-default
     Enable or disable the dynamic generation programs.  See MakeTeX configuration (Kpathsea).  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.  See Preloaded executables.

--enable-shared
     Build Kpathsea as a shared library.  See Shared library (Kpathsea).

--with-editor=CMD
     Change the default editor invoked by the e interactive command. See 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.  See 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).  See Optional Features (Autoconf).  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.  See configure environment (Kpathsea).

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.  See 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 (see 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. See initex invocation.

bases
install-bases
     Make or install the Metafont .base files.  See inimf invocation.

mems
install-mems
     Make or install the MetaPost .mem files.  See 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. See TeX or Metafont failing (Kpathsea).

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 (see Config files (Kpathsea)).

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.)