summaryrefslogtreecommitdiff
path: root/Master/texmf-doc/source/english/texlive-en/installation.tex
blob: b8d6d7721ab7d34981fdece826a19609f50899da (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
\section{Installation}
\label{sec: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: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{Testing the installation}
\label{sec:test-install}

After installing \TL{} as best you can, you naturally want to test
it out, so you can start creating beautiful documents and\slash or fonts.

This section gives some basic procedures for testing that the new system
is functional.  We give Unix commands; under \MacOSX{} and Windows,
you're more likely to run the tests through a graphical interface, but
the principles are the same.

\begin{enumerate}

\item Make sure that you can run the \cmdname{tex} program in the first
place:

\begin{alltt}
> \Ucom{tex -{}-version}
TeX 3.141592 (Web2C 7.5.5)
kpathsea version 3.5.5
...
\end{alltt}
If this comes back with `command not found' instead of version and
copyright information, most likely you don't have the correct
\dirname{bin} subdirectory in your \envname{PATH}.  See
the environment-setting information on \p.\pageref{text:path}.

\item Process a basic \LaTeX{} file:
\begin{alltt}
> \Ucom{latex sample2e.tex}
This is pdfeTeXk, Version 3.141592...
...
Output written on sample2e.dvi (3 pages, 7496 bytes).
Transcript written on sample2e.log.
\end{alltt}
If this fails to find \filename{sample2e.tex} or other files, perhaps
you have interference from old environment variables or configuration
files.  For a deep analysis, you can always ask \TeX{} to report on
exactly what it is searching for, and finding; see ``Debugging actions''
on page~\pageref{Debugging}.

\item Preview the result online:
\begin{alltt}
> \Ucom{xdvi sample2e.dvi}
\end{alltt}
(Under Windows, the analogous command is \cmdname{dviout}.)  You should
see a new window with a nice document explaining some of the basics of
\LaTeX{}.  (Well worth reading, by the way if you're new to the system.)
You do have to be running under X for \cmdname{xdvi} to work; if you're
not, or your \envname{DISPLAY} environment variable is set incorrectly,
you'll get an error \samp{Can't open display}.

\item Create a \PS{} file for printing or display:
\begin{alltt}
> \Ucom{dvips sample2e.dvi -o sample2e.ps}
\end{alltt}

\item Create a \acro{PDF} file instead of \dvi{}; this processes the
\filename{.tex} file and writes \acro{PDF} directly:
\begin{alltt}
> \Ucom{pdflatex sample2e.tex}
\end{alltt}

\item Preview the \acro{PDF} file:
\begin{alltt}
> \Ucom{gv sample2e.pdf}
\textrm{or:}
> \Ucom{xpdf sample2e.pdf}
\end{alltt}
Unfortunately neither \cmdname{gv} nor \cmdname{xpdf} are currently
included in \TL{}, so you must install them separately.  See
\url{http://www.gnu.org/software/gv} and
\url{http://www.foolabs.com/xpdf}, respectively.

\item Other standard test files you may find useful:

\begin{ttdescription}
\item [small2e.tex] A simpler document than \filename{sample2e}, to
reduce the input size if you're having troubles.
\item [testpage.tex] Test if your printer introduces any offsets.
\item [nfssfont.tex] For printing font tables and tests.
\item [testfont.tex] Also for font tables, but using plain \TeX{}.
\item [story.tex] The most canonical (plain) \TeX{} test file of all.
You must type \samp{\bs bye} to the \code{*} prompt after \samp{tex
story.tex}.
\end{ttdescription}
You can process these in the same way as we did with
\filename{sample2e.tex}.

\end{enumerate}

If you are new to \TeX{}, or otherwise need help with actually
constructing \TeX{} or \LaTeX{} documents, please visit
\url{http://tug.org/begin.html} for some introductory resources.


%