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

	teTeX-3.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.):
  13 MB for the tar file containing the sources
  88 MB for the tar file containing the complete fonts/macros subtree (texmf)
  54 MB for the unpacked source tree
 228 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, 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
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 prefix in the
following.

The standard directory layout is:
  $prefix/share/texmf		% variable runtime and configuration data
  $prefix/share/texmf-dist	% distributed tree with fonts, macros, ...
  $prefix/share/texmf-local	% for local additions
  $prefix/share/texmf-config    % system tree for modified configuration files
  $prefix/share/texmf-var       % system tree for cached variable runtime files
  $HOME/.texmf-config           % user tree for modified configuration files
  $HOME/.texmf-var              % user tree for cached variable runtime files
  $prefix/info			% GNU style info manuals
  $prefix/man			% UNIX manual pages
  $prefix/bin/$PLATFORM		% binaries

You can omit the "share/" part for the texmf directories if you want.
$prefix/share/texmf and $prefix/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 $prefix/bin), specify the --disable-multiplatform
option for configure.

For now, you have to create two texmf directories 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 /usr/local/teTeX/share/texmf-dist
  # gzip -dc tetex-texmf.tar.gz \
      | (umask 0; cd /usr/local/teTeX/share/texmf-dist; tar xvf -)

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

One compatibility note: DO NOT install the distributed texmf tree over an
existing older texmf tree. There have been many changes in the directory
structure this time and you'll end up with duplicates, obsolete files etc.

The ONLY way that I recommend is to make a clean new installation without
any other trees first. If all works, you can just add your additional
tree(s) to the TEXMF variable before or after the TEXMFMAIN setting in
the installed texmf.cnf file.

In order to do this, do the following AFTER THE INSTALLATION:
First locate the file using
  kpsewhich texmf.cnf
Then, edit the definition of the TEXMF variable. The expression on the
right side of the "=" sign is a "brace expression", i.e. a list of values
enclosed by braces and separated by a comma.

To add for example /my/fancy/texmf-dir to the list, you should could change:
  TEXMF = {...!!$TEXMFLOCAL,!!$TEXMFDIST}
into
  TEXMF = {...!!$TEXMFLOCAL,!!$TEXMFDIST,/my/fancy/texmf-dir}
(The ... mean some omitted data).

============================================================================
  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-3.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-3.0   # replace 3.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 -1 | grep -v '^\.' | wc -l  # should be 137

(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:
  a2ping afm2tfm aleph allcm allec allneeded bibtex ctangle ctie cweave
  dmp dvi2fax dvicopy dvigif dvihp dvilj dvilj2p dvilj4 dvilj4l dvilj6
  dvipdfm dvipdft dvipng dvips dvired dvitomp dvitype e2pall ebb epstopdf
  etex fdf2tan fdf2tex fmtutil fmtutil-sys fontinst gftodvi gftopk gftype
  gsftopk info infokey install-info kpseaccess kpsepath kpsereadlink
  kpsestat kpsetool kpsewhere kpsewhich kpsexpand lambda lamed latex
  mag makeindex makeinfo makempx makempy mf mf-nowin mft 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 patgen pdfcrop pdfetex pdflatex
  pdftex pdfxtex pfb2pfa pk2bm pktogf pktype pltotf pooltype ps2frag
  ps2pk ps4pdf pslatex rubibtex rumakeindex tangle tcdialog tex texconfig
  texconfig-dialog texconfig-sys texdoc texdoctk texexec texfind texfont
  texhash texi2dvi texi2html texi2pdf texindex texlinks texshow texutil
  tftopl thumbpdf tie ttf2afm uniqleaf updmap updmap-sys vftovp vptovf
  weave xdvi xdvi-motif.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

A warning: running "make install" might create ls-R files in some
subdirectories of $HOME. So, if "su" does not change $HOME", you should
better "su -". Similar, if you "sudo" and this does not change the $HOME
variable, try "sudo -H". After switching the user id, you might need to
"cd" back into the build directory before running "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/i686-pc-linux-gnu); similarly, MANPATH
and INFOPATH to include the relevant newly installed subdirectories,
i.e. $prefix/man resp. $prefix/info. To avoid conflicts with a
possible different TeX installation, make sure to put the new directories
first. E.g. for setting PATH, use something like the following, but
replace i686-pc-linux-gnu by your actual platform directory:
  PATH=/usr/local/teTeX/bin/i686-pc-linux-gnu:$PATH; export PATH
or
  setenv PATH /usr/local/teTeX/bin/i686-pc-linux-gnu:$PATH

As an alternative to adjust PATH, you could as well create symbolic
links in a standard location such as /usr/local/bin:

    Example using GNU-ls (which supports the "force" option):
      ln -sf /usr/local/teTeX/bin/i686-pc-linux-gnu/* /usr/local/bin

    Example using standard ln:
      (cd /usr/local/teTeX/bin/i686-pc-linux-gnu; echo *) \
        | (cd /usr/local/bin; xargs rm -f)
      ln -s /usr/local/teTeX/bin/i686-pc-linux-gnu/* /usr/local/bin


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 conf
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-sys
===============================================
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.

Please note, that texconfig writes two kind of files into two different
directory trees: changes configuration files go into the tree where the
TEXMFCONFIG variable points to (default is ~/.texmf-config) and updated
cached variable runtime files such as formats go into the tree where
the TEXMFVAR variable points to (default is ~/.texmf-var).

Using texconfig-sys: if you are setting up a TeX installation used
by multiple users, you can either configure your personal defaults
(which is the default) or you can configure the global defaults (for
all users) which are stored in the TEXMFSYSCONFIG / TEXMFSYSVAR trees
(for configuration data resp. variable runtime files). For configuring
the global defaults, you should use the wrapper script texconfig-sys
which calls texconfig with redirected TEXMFVAR and TEXMFCONFIG variables
(for fmtutil and updmap, equivalent wrapper scripts exist: fmtutil-sys
and updmap-sys).

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

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


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

teTeX-3.0 was successfully compiled on the following platforms:
  - ix86/Linux,		GNU gcc-3.4.3, GNU flex 2.5.4, GNU bison 1.875, GNU make 3.80
  - Sparc/Solaris 9,	Sun C 5.5, GNU flex 2.5.4, GNU bison 1.875, GNU make 3.80
  - x86/Solaris 10,	Sun C 5.5, GNU flex 2.5.4, GNU bison 1.875, GNU make 3.80
  - Digital UNIX 4.0E,  gcc 2.95.3, make (OS), flex (OS), yacc (OS), awk (OS)
  - AIX 3.2.5 (325102), gcc 2.95.3, make (OS),  lex (OS), yacc (OS), awk (OS)
  - ULTRIX V4.5,        gcc 2.95.3, gmake 3.80, lex (OS), yacc (OS), awk (OS)
  - sparc/Linux,	GNU gcc-3.3.5, GNU flex 2.5.31, GNU bison 1.875d, GNU make 3.80
  - ix86/Linux,		Fedora Core 2 and 3, Debian/unstable,
			Debian/Woody, RedHat 6.2, 7.1, 7.3, 9.0, SuSE 7.3,
			9.0, 9.1, Vine Linux 2.6/3.1
  - amd64/Linux		SuSE 9.0, SuSE 9.2
  - Mac OS X		10.3.6, 10.3.7, Panther
  - Sparc/Solaris	2.5.1, 2.7, 2.8, 2.9
  - ix86/Solaris	10
  - rs6000/AIX		4.3, 5.1
  - iris4d/IRIX64	6.5
  - alpha/OSF1		V4.0, V5.0, V5.1
  - hp9000s700/HP-UX	B.10.20, B.11.00, B.11.11
  - ia64/HP-UX		B.11.22
  - Irix		6.5.20M


=============================================================================
 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 guarantee 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-dist and
  create an empty /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.

  Also, remove any config file from your new texmf-local tree:
    dvipdfm/config/config
    dvips/config/config.ps
    metafont/misc/modes.mf
    tex/generic/config/pdftexconfig.tex
    web2c/fmtutil.cnf
    web2c/mktex.cnf
    web2c/updmap.cfg
    xdvi/XDvi

  It is better to start with new templates from the distribution and
  make the changes / additions on that basis (e.g. by running texconfig
  / updmap). Also note, that the new directory tree for changed
  configuration files is specified by $TEXMFCONFIG (which defaults
  to $TEXMFMAIN). You should not maintain config files in a different
  directory other than the one specified by $TEXMFCONFIG.

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

=============================================================================
 G) scanning texmf trees for duplicates
=============================================================================

You can use the tool "uniqleaf" to find duplicate file names with one
or more texmf trees. One application might be to look for duplicates
among the system's files and your own files in your local texmf trees.

Since the system's texmf tree is so large and contains lots of files
with the same name (e.g. README, install.txt, TODO), it generates a lot
of output if you scan it completely. My suggestion is to scan parts of
the texmf trees separately:
  uniqleaf tetex-prefix/share/texmf-dist/fonts /your/tree/texmf/fonts
  uniqleaf tetex-prefix/share/texmf-dist/bibtex  /your/tree/texmf/bibtex

Scanning teTeX's texmf-dist/tex tree produces output mentioning the
following files which you can ignore:
    cslatex/fonttext.cfg cslatex/hyphen.cfg cslatex/macce.def
    csplain/czech.sty csplain/dcfonts.tex csplain/ecfonts.tex
    csplain/slovak.sty cyrplain/base/plainenc.tex generic/babel/czech.sty
    generic/babel/hyphen.cfg generic/babel/slovak.sty
    generic/config/fonttext.cfg generic/config/language.dat
    lambda/config/language.dat latex/base/macce.def
    plain/enctex/dcfonts.tex plain/enctex/ecfonts.tex
    plain/vietnam/plainenc.tex platex/config/hyphen.cfg
    platex/config/language.dat

To check your "tex" part of your texmf tree against teTeX's tree, I suggest
that you compare each subdirectory of tetex-prefix/share/texmf-dist/tex
individually against your tree:
  cd tetex-prefix/share/texmf-dist/tex
  for i in *; do uniqleaf $i /your/tree/texmf/tex; done
