View source for Notes on TeX Live setup

==Introduction==
This page describes steps to install [http://tug.org/texlive TeX Live] (TL from now) and needed tweaks so that other kpathsea programs that are not part of TL can also use TL data. This is useful if we recompile some program from sources and want it to be able to find TL data. For example, one might want to recompile pdftex with some patch, and use it instead of the binary coming with TL.

This guide was written for TL2008 on Ubuntu linux 8.01 and should work with no or little change for other Linux/UNIX systems. 

When in doubt, please refer to the [http://www.tug.org/texlive/doc/texlive-en/texlive-en.html official TeX Live documentation]. This guide serves as a quick guide for some very specific purposes:
* how to install TL with minimal effort and confusion
* how to use TL data with non-TL binaries
* how to use different versions of pdftex
* how to add local packages in a systematic way

== Install TL ==
* start with a shell where no tex-related environment variables are defined. A quick check can be done by 
<geshi lang="bash">
printenv | fgrep TEX
</geshi>
* download [http://mirror.ctan.org/systems/texlive/Images/texlive2008.iso.lzma latest TL iso image] to e.g. '''$HOME/iso-images''' 
* unpack the image:
<geshi lang="bash">
cd $HOME/iso-images
unlzma texlive2008.iso.lzma
</geshi>
* mount the TL image:
<geshi lang="bash">
mkdir -p /mnt/texlive2008
mount -t iso 9660 -o loop $HOME/iso-images/texlive2008.iso /mnt/texlive2008/
</geshi>
* run the TL installer:
<geshi lang="bash">
perl /mnt/texlive2008/install-tl
</geshi>
* in next menu, change the destination of installation to '''/opt/texlive/2008''' by entering:
<pre>
d<Enter>
1<Enter>
/opt/texlive/2008<Enter>
r<Enter>
</pre>
* start the installation process by entering '''i<Enter>'''. When the installation process is done, the last messages should look like this:
<pre>
 pre-generating all format files (fmtutil-sys --all), be patient...done

 See 
   /opt/texlive/2008/index.html 
 for links to documentation.  The TeX Live web site (http://tug.org/texlive/) 
 contains any updates and corrections.

 TeX Live is a joint project of the TeX user groups around the world;
 please consider supporting it by joining the group best for you. The
 list of groups is available on the web at http://tug.org/usergroups.html.

 Add /opt/texlive/2008/texmf/doc/man to MANPATH.
 Add /opt/texlive/2008/texmf/doc/info to INFOPATH.
 Most importantly, add /opt/texlive/2008/bin/i386-linux
 to your PATH for current and future sessions.

 Welcome to TeX Live!

/mnt/texlive2008/install-tl: done.
Logfile: /opt/texlive/2008/install-tl.log
</pre>
* '''N.B.''': if you are not using '''i386-linux''', the value to be added to the '''PATH''' variable is different; for example if you are using 64-bit linux, the installation log will report '''x86_64-linux''' instead of '''i386-linux'''. 
* create a partial copy of the main TL configuration file (we will modify this copy later):
<geshi lang="bash">
cat /opt/texlive/2008/texmf/web2c/texmf.cnf | \
grep 'SELFAUTOPARENT\|^TEXMF \|^TEXMFDBS ' | \
grep -v '^%' > /opt/texlive/2008/texmf.cnf
</geshi>
* change some environment variables permanently as instructed by the installation log: add to '''/etc/profile''' the following lines ('''don't forget to check the value of PATH if you are not using i386-linux'''):
<geshi lang="bash">
## added for TeX Live
TEXMFCNF=/opt/texlive/2008:/opt/texlive/2008/texmf/web2c
MANPATH=/mnt/texlive2008/texmf/doc/man:$MANPATH
INFOPATH=/mnt/texlive2008/texmf/doc/info:$INFOPATH
PATH=/opt/texlive/2008/bin/i386-linux:$PATH
export TEXMFCNF MANPATH INFOPATH PATH
</geshi>
* logout and login again to ensure that the above environment variables are set. With '''bash''' as the default shell, it can be done by saying:
<geshi lang="bash">
exec bash -login
</geshi>
* test the installation:
<geshi lang="bash">
pdflatex sample2e
</geshi>
* if things go well, we should get a log similar to the below:
<pre>
$ pdflatex sample2e
This is pdfTeXk, Version 3.1415926-1.40.9 (Web2C 7.5.7)
 %&-line parsing enabled.
entering extended mode
(/mnt/texlive2008/texmf-dist/tex/latex/base/sample2e.tex
LaTeX2e <2005/12/01>
.
.
.
Output written on sample2e.pdf (3 pages, 69560 bytes).
Transcript written on sample2e.log.
</pre>

== Keeping packages up-to-date ==
* Tell TL that we want to update packages from TL site:
<geshi lang="bash">
tlmgr option location http://mirror.ctan.org/systems/texlive/tlnet/2008
</geshi>
* check which packages can be updated:
<geshi lang="bash">
tlmgr update --list
</geshi>
* update one package (rerun without --dry-run when you are sure):
<geshi lang="bash">
tlmgr update --dry-run <package-name>
</geshi>
* update all package (rerun without --dry-run when you are sure):
<geshi lang="bash">
tlmgr update --dry-run --all
</geshi>
* '''Recommendations for update''': 
** don't update until you know why you have to (don't touch things that aren't broken)
** backup before update, so things can be reverted if needed. See [http://www.tug.org/texlive/doc/tlmgr.html tlmgr manual] for further info on backup/restore. 
** do '''not''' update all packages in one go

== Use non-TL binaries with TL data ==
TL and all kpathsea programs use one or more config files called '''texmf.cnf''' to search for needed data. In previous steps we have already defined an environment variable TEXMFCNF, which in sequence causes that all kpathsea programs will read first the customized config file '''/opt/texlive/2008/texmf.cnf''', then the default TL config file '''/opt/texlive/2008/texmf/web2c/texmf.cnf'''. The values defined in the first '''texmf.cnf''' will override values in  later ones.

This is critical to have TEXMFCNF defined explicitly as above. If TEXMFCNF is not defined, it's very hard to track down which config file(s) are being read, since there can be several '''texmf.cnf''' files laying around and which of them are read depends on quite a few factors. By setting TEXMFCNF to a fixed value, we can get rid of this headache and can concentrate on our customized config file '''/opt/texlive/2008/texmf.cnf'''

Then to make  non-TL binaries work with TL data, we change our '''texmf.cnf''' to get rid of SELFAUTOPARENT as follows: 
<geshi lang="bash">
sed -i -e 's:.SELFAUTOPARENT:/opt/texlive/2008:' /opt/texlive/2008/texmf.cnf 
</geshi>

== Add another texmf tree ==
Suppose we have tetex previously installed to '''/opt/tetex-3.0'''. The tetex texmf tree is then located at '''/opt/tetex-3.0/share/texmf'''. To add this texmf tree to our setup, we do this:
<geshi lang="bash">
ln -s /opt/tetex-3.0/share/texmf /opt/texlive/texmf-tetex
sed -i '
/^TEXMFLOCAL/ a\
TEXMFTETEX = /opt/texlive/texmf-tetex
s/^TEXMF = .*TEXMFLOCAL/&,!!$TEXMFTETEX/
s/^TEXMFDBS = .*TEXMFLOCAL/&,!!$TEXMFTETEX/
s/^SYSTEXMF = .*TEXMFLOCAL/&;$TEXMFTETEX/
' /opt/texlive/2008/texmf.cnf
</geshi>

We can repeat the above steps to add as many texmf trees as we need. For each texmf tree we must:
* choose a variable name that it's not used yet (TEXMFTETEX in the above example)
* locate the path to the texmf tree, and make a symlink in '''/opt/texlive'''
* adjust the above commands accordingly.

Or, it is possible to use the below script to automate the above steps. 
Save it to a file called eg '''add-texmf-tree.sh'''.
<geshi lang="bash">
#!/bin/bash
# script to add a texmf tree to texmf.cnf
# Usage: $0 <variable-name> <texmf-location> /path/to/texmf.cnf
# Example: $0 TEXMFTETEX /opt/texlive/texmf-tetex /opt/texlive/2008/texmf.cnf

VARNAME=$1
LOCATION=$(echo "$2" | sed 's,/$,,')
CFG_FILE=$3

ExitWithError() {
    echo -e "Error: $@"
    exit
}


#******************************************
# check the arguments for possible mistakes
#__________________________________________
[ -n "$CFG_FILE" ]  || ExitWithError "Missing argument(s).\nUsage: $0 <variable-name> <texmf-location> /path/to/texmf.cnf"
[ -d $LOCATION ]    || ExitWithError "$LOCATION is not a directory"
[ -f $CFG_FILE ]    || ExitWithError "$CFG_FILE is not a regular file"
[ -w $CFG_FILE ]    || ExitWithError "$CFG_FILE is not writable"

echo $VARNAME | grep -q '^TEXMF[A-Z0-9_]*$' || \
    ExitWithError "<variable-name> can contain only uppercase letter, digits and underscore and must start with 'TEXMF'"

grep -q '^TEXMF = ' $CFG_FILE || \
    ExitWithError "$CFG_FILE do not contain TEXMF; is it a texmf.cnf file?"

! grep -q "^$VARNAME = " $CFG_FILE || \
    ExitWithError "$VARNAME is already used in $CFG_FILE; choose a different name"


#*************************************
# backup texmf.cnf before changing it:
#_____________________________________
cp texmf.cnf texmf.cnf--`date '+%Y-%m-%d.%T'`


#*****************
# change texmf.cnf
#_________________
sed -i "
/^TEXMFLOCAL/ a\
$VARNAME = $LOCATION
s/^TEXMF = .*TEXMFLOCAL/&,!!\$$VARNAME/
s/^TEXMFDBS = .*TEXMFLOCAL/&,!!\$$VARNAME/
s/^SYSTEXMF = .*TEXMFLOCAL/&;\$$VARNAME/
" $CFG_FILE
</geshi>

Usage:
<geshi lang="bash">
sh add-texmf-tree.sh TEXMFTETEX /opt/texlive/texmf-tetex /opt/texlive/2008/texmf.cnf
</geshi>

Some notes on the relevant variables above:
* '''TEXMF''': specifies which texmf trees are searched, and in which order. The order of the texmf trees given in '''TEXMF''' is important: earlier trees take precedence over the later ones in '''TEXMF'''. Edit '''texmf.cnf''' manually to change the order if needed.
* '''TEXMFDBS''': contains list of texmf trees with '''ls-R''' filename databases. Running '''texhash''' without arguments will re-generate '''ls-R''' for texmf trees listed in '''TEXMFDBS'''. It's OK to have ls-R in a tree not listed in TEXMFDBS; it will be used, but will not be updated by running '''texhash'''.
** '''N.B.''': a texmf tree with ls-R will '''not''' be searched if that tree is not listed in TEXMFDBS?
* '''SYSTEXMF''': contains a list of ''system'' texmf trees; its meaning is roughly this: if the source of a font is found in a system texmf tree and that tree is not writeable for the current user, then the scripts '''mktexpk''', '''mktextfm''', and '''mktexmf''' will install their output into '''VARTEXFONTS'''.

== Run pdftex compiled from sources ==
Sometimes it's desirable to run a different version of pdftex than the one that comes with TL, for example when we want to run pdftex with some features or bugfixes not included in the version in TL. Then we must compile pdftex from sources and do some extra steps.
* compiling pdftex from sources: download pdftex sources tarball and apply patches if needed. Suppose that we have unpacked pdftex sources to '''$HOME/src/pdftex-1.40.9''', then to build it:
<geshi lang="bash">
cd $HOME/src/pdftex-1.40.9
./build.sh
</geshi>
* when the above process finishes, the pdftex binary should be located at '''$HOME/src/pdftex-1.40.9/build/texk/web2c/pdftex'''
* make symlinks (suppose that '''$HOME/bin''' is in '''$PATH'''):
<geshi lang="bash">
ln -s $HOME/src/pdftex-1.40.9/build/texk/web2c/pdftex $HOME/bin/pdftex2
ln -s $HOME/src/pdftex-1.40.9/build/texk/web2c/pdftex $HOME/bin/pdflatex2
</geshi>
* create formats:
<geshi lang="bash">
cd $(kpsewhich -expand-var '$TEXMFVAR')/web2c/pdftex
pdftex2 -ini -translate-file=cp227.tcx '*pdfetex.ini'
mv pdfetex.fmt pdftex2.fmt
pdflatex2 -ini -translate-file=cp227.tcx '*pdflatex.ini'
mv pdflatex.fmt pdflatex2.fmt
</geshi>
* test the new binary:
<geshi lang="bash">
pdftex2 story \\bye
pdflatex2 sample2e
</geshi>
* repeat the above steps for if needed; substitute pdftex2/pdflatex2 with whichever names that suit better your need/taste.

== Maintain packages installed locally ==
If we keep installing local packages to a texmf tree for some time, we will find out that it's getting difficult to keep track of what has been installed, and how to remove or upgrade a package. This is the place where a ''package management system'' is useful. We will use miktex tools to maintain our local packages.

(''to be continued'')