Notes on TeX Live setup: Difference between revisions

From STMDocs
Jump to navigation Jump to search
No edit summary
 
(44 intermediate revisions by one other user not shown)
Line 1: Line 1:
==Introduction==
==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 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.  
This guide was written for TL2008 on Ubuntu linux 8.04 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:
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 install TL with minimal effort and confusion
* how to use TL data with non-TL binaries
* 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
* how to add local packages in a systematic way
* how to use different versions of pdftex


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


Line 60: Line 64:
Logfile: /opt/texlive/2008/install-tl.log
Logfile: /opt/texlive/2008/install-tl.log
</pre>
</pre>
* '''N.B.''': if you are not using '''linux-i386''', 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 '''linux-i386'''.  
* '''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'''.  
* make a copy of the main TL configuration file:
* create a partial copy of the main TL configuration file (we will modify this copy later):
<geshi lang="bash">
<source lang="bash">
cp /opt/texlive/2008/texmf/web2c/texmf.cnf /opt/texlive/2008/texmf-var/web2c/
cat /opt/texlive/2008/texmf/web2c/texmf.cnf | \
</geshi>
grep 'SELFAUTOPARENT\|^TEXMF \|^TEXMFDBS ' | \
* 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 linux-i386'''):
grep -v '^%' > /opt/texlive/2008/texmf.cnf
<geshi lang="bash">
</source>
* 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'''):
<source lang="bash">
## added for TeX Live
## added for TeX Live
TEXMFCNF=/opt/texlive/2008/texmf-var/web2c
TEXMFCNF=/opt/texlive/2008:/opt/texlive/2008/texmf/web2c
MANPATH=/mnt/texlive2008/texmf/doc/man:$MANPATH
MANPATH=/mnt/texlive2008/texmf/doc/man:$MANPATH
INFOPATH=/mnt/texlive2008/texmf/doc/info:$INFOPATH
INFOPATH=/mnt/texlive2008/texmf/doc/info:$INFOPATH
PATH=/opt/texlive/2008/bin/i386-linux:$PATH
PATH=/opt/texlive/2008/bin/i386-linux:$PATH
export TEXMFCNF MANPATH INFOPATH PATH
export TEXMFCNF MANPATH INFOPATH PATH
</geshi>
</source>
* 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:
* 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">
<source lang="bash">
exec bash -login
exec bash -login
</geshi>
</source>
* ensure that the new configuration file can be searched:
<geshi lang="bash">
texhash /opt/texlive/2008/texmf-var/
</geshi>
* test the installation:
* test the installation:
<geshi lang="bash">
<source lang="bash">
pdflatex sample2e
pdflatex sample2e
</geshi>
</source>
* if things go well, we should get a log similar to the below:
* if things go well, we should get a log similar to the below:
<pre>
<pre>
Line 100: Line 102:
Transcript written on sample2e.log.
Transcript written on sample2e.log.
</pre>
</pre>
== Keeping packages up-to-date ==
There are 2 possible ways to keep packages up-to-date:
* using tlmgr: this is for real brave men; see [http://www.tug.org/texlive/doc/tlmgr.html tlmgr manual] and http://www.tug.org/texlive/tlmgr.html for further info.
* manual update: this is the simple, stupid way that I prefer. Let's update ie hyperref manually:
<source lang="bash">
mkdir -p /opt/texlive/tds-packages
cd /opt/texlive/tds-packages
wget http://tug.org/applications/hyperref/ftp/hyperref.tds.zip
cd /opt/texlive/texmf-local
unzip ../tds-packages/hyperref.tds.zip
texhash `pwd`
</source>
* it's a good idea to keep the tds packages around, so that we know which packages have been installed this way.


== Use non-TL binaries with TL data ==
== Use non-TL binaries with TL data ==
TL and all kpathsea programs use a config file called '''texmf.cnf''' to search for needed data. In previous steps we have already defined an environment variable TEXMFCNF, which causes that all kpathsea programs will read the config file located at '''/opt/texlive/2008/texmf-var/web2c/texmf.cnf'''. This is a good practice to follow, since it simplifies all configuration issues into one single, fixed place.
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  the later one(s).


Then to make  non-TL binaries work with TL data, we change texmf.cnf to get rid of '''$SELFAUTOPARENT''':
It 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'''
<geshi lang="bash">
cd /opt/texlive/2008/texmf-var/web2c
cp texmf.cnf texmf.cnf.orig
sed -i -e 's:.SELFAUTOPARENT:/mnt/texlive2008:' texmf.cnf
</geshi>


== Keeping packages up-to-date ==
Since we have already defined TEXMFCNF in previous step and made a copy of '''texmf.cnf''', now it is simple to make  non-TL binaries work with TL data: we change our '''texmf.cnf''' to get rid of SELFAUTOPARENT as follows:  
* Tell TL that we want to update packages from TL site:
<source lang="bash">
<geshi lang="bash">
sed -i -e 's:.SELFAUTOPARENT:/opt/texlive/2008:' /opt/texlive/2008/texmf.cnf
tlmgr option location http://mirror.ctan.org/systems/texlive/tlnet/2008
</source>
</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
** backup before update, so things can be reverted
** do not update all packages in one go


== Add another texmf tree ==
== 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:
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">
<source lang="bash">
ln -s /opt/tetex-3.0/share/texmf /opt/texlive/texmf-tetex
ln -s /opt/tetex-3.0/share/texmf /opt/texlive/texmf-tetex
sed -i '
sed -i '
/^TEXMFLOCAL/ a\
/^TEXMFLOCAL/ a\
TEXMFTETEX = /opt/texlive/texmf-tetex
TEXMFTETEX = /opt/texlive/texmf-tetex
s/^TEXMF = .*TEXMFLOCAL/&,!!$TEXMFTETEX/
s/^\(TEXMF = .*\)}/\1,$TEXMFTETEX}/
s/^TEXMFDBS = .*TEXMFLOCAL/&,!!$TEXMFTETEX/
' /opt/texlive/2008/texmf.cnf
s/^SYSTEXMF = .*TEXMFLOCAL/&;$TEXMFTETEX/
texhash /opt/texlive/texmf-tetex
' /opt/texlive/2008/texmf-var/web2c/texmf.cnf
</source>
</geshi>


We can repeat the above steps to add as many texmf trees as we need. For each texmf tree we must:
We can repeat the above steps to add as many texmf trees as we need. For each texmf tree we must:
Line 151: Line 144:
* adjust the above commands accordingly.
* adjust the above commands accordingly.


Or, it is possible to use the below script to automate the above steps.  
Or, it is possible to use [http://download.river-valley.com/add-texmf-tree.sh this script] to automate the above steps. Usage:
Save it to a file called eg '''add-texmf-tree.sh'''.
<source lang="bash">
<geshi lang="bash">
sh add-texmf-tree.sh TEXMFTETEX /opt/texlive/texmf-tetex /opt/texlive/2008/texmf.cnf
#!/bin/bash
</source>
# script to add a texmf tree to texmf.cnf
The script will do some checking before changing '''texmf.cnf''' to ensure that the parameters are correct. The current '''texmf.cnf''' will be backed up with timestamp appended like e.g. '''texmf.cnf--2008-10-20.19:43:05'''
# Usage: $0 <variable-name> <texmf-location> /path/to/texmf.cnf
# Example: $0 TEXMFTETEX /opt/texlive/texmf-tetex /opt/texlive/2008/texmf-var/web2c/texmf.cnf
 
# set -x
set -e
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 || \
=== Use ls-R or not ===
    ExitWithError "$CFG_FILE do not contain TEXMF; is it a texmf.cnf file?"
Each texmf tree can have a file called '''ls-R''' at the top level, which can help to speed up searching if the texmf tree is large. But using ls-R is not always the best option, since it requires some extra effort to get it right. If a texmf tree is small and changes often, it's better not to use ls-R. If a texmf tree is large, then it's worthwhile to go for the trouble.


! grep -q "^$VARNAME = " $CFG_FILE || \
To use ls-R with the texmf tree in the previous example, we must:
    ExitWithError "$VARNAME is already used in $CFG_FILE; choose a different name"
* edit texmf.cnf:
** change '''$TEXMFTETEX''' to '''!!$TEXMFTETEX''' (only on one line -- the one starting with '''TEXMF = ...'''
** add '''!!$TEXMFTETEX''' to TEXMFDBS
* run '''texhash /opt/texlive/texmf-tetex''' to make ls-R in sync with the contents of texmf tree.


Failing to do any of the above steps will cause that some files might not be found as expected, and it's not always easy to trace down the reason.


#*************************************
=== Change the order of file searching ===
# backup texmf.cnf before changing it:
If we need to change the precedence of a texmf tree, we can edit texmf.cnf and change the variable TEXMF.
#_____________________________________
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'''.  
cp texmf.cnf texmf.cnf--`date '+%Y-%m-%d.%T'`


 
=== Some notes on other relevant variables ===
#*****************
* '''TEXMFDBS''': contains list of texmf trees with '''ls-R''' filename databases. It's not clear how the presence of ls-R in a texmf tree and the presence of that tree in TEXMF and TEXMFDBS are related. To avoid potential problems, it's better to stick with either one of the below scenarios:
# change texmf.cnf
** no ls-R, no presence of texmf tree in TEXMFDBS, presence in TEXMF without '''!!'''
#_________________
** ls-R in sync with  contents of texmf tree, presence in TEXMF and TEXMFDBS with '''!!'''
sed -i "
* '''SYSTEXMF''' (not listed above): 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 writable for the current user, then the scripts '''mktexpk''', '''mktextfm''', and '''mktexmf''' will install their output into '''VARTEXFONTS''', otherwise the generated fonts (tfm/pk/mf) will be left in the current directory. If we are not using MF fonts, we can safely forget this variable. If we are using MF fonts and want the fonts generated on-the-fly to be placed to proper location, we must add the relevant texmf tree to SYSTEXMF. Usually not needed, since most TeX fonts are available in outline formats and when not, they can be easily converted from MF to Type1 format using '''textrace'''. It is best if we can avoid touching this variable.
/^TEXMFLOCAL/ a\
$VARNAME = $LOCATION
s/^TEXMF = .*TEXMFLOCAL/&,!!\$$VARNAME/
s/^TEXMFDBS = .*TEXMFLOCAL/&,!!\$$VARNAME/
s/^SYSTEXMF = .*TEXMFLOCAL/&;\$$VARNAME/
" $CFG_FILE
</geshi>
 
Some notes on the relevant variables above:
* '''TEXMF''': specifies whhich texmf trees are searched, and in which order. The order of the texmf trees given in '''TEXMF''' is important: earlier trees take predecence over 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-generating '''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'''.
* '''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 ==
== Run pdftex compiled from sources ==
Sometimes it's desirable to run a different version of pdftex than the one comming 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.
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:
* 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">
<source lang="bash">
cd $HOME/src/pdftex-1.40.9
cd $HOME/src/pdftex-1.40.9
./build.sh
./build.sh
</geshi>
</source>
* when the above process finishes, the pdftex binary should be located at '''$HOME/src/pdftex-1.40.9/build/texk/web2c/pdftex'''
* when the above process finishes, the pdftex binary should be located at '''$HOME/src/pdftex-1.40.9/build/texk/web2c/pdftex'''
* edit '''/home/opt/texlive/2008/texmf-var/web2c/fmtutil.cnf''' to apply the below changes:
<geshi lang="diff">
$ diff -u fmtutil.cnf.orig fmtutil.cnf
--- fmtutil.cnf.orig    2008-09-21 17:03:06.642547786 +0200
+++ fmtutil.cnf 2008-09-21 17:03:11.086872146 +0200
@@ -95,6 +95,7 @@
# $Id: format.latex.cnf 9357 2008-07-08 11:58:23Z preining $
latex          pdftex language.dat    -translate-file=cp227.tcx *latex.ini
pdflatex        pdftex language.dat    -translate-file=cp227.tcx *pdflatex.ini
+pdflatex2        pdftex2      language.dat    -translate-file=cp227.tcx *pdflatex2.ini
#
lualatex        luatex  language.dat    lualatex.ini
pdflualatex    luatex  language.dat    pdflualatex.ini
@@ -126,6 +127,7 @@
etex          pdftex  language.def    -translate-file=cp227.tcx *etex.ini
pdfetex                pdftex  language.def    -translate-file=cp227.tcx *pdfetex.ini
pdftex        pdftex  language.def    -translate-file=cp227.tcx *pdfetex.ini
+pdftex2                pdftex2 language.def    -translate-file=cp227.tcx *pdfetex2.ini
# ------------------------------------------------------------------
# $Id: format.physe.cnf 8442 2008-05-31 23:30:56Z karl $
physe          pdftex -              physe.ini
</geshi>
* create a file '''$HOME/texmf/tex/generic/config/pdfetex2.ini''' with the contents
<geshi lang="tex">
\input pdfetex.ini
</geshi>
* create a file '''$HOME/texmf/tex/generic/config/pdflatex2.ini''' with the contents
<geshi lang="tex">
\input pdflatex.ini
</geshi>
* make symlinks (suppose that '''$HOME/bin''' is in '''$PATH'''):
* make symlinks (suppose that '''$HOME/bin''' is in '''$PATH'''):
<geshi lang="bash">
<source 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/pdftex2
ln -s $HOME/src/pdftex-1.40.9/build/texk/web2c/pdftex $HOME/bin/pdflatex2
ln -s $HOME/src/pdftex-1.40.9/build/texk/web2c/pdftex $HOME/bin/pdflatex2
</geshi>
</source>
* find out the location of format files:
<source lang="bash">
ls -d $(dirname $(kpsewhich -engine=pdftex pdflatex.fmt) )
/opt/texlive/2008/texmf-var/web2c/pdftex
</source>
* create formats:
* create formats:
<geshi lang="bash">
<source lang="bash">
fmtutil --byfmt pdftex2
cd /tmp
fmtutil --byfmt pdflatex2
 
</geshi>
pdftex2 -ini -translate-file=cp227.tcx '*pdfetex.ini'
* the new formats will be located in '''$HOME/.texlive2008/texmf-var/web2c/pdftex2'''. To make it searchable to pdftex, we need to:
mv pdfetex.fmt /opt/texlive/2008/texmf-var/web2c/pdftex/pdftex2.fmt
<geshi lang="bash">
 
ln -s $HOME/.texlive2008/texmf-var/web2c/pdftex2 $HOME/.texlive2008/texmf-var/web2c/pdftex
pdflatex2 -ini -translate-file=cp227.tcx '*pdflatex.ini'
</geshi>
mv pdflatex.fmt /opt/texlive/2008/texmf-var/web2c/pdftex/pdflatex2.fmt
 
texhash
</source>
* test the new binary:
* test the new binary:
<geshi lang="bash">
<source lang="bash">
pdftex2 story \\bye
pdftex2 story \\bye
pdflatex2 sample2e
pdflatex2 sample2e
</geshi>
</source>
* repeat the above steps for other versions if needed; substitute pdftex2/pdflatex2 with whichever names that suit better your need/taste.


== Maintain packages installed locally ==
== 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.
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.
===Install miktex tools===
* download miktex sources from http://miktex.org/SourceCode.aspx
* unpack the source tarball to $HOME/src/miktex-2.7.3135
* install all PREREQUISITES listed in ~/src/miktex-2.7.3135/README.unx
* compile and install:
<source lang="bash">
cmake -G "Unix Makefiles" -DMIKTEX_INSTALLROOT=/opt/texlive/texmf-local -DCMAKE_INSTALL_PREFIX=/opt/miktex-2.7.3135
make
make install
</source>
* if things go well, the miktex tools will be installed to /opt/miktex-2.7.3135.
* '''TODO''': we will make a tarball of pre-compiled miktex tools binaries for i386-linux and x86_64-linux, to save the compilation step for you. Then to install it, one can simply unpack the tarball to '''/opt'''.
* we need to make a wrapper to run miktex tools. Create a file named '''run-miktex-tools''' with file mode 755 and with the following contents:
<source lang="bash">
#!/bin/bash                       
export LD_LIBRARY_PATH=/opt/miktex-2.7.3135/lib
export PATH=/opt/miktex-2.7.3135/bin:$PATH
 
opt="--repository=/opt/miktex-repository/package-repository"
tool=$1                           
shift                             
 
ExecCmd() {
    echo "$@"                     
    "$@"                         
}
 
case "$tool" in                   
mpm|mpc)
    ExecCmd $tool $opt "$@"       
    ;;
*)
    ExecCmd $tool "$@"           
    ;;                           
esac                             
exit                             
</source>
* test if it works -- we should get help messages on mpm usage from the below command:
<source lang="bash">
run-miktex-tools mpm --help
</source>
* up to this point, miktex tools are setup so that it will look for available packages at '''/opt/miktex-repository/package-repository''' and install requested packages to '''/opt/texlive/texmf-local'''.
===Set up miktex repository===
Before we can use miktex tools to install any packages, we must set up the local package repository.
<source lang="bash">
mkdir -p  /opt/miktex-repository/package-repository
cd /opt/miktex-repository/package-repository
wget http://www.ctan.org/tex-archive/systems/win32/miktex/tm/packages/miktex-zzdb1-2.7.tar.lzma
wget http://www.ctan.org/tex-archive/systems/win32/miktex/tm/packages/miktex-zzdb2-2.7.tar.lzma
run-miktex-tools mpm --update-db
</source>
===Create a package for use with miktex tools===
Suppose we have a texmf tree and we want to create a package from that texmf tree.


(''to be continued'')
(''to be continued'')

Latest revision as of 03:12, 17 July 2018

Introduction

This page describes steps to install 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.04 and should work with no or little change for other Linux/UNIX systems.

When in doubt, please refer to the 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
printenv | fgrep TEX
cd $HOME/iso-images
unlzma texlive2008.iso.lzma
  • mount the TL image:
mkdir -p /mnt/texlive2008
mount -t iso 9660 -o loop $HOME/iso-images/texlive2008.iso /mnt/texlive2008/
  • run the TL installer:
perl /mnt/texlive2008/install-tl
  • in next menu, change the destination of installation to /opt/texlive/2008 by entering:
d<Enter>
1<Enter>
/opt/texlive/2008<Enter>
r<Enter>
  • start the installation process by entering i<Enter>. When the installation process is done, the last messages should look like this:
 .
 .
 .
 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
  • 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):
cat /opt/texlive/2008/texmf/web2c/texmf.cnf | \
grep 'SELFAUTOPARENT\|^TEXMF \|^TEXMFDBS ' | \
grep -v '^%' > /opt/texlive/2008/texmf.cnf
  • 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):
## 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
  • 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:
exec bash -login
  • test the installation:
pdflatex sample2e
  • if things go well, we should get a log similar to the below:
$ 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.

Keeping packages up-to-date

There are 2 possible ways to keep packages up-to-date:

mkdir -p /opt/texlive/tds-packages
cd /opt/texlive/tds-packages
wget http://tug.org/applications/hyperref/ftp/hyperref.tds.zip 
cd /opt/texlive/texmf-local
unzip ../tds-packages/hyperref.tds.zip
texhash `pwd`
  • it's a good idea to keep the tds packages around, so that we know which packages have been installed this way.

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 the later one(s).

It 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

Since we have already defined TEXMFCNF in previous step and made a copy of texmf.cnf, now it is simple to make non-TL binaries work with TL data: we change our texmf.cnf to get rid of SELFAUTOPARENT as follows:

sed -i -e 's:.SELFAUTOPARENT:/opt/texlive/2008:' /opt/texlive/2008/texmf.cnf

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:

ln -s /opt/tetex-3.0/share/texmf /opt/texlive/texmf-tetex
sed -i '
/^TEXMFLOCAL/ a\
TEXMFTETEX = /opt/texlive/texmf-tetex
s/^\(TEXMF = .*\)}/\1,$TEXMFTETEX}/
' /opt/texlive/2008/texmf.cnf
texhash /opt/texlive/texmf-tetex

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 this script to automate the above steps. Usage:

sh add-texmf-tree.sh TEXMFTETEX /opt/texlive/texmf-tetex /opt/texlive/2008/texmf.cnf

The script will do some checking before changing texmf.cnf to ensure that the parameters are correct. The current texmf.cnf will be backed up with timestamp appended like e.g. texmf.cnf--2008-10-20.19:43:05

Use ls-R or not

Each texmf tree can have a file called ls-R at the top level, which can help to speed up searching if the texmf tree is large. But using ls-R is not always the best option, since it requires some extra effort to get it right. If a texmf tree is small and changes often, it's better not to use ls-R. If a texmf tree is large, then it's worthwhile to go for the trouble.

To use ls-R with the texmf tree in the previous example, we must:

  • edit texmf.cnf:
    • change $TEXMFTETEX to !!$TEXMFTETEX (only on one line -- the one starting with TEXMF = ...
    • add !!$TEXMFTETEX to TEXMFDBS
  • run texhash /opt/texlive/texmf-tetex to make ls-R in sync with the contents of texmf tree.

Failing to do any of the above steps will cause that some files might not be found as expected, and it's not always easy to trace down the reason.

Change the order of file searching

If we need to change the precedence of a texmf tree, we can edit texmf.cnf and change the variable TEXMF. 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.

Some notes on other relevant variables

  • TEXMFDBS: contains list of texmf trees with ls-R filename databases. It's not clear how the presence of ls-R in a texmf tree and the presence of that tree in TEXMF and TEXMFDBS are related. To avoid potential problems, it's better to stick with either one of the below scenarios:
    • no ls-R, no presence of texmf tree in TEXMFDBS, presence in TEXMF without !!
    • ls-R in sync with contents of texmf tree, presence in TEXMF and TEXMFDBS with !!
  • SYSTEXMF (not listed above): 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 writable for the current user, then the scripts mktexpk, mktextfm, and mktexmf will install their output into VARTEXFONTS, otherwise the generated fonts (tfm/pk/mf) will be left in the current directory. If we are not using MF fonts, we can safely forget this variable. If we are using MF fonts and want the fonts generated on-the-fly to be placed to proper location, we must add the relevant texmf tree to SYSTEXMF. Usually not needed, since most TeX fonts are available in outline formats and when not, they can be easily converted from MF to Type1 format using textrace. It is best if we can avoid touching this variable.

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:
cd $HOME/src/pdftex-1.40.9
./build.sh
  • 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):
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
  • find out the location of format files:
ls -d $(dirname $(kpsewhich -engine=pdftex pdflatex.fmt) )
/opt/texlive/2008/texmf-var/web2c/pdftex
  • create formats:
cd /tmp

pdftex2 -ini -translate-file=cp227.tcx '*pdfetex.ini'
mv pdfetex.fmt /opt/texlive/2008/texmf-var/web2c/pdftex/pdftex2.fmt

pdflatex2 -ini -translate-file=cp227.tcx '*pdflatex.ini'
mv pdflatex.fmt /opt/texlive/2008/texmf-var/web2c/pdftex/pdflatex2.fmt

texhash
  • test the new binary:
pdftex2 story \\bye
pdflatex2 sample2e
  • repeat the above steps for other versions 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.

Install miktex tools

  • download miktex sources from http://miktex.org/SourceCode.aspx
  • unpack the source tarball to $HOME/src/miktex-2.7.3135
  • install all PREREQUISITES listed in ~/src/miktex-2.7.3135/README.unx
  • compile and install:
cmake -G "Unix Makefiles" -DMIKTEX_INSTALLROOT=/opt/texlive/texmf-local -DCMAKE_INSTALL_PREFIX=/opt/miktex-2.7.3135
make
make install
  • if things go well, the miktex tools will be installed to /opt/miktex-2.7.3135.
  • TODO: we will make a tarball of pre-compiled miktex tools binaries for i386-linux and x86_64-linux, to save the compilation step for you. Then to install it, one can simply unpack the tarball to /opt.
  • we need to make a wrapper to run miktex tools. Create a file named run-miktex-tools with file mode 755 and with the following contents:
#!/bin/bash                        
export LD_LIBRARY_PATH=/opt/miktex-2.7.3135/lib
export PATH=/opt/miktex-2.7.3135/bin:$PATH
  
opt="--repository=/opt/miktex-repository/package-repository"
tool=$1                            
shift                              
  
ExecCmd() {
    echo "$@"                      
    "$@"                           
} 
  
case "$tool" in                    
mpm|mpc)
    ExecCmd $tool $opt "$@"        
    ;;
*)
    ExecCmd $tool "$@"             
    ;;                             
esac                               
exit
  • test if it works -- we should get help messages on mpm usage from the below command:
run-miktex-tools mpm --help
  • up to this point, miktex tools are setup so that it will look for available packages at /opt/miktex-repository/package-repository and install requested packages to /opt/texlive/texmf-local.

Set up miktex repository

Before we can use miktex tools to install any packages, we must set up the local package repository.

mkdir -p  /opt/miktex-repository/package-repository
cd /opt/miktex-repository/package-repository
wget http://www.ctan.org/tex-archive/systems/win32/miktex/tm/packages/miktex-zzdb1-2.7.tar.lzma
wget http://www.ctan.org/tex-archive/systems/win32/miktex/tm/packages/miktex-zzdb2-2.7.tar.lzma
run-miktex-tools mpm --update-db

Create a package for use with miktex tools

Suppose we have a texmf tree and we want to create a package from that texmf tree.

(to be continued)