summaryrefslogtreecommitdiff
path: root/Build/source/texk/web2c/doc/install.texi
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2006-01-17 21:41:51 +0000
committerKarl Berry <karl@freefriends.org>2006-01-17 21:41:51 +0000
commit487ca4806cc046076293cf6cc5fbba0db282bac7 (patch)
tree847b412ab5158dd7bdd7ed7e5a4cc3fbca94be32 /Build/source/texk/web2c/doc/install.texi
parenta3d3111bfe26b8e5f5bc6049dfb2a4ca2edc7881 (diff)
texk 1
git-svn-id: svn://tug.org/texlive/trunk@1485 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Build/source/texk/web2c/doc/install.texi')
-rw-r--r--Build/source/texk/web2c/doc/install.texi347
1 files changed, 347 insertions, 0 deletions
diff --git a/Build/source/texk/web2c/doc/install.texi b/Build/source/texk/web2c/doc/install.texi
new file mode 100644
index 00000000000..c570b0b0a46
--- /dev/null
+++ b/Build/source/texk/web2c/doc/install.texi
@@ -0,0 +1,347 @@
+@ifclear version
+@defcodeindex cm
+@defcodeindex fl
+@defcodeindex op
+@end ifclear
+
+@node Installation
+@chapter Installation
+
+@cindex configuration
+@cindex compilation
+@cindex installation
+
+@ifset version
+(A copy of this chapter is in the distribution file @file{web2c/INSTALL}.)
+@end ifset
+
+Installing Web2c is mostly the same as installing any other
+Kpathsea-using program. Therefore, for the basic steps involved,
+see @ref{Installation,,, kpathsea, Kpathsea}. (A copy is in the file
+@file{kpathsea/INSTALL}.)
+
+One peculiarity to Web2c is that the source distribution comes in two
+files: @file{web.tar.gz} and @file{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.)
+@xref{unixtex.ftp,,, kpathsea, Kpathsea}.
+
+@pindex mpost@r{, reason for name change}
+Another peculiarity is the MetaPost program. Although it has been
+installed previously as @code{mp}, as of Web2c 7.0 the installed name is
+now @code{mpost}, to avoid conflict with the @code{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 @file{kpathsea/BUGS} (@pxref{Bugs,,,
+kpathsea, Kpathsea}). See also the Web2c home page,
+@url{http://www.tug.org/web2c}.
+
+Points worth repeating:
+
+@itemize @bullet
+@item
+@cindex directory structure
+@cindex basic fonts and macros
+@cindex fonts, basic
+@cindex macros, basic
+Before starting the standard compilation and installation you must
+install the basic fonts, macros, and other library files.
+@xref{Installation,,,kpathsea, Kpathsea}.
+
+@item
+If you do not wish to use the standard file locations, see @ref{Changing
+search paths,,, kpathsea, Kpathsea}.
+
+@item
+Some Web2c features are enabled or disabled at @code{configure} time,
+as described in the first section below.
+
+@end itemize
+
+@menu
+* configure options:: Especially --with and --enable.
+* Compile-time options:: Unusual -D's.
+* Additional targets:: Breaking down the task.
+* Triptrap:: Running the torture tests.
+* Runtime options:: Array sizes and the like.
+@end menu
+
+
+@node configure options
+@section @code{configure} options
+
+@cindex configuration, compile-time
+@cindex compile-time options
+@pindex configure --with/--enable @r{options}
+This section gives pointers to descriptions of the @samp{--with} and
+@samp{--enable} @code{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 @code{configure} accepts, run
+@samp{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 @code{configure} usage,
+see @ref{Invoking configure,, Running @code{configure} scripts, autoconf,
+Autoconf}, a copy is in the file @file{kpathsea/CONFIGURE}.
+
+@table @samp
+@item --disable-dump-share
+Do not make fmt/base/mem files sharable across different endian
+architectures. @xref{Hardware and memory dumps}.
+
+@item --without-maketexmf-default
+@itemx --without-maketexpk-default
+@itemx --without-maketextfm-default
+@itemx --with-maketextex-default
+Enable or disable the dynamic generation programs. @xref{mktex
+configuration,,, kpathsea, Kpathsea}. The defaults are the inverse of
+the options, i.e., everything is enabled except @code{mktextex}.
+
+@item --enable-shared
+Build Kpathsea as a shared library. @xref{Shared library,,, kpathsea,
+Kpathsea}.
+
+@item --with-editor=@var{cmd}
+Change the default editor invoked by the @samp{e} interactive command.
+@xref{Editor invocation}.
+
+@item --with-epsfwin
+@itemx --with-hp2627win
+@itemx --with-mftalkwin
+@itemx --with-nextwin
+@itemx --with-regiswin
+@itemx --with-suntoolswin
+@itemx --with-tektronixwin
+@itemx --with-unitermwin
+@itemx --with-x
+@itemx --with-x-toolkit=KIT
+@itemx --with-x11win
+@itemx --with-x11
+Define Metafont graphics support; by default, no graphics support is
+enabled. @xref{Online Metafont graphics}.
+
+@item --x-includes=@var{dir}
+@itemx --x-libraries=@var{dir}
+Define the locations of the X11 include files and libraries; by default,
+@code{configure} does its best to guess). @xref{Optional Features,,,
+autoconf, Autoconf}. A copy is in @file{kpathsea/CONFIGURE}.
+@end table
+
+
+@node Compile-time options
+@section Compile-time options
+
+@cindex compile-time options
+@cindex @samp{#define} options
+@opindex -D @r{compiler options}
+In addition to the @code{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 @code{configure}. Using any of
+these is unusual.
+
+To specify extra compiler flags (@samp{-D@var{name}} in this case), the
+simplest thing to do is:
+@example
+make XCFLAGS="@var{ccoptions}"
+@end example
+@noindent You can also set the @code{CFLAGS} environment variable before
+running @code{configure}. @xref{configure environment,,, kpathsea, Kpathsea}.
+
+Anyway, here are the possibilities:
+
+@table @samp
+@item -DFIXPT
+@itemx -DNO_MF_ASM
+@vindex FIXPT
+@cindex fixed-point arithmetic
+@cindex floating-point arithmetic
+@cindex assembly language routines
+@cindex fraction routines
+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
+@samp{NO_MF_ASM} is defined), and floating-point routines are used
+otherwise.
+
+@item -DIPC_DEBUG
+@vindex IPC_DEBUG
+Report on various interprocess communication activities. @xref{IPC and
+TeX,, IPC and @TeX{}}.
+@end table
+
+
+@node Additional targets
+@section Additional targets
+
+@cindex additional Make targets
+@cindex targets, additional Make
+@cindex Make targets, additional
+
+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 @file{kpathsea/} and @file{web2c/}), or in the
+@file{web2c/} directory.
+
+@table @samp
+@item c-sources
+@cmindex c-sources @r{Makefile target}
+@cindex non-Unix system, compiling on
+Make only the C files, translated from the Web sources, presumably
+because you want to take them to a non-Unix machine.
+
+@item formats
+@itemx install-formats
+@cmindex formats @r{Make target}
+@cmindex install-formats @r{Make target}
+Make or install all the memory dumps (@pxref{Memory dumps}). By
+default, the standard plain formats plus @file{latex.fmt} are made. You
+can add other formats by redefining the @code{fmts}, @code{bases}, and
+@code{mems} variables. See the top of @file{web2c/Makefile} for the
+possibilities.
+
+@item fmts
+@itemx install-fmts
+@cmindex fmts @r{Make target}
+@cmindex install-fmts @r{Make target}
+Make or install the @TeX{} @file{.fmt} files. @xref{Initial TeX}.
+
+@item bases
+@itemx install-bases
+@cmindex bases @r{Make target}
+@cmindex install-bases @r{Make target}
+
+Make or install the Metafont @file{.base} files. @xref{Initial Metafont}.
+
+@item mems
+@itemx install-mems
+@cmindex mems @r{Make target}
+@cmindex install-mems @r{Make target}
+Make or install the MetaPost @file{.mem} files. @xref{Initial MetaPost}.
+
+@item triptrap
+@itemx trip
+@itemx trap
+@itemx mptrap
+@cmindex triptrap @r{Make target}
+@findex trip @r{Make target}
+@findex trap @r{Make target}
+@findex mptrap @r{Make target}
+To run the torture tests for @TeX{}, Metafont, and MetaPost
+(respectively). See the next section.
+
+@end table
+
+
+@node Triptrap
+@section Trip, trap, and mptrap: Torture tests
+
+@cindex Gruff, Billy Goat
+@cindex trip test
+@cindex trap test
+@cindex mptrap test
+@cindex torture tests
+
+@flindex tripman.tex
+@flindex trapman.tex
+@flindex mptrap.readme
+To validate your @TeX{}, Metafont, and MetaPost executables, run
+@samp{make triptrap}. This runs the trip, trap, and mptrap ``torture
+tests''. See the files @file{triptrap/tripman.tex},
+@file{triptrap/trapman.tex}, and @file{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:
+
+@itemize @bullet
+@item string usage and table sizes;
+@item glue set ratios;
+@item @samp{down4}, @samp{right4}, and @samp{y4} commands in DVItype output;
+@item dates and times.
+@end itemize
+
+@noindent Any other differences are trouble. The most common culprit in
+the past has been compiler bugs, especially when optimizing.
+@xref{TeX or Metafont failing,, @TeX{} or Metafont failing, kpathsea,
+Kpathsea}.
+
+The files @file{trip.diffs}, @file{mftrap.diffs}, and
+@file{mptrap.diffs} in the @file{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
+@example
+make trip >&mytrip.diffs
+diff triptrap/trip.diffs mytrip.diffs
+@end example
+
+To run the tests separately, use the targets @code{trip}, @code{trap},
+and @code{mptrap}.
+
+To run simple tests for all the programs as well as the torture tests,
+run @samp{make check}. You can compare the output to the distributed
+file @file{tests/check.log} if you like.
+
+
+@node Runtime options
+@section Runtime options
+
+@cindex runtime options
+
+@cindex configuration file values
+@cindex array sizes
+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 @file{texmf.cnf} runtime file read by
+Kpathsea (@pxref{Config files,,, kpathsea, Kpathsea}).
+
+Rather than exhaustively listing them here, please see the last section
+of the distributed @file{kpathsea/texmf.cnf}. Some of the more
+interesting values:
+
+@vtable @samp
+@item main_memory
+Total words of memory available, for @TeX{}, Metafont, and MetaPost.
+Must remake the format file after changing.
+
+@item extra_mem_bot
+@cindex boxes, memory for
+@cindex glue, memory for
+@cindex breakpoints, memory for
+@cindex PiC@TeX{}, increasing memory for
+Extra space for ``large'' @TeX{} data structures: boxes, glue,
+breakpoints, et al. If you use PiC@TeX{}, you may well want to set this.
+
+@item font_mem_size
+@cindex TFM files, memory for
+Words of font info available for @TeX{}; this is approximately the total
+size of all TFM files read.
+
+@item hash_extra
+@cindex control sequence names, space for
+@cindex hash table, increasing size of
+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 @code{hash_extra}.
+
+@end vtable
+
+@cindex array limit, fixed
+@cindex swap space, as array limit
+@cindex reallocation of arrays
+@cindex dynamic array allocation
+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 Bib@TeX{} implementation does do dynamic
+reallocation of some arrays.)