summaryrefslogtreecommitdiff
path: root/Master/texmf-doc/source/english/texlive-en/installation.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-doc/source/english/texlive-en/installation.tex')
-rw-r--r--Master/texmf-doc/source/english/texlive-en/installation.tex552
1 files changed, 552 insertions, 0 deletions
diff --git a/Master/texmf-doc/source/english/texlive-en/installation.tex b/Master/texmf-doc/source/english/texlive-en/installation.tex
new file mode 100644
index 00000000000..29b6be4eb7c
--- /dev/null
+++ b/Master/texmf-doc/source/english/texlive-en/installation.tex
@@ -0,0 +1,552 @@
+\section{Unix installation}
+\label{sec:unix-install}
+
+As introduced in section~\ref{sec:basic} (\p.\pageref{sec:basic}),
+\TL{} has three principal uses:
+
+\begin{enumerate}
+\item Run directly from media.
+\item Install to disk.
+\item Integrate a particular package or collection into your existing
+\TeX{} installation.
+\end{enumerate}
+
+\noindent The following sections describes the Unix-specific procedures
+for each of these.
+
+\ifSingleColumn \begin{figure}[ht]\noindent \fi
+\begin{warningbox}
+\textbf{Warning: } The \TK{} \CD{}s and \DVD{} are in ISO 9660 (High Sierra)
+format, \emph{with} Rock Ridge (and Joliet, for Windows)
+extensions. Therefore, in order to take full advantage of the \TK{}
+under Unix, your system needs to be able to use the Rock Ridge
+extensions. Please consult the documentation for your \cmdname{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 discs on one which
+does support Rock Ridge, and use this with the others.
+
+\leavevmode\quad Modern systems should be able to use the discs without
+problems. If troubles, let us know. The discussion below assumes you
+have been able to mount the \CD{}s with full Rock Ridge compatibility.
+\end{warningbox}
+\ifSingleColumn\end{figure}\fi
+
+
+%
+\subsection{Portable \protect\TL{} on DVD and USB (Unix)}
+\label{sec:portable-unix}
+
+\def\runlive{% text repeated in windows section
+It is possible to use the \TeX{} system directly from the \pkgname{live}
+\DVD{}, without installing the distribution to hard disk. (Thus the
+name \TeX\ `Live', in fact.) It is \emph{not} possible to run \TeX{}
+directly from the other \CD{}s (see section~\ref{sec:multiple-dist},
+\p.\pageref{sec:multiple-dist}).
+}
+
+\def\startinst{% repeated in other subsections
+To start, you 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 \acro{GNU}/Linux, except the name of the device
+(\filename{/dev/cdrom}, here) may vary. (All our examples will use
+\texttt{>} as the shell prompt; user input is
+\Ucom{\texttt{underlined}}.)
+\begin{alltt}
+> \Ucom{mount -t iso9660 /dev/cdrom /mnt/cdrom}
+\end{alltt}
+
+\noindent Change the current directory to the mount point:
+\begin{alltt}
+> \Ucom{cd /mnt/cdrom}
+\end{alltt}
+
+\noindent (Under \MacOSX, the directory is typically under
+\dirname{/Volumes}, and the media will be mounted automatically.)
+
+Your \code{umask} at the time of installation will be respected by the
+\TL{} installer. Therefore, if you want your installation to be usable
+by users other than you, make sure your setting is sufficiently
+permissive, for instance, \code{umask 002}. For more information about
+\code{umask}, consult your system documentation.
+
+}
+
+\runlive
+\startinst
+
+Then, in a terminal, run this command:
+
+\begin{alltt}
+> \Ucom{sh tl-portable.sh}
+\end{alltt}
+
+This \filename{tl-portable.sh} script is at the top level of the
+distribution. It starts up a secondary shell with the necessary
+environment settings. When it runs for the first time, some files will
+be generated in a directory \dirname{~/.texlive2008}. On subsequent
+runs, though, it will start almost instantaneously.
+
+You can run several parallel \TL{} sessions this way, each in a
+different terminal.
+
+You can also use \filename{tl-portable.sh} to run \TL{} on a \acro{USB}
+stick. In this case, copy all the top-level files and the contents of
+the \dirname{bin}, \dirname{texmf}, \dirname{texmf-dist}, and
+\dirname{tlpkg} directories (at least) to the stick. A
+\dirname{texmf-local} directory on the stick will also be found and
+used. Then run \filename{tl-portable.sh} from the root of the stick, as
+above. In this case, the script will notice that the stick is writable
+and use it for generated files. You could probably burn the resulting contents
+of the stick back to \DVD{} if that's more convenient to (for example) give
+to others.
+
+\def\textifindoubt{%
+If in doubt, please ask any local system gurus to help you with
+problems; for example, the way to mount the \TL{} 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.
+}
+
+
+
+%
+\subsection{Installing \protect\TeX\protect\ Live to disk}
+\label{sec:unix-install-disk}
+
+It is possible, indeed typical, to install the \TL{} distribution to
+hard disk. This can be done from either the \pkgname{live} or
+\pkgname{inst} distributions. (See section~\ref{sec:multiple-dist},
+\p.\pageref{sec:multiple-dist}, for an explanation of the different
+distributions.)
+
+\startinst
+
+Run the installation script \filename{install-tl.sh}:
+\begin{alltt}
+> \Ucom{sh install-tl.sh}\\
+Welcome to TeX Live...
+\end{alltt}
+
+\noindent 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 shown. Either uppercase or lowercase is ok; we'll use
+lowercase in our examples.
+
+Table~\ref{tab:main-menu-options} briefly lists the options in the main
+menu. The order in which you select the options makes little
+difference, except that \Ucom{i} must be last. It's reasonable to go
+through them in the order presented here.
+
+% apparently here.sty [H] doesn't support table*.
+\begin{table}[H]
+\caption{Main menu options for the installation.}
+\label{tab:main-menu-options}
+\begin{tabular}{>{\ttfamily}ll}
+p & The platform you are running on.\\
+b & The architectures for which to install binaries.\\
+s & The base installation scheme to use (minimal, recommended,
+ full, etc.)\\
+c & Override the base scheme for individual collections.\\
+l & Override for language collections.\\
+d & Directories in which to install.\\
+o & Other options.\\
+i & Perform the installation.\\
+\end{tabular}
+\end{table}
+
+Here are further details on each option.
+
+\textbf{\optname{p} -- Current platform.} Since the installation script
+automatically guesses which platform you're running on, it is usually
+unnecessary to use this option. It's there in case you need to override
+the automatic detection.
+
+\textbf{\optname{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 omit installing the current platform). This can be useful if you are
+sharing a \TeX\ tree across a network of heterogenous machines. For a
+list of the supported architectures, see table~\ref{tab:archlist},
+\p.\pageref{tab:archlist}.
+
+\textbf{\optname{s} -- Base installation scheme.} From this menu, you
+can choose an overall set of package collections, called a ``scheme''.
+The default \optname{full} scheme installs everything available, but you
+can also choose the \optname{basic} scheme for a minimal system, or
+\optname{medium} to get something in between. There are also specific
+sets for Omega and \acro{XML}.
+
+\textbf{\optname{c} -- Individual collections.} From this menu, you can
+override the scheme's set of collections to install. Collections are
+one level more detailed than schemes\Dash collections consist of one or
+more packages, where packages (the lowest level grouping in \TL) contain
+the actual \TeX\ macro files, font families, and so on. In this menu,
+selection letters are case-sensitive.
+
+\textbf{\optname{l} -- Language collections}. This menu has the same
+basic purpose as \Ucom{c}, to override the collection set in the chosen
+scheme. In this case, the collections are specifically for different
+languages. Selection letters are case-sensitive here too. Here is a
+list of the language collections in \TL:
+
+% xx really should generate list from texmf/tpm/collection/tex-lang*
+% a la install-tl.sh.
+\begin{tabbing}
+\hspace{.25\linewidth} \=
+\hspace{.25\linewidth} \=
+\hspace{.25\linewidth} \=
+\hspace{.25\linewidth} \kill
+(some) African scripts \>
+Arabic \>
+Armenian \>
+Chinese\,Japanese\,Korean \\
+Croatian \>
+Cyrillic \>
+Czech/Slovak \>
+Danish \\
+Dutch \>
+Finnish \>
+French \>
+German \\
+Greek \>
+Hebrew \>
+Hungarian \>
+Indic \\
+Italian \>
+Latin \>
+Manju \>
+Mongolian \\
+Norwegian \>
+Polish \>
+Portuguese \>
+Spanish \\
+Swedish \>
+Tibetan \>
+\acro{UK} English \>
+Vietnamese \\
+\end{tabbing}
+
+\noindent Language collections typically include fonts, macros,
+hyphenation patterns, and other support files. (For instance,
+\pkgname{frenchle.sty} is installed if you select the \optname{French}
+collection.) In addition, installing a language collection will alter
+the \filename{language.dat} configuration file controlling which
+hyphenation patterns are loaded.
+
+\textbf{\optname{d} -- Installation directories}. The following
+directories can be changed here:
+\label{text:instdir}
+
+\begin{ttdescription}
+\item [TEXDIR] The top-level directory under which
+everything else will be installed. The default value is
+\dirname{/usr/local/texlive/2007}, and is often changed. We recommend
+including the year in the name, to keep different releases of \TL{}
+separate. (You may wish to make a version-independent name such
+\dirname{/usr/local/texlive-cur} via a symbolic link, which you can then
+update after testing the new release.)
+
+Under \MacOSX, the usual frontends look for \TeX{} in
+\dirname{/usr/local/teTeX}, so you may wish to install \TL{} there.
+
+If you use a \path|~| in this value, it is immediately expanded to your
+home directory (and this is reflected in the prompt). The expanded
+value is also used in the custom configuration files written by the
+installer.
+
+\item [TEXMFLOCAL] This tree is the recommended location to for any
+locally-created or installed packages or configuration files. The
+default value is \dirname{/usr/local/texlive/texmf-local}, independent
+of the current \TL{} release.
+
+\item [TEXMFSYSVAR] This tree is where \cmdname{texconfig-sys} puts
+files that \emph{are} version-specific. The default value is
+\dirname{TEXDIR/texmf-var}, and there's generally no reason to change
+it. See section~\ref{sec:texconfig}, \p.\pageref{sec:texconfig} for
+more information.
+
+\item [TEXMFHOME] This tree is the recommended location for personal
+macro files or packages. The default value is \dirname{~/texmf}. In
+contrast to \dirname{TEXDIR}, here a \path|~| is preserved in the
+newly-written configuration files, since it usefully refers to the home
+directory of each individual running \TeX. It expands to
+\filename{\$HOME} on Unix and \filename{\%USERPROFILE\%} on Windows.
+
+\end{ttdescription}
+
+\textbf{\optname{o} -- Other options.} From this menu, you can select
+the following general options:
+
+\begin{ttdescription}
+\item [a] Specify an alternate directory for generated fonts.
+The default is to use the \envname{TEXMFVAR} tree, as explained above.
+Setting this is useful if you plan to mount the main tree read-only, and
+therefore you need another location (perhaps host-specific) for
+dynamically created fonts.
+
+\item [l] Create symbolic links for the binaries, man pages,
+and\slash or \acro{GNU} Info files in other locations. For example, you may
+wish to make the man pages available under \dirname{/usr/local/man} and
+the Info files available under \dirname{/usr/local/info}. (Of course
+you need appropriate privileges to write in the specified directories.)
+
+It is not advisable to overwrite a \TeX\ system that came with your
+system with this option. It's intended primarily for creating the links
+in standard directories that are known to users, such as
+\dirname{/usr/local/bin}, which don't already contain any \TeX\ files.
+
+\item [d] Skip installation of the font/macro documentation tree.
+This is useful if you need to save space, or if you've previously
+installed the documentation elsewhere.
+
+\item [s] Skip installation of the main font/macro source
+tree. This is useful if you are arranging to share that tree between
+machines and\slash or architectures in some other way, such as \acro{NFS}.
+
+\end{ttdescription}
+
+\textbf{i -- Perform installation.} When you're satisfied with your
+configuration options, enter \Ucom{i} to actually do the installation
+from the media to your chosen locations.
+
+% text is similar to above, but no TEXMFSYSVAR, so we have to write out.
+After the installation completes, your next step is to include the
+architecture-specific subdirectory of \dirname{TEXDIR/bin} in your
+\envname{PATH}, so the newly-installed programs can be found. The
+architecture names are listed in table~\ref{tab:archlist},
+\p.\pageref{tab:archlist}, or you can simply list the directory
+\dirname{TEXDIR/bin}.
+
+The syntax for doing this, and the initialization file to use, depends
+on your shell. If you use a Bourne-compatible shell (\cmdname{sh},
+\cmdname{bash}, \cmdname{ksh}, et al.), put the following into your
+\filename{$HOME/.profile} file:
+
+\begin{alltt}
+PATH=/usr/local/texlive/2007/bin/\var{archname}:$PATH; export PATH
+\end{alltt}
+
+\noindent For C shell-compatible shells (\cmdname{csh}, \cmdname{tcsh}),
+put the following into your \filename{$HOME/.cshrc} file:
+\begin{alltt}
+setenv PATH /usr/local/texlive/2007/bin/\var{archname}:$PATH
+\end{alltt}
+
+After the main installation has completed, and environment variables
+have been set, the last step is to run \cmdname{texconfig} or
+\cmdname{texconfig-sys} to customize your installation to your needs.
+This is explained in section~\ref{sec:texconfig},
+\p.\pageref{sec:texconfig}.
+
+Here is a minimal annotated example which accepts the default
+directories and installs binaries for the current system only. Thus,
+only one command is needed, \Ucom{i} for install. The \texttt{>} is the
+shell prompt as usual.
+
+\begin{alltt}
+> \Ucom{sh install-tl.sh}
+\Ucom{i} # perform installation
+> \Ucom{texconfig} ... # see section \ref{sec:texconfig}
+# New PATH element, with GNU/Linux as the example:
+> \Ucom{PATH=/usr/local/texlive/2007/bin/i386-linux:\$PATH; export PATH}
+\end{alltt}
+
+If your Unix system supports the \cmdname{manpath} command (type \code{man
+manpath} to learn more), you can make the \TL\ manual pages available
+system-wide via the normal \cmdname{man} command by editing the file
+\filename{/etc/manpath.config}; you might need root permissions for this.
+With the following entry in \filename{/etc/manpath.config} the \TL\
+manual pages will be found at their original places within the \TL\ tree
+(adapt the binary path for your system architecture):
+
+\begin{verbatim}
+MANPATH_MAP /usr/local/texlive/2007/bin/i386-linux \
+ /usr/local/texlive/2007/texmf/doc/man
+\end{verbatim}
+
+\textifindoubt
+
+\begin{table*}[ht]
+\caption[Supported system architectures.]{Supported system
+architectures.}
+\label{tab:archlist}
+\begin{tabular}{>{\ttfamily}ll}
+alpha-linux & HP Alpha GNU/Linux \\
+hppa-hpux & HPPA HP-UX \\
+i386-darwin & x86 \MacOSX \\
+i386-freebsd & x86 FreeBSD \\
+i386-linux & x86 GNU/Linux \\
+i386-openbsd & x86 OpenBSD \\
+i386-solaris & x86 Solaris \\
+mips-irix & SGI IRIX \\
+powerpc-aix & IBM RS/6000 AIX \\
+powerpc-darwin & PowerPC \MacOSX \\
+powerpc-linux & PowerPC GNU/Linux \\
+sparc-linux & Sun Sparc GNU/Linux \\
+sparc-solaris & Sun Sparc Solaris \\
+win32 & Windows (32-bit) \\
+x86\_64-linux & x86 64-bit GNU/Linux \\
+\hline
+\end{tabular}
+\end{table*}
+
+
+\subsubsection{Non-interactive installation}
+\label{sec:noninteractive-install}
+
+It is possible to override the default directories with environment
+variables, and then install non-interactively. Example:
+\begin{alltt}
+> \Ucom{TEXLIVE_INSTALL_PREFIX=/opt/texlive}
+> \Ucom{export TEXLIVE_INSTALL_PREFIX}
+> \Ucom{echo i | sh install-tl.sh}
+\end{alltt}
+
+The \envname{TEXLIVE\_INSTALL\_PREFIX} variable overrides the default
+location of \dirname{/usr/local/texlive}, leaving all else
+unchanged---so with the above invocation, the main installation will go
+to \dirname{/opt/texlive/2007}.
+
+In the usual Unix way, the final \Ucom{echo i} can be replaced by any
+sequence of input commands via a here document, so any sequence of
+commands can be scripted.
+
+Here are all the possible overrides:
+
+\begin{ttdescription}
+\item [TEXLIVE\_INSTALL\_PREFIX]
+ Override \dirname{/usr/local/texlive}.
+\item [TEXLIVE\_INSTALL\_TEXDIR]
+ Override \dirname{\$TEXLIVE_INSTALL_PREFIX}/2007.
+\item [TEXLIVE\_INSTALL\_TEXMFLOCAL]
+ Override \dirname{\$TEXLIVE_INSTALL_PREFIX/texmf-var}.
+\item [TEXLIVE\_INSTALL\_TEXMFSYSVAR]
+ Override \dirname{\$TEXLIVE_INSTALL_TEXDIR/texmf-var}.
+\item [TEXLIVE\_INSTALL\_TEXMFHOME]
+ Override \dirname{\$HOME/texmf}.
+\end{ttdescription}
+
+It would be better to support a standard \acro{GNU}-style
+\filename{configure} with options, instead of these environment
+variables. Volunteers are welcome!
+
+
+%
+\subsection{Installing individual packages to disk}
+
+You can add individual packages or collections from the current
+distribution to an existing non-\TL{} setup, or an earlier
+\TL{} installation.
+
+\startinst
+
+Run the installation script \filename{install-pkg.sh} (not
+\filename{install-tl.sh}, which is intended for complete installations
+only):
+\begin{alltt}
+> \Ucom{sh install-pkg.sh \var{options}}
+\end{alltt}
+
+The first set of options controls what gets read:
+
+\begin{ttdescription}
+\item [-{}-package=\var{pkgname}] The individual package to work on.
+
+\item [-{}-collection=\var{colname}] The individual collection to work on.
+
+\item [-{}-nodoc] Exclude documentation files from the operation.
+
+\item [-{}-nosrc] Exclude source files from the operation.
+
+\item [-{}-cddir=\var{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.
+
+\item [-{}-listdir=\var{dir}] The so-called `lists' directory within
+\var{cddir} from which to read the package information. The only
+reason to change the default is if you're making changes to \TL{}
+yourself.
+
+\end{ttdescription}
+
+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
+\envname{\$TEXMFMAIN} with \cmdname{kpsewhich}. You can override it by
+setting either the environment variable \envname{TEXMFMAIN} or
+\envname{TEXMF}.
+
+\begin{ttdescription}
+\item [-{}-listonly] List the files that would be installed, but don't
+actually install anything.
+
+\item [-{}-archive=\var{tarfile}] Instead of installing the files into
+the \TeX{} system, make a \cmdname{tar} archive.
+
+\end{ttdescription}
+
+Additional options:
+
+\begin{ttdescription}
+
+\item [-{}-config] After installation, run \code{texconfig init}.
+
+\item [-{}-nohash] After installation, don't run \cmdname{mktexlsr} to
+rebuild the filename database.
+
+\item [-{}-verbose] Give more information as the script runs.
+
+\end{ttdescription}
+
+Here are some usage examples:
+
+\begin{enumerate}
+
+\item To see the files in the package \pkgname{fancyhdr} without
+installing it:
+
+\begin{alltt}
+\ifSingleColumn> \Ucom{sh install-pkg.sh --package=fancyhdr --listonly}
+\else> \Ucom{sh install-pkg.sh --package=fancyhdr \bs}
+> \Ucom{--listonly}
+\fi{}
+texmf/doc/latex/fancyhdr/README
+texmf/doc/latex/fancyhdr/fancyhdr.pdf
+...
+\end{alltt}
+
+\item Install the \LaTeX{} package \pkgname{natbib}:
+\begin{alltt}
+> \Ucom{sh install-pkg.sh --package=natbib}
+\end{alltt}
+
+\item Install the \LaTeX{} package \pkgname{alg} without source files or
+documentation:
+\begin{alltt}
+\ifSingleColumn> \Ucom{sh install-pkg.sh --package=alg --nosrc --nodoc}
+\else> \Ucom{sh install-pkg.sh -{}-package=alg \bs}
+> \Ucom{-{}-nosrc -{}-nodoc}
+\fi\end{alltt}
+
+\item Install all the packages in the collection of additional
+plain \TeX\ macros:
+\begin{alltt}
+> \Ucom{sh install-pkg.sh --collection=tex-plainextra}
+\end{alltt}
+
+\item Write all files in the \pkgname{pstricks} package to a
+\cmdname{tar} file in \path|/tmp|:
+\begin{alltt}
+\ifSingleColumn> \Ucom{sh install-pkg.sh --package=pstricks --archive=/tmp/pstricks.tar}
+\else
+> \Ucom{sh install-pkg.sh -{}-package=pstricks \bs}
+> \Ucom{-{}-archive=/tmp/pstricks.tar}
+\fi\end{alltt}
+
+\end{enumerate}
+
+\textifindoubt
+
+
+%