summaryrefslogtreecommitdiff
path: root/Build/source/doc/tlbuild-incl/install-tl.texi
blob: f6bae78e392d76ad5b0fd790f5cd237628ff2fe0 (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
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
@node install-tl
@appendix install-tl

@node install-tl NAME
@appendixsec install-tl NAME

install-tl - TeX Live cross-platform installer

@node install-tl SYNOPSIS
@appendixsec install-tl SYNOPSIS

install-tl [@emph{option}]...

install-tl-windows.bat [@emph{option}]...

@node install-tl DESCRIPTION
@appendixsec install-tl DESCRIPTION

This installer creates a runnable TeX Live installation from various
media, including over the network, from local hard disk, a DVD, etc. The
installer works on all platforms supported by TeX Live. For information
on initially downloading TeX Live, see
@url{https://tug.org/texlive/acquire.html}.

The basic idea of TeX Live installation is for you to choose one of the
top-level @emph{schemes}, each of which is defined as a different set of
@emph{collections} and @emph{packages}, where a collection is a set of packages,
and a package is what contains actual files. Each package is in exactly
one collection, while schemes can contain any combination of packages
and collections.

Within the installer, you can choose a scheme, and further customize the
set of collections to install, but not the set of the packages.  To work
at the package level, use @code{tlmgr} (reference just below) after the
initial installation is complete.

The default is @code{scheme-full}, which installs everything, and this is
highly recommended.

@node install-tl REFERENCES
@appendixsec REFERENCES

Post-installation configuration, package updates, and more, are
handled through @strong{tlmgr}(1), the TeX Live Manager
(@url{https://tug.org/texlive/tlmgr.html}).

The most up-to-date version of this installer documentation is on the
Internet at @url{https://tug.org/texlive/doc/install-tl.html}.

For step-by-step instructions, see
@url{https://tug.org/texlive/quickinstall.html}.

For the full documentation of TeX Live, see
@url{https://tug.org/texlive/doc}.

@node install-tl EXAMPLES
@appendixsec install-tl EXAMPLES

With no options, @code{install-tl} drops you into an interactive menu where
essentially all default settings can be changed. With options, you can
initialize the settings in various ways, or perform the installation
without interaction. Some examples:

@table @asis
@item @code{install-tl --paper=letter}
@anchor{install-tl @code{install-tl --paper=letter}}

Initialize paper size setting. The only values allowed are @code{letter} and
(the default) @code{a4}.

@item @code{install-tl --scheme} @emph{scheme}
@anchor{install-tl @code{install-tl --scheme} @emph{scheme}}

Initialize the installation scheme; the default is @code{full}.  For a list
of schemes, see the interactive @code{S} menu.

@item @code{install-tl --no-interaction}
@anchor{install-tl @code{install-tl --no-interaction}}

Perform the installation immediately after parsing options, without
entering the interactive menu.

@item @code{install-tl --profile} @emph{texlive.profile}
@anchor{install-tl @code{install-tl --profile} @emph{texlive.profile}}

Install, without interaction, according to the given TL profile file;
see @ref{install-tl PROFILES,, PROFILES} below. To initialize from the profile and then enter the
interactive menu, add @code{--init-from-profile}.

@end table

Full documentation follows.

@node install-tl OPTIONS
@appendixsec install-tl OPTIONS

As usual, all options can be specified in any order, and with either a
leading @code{-} or @code{--}.  An argument value can be separated from its
option by either a space or @code{=}.

The options relating to customization of the installation can also be
selected in the interactive installation menus (GUI or text).

@table @asis
@item @strong{-gui} [[=]@emph{module}]
@anchor{install-tl @strong{-gui} [[=]@emph{module}]}

@item @strong{-no-gui}
@anchor{install-tl @strong{-no-gui}}

If no @emph{module} is given, starts the Tcl/Tk (see below) GUI installer.

If @emph{module} is given loads the given installer module. Currently the
following modules are supported:

@table @asis
@item @code{text}
@anchor{install-tl @code{text}}

The text mode user interface (default on Unix systems, including Macs).
Same as the @code{-no-gui} option.

@item @code{tcl} (or "perltk" or "wizard" or "expert" or nothing)
@anchor{install-tl @code{tcl} (or "perltk" or "wizard" or "expert" or nothing)}

The Tcl/Tk user interface (default on Windows).  It starts
with a small number of configuration options, roughly equivalent
to what the former wizard option offers, but a button @code{Advanced}
takes you to a screen with roughly the same options as the former
@code{perltk} interface.

@end table

The default GUI requires Tcl/Tk. This was standard on Macs, but has been
removed in the latest macOS releases. It's often already installed on
GNU/Linux, or can be easily installed through a distro package manager.
For Windows, TeX Live provides a Tcl/Tk runtime.

@item @strong{-lang} @emph{llcode}
@anchor{install-tl @strong{-lang} @emph{llcode}}

By default, the Tcl GUI uses the language detection built into
Tcl/Tk. If that fails you can select a different language by
giving this option with a language code (based on ISO 639-1).
Currently supported (but not necessarily completely translated) are:
English (en, default), Czech (cs), German (de), French (fr), Italian
(it), Japanese (ja), Dutch (nl), Polish (pl), Brazilian Portuguese
(pt_BR), Russian (ru), Slovak (sk), Slovenian (sl), Serbian (sr),
Ukrainian (uk), Vietnamese (vi), simplified Chinese (zh_CN), and
traditional Chinese (zh_TW).

@item @strong{-repository} @emph{url|path}
@anchor{install-tl @strong{-repository} @emph{url|path}}

Specify the package repository to be used as the source of the
installation. In short, this can be a directory name or a url using
http(s), ftp, or scp. The documentation for @code{tlmgr} has the details
(@url{https://tug.org/texlive/doc/tlmgr.html#OPTIONS}).

For installation, the default is to pick a mirror automatically, using
@url{https://mirror.ctan.org/systems/texlive/tlnet}; the chosen mirror is
then used for the entire download. You can use the special argument
@code{ctan} as an abbreviation for this. (See @url{https://ctan.org} for more
about CTAN and its mirrors.)

After installation is complete, you can use that installation as the
repository for another installation.  If you chose to install less than
the full scheme containing all packages, the list of available schemes
will be adjusted accordingly.

@item @strong{-select-repository}
@anchor{install-tl @strong{-select-repository}}

This option allows you to choose a particular mirror from the current
list of active CTAN mirrors. This option is supported in the @code{text}
and @code{gui} installer modes, and will also offer to install
from local media if available, or from a repository specified on the
command line. It's useful when the (default) automatic redirection does
not choose a good host for you.

@item @strong{-all-options}
@anchor{install-tl @strong{-all-options}}

Normally options not relevant to the current platform are not shown
(e.g., when running on Unix, Windows-specific options are omitted).
Giving this command line option allows configuring such "foreign"
settings.

@item @strong{-custom-bin} @emph{path}
@anchor{install-tl @strong{-custom-bin} @emph{path}}

If you have built your own set of TeX Live binaries (e.g., because
precompiled binaries were not provided by TL for your platform), this
option allows you to specify the @emph{path} to a directory where the
binaries for the current system are present. The installation will
continue as usual, but at the end all files from @emph{path} are copied over
to @code{bin/custom/} under your installation directory and this
@code{bin/custom/} directory is what will be added to the path for the
post-install actions. To install multiple custom binary sets, manually
rename @code{custom} before doing each.

For more information on custom binaries, see
@url{https://tug.org/texlive/custom-bin.html}.  For general information on
building TeX Live, see @url{https://tug.org/texlive/build.html}.

@item @strong{-debug-fakenet}
@anchor{install-tl @strong{-debug-fakenet}}

Pretend we're doing a network install. This is for the sole purpose of
testing the code to handle broken downloads, via moving package files
aside in a tlnet mirror hierarchy.

@item @strong{-debug-setup-vars}
@anchor{install-tl @strong{-debug-setup-vars}}

Print final values of directory variables; for more debugging
information on how they were set, also specify @code{-v}.

@item @strong{-debug-translation}
@anchor{install-tl @strong{-debug-translation}}

In the former Perl/Tk GUI modes, this option reported any missing,
or more likely untranslated, messages to standard error. Not yet
implemented for the Tcl interface. Helpful for translators to see
what remains to be done.

@item @strong{-force-platform} @emph{platform}
@anchor{install-tl @strong{-force-platform} @emph{platform}}

Instead of auto-detecting the current platform, use @emph{platform}.
Binaries for this platform must be present in @code{bin/}@emph{platform}@code{/} and
they must be runnable, or installation will fail. @code{-force-arch} is a
synonym.

@item @strong{-help}, @strong{@asis{}-@asis{}-@asis{}help}, @strong{-?}
@anchor{install-tl @strong{-help}@comma{} @strong{@asis{}-@asis{}-@asis{}help}@comma{} @strong{-?}}

Display this help and exit. (This help is also on the web at
@url{https://tug.org/texlive/doc/install-tl.html}). Sometimes the @code{perldoc}
and/or @code{PAGER} programs on the system have problems, possibly resulting
in control characters being literally output. This can't always be
detected, but you can set the @code{NOPERLDOC} environment variable and
@code{perldoc} will not be used.

@item @strong{-in-place}
@anchor{install-tl @strong{-in-place}}

This is a quick-and-dirty installation option in case you already have
an rsync or svn checkout of TeX Live.  It will use the checkout as-is
and will just do the necessary post-install.  Be warned that the file
@code{tlpkg/texlive.tlpdb} may be rewritten, that removal has to be done
manually, and that the only realistic way to maintain this installation
is to redo it from time to time.  This option is not available via the
installer interfaces.  USE AT YOUR OWN RISK.

@item @strong{-init-from-profile} @emph{profile_file}
@anchor{install-tl @strong{-init-from-profile} @emph{profile_file}}

Similar to @strong{-profile} (see @ref{install-tl PROFILES,, PROFILES} below), but only initializes
the installation configuration from @emph{profile_file} and then starts a
normal interactive session. Environment variables are not ignored.

@item @strong{-logfile} @emph{file}
@anchor{install-tl @strong{-logfile} @emph{file}}

Write both all messages (informational, debugging, warnings) to @emph{file},
in addition to standard output or standard error.

If this option is not given, the installer will create a log file
in the root of the writable installation tree,
for example, @code{/usr/local/texlive/YYYY/install-tl.log} for the @emph{YYYY}
release.

@item @strong{-no-cls}
@anchor{install-tl @strong{-no-cls}}

For the text mode installer only: do not clear the screen when entering
a new menu. For debugging.

@item @strong{-no-continue}
@anchor{install-tl @strong{-no-continue}}

Quit early on installation failure of a non-core package.

By default, a few core packages are installed first; then, a failed
installation of any other (non-core) package is noted, but does not stop
the installation. Any such failed packages are retried, once.

If the retry also fails, by default the installer proceeds to completion
anyway, with the idea that it was a transient network problem and
reinstallation will succeed later. If this option is specified, and the
retry fails, the installer aborts.

@item @strong{-no-doc-install}
@anchor{install-tl @strong{-no-doc-install}}

@item @strong{-no-src-install}
@anchor{install-tl @strong{-no-src-install}}

Do not install the documentation resp. source package files, both for
the immediate installation and for future updates. After installation,
inclusion of the doc/src files can be re-enabled via @code{tlmgr}:

@verbatim
  tlmgr option docfiles 1
  tlmgr option srcfiles 1
@end verbatim

If you later find that you want the doc/src files for a package that has
been installed without them, you can get them like this (using the
@code{fontspec} package as the example):

@verbatim
  tlmgr install --reinstall --with-doc --with-src fontspec
@end verbatim

The source files mentioned here are those relating to TeX packages, such
as @code{.dtx} files. The sources that are compiled to make the binaries are
available separately: see @url{https://tug.org/texlive/svn/}.

@item @strong{-no-installation}
@anchor{install-tl @strong{-no-installation}}

Do not perform any installation. This is for debugging the
initialization and setup routines without touching the disk.

@item @strong{-no-interaction}
@anchor{install-tl @strong{-no-interaction}}

Do not enter the interactive menu; immediately perform the installation
after initialization and option parsing. Also omit the check for a
previous installation and asking about importing previous settings.

@item @strong{-no-persistent-downloads}
@anchor{install-tl @strong{-no-persistent-downloads}}

@item @strong{-persistent-downloads}
@anchor{install-tl @strong{-persistent-downloads}}

For network installs, activating this option makes the installer try to
set up a persistent connection using the @code{LWP} Perl module.  This
opens only one connection between your computer and the server per
session and reuses it, instead of initiating a new download for each
package, which typically yields a significant speed-up.

This option is turned on by default, and the installation program will
fall back to using @code{wget} if this is not possible.  To disable usage of
LWP and persistent connections, use @code{-no-persistent-downloads}.

@item @strong{-no-verify-downloads}
@anchor{install-tl @strong{-no-verify-downloads}}

By default, if a GnuPG @code{gpg} binary is found in PATH, downloads are
verified against a cryptographic signature. This option disables such
verification.  The full description is in the Crytographic Verification
section of the @code{tlmgr} documentation, e.g.,
@url{https://tug.org/texlive/doc/tlmgr.html#CRYPTOGRAPHIC-VERIFICATION}

@item @strong{-non-admin}
@anchor{install-tl @strong{-non-admin}}

For Windows only: configure for the current user, not for all users.

@item @strong{-paper} @code{a4}@strong{|}@code{letter}
@anchor{install-tl @strong{-paper} @code{a4}@strong{|}@code{letter}}

Set the default paper size for all TeX Live programs, as specified.
The default is @code{a4}. The paper size can be set after installation with
the @code{tlmgr paper} command.

@item @strong{-portable}
@anchor{install-tl @strong{-portable}}

Install for portable use, e.g., on a USB stick.  See the
@code{instopt_portable} description below for details.

@item @strong{-print-platform}
@anchor{install-tl @strong{-print-platform}}

Print the TeX Live identifier for the detected platform
(hardware/operating system) combination to standard output, and exit.
@code{-print-arch} is a synonym.

@item @strong{-profile} @emph{profile_file}
@anchor{install-tl @strong{-profile} @emph{profile_file}}

Load @emph{profile_file} and do the installation with no user interaction,
that is, a batch (unattended) install.  Environment variables are
ignored. See @ref{install-tl PROFILES,, PROFILES} below.

@item @strong{-q}
@anchor{install-tl @strong{-q}}

Omit normal informational messages.

@item @strong{-scheme} @emph{scheme}
@anchor{install-tl @strong{-scheme} @emph{scheme}}

Schemes are the highest level of package grouping in TeX Live; the
default is to use the @code{full} scheme, which includes everything. This
option overrides that default. The @emph{scheme} argument value may
optionally have a prefix @code{scheme-}. The list of supported scheme names
depends on what your package repository provides; see the interactive
menu list.

@item @strong{-texdir} @emph{dir}
@anchor{install-tl @strong{-texdir} @emph{dir}}

Specify the system installation directory; the default is
@code{/usr/local/texlive/YYYY} for release YYYY. Specifying this option also
causes the @code{TEXMFLOCAL}, @code{TEXMFSYSCONFIG}, and @code{TEXMFSYSVAR}
directories to be set as subdirectories of @emph{dir}, so they don't have to
be set individually.

There is a brief summary of these directories trees at @ref{install-tl DIRECTORY
TREES,, DIRECTORY
TREES} below; for details on the trees set up by default, and their
intended usage, see the main TeX Live documentation at
@url{https://tug.org/texlive/doc}.

@item @strong{-texuserdir} @emph{dir}
@anchor{install-tl @strong{-texuserdir} @emph{dir}}

Specify the user installation directory; the default is
@code{~/.texliveYYYY} (except on Macs, where there is no leading dot).
Specifying this also causes the @code{TEXMFHOME}, @code{TEXMFCONFIG}, and
@code{TEXMFVAR} directories to be set as subdirectories of @emph{dir}.

@item @strong{-texmflocal} @emph{dir}
@anchor{install-tl @strong{-texmflocal} @emph{dir}}

Specify the @code{TEXMFLOCAL} directory; the default is
@code{/usr/local/texlive/texmf-local}, that is, one level up from the main
installation. This is so locally-installed packages can be easily used
across releases, which is usually desirable. Specifying the @code{-texdir}
option changes this, putting @code{TEXMFLOCAL} under the main tree. The
@code{-texmflocal} option can be used to specify an explicit directory.

Anything installed here must follow the TeX directory structure (TDS),
e.g., @code{TEXMFHOME/tex/latex/mypkg/mypkg.sty}. TDS reference:
@url{https://tug.org/tds}.

@item @strong{-texmfhome} @emph{dir}
@anchor{install-tl @strong{-texmfhome} @emph{dir}}

Specify the @code{TEXMFHOME} directory; the default is @code{~/texmf}, except on
Macs, where it is @code{~/Library/texmf}. Analogously to @code{TEXMFLOCAL}, the
@code{-texuserdir} option changes this default.

Also as with @code{TEXMFLOCAL}, anything installed here must follow the TDS.

@item @strong{-texmfsysconfig} @emph{dir}
@anchor{install-tl @strong{-texmfsysconfig} @emph{dir}}

@item @strong{-texmfsysvar} @emph{dir}
@anchor{install-tl @strong{-texmfsysvar} @emph{dir}}

Specify the @code{TEXMFSYSCONFIG} and @code{TEXMFSYSVAR} system directories.

@item @strong{-texmfconfig} @emph{dir}
@anchor{install-tl @strong{-texmfconfig} @emph{dir}}

@item @strong{-texmfvar} @emph{dir}
@anchor{install-tl @strong{-texmfvar} @emph{dir}}

Specify the @code{TEXMFCONFIG} and @code{TEXMFVAR} user directories.
The defaults are @code{~/.texliveYYYY/texmf-@{config,var@}}, except on Macs,
where the leading dot is omitted (@code{~/texliveYYYY/...}).

@item @strong{-v}
@anchor{install-tl @strong{-v}}

Include verbose debugging messages; repeat for maximum debugging: @code{-v
-v}.  (Further repeats are accepted but ignored.)

@item @strong{-version}, @strong{@asis{}-@asis{}-@asis{}version}
@anchor{install-tl @strong{-version}@comma{} @strong{@asis{}-@asis{}-@asis{}version}}

Output version information and exit.  If @code{-v} is also given, the
versions of the TeX Live modules used are also reported.

@end table

@node install-tl PROFILES
@appendixsec PROFILES

A @emph{profile} file normally contains all the values needed to perform an
installation. After a normal installation has finished, a profile for
that exact installation is written to the file @code{tlpkg/texlive.profile}.
In addition, from the text menu one can select @code{P} to save the current
setup as a profile at any time. These are small text files; feel free to
peruse and edit them according to your needs.

Such a profile file can be given as the argument to @code{-profile}, for
example to redo the exact same installation on a different system.
Alternatively, you can use a custom profile, most easily created by
starting from a generated one and changing values. An empty profile
file will cause the installer to use the defaults.

As mentioned above, the installer only supports selection by scheme and
collections, not individual packages, so packages cannot be specified in
profile files either. Use @code{tlmgr} to work at the package level.

Within a profile file, each line consists of

@emph{variable} [@emph{value}]

except for comment lines starting with @code{#}.  The possible variable
names are listed below.  Values, when present, are either @code{0} or @code{1}
for booleans, or strings (which must be specified without any quote
characters).  Leading whitespace is ignored.

If the variable @code{selected_scheme} is defined and @emph{no} collection
variables at all are defined, then the collections required by the
specified scheme (which might change over time) are installed, without
explicitly listing them. This eases maintenance of profile files. If any
collections are specified in a profile, though, then the scheme is
ignored and all desired collections must be given explicitly.

For example, a line 

@verbatim
  selected_scheme scheme-small
@end verbatim

along with definitions for the installation directories (given below
under "path options") suffices to install the "small" scheme with all
default options.  The schemes are described in the @code{S} menu in the
text installer, or equivalent.

In addition to @code{selected_scheme}, here are the other variable names
supported in a profile:

@strong{collection options} (prefix @code{collection-})

Collections are specified with a variable name with the prefix
@code{collection-} followed by a collection name; there is no value.  For
instance, @code{collection-basic}.  The collections are described in the
@code{C} menu.

Schemes and collections (and packages) are ultimately defined by the
files in the @code{tlpkg/tlpsrc/} source directory.

@strong{path options}

It is best to define all of these, even though they may not be used in a
given installation, so as to avoid unintentionally getting a default
value that could cause problems later.

@verbatim
  TEXDIR
  TEXMFLOCAL
  TEXMFSYSCONFIG
  TEXMFSYSVAR
  TEXMFCONFIG
  TEXMFVAR
  TEXMFHOME
@end verbatim

@strong{installer options} (prefix @code{instopt_})

@table @asis
@item @code{instopt_adjustpath} (default 0 on Unix, 1 on Windows)
@anchor{install-tl @code{instopt_adjustpath} (default 0 on Unix@comma{} 1 on Windows)}

Adjust @code{PATH} environment variable.

@item @code{instopt_adjustrepo} (default 1)
@anchor{install-tl @code{instopt_adjustrepo} (default 1)}

Set remote repository to a multiplexed CTAN mirror after installation;
see @code{-repository} above.

@item @code{instopt_letter} (default 0)
@anchor{install-tl @code{instopt_letter} (default 0)}

Set letter size paper as the default, instead of a4.

@item @code{instopt_portable} (default 0)
@anchor{install-tl @code{instopt_portable} (default 0)}

Install for portable use, e.g., on a USB stick, without touching the
host system. Specifically, this forces the user directories
@code{TEXMFHOME}, @code{TEXMFCONFIG}, @code{TEXMFVAR} to be identical to the system
directories @code{TEXMFLOCAL}, @code{TEXMFSYSCONFIG}, @code{TEXMFSYSVAR},
respectively (regardless of other options and environment variable.)

In addition, on Windows, it disables the desktop integration, path
adjustment, and file associations actions usually performed.

@item @code{instopt_write18_restricted} (default 1)
@anchor{install-tl @code{instopt_write18_restricted} (default 1)}

Enable @code{\write18} for a restricted set of programs.

@end table

@strong{tlpdb options} (prefix @code{tlpdbopt_})

The definitive list is given in @code{tlpkg/TeXLive/TLConfig.pm}, in the hash
@code{%TeXLive::TLConfig::TLPDBOptions}, together with explanations.  All
items given there @emph{except} for @code{tlpdbopt_location} can be specified.
Here is the current list:

@verbatim
  tlpdbopt_autobackup
  tlpdbopt_backupdir
  tlpdbopt_create_formats
  tlpdbopt_desktop_integration
  tlpdbopt_file_assocs
  tlpdbopt_generate_updmap
  tlpdbopt_install_docfiles
  tlpdbopt_install_srcfiles
  tlpdbopt_post_code
  tlpdbopt_sys_bin
  tlpdbopt_sys_info
  tlpdbopt_sys_man
  tlpdbopt_w32_multi_user
@end verbatim

@strong{platform options} (prefix @code{binary_})

For each supported platform in TeX Live (directories under @code{bin/}), the
variable @code{binary_}@emph{PLATFORM} can be set with value 1.  For example:

@verbatim
  binary_x86_64-linux 1
@end verbatim

If no @code{binary_} settings are made, the default is whatever the
current machine is running.

In releases before 2017, many profile variables had different
names (not documented here; see the @code{install-tl} source).  They are
accepted and transformed to the names given above.  When a profile is
written, the names above are always used.

For more details on all of the above options, consult the TeX Live
installation manual, linked from @url{https://tug.org/texlive/doc}.

@node install-tl ENVIRONMENT VARIABLES
@appendixsec ENVIRONMENT VARIABLES

For ease in scripting and debugging, @code{install-tl} looks for the
following environment variables. They are not of interest for normal
user installations.

@table @asis
@item @code{NOPERLDOC}
@anchor{install-tl @code{NOPERLDOC}}

Don't try to run the @code{--help} message through @code{perldoc}.

@item @code{TEXLIVE_DOWNLOADER}
@anchor{install-tl @code{TEXLIVE_DOWNLOADER}}

@item @code{TL_DOWNLOAD_PROGRAM}
@anchor{install-tl @code{TL_DOWNLOAD_PROGRAM}}

@item @code{TL_DOWNLOAD_ARGS}
@anchor{install-tl @code{TL_DOWNLOAD_ARGS}}

These override the normal choice of a download program; see the @code{tlmgr}
documentation, e.g.,
@url{https://tug.org/texlive/doc/tlmgr.html#ENVIRONMENT-VARIABLES}.

@item @code{TEXLIVE_INSTALL_ENV_NOCHECK}
@anchor{install-tl @code{TEXLIVE_INSTALL_ENV_NOCHECK}}

Omit the check for environment variables containing the string @code{tex}.
People developing TeX-related software are likely to have many such
variables.

@item @code{TEXLIVE_INSTALL_NO_CONTEXT_CACHE}
@anchor{install-tl @code{TEXLIVE_INSTALL_NO_CONTEXT_CACHE}}

Omit creating the ConTeXt cache.  This is useful for redistributors.

@item @code{TEXLIVE_INSTALL_NO_DISKCHECK}
@anchor{install-tl @code{TEXLIVE_INSTALL_NO_DISKCHECK}}

If set to 1, omit free disk space check. By default, if a
POSIX-compliant @code{df} program (supporting @code{-Pk}) is available, the
installer checks for available disk space in the selected installation
location, and will abort installation if there is insufficient disk
space, plus a margin of 100MB. An equivalent check is made on Windows
(not involving @code{df}).

@item @code{TEXLIVE_INSTALL_NO_RESUME}
@anchor{install-tl @code{TEXLIVE_INSTALL_NO_RESUME}}

Omit check for installing on top of a previous installation and then
asking about importing previous settings.

@item @code{TEXLIVE_INSTALL_NO_WELCOME}
@anchor{install-tl @code{TEXLIVE_INSTALL_NO_WELCOME}}

Omit printing the welcome message after successful installation, e.g.,
when testing.

@item @code{TEXLIVE_INSTALL_PAPER}
@anchor{install-tl @code{TEXLIVE_INSTALL_PAPER}}

Set the default paper size for all relevant programs; must be either
@code{letter} or @code{a4}. The default is @code{a4}.

@item @code{TEXLIVE_INSTALL_PREFIX}
@anchor{install-tl @code{TEXLIVE_INSTALL_PREFIX}}

@item @code{TEXLIVE_INSTALL_TEXMFCONFIG}
@anchor{install-tl @code{TEXLIVE_INSTALL_TEXMFCONFIG}}

@item @code{TEXLIVE_INSTALL_TEXMFVAR}
@anchor{install-tl @code{TEXLIVE_INSTALL_TEXMFVAR}}

@item @code{TEXLIVE_INSTALL_TEXMFHOME}
@anchor{install-tl @code{TEXLIVE_INSTALL_TEXMFHOME}}

@item @code{TEXLIVE_INSTALL_TEXMFLOCAL}
@anchor{install-tl @code{TEXLIVE_INSTALL_TEXMFLOCAL}}

@item @code{TEXLIVE_INSTALL_TEXMFSYSCONFIG}
@anchor{install-tl @code{TEXLIVE_INSTALL_TEXMFSYSCONFIG}}

@item @code{TEXLIVE_INSTALL_TEXMFSYSVAR}
@anchor{install-tl @code{TEXLIVE_INSTALL_TEXMFSYSVAR}}

Specify the respective directories. @code{TEXLIVE_INSTALL_PREFIX} defaults
to @code{/usr/local/texlive}. All the defaults can be seen by running the
installer interactively and then typing @code{D} for the directory menu.

The various command line options for specifying directories override
these environment variables; since specifying both is usually
accidental, a warning is given if the values are different.

@end table

@node install-tl DIRECTORY TREES
@appendixsec DIRECTORY TREES

There are a plethora of ways to specify the plethora of directory trees
used by TeX Live. By far the simplest, and recommended, approach is not
to change anything. The defaults suffice for the vast majority of
installations.

But, for the sake of explanation, here is a table of the trees and the
command line options that change them. The first group of three are
system directories, and the second group of three are user directories;
the two groups are quite analogous.

@verbatim
  +----------------+--------------------------------------+--------------+------------------+
  |    tree        | default                              | group change | single change    |
  +----------------+--------------------------------------+--------------+------------------+
  | TEXMFLOCAL     | /usr/local/texlive/texmf-local       | --texdir     | --texmflocal     |
  | TEXMFSYSVAR    | /usr/local/texlive/YYYY/texmf-var    | --texdir     | --texmfsysvar    |
  | TEXMFSYSCONFIG | /usr/local/texlive/YYYY/texmf-config | --texdir     | --texmfsysconfig |
  +----------------+--------------------------------------+--------------+------------------+
  | TEXMFHOME      | ~/texmf                              | --texuserdir | --texmfhome      |
  | TEXMFVAR       | ~/.texliveYYYY/texmf-var             | --texuserdir | --texmfvar       |
  | TEXMFCONFIG    | ~/.texliveYYYY/texmf-config          | --texuserdir | --texmfconfig    |
  +----------------+--------------------------------------+--------------+------------------+
@end verbatim

In addition, as mentioned in the previous section, each tree has an
environment variable @code{TEXLIVE_INSTALL_}@emph{tree} which overrides the
default; command line and profile settings both override environment
variable settings.

The defaults vary slightly on Macs, as explained above in @ref{install-tl OPTIONS,, OPTIONS}.

For the user trees, the default value uses @code{~}, and this is left as a
literal @code{~} in @code{texmf.cnf}. That way, each user can have their own
@code{TEXMFHOME}, etc., as intended. On the other hand, for the system
trees, if @code{~} is used during the installation, this is assumed to
simply be a typing shorthand, and the expanded home directory is written
in @code{texmf.cnf}, since it doesn't make sense to have user-specific
system directories.

For more on the directory trees and their intended usage, see the main
TeX Live documentation at @url{https://tug.org/texlive/doc}.

@node install-tl BUGS
@appendixsec install-tl BUGS

The @code{install-tl} script copies itself into the installed tree.
Usually, it can be run from there, using the installed tree as the
source for another installation.  Occasionally, however, there may be
incompatibilities in the code of the new @code{install-tl} and the
infrastructure, resulting in (probably) inscrutable Perl errors.  The
way forward is to run @code{install-tl} out of the installer package
(@code{install-tl-unx.tar.gz} or @code{install-tl.zip}) instead of the
installation. Feel free to also report the issue; usually the code
can be easily synced up again.

By the way, do not try to use @code{install-tl} to adjust options or
installed packages in an existing installed tree. Use @code{tlmgr} instead.

@node install-tl AUTHORS AND COPYRIGHT
@appendixsec AUTHORS AND COPYRIGHT

This script and its documentation were written for the TeX Live
distribution (@url{https://tug.org/texlive}) and both are licensed under the
GNU General Public License Version 2 or later.

$Id: install-tl 69711 2024-02-05 17:23:27Z karl $