3 Unix installation

As introduced in section 1.1 on p. 8, TeX Live has three principal uses:

  1. Run directly from media.
  2. Install to disk.
  3. Integrate a particular package or collection into your existing TeX installation.

The following sections describes the Unix-specific procedures for each of these.


Warning: The TeX-Collection CDs and DVD are in ISO 9660 (High Sierra) format, with Rock Ridge (and Joliet, for Windows) extensions. Therefore, in order to take full advantage of the TeX-Collection under Unix, your system needs to be able to use the Rock Ridge extensions. Please consult the documentation for your mount command to see how to do this. If you have several different machines on a local network, you may be able to mount the CDs on one which does support Rock Ridge, and use this with the others.

Linux, FreeBSD, Sun, SGI and Alpha systems should be able to use the CDs without problems. We would appreciate receiving detailed advice from users on other systems who succeed, for future versions of this documentation.

The discussion below assumes you have been able to mount the CDs with full Rock Ridge compatibility.


3.1 Running TeX Live directly from media (Unix)

Only Linux, Mac OS X, and Windows binaries are included on the demo CD; if you want to run live on other Unix systems, you’ll need to use the DVD.

To start, we must mount the CD or DVD, with Rock Ridge extensions enabled. The exact command to do this varies from system to system; the following works under Linux, except the name of the device ( /dev/cdrom, here) may vary. (All our examples will use > as the shell prompt; user input is underlined.)

> mount -t iso9660 /dev/cdrom /mnt/cdrom

Change the current directory to the mount point:

> cd /mnt/cdrom

Under Mac OS X, the directory is typically under /Volumes, and the media will be mounted automatically.

Run the installation script install-tl.sh:


> sh install-tl.sh
Welcome to TeX Live...

After various greeting messages and a list of the main menu options, the installation will ask you to enter a command. Do this by typing the desired character and hitting return; don’t type the angle brackets. Either uppercase or lowercase is ok; we’ll use lowercase in our examples.

For running live, our first command will be d and then the subcommand 1 to set directories. Even in this case, we must choose a directory on the local disk to place files that the TeX system itself generates, such as fonts and formats, and also to provide a place for updated configuration files, if need be. We’ll use /usr/local/texmf-local in this example. (If the default value of /usr/TeX works for you, then you can skip this step.)


Enter command: d
Current directories setup:
<1>  TEXDIR:     /usr/TeX
...
Enter command: 1
New value for TEXDIR [/usr/TeX]: /usr/local/texmf-local
...
Enter command: r

Back at the main menu, our second and last command is r, to set up for running live off the media without installing to disk:


Enter command: r
Preparing destination directories...
...
Welcome to the TeX Live system!
>

And we are back at the system prompt, as shown.

Next, it is necessary to alter two environment variables: PATH, to an architecture-dependent value (so that we can run the programs), and VARTEXMF, to the value specified above. See table 1 for a list of the architecture names for the different systems, and whether they are available on the demo CD. All systems are available in the inst and live distributions. (In addition to the version-specific names listed here, there are generic names without the version numbers. For instance, sparc-solaris links to sparc-solaris2.7. The generic names can be used to protect against the version numbers changing in the future, if you wish.)

After the main installation has completed, and environment variables have been set, the next step is to run texconfig to customize your installation for your needs. This is explained in section 4.1, p. 29.


Table 1: Supported system architectures.
alpha-linux HP Alpha Linux
alphaev5-osf4.0d HP Alphaev5 OSF
i386-freebsd4.8 Intel x86 FreeBSD
i386-linux Intel x86 GNU/Linux demo CD
i386-openbsd3.3 Intel x86 OpenBSD
i386-solaris2.8 Intel x86 Solaris
mips-irix6.5 SGI IRIX
powerpc-aix4.3.3.0 IBM RS/6000 AIX
powerpc-darwin6.3 Mac OS X demo CD
sparc-solaris2.7 Sun Sparc Solaris
sparc64-linux Sun Sparc Linux
win32 Windows (32-bit) demo CD




The syntax for setting the environment variables, and the initialization file to put them in, depends on the shell you use. If you use a Bourne-compatible shell (sh, bash, ksh, et al.), put the following into your $HOME/.profile file:


PATH=/mnt/cdrom/bin/archname:$PATH; export PATH
VARTEXMF=/usr/local/texmf-local/texmf-var; export VARTEXMF

For C shell-compatible shells (csh, tcsh), put the following into your $HOME/.cshrc file:


setenv PATH /mnt/cdrom/bin/archname:$PATH
setenv VARTEXMF /usr/local/texmf-local/texmf-var

Then log out, log back in, and test your installation (see section 4.2 on p. 30).

If in doubt, please ask any local system gurus to help you with problems; for example, the way to mount the TeX Live media, which directory or directories to use, and precise details of the changes to your personal initialization files can and do vary from site to site.

3.2 Installing TeX Live to disk

It is possible, indeed typical, to install the TeX system from the TeX Live to disk. This can be done either from the live DVD, or the inst CD. It can also be done from the demo CD, if you don’t need the omitted packages or systems. (See section 2.1 on p. 10 for an explanation of the different distributions.)

To start, we must mount the CD or DVD, with Rock Ridge extensions enabled. The exact command to do this varies from system to system; the following works under Linux, except the name of the device ( /dev/cdrom, here) may vary. (All our examples will use > as the shell prompt; user input is underlined.)

> mount -t iso9660 /dev/cdrom /mnt/cdrom

Change the current directory to the mount point:

> cd /mnt/cdrom

Under Mac OS X, the directory is typically under /Volumes, and the media will be mounted automatically.

Run the installation script install-tl.sh:


> sh install-tl.sh
Welcome to TeX Live...

After various greeting messages and a list of the main menu options, the installation will ask you to enter a command. Do this by typing the desired character and hitting return; don’t type the angle brackets. Either uppercase or lowercase is ok; we’ll use lowercase in our examples.

Here is an introductory list of the options in the main menu. The order in which you select the options makes little difference, except that i must be last. It’s reasonable to go through them in the order presented here.


Table 2: Main menu options for the installation.
p The system you are running on.
b The architectures to install binaries for.
s The base installation scheme to use (minimal, recommended, full, etc.)
c Override the installation scheme for individual collections.
l Override for language collections.
d Directories in which to install.
o General options.
i Perform the installation.

Here are further details on each option.

p – Current platform. Since the installation script automatically guesses which platform you’re running on, this is generally unnecessary to override. It’s there in case the automatic detection fails.

b – Binary architectures. By default, only the binaries for your current platform will be installed. From this menu, you can select installation of binaries for other architectures as well (or not install the current platforms). This is often useful if you are sharing a TeX tree across a network of heterogenous machines. For a list of the supported architectures, see table 1, p. 19.

s – Base installation scheme. From this menu, you can choose an overall common set of packages. The default is a recommended set for typical needs, but you can also choose a basic set to conserve disk space, or a full set to get absolutely everything. The Live scheme is used for creating the TeX Live demo distribution itself, and isn’t generally useful to select for a particular site. There are also specific sets for Omega and XML users.

c – Individual collections. From this menu, you can override the basic scheme’s choice of which collections to install. Each collection — TeX macro files, Metafont font families, and so on — consists of several packages. In this menu, selection letters are case-sensitive.

l – Language collections. This menu has the same basic functionality as c, to override collection choices. In this case, the collections are specifically for different languages. Selection letters are case-sensitive here. Here is a list of the language collections in TeX Live:

(some) African scripts Armenian Chinese,Japanese,Korean Croatian

Cyrillic Czech/Slovak Danish Dutch

Finnish French German Greek

Hungarian Indic Italian Latin

Manju Mongolian Norwegian Polish

Portuguese Spanish Swedish Tibetan

UK English Vietnamese

Language collections typically includes fonts, macros, hyphenation patterns, and other support files. (For instance, frenchle.sty is installed if you select the French collection.) In addition, installing a language collection will alter the language.dat configuration file controlling which hyphenations are loaded.

d – Installation directories. Three directories can be changed here:

TEXDIR
By default, the top-level directory under which everything else will be installed. The default value is /usr/TeX, and is often changed. For example, changing to a value such as /usr/local/ texlive2003 would make it possible to keep different releases of TeX Live separate. You may then wish to make /usr/local/texlive a symbolic link, after testing the new release.

Under Mac OS X, the usual frontends look for TeX in /usr/local/teTeX, so you may wish to install TeX Live there.

TEXMFLOCAL
This tree is where the TeX system scripts install non-version-specific files, primarily fonts. The default value is TEXDIR/texmf-local. It’s also the recommended location to put any local packages or configuration settings. Therefore, it’s desirable to change it to a location independent of the current TeX Live release; for example, /usr/local/texmf-local.
VARTEXMF
This tree is where the scripts install files that are version-specific, primarily format files and the configuration files which are modified by texconfig (see section 4.1, p. 29). The default value is TEXDIR/texmf-var, and there’s generally no reason to change it.

o - General options. From this menu, you can select three general options affecting the installation:

a
Specify an alternate directory for generated fonts. The default is to use the VARTEXMF tree, as explained above. Setting this is useful if you plan to mount the main tree read-only, and therefore another location (perhaps machine-specific) must be used for dynamically created fonts.
l
Create symbolic links for the binaries, man pages, and/or GNU Info files in other locations. For example, you may wish to make the man pages available under /usr/local/man and the Info files available under /usr/local/info. (Of course you need appropriate privileges to write in the specified directories.)
d
Skip installation of the font/macro documentation tree. This is useful to save space, or if you’ve previously installed the documentation elsewhere.
s
Skip installation of the main font/macro source tree. This is useful if you are arranging to share that tree between machines and/or architectures in some other way, such as NFS or automount.

i - Perform installation. When you’re satisfied with your configuration options, enter i to actually do the installation from the media to your chosen locations.

The last step is to include the architecture-specific subdirectory of TEXDIR/bin in your PATH, so the newly-installed programs can be found. The architecture names are listed in table 1, p. 19, or you can simply list the directory TEXDIR/bin.

The syntax for doing this, and the initialization file to put it in, depends on the shell you use. If you use a Bourne-compatible shell (sh, bash, ksh, et al.), put the following into your $HOME/.profile file:


PATH=/TEXDIR/bin/archname:$PATH; export PATH

For C shell-compatible shells (csh, tcsh), put the following into your $HOME/.cshrc file:


setenv PATH /TEXDIR/bin/archname:$PATH

After the main installation has completed, and environment variables have been set, the next step is to run texconfig to customize your installation for your needs. This is explained in section 4.1, p. 29.

Here is a brief annotated example which selects a full installation, with binaries for the current system only, with directory changes as recommended above. The prompts and RETURN keys are omitted for brevity.


> sh install-tl.sh
s b r                     # scheme, full, return to main
d                         # change directories
1 /usr/local/texlive2003  # top-level dir
2 /usr/local/texmf-local  # TEXMFLOCAL outside TEXDIR
r                         # return to main
i                         # perform installation
> texconfig ...
# New PATH, assuming Linux:
> PATH=/usr/local/texlive2003/bin/i386-linux:$PATH; export PATH

If in doubt, please ask any local system gurus to help you with problems; for example, the way to mount the TeX Live media, which directory or directories to use, and precise details of the changes to your personal initialization files can and do vary from site to site.

3.3 Installing individual packages to disk

You can add individual packages or collections from the current distribution to an existing non-TeX Live setup, or an earlier TeX Live installation. You can do this from the demo CD or the live DVD, but not from the inst CD. (See section 2.1 on p. 10.)

To start, we must mount the CD or DVD, with Rock Ridge extensions enabled. The exact command to do this varies from system to system; the following works under Linux, except the name of the device ( /dev/cdrom, here) may vary. (All our examples will use > as the shell prompt; user input is underlined.)

> mount -t iso9660 /dev/cdrom /mnt/cdrom

Change the current directory to the mount point:

> cd /mnt/cdrom

Under Mac OS X, the directory is typically under /Volumes, and the media will be mounted automatically.

Run the installation script install-pkg.sh (not install-tl.sh, which is intended for complete installations only):


> sh install-pkg.sh options

This first set of options controls what gets read:

--package=pkgname
The individual package to work on.
--collection=colname
The individual collection to work on.
--nodoc
Exclude documentation files from the operation.
--nosrc
Exclude source files from the operation.
--cddir=dir
Source directory to read from; defaults to the current directory. If you followed the instructions above, that will be the distribution directory, and won’t need to be changed.
--listdir=dir
The so-called ‘lists’ directory within cddir from which to read the package information. The default is cddir/texmf/tpm/lists; the only reason to change it is if you’re making changes to TeX Live yourself.

What actually happens is controlled by the following options. If neither of these are specified, the default action is to install the selected files. The main destination tree is found by expanding $TEXMFMAIN with kpsewhich. You can override it by setting either the environment variable TEXMFMAIN or TEXMF.

--listonly
List the files that would be installed, but don’t actually install anything.
--archive=tarfile
Instead of installing the files into the TeX system, make a tar archive.

Additional options:

--config
After installation, run texconfig init.
--nohash
After installation, don’t run mktexlsr to rebuild the filename database.
--verbose
Give more information as the script runs.

Here are some usage examples:

  1. To see the files in the package fancyhdr without installing it:

    > sh install-pkg.sh --package=fancyhdr --listonly

    texmf/doc/latex/fancyhdr/README
    texmf/doc/latex/fancyhdr/fancyhdr.dvi
    texmf/doc/latex/fancyhdr/fancyhdr.pdf
    ...
  2. Install the LaTeX package natbib:

    > sh install-pkg.sh --package=natbib
  3. Install the LaTeX package alg without source files or documentation:

    > sh install-pkg.sh  --package=alg --nosrc --nodoc
  4. Install all the packages in the collection of additional plain TeX macros:

    > sh install-pkg.sh --collection=tex-plainextra
  5. Write all files in the pstricks package to a tar file in /tmp:

    > sh install-pkg.sh --package=pstricks --archive=/tmp/pstricks.tar

If in doubt, please ask any local system gurus to help you with problems; for example, the way to mount the TeX Live media, which directory or directories to use, and precise details of the changes to your personal initialization files can and do vary from site to site.