diff options
Diffstat (limited to 'Master/texmf-doc/source/english/texlive-en/installation.tex')
-rw-r--r-- | Master/texmf-doc/source/english/texlive-en/installation.tex | 552 |
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 + + +% |