-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathtexlive-en.tex
3960 lines (3245 loc) · 163 KB
/
texlive-en.tex
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
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
% $Id$
% TeX Live documentation. Originally written by Sebastian Rahtz and
% Michel Goossens, now maintained by Karl Berry and others.
% Public domain.
%
\documentclass{article}
\let\tldocenglish=1 % for live4ht.cfg
\usepackage{tex-live}
\usepackage[latin1]{inputenc} % translators: use your preferred encodings.
\usepackage[T1]{fontenc}
\title{%
{\huge \textit{The \TeX\ Live Guide---2021}}
}
\author{Karl Berry, editor \\[3mm]
\url{https://tug.org/texlive/}
}
\date{March 2021}
\begin{document}
\maketitle
\begin{multicols}{2}
\tableofcontents
%\listoftables
\end{multicols}
\section{Introduction}
\label{sec:intro}
\subsection{\protect\TeX\protect\ Live and the \protect\TeX\protect\ Collection}
This document describes the main features of the \TL{} software
distribution\Dash \TeX{} and related programs for \GNU/Linux
and other Unix flavors, \MacOSX, and Windows systems.
You may have acquired \TL{} by downloading, or on the \TK{} \DVD, which
\TeX{} user groups distribute among their members, or in other ways.
Section \ref{sec:tl-coll-dists} briefly describes the contents of the
\DVD. Both \TL{} and the \TK{} are cooperative efforts by the \TeX{}
user groups. This document mainly describes \TL{} itself.
\TL{} includes executables for \TeX{}, \LaTeXe{}, \ConTeXt,
\MF, \MP, \BibTeX{} and many other programs; an extensive collection
of macros, fonts and documentation; and support for typesetting in
many different scripts from around the world.
For a brief summary of the major changes in this edition of \TL{},
see the end of the document, section~\ref{sec:history}
(\p.\pageref{sec:history}).
\htmlanchor{platforms}
\subsection{Operating system support}
\label{sec:os-support}
\TL{} contains binaries for many Unix-based platforms, including
\GNU/Linux, \MacOSX, and Cygwin. The included sources can be compiled
on platforms for which we do not provide binaries.
As to Windows: Windows~7 and later are supported. Windows Vista
may still mostly work, but \TL{} will no longer even install on Windows
XP or earlier. \TL{} includes no
64-bit executables for Windows, but the 32-bit executables should
run on 64-bit systems. But see
\url{https://tug.org/texlive/windows.html} for options to add
64-bit binaries.
See section~\ref{sec:tl-coll-dists} for alternate solutions
for Windows and \MacOSX.
\subsection{Basic installation of \protect\TL{}}
\label{sec:basic}
You can install \TL{} either from \DVD{} or over the Internet
(\url{https://tug.org/texlive/acquire.html}). The net installer itself is
small, and downloads everything requested from the Internet.
The \DVD{} installer lets you install to a local disk. You cannot run
\TL{} directly from the \TK{} \DVD{} (or its \code{.iso} image), but you
can prepare a runnable installation on, e.g., a \USB{} stick (see
section~\ref{sec:portable-tl}). Installation is described in later
sections (\p.\pageref{sec:install}), but here is a quick start:
\begin{itemize*}
\item For Unix, the installation script is \filename{install-tl}; on
Windows, one should instead invoke \filename{install-tl-windows}.
The installer will operate in a graphical mode given the option
\code{-gui} (default for Windows and \MacOSX), or a text mode given
the option \code{-gui=text} (default for everything else).
\item One of the installed items is the `\TL\ Manager' program,
named \prog{tlmgr}. Like the installer, it can be used in both \GUI{}
mode and in text mode. You can use it to install and uninstall
packages and do various configuration tasks.
\end{itemize*}
\htmlanchor{security}
\subsection{Security considerations}
\label{sec:security}
To the best of our knowledge, the core \TeX\ programs themselves are
(and always have been) extremely robust. However, the contributed
programs in \TeX\ Live may not reach the same level, despite everyone's
best efforts. As always, you should be careful when running programs on
untrusted input; to improve safety, use a new subdirectory or chroot.
This need for care is especially urgent on Windows, since in general
Windows finds programs in the current directory before anything else,
regardless of the search path. This opens up a wide variety of possible
attacks. We have closed many holes, but undoubtedly some remain,
especially with third-party programs. Thus, we recommend checking for
suspicious files in the current directory, especially executables
(binaries or scripts). Ordinarily they should not be present, and
definitely should not normally be created by merely processing a document.
Finally, \TeX\ (and its companion programs) are able to write files when
processing documents, a feature that can also be abused in a wide
variety of ways. Again, processing unknown documents in a new
subdirectory is the safest bet.
Another aspect of security is ensuring that downloaded material has not
been changed from what was created. The \prog{tlmgr} program
(section~\ref{sec:tlmgr}) will automatically perform cryptographic
verification on downloads if the \prog{gpg} (GNU Privacy Guard) program
is available. It is not distributed as part of \TL, but see
\url{https://texlive.info/tlgpg/} for information about \prog{gpg} if
need be.
\subsection{Getting help}
\label{sec:help}
The \TeX{} community is active and friendly, and most serious questions
end up getting answered. However, the support is informal, done by
volunteers and casual users, so it's especially important that you do
your homework before asking. (If you prefer guaranteed commercial
support, you can forgo \TL{} completely and purchase a vendor's system;
\url{https://tug.org/interest.html#vendors} has a list.)
Here is a list of resources, approximately in the order we recommend
using them:
\begin{description}
\item [Getting started] If you are new to \TeX, the web page
\url{https://tug.org/begin.html} gives a brief introduction to the system.
\item [\TeX{} FAQ] The \TeX{} FAQ is a huge compendium
of answers to all sorts of questions, from the most basic to the
most arcane. It is included on \TL{} in
\OnCD{texmf-dist/doc/generic/FAQ-en/}, and is available
on the Internet through \url{https://texfaq.org}. Please
check here first.
\item [\TeX{} Catalogue] If you are looking for a particular package,
font, program, etc., the \TeX{} Catalogue is the place to look. It is a
huge collection of all \TeX{}-related items. See
\url{https://ctan.org/pkg/catalogue}.
\item [\TeX{} Web Resources] The web page
\url{https://tug.org/interest.html} has many \TeX{}-related links, in
particular for numerous books, manuals, and articles on all aspects of
the system.
\item [support archives] Principal support forums for \TeX\ include
the \LaTeX{} community site at \url{https://latex.org}, the
q\&a site \url{https://tex.stackexchange.com}, the Usenet newsgroup
\url{news:comp.text.tex}, and the mailing list \email{[email protected]}.
Their archives have years of past questions and answers for your
searching pleasure, via, for the latter two,
\url{http://groups.google.com/group/comp.text.tex/topics} and
\url{https://tug.org/mail-archives/texhax}. And a general web search
never hurts.
\item [asking questions] If you cannot find an answer, you can post to
\url{http://latex-community.org/} and
\url{https://tex.stackexchange.com/} through their web interfaces, to
\dirname{comp.text.tex} through Google or your newsreader, or to
\email{[email protected]} through email. But before you post anywhere,
please read this FAQ entry, to maximize your chances of getting a useful
answer:
\url{https://texfaq.org/FAQ-askquestion}.
\item [\TL{} support] If you want to report a bug or have
suggestions or comments on the \TL{} distribution, installation, or
documentation, the mailing list is \email{[email protected]}. However,
if your question is about how to use a particular program included in
\TL{}, please write to that program's maintainer or
mailing list. Often running a program with the \code{-{}-help} option
will provide a bug reporting address.
\end{description}
The other side of the coin is helping others who have questions. All
the above resources are open to anyone, so feel free to join, start
reading, and help out where you can.
% don't use \TL so the \uppercase in the headline works. Also so
% tex4ht ends up with the right TeX. Likewise the \protect's.
\section{Overview of \protect\TeX\protect\ Live}
\label{sec:overview-tl}
This section describes the contents of \TL{} and the \TK{} of which it
is a part.
\subsection{The \protect\TeX\protect\ Collection: \protect\TL,
pro\protect\TeX{}t, Mac\protect\TeX}
\label{sec:tl-coll-dists}
The \TK{} \DVD{} comprises the following:
\begin{description}
\item [\TL] A complete \TeX{} system to be installed to disk. Home
page: \url{https://tug.org/texlive/}.
\item [Mac\TeX] for \MacOSX\ (currently named macOS by Apple, but we
continue to use the older name in this document), this adds a native
\MacOSX\ installer and other Mac applications to \TL{}. Home page:
\url{https://tug.org/mactex/}.
\item [pro\TeX{}t] An enhancement of the \MIKTEX\ distribution for Windows,
\ProTeXt\ adds a few extra tools to \MIKTEX, and simplifies
installation. It is entirely independent of \TL{}, and has its own
installation instructions. Home page:
\url{https://tug.org/protext/}.
\item [CTAN] A snapshot of the \CTAN{} repository (\url{https://ctan.org/}).
\end{description}
\CTAN{} and \pkgname{protext} do not follow the same copying conditions
as \TL{}, so be careful when redistributing or modifying.
\subsection{Top level \protect\TL{} directories}
\label{sec:tld}
Here is a brief listing and description of the top level directories in a
\TL{} installation.
\begin{ttdescription}
\item[bin] The \TeX{} system programs, arranged by platform.
%
\item[readme-*.dir] Quick overview and useful links for \TL{},
in various languages, in both \HTML{} and plain text.
%
\item[source] The source to all included programs, including the main
\Webc{}-based \TeX{} distributions.
%
\item[texmf-dist] The principal tree; see \dirname{TEXMFDIST} below.
%
\item[tlpkg] Scripts, programs and data for managing the
installation, and special support for Windows.
\end{ttdescription}
For documentation, the comprehensive links in the top-level file
\OnCD{doc.html} may be helpful. The documentation for nearly everything
(packages, formats, fonts, program manuals, man pages, Info files) is in
\dirname{texmf-dist/doc}. You can use the \cmdname{texdoc} program to
find documentation wherever it is located.
This \TL\ documentation itself is in \dirname{texmf-dist/doc/texlive},
available in several languages:
\begin{itemize*}
\item{Czech/Slovak:} \OnCD{texmf-dist/doc/texlive/texlive-cz}
\item{German:} \OnCD{texmf-dist/doc/texlive/texlive-de}
\item{English:} \OnCD{texmf-dist/doc/texlive/texlive-en}
\item{French:} \OnCD{texmf-dist/doc/texlive/texlive-fr}
\item{Italian:} \OnCD{texmf-dist/doc/texlive/texlive-it}
\item{Japanese:} \OnCD{texmf-dist/doc/texlive/texlive-ja}
\item{Polish:} \OnCD{texmf-dist/doc/texlive/texlive-pl}
\item{Russian:} \OnCD{texmf-dist/doc/texlive/texlive-ru}
\item{Serbian:} \OnCD{texmf-dist/doc/texlive/texlive-sr}
\item{Simplified Chinese:} \OnCD{texmf-dist/doc/texlive/texlive-zh-cn}
\end{itemize*}
\subsection{Overview of the predefined texmf trees}
\label{sec:texmftrees}
This section lists the predefined variables specifying the texmf trees
used by the system, and their intended purpose, and the default layout
of \TL{}. The command \texttt{tlmgr~conf} shows the values of these
variables, so that you can easily find out how they map to particular
directories in your installation.
All of the trees, including the personal ones, should follow the \TeX\
Directory Structure (\TDS, \url{https://tug.org/tds}), with all its
myriad subdirectories, or files may not be found. Section
\ref{sec:local-personal-macros} (\p.\pageref{sec:local-personal-macros})
describes this in more detail. The order here is the reverse order in
which the trees are searched, that is, later trees in the list override
earlier ones.
\begin{ttdescription}
\item [TEXMFDIST] The tree which holds nearly all of the files in the original
distribution---configuration files, scripts, packages, fonts, etc.
(The main exception are the per-platform executables, which are stored
in a sibling directory \code{bin/}.)
\item [TEXMFSYSVAR] The (site-wide) tree used by \verb+texconfig-sys+,
\verb+updmap-sys+ and \verb+fmtutil-sys+, and also by \verb+tlmgr+, to
store (cached) runtime data such as format files and generated map files.
\item [TEXMFSYSCONFIG] The (site-wide) tree used by the utilities
\verb+texconfig-sys+, \verb+updmap-sys+, and \verb+fmtutil-sys+ to
store modified configuration data.
\item [TEXMFLOCAL] The tree which administrators can use for system-wide
installation of additional or updated macros, fonts, etc.
\item [TEXMFHOME] The tree which users can use for their own individual
installations of additional or updated macros, fonts, etc.
The expansion of this variable dynamically adjusts for each user to
their own individual directory.
\item [TEXMFVAR] The (personal) tree used by \verb+texconfig+,
\verb+updmap-user+ and \verb+fmtutil-user+ to store (cached) runtime data such
as format files and generated map files.
\item [TEXMFCONFIG] The (personal) tree used by the utilities
\verb+texconfig+, \verb+updmap-sys+, and \verb+fmtutil-sys+ to store modified
configuration data.
\item [TEXMFCACHE] The tree(s) used by \ConTeXt\ MkIV and Lua\LaTeX\
to store (cached) runtime data; defaults to \code{TEXMFSYSVAR},
or (if that's not writable), \code{TEXMFVAR}.
\end{ttdescription}
\noindent
The default layout is:
\begin{description}
\item[system-wide root] can span multiple \TL{} releases
(\texttt{/usr/local/texlive} by default on Unix):
\begin{ttdescription}
\item[2020] A previous release.
\item[2021] The current release.
\begin{ttdescription}
\item [bin] ~
\begin{ttdescription}
\item [i386-linux] \GNU/Linux binaries (32-bit)
\item [...]
\item [x86\_64-darwin] \MacOSX\ binaries
\item [x86\_64-linux] \GNU/Linux binaries (64-bit)
\item [win32] Windows binaries
\end{ttdescription}
\item [texmf-dist\ \ ] \envname{TEXMFDIST} and \envname{TEXMFMAIN}
\item [texmf-var \ \ ] \envname{TEXMFSYSVAR}, \envname{TEXMFCACHE}
\item [texmf-config] \envname{TEXMFSYSCONFIG}
\end{ttdescription}
\item [texmf-local] \envname{TEXMFLOCAL}, intended to be
retained from release to release.
\end{ttdescription}
\item[user's home directory] (\texttt{\$HOME} or
\texttt{\%USERPROFILE\%})
\begin{ttdescription}
\item[.texlive2020] Privately generated and configuration data
for a previous release.
\item[.texlive2021] Privately generated and configuration data
for the current release.
\begin{ttdescription}
\item [texmf-var\ \ \ ] \envname{TEXMFVAR}, \envname{TEXMFCACHE}
\item [texmf-config] \envname{TEXMFCONFIG}
\end{ttdescription}
\item[texmf] \envname{TEXMFHOME} Personal macros, etc.
\end{ttdescription}
\end{description}
\subsection{Extensions to \protect\TeX}
\label{sec:tex-extensions}
Knuth's original \TeX{} itself is frozen, apart from rare bug fixes. It
is present in \TL\ as the program \prog{tex}, and will remain so
for the foreseeable future. \TL{} also contains several extended versions of
\TeX\ (also known as \TeX\ engines):
\begin{description}
\item [\eTeX] adds a set of new primitives
\label{text:etex} (related to macro expansion, character scanning,
classes of marks, additional debugging features, and more) and the
\TeXXeT{} extensions for bidirectional typesetting. In default mode,
\eTeX{} is 100\% compatible with ordinary \TeX. See
\OnCD{texmf-dist/doc/etex/base/etex_man.pdf}.
\item [pdf\TeX] builds on the \eTeX\ extensions, adding support for
writing PDF output as well as \dvi{}, and many non-output-related
extensions. This is the program invoked for many common formats, e.g.,
\prog{etex}, \prog{latex}, \prog{pdflatex}. Its web site is
\url{http://www.pdftex.org/}. See
\OnCD{texmf-dist/doc/pdftex/manual/pdftex-a.pdf} for the manual, and
\OnCD{texmf-dist/doc/pdftex/samplepdftex/samplepdf.tex} for example
usage of some of its features.
\item [Lua\TeX] adds support for Unicode input and OpenType\slash
TrueType- and system fonts. It also incorporates a Lua interpreter
(\url{https://lua.org/}), enabling solutions for many thorny \TeX{}
problems. When called as \filename{texlua}, it functions as a standalone
Lua interpreter. Its web site is \url{http://www.luatex.org/}, and the
reference manual is \OnCD{texmf-dist/doc/luatex/base/luatex.pdf}.
\item [(e)(u)p\TeX] have native support for Japanese typesetting
requirements; p\TeX\ is the basic engine, while the e- variants add
\eTeX\ functionality and u- add Unicode support.
\item [\XeTeX] adds support for Unicode input and OpenType\slash
TrueType- and system fonts, implemented using standard third-party
libraries. See \url{https://tug.org/xetex}.
\item [\OMEGA\ (Omega)] is based on Unicode (16-bit characters), thus
supports working with almost all the world's scripts simultaneously. It
also supports so-called `\OMEGA{} Translation Processes' (OTPs),
for performing complex transformations on arbitrary input. Omega is no
longer included in \TL{} as a separate program; only Aleph is provided:
\item [Aleph] combines the \OMEGA\ and \eTeX\ extensions.
See \OnCD{texmf-dist/doc/aleph/base}.
\end{description}
\subsection{Other notable programs in \protect\TL}
Here are a few other commonly-used programs included in \TL{}:
\begin{cmddescription}
\item [bibtex, biber] bibliography support.
\item [makeindex, xindy] index support.
\item [dvips] convert \dvi{} to \PS{}.
\item [xdvi] \dvi{} previewer for the X Window System.
\item [dviconcat, dviselect] cut and paste pages
from \dvi{} files.
\item [dvipdfmx] convert \dvi{} to PDF, an alternative approach
to pdf\TeX\ (mentioned above).
\item [psselect, psnup, \ldots] \PS{} utilities.
\item [pdfjam, pdfjoin, \ldots] PDF utilities.
\item [context, mtxrun] Con\TeX{}t and PDF processor.
\item [htlatex, \ldots] \cmdname{tex4ht}: \AllTeX{} to HTML (and
XML and more) converter.
\end{cmddescription}
\htmlanchor{installation}
\section{Installation}
\label{sec:install}
\subsection{Starting the installer}
\label{sec:inst-start}
To begin, get the \TK{} \DVD{} or download the \TL{} net installer. See
\url{https://tug.org/texlive/acquire.html} for more information and other
methods of getting the software.
\begin{description}
\item [Net installer, .zip or .tar.gz:] Download from \CTAN, under
\dirname{systems/texlive/tlnet}; the url
\url{http://mirror.ctan.org/systems/texlive/tlnet} should redirect to a
nearby, up-to-date, mirror. You can retrieve either
\filename{install-tl.zip} which can be used under Unix and Windows, or
the considerably smaller \filename{install-unx.tar.gz} for Unix
only. After unpacking, \filename{install-tl} and
\filename{install-tl-windows.bat} will be in the \dirname{install-tl}
subdirectory.
\item[Net installer, Windows .exe:] Download from \CTAN{} as above,
and double-click. This starts up a first-stage installer and unpacker;
see figure~\ref{fig:nsis}. It gives two choices: ``Install''
and``Unpack only''.
\item [\TeX{} Collection \DVD:] go to the \DVD's \dirname{texlive}
subdirectory. Under Windows, the installer normally starts automatically
when you insert the \DVD. You can get the \DVD\ by becoming a member of
a \TeX\ user group (highly recommended,
\url{https://tug.org/usergroups.html}), or purchasing it separately
(\url{https://tug.org/store}), or burning your own from the \ISO\ image.
You can also mount the \ISO\ directly on most systems. After installing
from \DVD\ or \ISO, if you want to get continuing updates from the
Internet, please see \ref{sec:dvd-install-net-updates}.
\end{description}
\begin{figure}[tb]
\tlpng{nsis_installer}{.6\linewidth}
\caption{First stage of Windows \code{.exe} installer}\label{fig:nsis}
\end{figure}
The same installer program is run, whatever the source. The most
visible difference between the two is that with the net installer, what
you end up with is the packages that are currently available. This is
in contrast to the \DVD\ and \ISO\ images, which are not updated between
the major public releases.
If you need to download through proxies, use a \filename{~/.wgetrc} file
or environment variables with the proxy settings for Wget
(\url{https://www.gnu.org/software/wget/manual/html_node/Proxies.html}),
or the equivalent for whatever download program you are using. This does
not matter if you are installing from the \DVD\ or \ISO\ image.
The following sections explain installer start-up in more detail.
\subsubsection{Unix}
Below, \texttt{>} denotes the shell prompt; user input is
\Ucom{\texttt{bold}}.
The script \filename{install-tl} is a Perl script. The simplest way
to start it on a Unix-compatible system is as follows:
\begin{alltt}
> \Ucom{perl /path/to/installer/install-tl}
\end{alltt}
(Or you can invoke \Ucom{/path/to/installer/install-tl} if it stayed
executable, or \texttt{cd} to the directory first, etc.; we won't repeat
all the variations.) You may have to enlarge your terminal window so
that it shows the full text installer screen
(figure~\ref{fig:text-main}).
To install in \GUI\ mode (figure~\ref{fig:advanced-lnx}), you'll need to
have Tcl/Tk installed. Given that, you can run:
\begin{alltt}
> \Ucom{perl install-tl -gui}
\end{alltt}
The old \code{wizard} and \code{perltk}/\code{expert} options are
still available, but now do the same thing as \code{-gui}. For
a complete listing of the various options:
\begin{alltt}
> \Ucom{perl install-tl -help}
\end{alltt}
\textbf{About Unix permissions:} 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.
\textbf{Special considerations for Cygwin:} Unlike other
Unix-compatible systems, Cygwin does not by default include all of the
prerequisite programs needed by the \TL{} installer. See
section~\ref{sec:cygwin}.
\subsubsection{\MacOSX}
\label{sec:macosx}
As mentioned in section~\ref{sec:tl-coll-dists}, a separate distribution
is prepared for \MacOSX, named Mac\TeX\ (\url{https://tug.org/mactex}).
We recommend using the native Mac\TeX\ installer instead of the \TL\
installer on \MacOSX, because the native installer makes a few
Mac-specific adjustments, in particular to allow easily switching
between the various \TeX\ distributions for \MacOSX\ (Mac\TeX, Fink,
MacPorts, \ldots) using the so-called \TeX{}Dist data structure.
Mac\TeX\ is firmly based on \TL, and the main \TeX\ trees and binaries
are precisely the same. It adds a few extra folders with Mac-specific
documentation and applications.
\subsubsection{Windows}\label{sec:wininst}
If you are using the unpacked downloaded zip file, or the \DVD\
installer failed to start automatically, double-click
\filename{install-tl-windows.bat}.
You can also start the installer from the command-prompt. Below,
\texttt{>} denotes the prompt; user input is \Ucom{\texttt{bold}}. If
you are in the installer directory, run just:
\begin{alltt}
> \Ucom{install-tl-windows}
\end{alltt}
Or you can invoke it with an absolute location, such as:
\begin{alltt}
> \Ucom{D:\bs{}texlive\bs{}install-tl-windows}
\end{alltt}
for the \TK\ \DVD, supposing that \dirname{D:} is the optical
drive. Figure~\ref{fig:basic-w32} displays the initial basic screen
of the \GUI\ installer, which is the default for Windows.
To install in text mode, use:
\begin{alltt}
> \Ucom{install-tl-windows -no-gui}
\end{alltt}
For a complete listing of the various options:
\begin{alltt}
> \Ucom{install-tl-windows -help}
\end{alltt}
\begin{figure}[tb]
\begin{boxedverbatim}
Installing TeX Live 2021 from: ...
Platform: x86_64-linux => 'GNU/Linux on x86_64'
Distribution: inst (compressed)
Directory for temporary files: /tmp
...
Detected platform: GNU/Linux on Intel x86_64
<B> binary platforms: 1 out of 16
<S> set installation scheme: scheme-full
<C> customizing installation collections
40 collections out of 41, disk space required: 7172 MB
<D> directories:
TEXDIR (the main TeX directory):
/usr/local/texlive/2021
...
<O> options:
[ ] use letter size instead of A4 by default
...
<V> set up for portable installation
Actions:
<I> start installation to hard disk
<P> save installation profile to 'texlive.profile' and exit
<H> help
<Q> quit
\end{boxedverbatim}
\vskip-.5\baselineskip
\caption{Main text installer screen (\GNU/Linux)}\label{fig:text-main}
\end{figure}
\begin{figure}[tb]
\tlpng{basic-w32}{.6\linewidth}
\caption{Basic installer screen (Windows); the Advanced button will
result in something like figure~\ref{fig:advanced-lnx}}\label{fig:basic-w32}
\end{figure}
\begin{figure}[tb]
\tlpng{advanced-lnx}{\linewidth}
\caption{Advanced \GUI{} installer screen
(\GNU/Linux)}\label{fig:advanced-lnx}
\end{figure}
\htmlanchor{cygwin}
\subsubsection{Cygwin}
\label{sec:cygwin}
Before beginning the installation, use Cygwin's \filename{setup.exe} program to
install the \filename{perl} and \filename{wget} packages if you have
not already done so. The following additional packages are
recommended:
\begin{itemize*}
\item \filename{fontconfig} [needed by \XeTeX\ and Lua\TeX]
\item \filename{ghostscript} [needed by various utilities]
\item \filename{libXaw7} [needed by \code{xdvi}]
\item \filename{ncurses} [provides the \code{clear} command used by the installer]
\end{itemize*}
\subsubsection{The text installer}
Figure~\ref{fig:text-main} displays the main text mode screen under
Unix. The text installer is the default on Unix.
This is only a command-line installer; there is no cursor support at
all. For instance, you cannot tab around checkboxes or input fields.
You just type something (case-sensitive) at the prompt and press the
Enter key, and then the entire terminal screen will be rewritten, with
adjusted content.
The text installer interface is this primitive in order to make it run
on as many platforms as possible, even with a minimal Perl.
\subsubsection{The graphical installer}
\label{sec:graphical-inst}
The default graphical installer starts out simple, with just a
few options; see figure~\ref{fig:basic-w32}. It can be started with
\begin{alltt}
> \Ucom{install-tl -gui}
\end{alltt}
The Advanced button gives access to most of the options of the text
installer; see figure~\ref{fig:advanced-lnx}.
The \texttt{perltk}/\texttt{expert} and \texttt{wizard} \GUI{}
options now invoke the regular graphical installer.
\subsection{Running the installer}
\label{sec:runinstall}
The installer is intended to be mostly self-explanatory, but following are a
few notes about the various options and submenus.
\subsubsection{Binary systems menu (Unix only)}
\label{sec:binary}
\begin{figure}[tb]
\begin{boxedverbatim}
Available platforms:
===============================================================================
a [ ] Cygwin on Intel x86 (i386-cygwin)
b [ ] Cygwin on x86_64 (x86_64-cygwin)
c [ ] MacOSX current (10.14-) on ARM/x86_64 (universal-darwin)
d [ ] MacOSX legacy (10.6-) on x86_64 (x86_64-darwinlegacy)
e [ ] FreeBSD on x86_64 (amd64-freebsd)
f [ ] FreeBSD on Intel x86 (i386-freebsd)
g [ ] GNU/Linux on ARM64 (aarch64-linux)
h [ ] GNU/Linux on ARMv6/RPi (armhf-linux)
i [ ] GNU/Linux on Intel x86 (i386-linux)
j [X] GNU/Linux on x86_64 (x86_64-linux)
k [ ] GNU/Linux on x86_64 with musl (x86_64-linuxmusl)
l [ ] NetBSD on x86_64 (amd64-netbsd)
m [ ] NetBSD on Intel x86 (i386-netbsd)
o [ ] Solaris on Intel x86 (i386-solaris)
p [ ] Solaris on x86_64 (x86_64-solaris)
s [ ] Windows (win32)
\end{boxedverbatim}
\vskip-.5\baselineskip
\caption{Binaries menu}\label{fig:bin-text}
\end{figure}
Figure~\ref{fig:bin-text} displays the text mode binaries menu. By
default, only the binaries for your current platform will be installed.
From this menu, you can select installation of binaries for other
platforms as well. This can be useful if you are sharing a \TeX\
tree across a network of heterogeneous machines, or for a dual-boot
system.
\subsubsection{Selecting what is to be installed}
\label{sec:components}
\begin{figure}[tbh]
\begin{boxedverbatim}
Select scheme:
===============================================================================
a [X] full scheme (everything)
b [ ] medium scheme (small + more packages and languages)
c [ ] small scheme (basic + xetex, metapost, a few languages)
d [ ] basic scheme (plain and latex)
e [ ] minimal scheme (plain only)
f [ ] ConTeXt scheme
g [ ] GUST TeX Live scheme
h [ ] infrastructure-only scheme (no TeX at all)
i [ ] teTeX scheme (more than medium, but nowhere near full)
j [ ] custom selection of collections
\end{boxedverbatim}
\vskip-.5\baselineskip
\caption{Scheme menu}\label{fig:scheme-text}
\end{figure}
Figure~\ref{fig:scheme-text} displays the \TL\ scheme menu; from here,
you choose a ``scheme'', which is an overall set of package collections.
The default \optname{full} scheme installs everything available. This is
recommended, but you can also choose the \optname{basic} scheme for
just plain and \LaTeX, \optname{small} for a few more programs
(equivalent to the so-called Basic\TeX\ installation of Mac\TeX),
\optname{minimal} for testing purposes, and \optname{medium} or
\optname{teTeX} to get something in between. There are also various
specialized and country-specific schemes.
\begin{figure}[tb]
\centering \tlpng{stdcoll}{.7\linewidth}
\caption{Collections menu}\label{fig:collections-gui}
\end{figure}
You can refine your scheme selection with the `collections' menu
(figure~\ref{fig:collections-gui}, shown in \GUI\ mode for a change).
Collections are one level more detailed than schemes\Dash in essence, a
scheme consists of several collections, a collection consists of one or
more packages, and a package (the lowest level grouping in \TL) contains
the actual \TeX\ macro files, font files, and so on.
If you want more control than the collection menus provide, you can use
the \TeX\ Live Manager (\prog{tlmgr}) program after installation (see
section~\ref{sec:tlmgr}); using that, you can control the installation
at the package level.
\subsubsection{Directories}
\label{sec:directories}
The default layout is described in section~\ref{sec:texmftrees},
\p.\pageref{sec:texmftrees}. The default installation directory is
\dirname{/usr/local/texlive/2021} on Unix and
|%SystemDrive%\texlive\2021| on Windows. This arrangement enables
having many parallel \TL\ installations, such as one for each release
(typically by year, as here), and you can switch between them merely by
altering your search path.
That installation directory can be overridden by setting the so-called
\dirname{TEXDIR} in the installer. The \GUI\ screen for this and other
options is shown in figure~\ref{fig:advanced-lnx}. The most common reasons
to change it are either lacking enough disk space in that partition (the
full \TL\ needs several gigabytes), or lacking write permission for the
default location (you don't have to be root or administrator to install
\TL, but you do need write access to the target directory).
The installation directories can also be changed by setting a variety of
environment variables before running the installer (most likely,
\envname{TEXLIVE\_INSTALL\_PREFIX} or
\envname{TEXLIVE\_INSTALL\_TEXDIR}); see the documentation from
|install-tl --help| (available online at
\url{https://tug.org/texlive/doc/install-tl.html}) for the full list and
more details.
A reasonable alternative destination is a directory under your home,
especially if you will be the sole user. Use `|~|' to indicate this, as
in `|~/texlive/2021|'.
We recommend including the year in the name, to enable keeping different
releases of \TL{} side by side. (You may wish to also maintain a
version-independent name, such as \dirname{/usr/local/texlive-cur}, via a
symbolic link, which you can then repoint after testing the new release.)
Changing \dirname{TEXDIR} in the installer will also change
\dirname{TEXMFLOCAL}, \dirname{TEXMFSYSVAR} and
\dirname{TEXMFSYSCONFIG}.
\dirname{TEXMFHOME} is the recommended location for personal macro files
or packages. The default value is |~/texmf| (|~/Library/texmf| on
Macs). In contrast to \dirname{TEXDIR}, here a |~| is preserved in the
newly-written configuration files, since it usefully refers to the home
directory of the user running \TeX. It expands to \dirname{$HOME} on
Unix and \verb|%USERPROFILE%| on Windows. Special redundant note:
\envname{TEXMFHOME}, like all trees, must be organized according to the
\TDS, or files may not be found.
\dirname{TEXMFVAR} is the location for storing most cached runtime data
specific to each user. \dirname{TEXMFCACHE} is the variable name used
for that purpose by Lua\LaTeX\ and \ConTeXt\ MkIV (see
section~\ref{sec:context-mkiv}, \p.\pageref{sec:context-mkiv}); its
default value is \dirname{TEXMFSYSVAR}, or (if that's not writable),
\dirname{TEXMFVAR}.
\subsubsection{Options}
\label{sec:options}
\begin{figure}[tbh]
\begin{boxedverbatim}
Options customization:
===============================================================================
<P> use letter size instead of A4 by default: [ ]
<E> execution of restricted list of programs: [X]
<F> create all format files: [X]
<D> install font/macro doc tree: [X]
<S> install font/macro source tree: [X]
<L> create symlinks in standard directories: [ ]
binaries to:
manpages to:
info to:
<Y> after install, set CTAN as source for package updates: [X]
\end{boxedverbatim}
\vskip-.5\baselineskip
\caption{Options menu (Unix)}\label{fig:options-text}
\end{figure}
Figure~\ref{fig:options-text} shows the text mode options menu.
More info on each:
\begin{description}
\item[use letter size instead of A4 by default:] The default paper
size selection. Of course, individual documents can and should
specify a specific paper size, if desired.
\item[execution of restricted list of programs:] As of \TL\ 2010,
execution of a few external programs is allowed by default. The (very
short) list of allowed programs is given in the \filename{texmf.cnf}.
See the 2010 news (section~\ref{sec:2010news}) for more details.
\item[create all format files:] Although unnecessary format files
take time to generate and disk space to store, it is still recommended
to leave this option checked: if you don't, then format files will be
generated in people's private \dirname{TEXMFVAR} tree as they are
needed. In that location, they will not be updated automatically if
(for example) core packages or hyphenation patterns are updated in the
installation, and thus you could end up with incompatible format files.
\item[install font/macro \ldots\ tree:] Download/install the
documentation and source files included in most packages. Unchecking
is not recommended.
\item[create symlinks in standard directories:]
This option (Unix only) bypasses the need to change environment
variables. Without this option, \TL{} directories usually have to be
added to \envname{PATH}, \envname{MANPATH} and \envname{INFOPATH}. You
will need write permissions to the target directories. This option is
intended for accessing the \TeX\ system through directories that are
already known to users, such as \dirname{/usr/local/bin}, which don't
already contain any \TeX\ files. Do not overwrite existing files on
your system with this option, e.g., by specifying system directories.
The safest and recommended approach is to leave the option unchecked.
\item[after install, set CTAN as source for package updates:]
When installing from \DVD, this
option is enabled by default, since usually one wants to take any
subsequent package updates from the \CTAN\ area that is updated
throughout the year. The only likely reason to disable it is if you
install only a subset from the \DVD\ and plan to augment the
installation later. In any case, the package repository for the
installer, and for updates after installation, can be set
independently as needed; see section~\ref{sec:location} and
section~\ref{sec:dvd-install-net-updates}.
\end{description}
Windows-specific options, as displayed in the advanced \GUI{}
interface:
\begin{description}
\item[adjust searchpath] This ensures that all
programs will see the \TL{} binary directory on their search path.
\item[add menu shortcuts] If set, there will be a \TL{} submenu of
the Start menu. There is a third option `Launcher entry' besides
`TeX Live menu' and `No shortcuts'. This option is described in
section \ref{sec:sharedinstall}.
\item[File associations] The options are `Only new' (create
file associations, but do not overwrite existing ones), `All' and
`None'.
\item[install \TeX{}works front end]
\end{description}
When all the settings are to your liking, you can type `I' in the
text interface, or press the `Install' button in the
\GUI, to start the installation process. When it is done,
skip to section~\ref{sec:postinstall} to read what else needs to be
done, if anything.
\subsection{Command-line install-tl options}
\label{sec:cmdline}
Type
\begin{alltt}
> \Ucom{install-tl -help}
\end{alltt}
for a listing of command-line options. Either |-| or |--| can be used
to introduce option names. These are the most common ones:
\begin{ttdescription}
\item[-gui] Use the \GUI{} installer if possible. This requires
Tcl/Tk version 8.5 or higher. This is the case on \MacOSX\ and is
distributed with \TL{} on Windows. The legacy options
\texttt{-gui=perltk} and \texttt{-gui=wizard} are still available
but invoke the same \GUI{} interface; if Tcl/Tk is not available,
installation continues in text mode.
\item[-no-gui] Force using the text mode installer.
\item[-lang {\sl LL}] Specify the installer interface
language as a standard (usually two-letter) code. The installer tries
to automatically determine the right language but if it fails, or if
the right language is not available, then it uses English as a
fallback. Run \verb|install-tl --help| to get the list of available
languages.
\item[-portable] Install for portable use on, e.g., a \USB{} stick.
Also selectable from within the text installer with the \code{V}
command, and from the \GUI{} installer. See
section~\ref{sec:portable-tl}.
\item[-profile {\sl file}] Load the installation profile \var{file} and
do the installation with no user interaction. The installer always
writes a file \filename{texlive.profile} to the \dirname{tlpkg}
subdirectory of your installation. That file can be given as the
argument to redo the exact same installation on a different system,
for example. Alternatively, you can use a custom profile, most easily
created by starting from a generated one and changing values, or an
empty file, which will take all the defaults.
\item [-repository {\sl url-or-directory}] Specify package
repository from which to install; see following.
\htmlanchor{opt-in-place}
\item[-in-place] (Documented only for completeness: Do not use this
unless you know what you are doing.) If you already have an rsync, svn,
or other copy of \TL{} (see
\url{https://tug.org/texlive/acquire-mirror.html}) then this option
will use what you've got, as-is, and do only the necessary
post-install. Be warned that the file \filename{tlpkg/texlive.tlpdb}
may be overwritten; saving it is your responsibility. Also, package
removal has to be done manually. This option cannot be toggled via the
installer interface.
\end{ttdescription}
\subsubsection{The \optname{-repository} option}
\label{sec:location}
The default network package repository is a \CTAN{} mirror chosen
automatically via \url{http://mirror.ctan.org}.
If you want to override that, the location value can be a url
starting with \texttt{ftp:}, \texttt{http:}, \texttt{https:},
\texttt{file:/}, or a plain directory path. (When giving an
\texttt{http:}, \texttt{https:} or \texttt{ftp:}\ location, trailing