=============================================================================

	teTeX-2.0 installation instructions (compiling the sources)

=============================================================================

  1) prerequisites: disk space, ANSI C and C++ compiler (with header
     files + libraries), make utility, lexical scanner, parser generator,
     clean environment; eventually: perl/Tk
  2) getting the files
  3) install the inputs-tree
  4) unpack the sources
  5) configuring
  6) run make
  7) final configuration steps
  A) appendix: notes on some platforms
  B) appendix: note on moving the binaries around
  C) appendix: note on updating a single applications
  D) appendix: recreating format files

============================================================================
  1) prerequisites: disk space, ANSI C and C++ compiler (with header files
     + libraries), make utility, lexical scanner, parser generator,
     clean environment; eventually: perl/Tk
============================================================================

The disk space you need (approx.):
  10 MB for the tar file containing the sources
  48 MB for the tar file containing the complete fonts/macros subtree (texmf)
  48 MB for the unpacked source tree
 150 MB for the unpacked texmf tree
 140-200 MB for object files, binaries, ... during compilation
  15-30 MB for binaries, format files, bitmap fonts, ...

You'll also need an ANSI C compiler, a C++ compiler for pdftex, a make
utility, a lexical scanner and a parser generator. I have used the
GNU utilities (gcc, GNU make, flex, bison) for my tests. gawk 2.15
was reported to fail whereas gawk 3.x worked fine. To compile xdvi /
oxdvi, you need the include files and libraries for the X Windows System
(X11) including the Xaw library. On AIX 4.3.2, make sure to install
the packages:
  X11.samples.lib.Core + X11.samples.common
For building texinfo, you need a curses library with header files, e.g.
ncurses.

Note for Solaris 7 with Sun compilers. The following patches are needed:
  106327-04 SunOS 5.7: Shared library patch for C++
  106300-05 SunOS 5.7: Shared library patch for 64bit C++

Another note for SUN users: SUN's parallel make utility fails on some
of the Makefiles. /usr/ccs/bin/make from Solaris 2 (and later) is fine,
however.

Before building teTeX, make sure you have not inadvertently set any
of the environment variables listed in part 7 below, unless you know
exactly what you're doing.

For using the texdoctk and ConTeXt's helper utilities, you need the perl
interpreter with the Tk module.

=============================================================================
  2) getting the files
============================================================================

What you need:
    tetex-src.tar.gz    # the sources
    tetex-texmf.tar.gz  # the lib-tree with the fonts, macros, ...

The file
    tetex-texmfsrc.tar.gz
contains sources for packages that are contained in the texmf tarball.
The texmf tarball contains the files which are needed at runtime. This
archive contains additional files which are not needed, e.g. docstrip
sources of some packages.

============================================================================
  3) choose installation prefix and directory layout
============================================================================

Decide where the "root" of the installation will be, e.g. /usr/local
or /usr/local/teTeX. That directory will be named TETEXDIR in the
following.

The standard directory layout is:
  $TETEXDIR/man			% UNIX manual pages
  $TETEXDIR/share/texmf		% main tree with fonts, macros, ...
				% for tex, metafont + friends
  $TETEXDIR/info		% GNU style info manuals
  $TETEXDIR/bin/$PLATFORM	% binaries

You can omit the "share/" part for the texmf directory if you want.
$TETEXDIR/share/texmf and $TETEXDIR/texmf are auto-detected by configure.
If you choose something different, you have to specify that directory
with the --datadir option of configure (still, "/texmf" is appended to 
that given directory).

If you want to leave out the $PLATFORM directory level (i.e. put the
binaries directly into $TETEXDIR/bin), specify the --disable-multiplatform
option for configure.

For now, you have to create the texmf directory and unpack the tar archive
there. Example (the "#" character represents the prompt of your shell,
don't type it in):

  # mkdir -p /usr/local/teTeX/share/texmf
  # gzip -dc tetex-texmf.tar.gz \
      | (umask 0; cd /usr/local/teTeX/share/texmf; tar xvf -)

Now, optionally, unpack the texmfsrc tarball:
  # gzip -dc tetex-texmfsrc.tar.gz \
      | (umask 0; cd /usr/local/teTeX/share/texmf; tar xvf -)

============================================================================
  4) unpack the sources
============================================================================

Unpack the sources, e.g.:
  # cd /usr/local/src
  # gzip -dc tetex-src.tar.gz | tar xvf -

============================================================================
  5) configuring
============================================================================

teTeX uses one large directory tree which you have unpacked in step 3.
You can add additional texmf trees to the configuration by editing the
file tetex-src-2.0/texk/kpathsea/texmf.in, e.g. set up a tree where you
store your local additions (TEXMFLOCAL) or all variable data such as
configuration files, format files etc. (VARTEXMF).

That texmf.in will be installed as web2c/texmf.cnf in your main texmf
tree. You can edit that file later, too. Don't forget to remove the word
"original" in the first line of the file if you do any changes.

Have a look at the output of ./configure --help and the files INSTALL in
various subdirectories for instructions. The file texk/kpathsea/INSTALL
explains which environment variables configure uses in determining your
system's characteristics. The list there lacks the variables for C++
which are:
   `CXX':      The C++ compiler to use.
   `CXXFLAGS': Options to give the C++ compiler.
Make sure the shell variable "noclobber" is not set, then type something
like:

  # cd tetex-src-2.0   # replace 2.0 with the current release number
  # sh -c './configure --prefix=/usr/local/teTeX >configure.log 2>&1' &

Environment variables can be passed the following way:
  # env CC=cc CXX=CC CFLAGS='-O -g' \
      sh -c './configure --prefix=/usr/local/teTeX >configure.log 2>&1' &

You can watch the output of configure by running
  tail -f configure.log

============================================================================
  6) run make
============================================================================

Make sure, the shell variable "noclobber" is not set, then type "make
world" and relax :-) I also suggest to log all the output, e.g. by running
  # sh -c 'make world >world.log 2>&1' &

Before you think that everything is ok, please check the log file for
errors (GNU make always uses the string "Error:" whenever a command returns
an error code) and check if all binaries are built:
  # cd /usr/local/teTeX/bin/i686-pc-linux-gnu
  # ls | wc -l  # should be 145

(The number is only valid if you configure was run with default values
without turning off any of the sub-packages like pdftex.)

The complete list of binaries generated with "ls | sed s@^@\ \ @ | fmt" is:
  MakeTeXPK access afm2tfm allcm allec allneeded bibtex ctangle cweave
  dmp dvi2fax dvicopy dvihp dvilj dvilj2p dvilj4 dvilj4l dvilj6 dvipdfm
  dvipdft dvips dvired dvitomp dvitype e2pall ebb einitex elatex
  epstopdf etex evirtex fdf2tan fmtutil fontexport fontimport fontinst
  gftodvi gftopk gftype gsftopk info infokey inimf inimpost iniomega
  initex install-info kpsepath kpsestat kpsetool kpsewhich kpsexpand
  lambda latex mag makeindex makeinfo makempx makempy mf mf-nowin mft
  mfw mkfontdesc mkindex mkocp mkofm mktexfmt mktexlsr mktexmf mktexpk
  mktextfm mpost mpto mptopdf newer odvicopy odvips odvitype ofm2opl
  omega omfonts opl2ofm otangle otp2ocp outocp ovf2ovp ovp2ovf oxdvi
  oxdvi.bin patgen pdfeinitex pdfelatex pdfetex pdfevirtex pdfinitex
  pdflatex pdftex pdftosrc pdfvirtex pfb2pfa pk2bm pktogf pktype pltotf
  pooltype ps2frag ps2pk pslatex readlink rubibtex rumakeindex t1mapper
  tangle tcdialog tex texconfig texdoc texdoctk texexec texfind texfont
  texhash texi2dvi texi2html texi2pdf texindex texlinks texshow texutil
  tftopl thumbpdf tie ttf2afm updmap vftovp virmf virmpost viromega
  virtex vptovf weave xdvi xdvi.bin xdvizilla

"make world" is equivalent to
  make all install

If you need special privileges for 'make install', you can
run make in two separate steps:
  make all
  su
  make install

============================================================================
  7) final configuration steps
============================================================================

Overview:
  - set up PATH
  - check environment
  - configure teTeX using texconfig
  - generate fonts with a batch job
  - set up area for automatic font generation

Set up PATH:
===========
Set up your PATH to include the directory containing the just installed
binaries (e.g. /usr/local/teTeX/bin/sparc-sunos4.1.3); similarly, MANPATH
and INFOPATH to include the relevant newly installed subdirectories,
i.e. $TETEXDIR/man resp. $TETEXDIR/info.


Check environment
=================
Note, that the run-time search paths for all programs that use
the Kpathsea library can be configured by changing the paths in
TEXMFMAIN/web2c/texmf.cnf and changes to these paths does not require
to recompile any of the programs. Therefore, you hardly need to set
extra environment variables. If you define some environment variables,
they overrule the search paths in texmf.cnf unless they have an empty
path component (i.e. a colon at the beginning or end or a doubled colon
in the middle).

The variables to check are:
  AFMFONTS BIBINPUTS BSTINPUTS DVILJFONTS DVIPSFONTS DVIPSHEADERS GFFONTS
  GLYPHFONTS INDEXSTYLE MFBASES MFINPUTS MFPOOL MFTINPUTS MPINPUTS
  MPMEMS MPPOOL MPSUPPORT OCPINPUTS OFMFONTS OPLFONTS OTPINPUTS OVFFONTS
  OVPFONTS PKFONTS PSHEADERS T1FONTS T1INPUTS TEXBIB TEXCONFIG TEXDOCS
  TEXFONTMAPS TEXFONTS TEXFORMATS TEXINDEXSTYLE TEXINPUTS TEXMFCNF
  TEXMFDBS TEXMFINI TEXPICTS TEXPKS TEXPOOL TEXPSHEADERS TEXSOURCES
  TFMFONTS TRFONTS VFFONTS XDVIFONTS XDVIVFS

A simple way to check them is to run
  texconfig confall
once you have set up your PATH. Be careful if some variables are non-empty
and have a look at the locations of the binaries. Not all binaries are
checked, only some.

Configure teTeX using texconfig
===============================
Texconfig allows you to set the defaults for hyphenation, paper size,
print command, metafont mode, etc. You should run this command
interactively and see what options it offers.

For example, if you are not using A4 format paper, you should make
"lettersize" the default using:
    texconfig dvips paper letter
    texconfig dvipdfm paper letter
    texconfig xdvi us

Generate fonts with a batch job
===============================
After you have configured the resolution for the previewer and printers,
you might want to generate some bitmap fonts in a batch job. There are
scripts like allneeded(1), allcm(1) and allec(1) which can generate the
fonts that most users need. For details, have a look at the teTeX
documentation that can be found via
  texdoc TETEXDOC
or the teTeX-FAQ:
  texconfig faq

Set up area for automatic font generation
=========================================
Now, after optionally generating a large set of standard fonts, you
might want to set up an area that other users in your system can use to
put automatically generated fonts into.

If you don't mind that every use puts automatically generated fonts into
the main system tree, just make the main tree writable for that. It can be
done by the command:
  texconfig font rw

If you want the global tree to be read-only (this is the default), just do
  texconfig font ro

But, you should set up some varfonts area and enable the varfonts feature
in that case (replace the string "/some/varfonts/area" by the name of the
directory, where all the generated fonts should go):
  texconfig font vardir /some/varfonts/area
  texconfig font options appendonlydir varfonts

=============================================================================
 A) appendix: notes on some platforms
=============================================================================

teTeX-2.0 was successfully compiled on the following platforms:

 - alpha-dec-osf4.0e: Digital PWSau 433, Alpha EV5.6 (21164A) 433MHz
   Digital UNIX V4.0E, gcc 2.95.3, make (OS), flex (OS), yacc (OS), awk (OS)
 - rs6000-ibm-aix3.2.5: IBM RS/6000-390, POWER2 67MHz
   AIX 3.2.5 (325102), gcc 2.95.3, make (OS), lex (OS), yacc (OS), awk (OS)
 - mips-dec-ultrix4.5: DECstation 5000/120, MIPS R3000 20MHz
   ULTRIX V4.5, gcc 2.95.3, gmake 3.80, lex (OS), yacc (OS), awk (OS)
 - i686-pc-linux-gnu: Intel compatible PC, AMD Athlon 1700+
   SuSE Linux 7.2, gcc 2.95.3, GNU Make 3.80, GNU flex 2.5.4, GNU Bison
   1.28, GNU Awk 3.0.6

=============================================================================
 B) appendix: note on moving the binaries around
=============================================================================

If you move the binaries to a different location after "make install",
you have to consider the following things:

- make sure that the texmf.cnf file is still found. If
      kpsewhich texmf.cnf
  fails, you have to set the TEXMFCNF variable. If, for example the
  texmf tree is rooted in /usr/share/texmf, you should set the TEXMFCNF
  variable to
      .:/usr/share/texmf/web2c
  to make sure that all programs will find the texmf.cnf file. After
  setting the TEXMFCNF variable, try the kpsewhich command again and
  verify that the texmf.cnf file will be found.

- make sure that TEXMFMAIN is defined correctly in the texmf.cnf file.
  Execute the command
      kpsewhich -expand-var='$TEXMFMAIN'
  If this does not give you the root of your texmf directory, you have to
  correct the TEXMFMAIN variable. Just change the line which defines
  TEXMFMAIN in the texmf.cnf file and set it to the correct directory.
  In the above example you would set:
      TEXMFMAIN = /usr/share/texmf

- a single binary somewhere separated from the rest of the TeX system
  might get the wrong paths, because of two possible reasons:
    * not finding the main texmf.cnf file
    * different expansion of the SELFAUTO* variables

  So, if you encounter the first problem, set TEXMFCNF as described above.
  If you encounter the second problem, replace the SELFAUTO* variables in
  texmf.cnf by their expanded paths.

  Debugging this is not easy, but can be done by setting KPATHSEA_DEBUG=12
  and running the application. The output shows if the texmf.cnf is
  opened and how the search paths are set.

=============================================================================
 C) appendix: note on updating a single application
=============================================================================

When updating a currently working application, a way to avoid the problem
described in B) is to place the new binary into the same directory that
the older version resides in.

=============================================================================
  D) appendix: recreating format files
=============================================================================
If you need to recreate format files (e.g. because you have updated pdftex),
just
  fmtutil --all

=============================================================================
 E) appendix: note on moving the whole teTeX tree around
=============================================================================

If you want to move the whole teTeX tree around you may do it without
problems. If the relative position of the texmf.cnf file to the binaries
stays the same it will be found after moving the tree around. You just
have to adjust the PATH variable to the new location of the binaries.

If you, however, have set the variable TEXMFCNF or have not used the 
SELFAUTO* variables in texmf.cnf, you have to adjust them accordingly.

=============================================================================
 F) appendix: update teTeX to a new version
=============================================================================

If you want to update teTeX to a new version and have to garantee that
TeX can be used without a break you may install the new version in
another directory and move it to the final location afterwards.
Say, the old teTeX version is in /usr/local/teTeX.
The temporary location of the new version will be /usr/local/teTeX-new.

- Unpack the new texmf tree to /usr/local/teTeX-new/share/texmf.

- Configure the new version to be installed in /usr/local/teTeX-new:
    # sh -c './configure --prefix=/usr/local/teTeX-new >configure.log 2>&1' &

- Compile and install teTeX there according to section 6 of this document.

- If the old installation has a TEXMFLOCAL tree, copy it into the new
  teTeX tree, e.g.:
    # cd /usr/local
    # cp -r teTeX/share/texmf-local teTeX-new/share/
  Have a look at the packages in the new TEXMFLOCAL tree: They may be 
  older than the ones in the new TEXMF tree. Then, you should delete them
  from the new TEXMFLOCAL tree.

- Set the PATH variable temporarily in one shell to find the new binaries
  before the old ones.

- Configure the new version as described in section 7.

- Test the new version with some test files.

- If all tests succeed replace the old version by the new one:
    # cd /usr/local
    # mv teTeX teTeX-old && mv teTeX-new teTeX
  
- Remove the temporary path from the PATH variable. 
