summaryrefslogtreecommitdiff
path: root/info/tlmgrbasics/doc/tlmgr.tex
blob: 86f8989d7f8ad0266425ad29f8ffb8e8bce39499 (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
\documentclass[11pt]{article}
\usepackage[T1]{fontenc}
\usepackage{microtype}
\usepackage[osf]{mathpazo}

% using OT1 encoding for tt to avoid need for cm-super fonts
\renewcommand{\ttfamily}{\fontencoding{OT1}\fontfamily{cmtt}\selectfont}

\usepackage{hyperref}

\title{Basic Usage of \texttt{tlmgr}, the \TeX\,Live Manager}
\author{edited by Bob Tennent\thanks{\scriptsize Derived
from the man page \texttt{tlmgr.1} and licensed under
the GNU General Public Licence, Version 2 or later.}\\
\url{rdt@cs.queensu.ca}}

\usepackage[headheight=14pt]{geometry}
\usepackage{fancyhdr}
\pagestyle{fancy}
\begin{document}
\maketitle
\thispagestyle{empty}


\tableofcontents

\clearpage

\section{Introduction}

\texttt{tlmgr} manages an existing \TeX\,Live installation,
both packages and configuration options. For information
on initially downloading and installing \TeX\,Live, see
\url{https://tug.org/texlive/acquire.html}.

\TeX\,Live is organized into a few top-level
\textit{schemes}, each of which specifies a set of
\textit{collections} and \textit{packages}, where a
collection is a set of packages, and a package is what
contains actual files. Schemes typically contain a mix of
collections and packages, but each package is included in
exactly one collection, no more and no less. A \TeX\,Live
installation can be customized and managed at any level.

We will describe usage of \texttt{tlmgr} in the
command-line interface. There are graphical front-ends
for \texttt{tlmgr}: \texttt{tlshell}, \texttt{tlcockpit}
and, for Macs, a \TeX\,Live Utility; these must
be started as separate programs. These is also a
graphical user interface in \texttt{tlmgr} itself;
consult the documentation here: 
\begin{center}
  \url{https://tug.org/texlive/doc/tlmgr.html#GUI-FOR-TLMGR}.
\end{center}



\section{Usage}

\begin{quote}
  \texttt{tlmgr} 
  \verb|[|\textit{global options} \verb|]| 
  \textit{action} 
  \verb|[|\textit{action-specific options}\verb|]|  
  \verb|[|\textit{operands}\verb|]|
\end{quote}

The actions and relevant action-specific options and
operands are described in Section~\ref{Actions}. The global
options are described in Section~\ref{GlobalOptions}.

Options, whether global or action-specific, may be
given anywhere on the command line, and in any order.
The first non-option argument will be treated as the
main action. In all cases, \verb|--|\textit{option} and
\verb|-|\textit{option} are equivalent, and an \verb|=| is
optional between an option name and its value.

This report documents only the most commonly-used actions
and options for \texttt{tlmgr}. Complete documentation may
be found at
\begin{center}
  \url{https://tug.org/texlive/doc/tlmgr.html}. 
\end{center}

\clearpage
\section{Examples}

After successfully installing \TeX\,Live, the following are
examples of common operations with \texttt{tlmgr}:
\begin{description}

\item\texttt{tlmgr -help install}\par

Displays reference documentation on the \texttt{install} action.

\item\texttt{tlmgr option repository ctan}\par 

Tells \texttt{tlmgr} to use a nearby CTAN mirror for
future updates; \texttt{ctan} is just an alias for
\url{http://mirror.ctan.org/systems/texlive/tlnet}. Caveat:
\texttt{mirror.ctan.org} resolves to many different
hosts, and they are not perfectly synchronized; we
recommend updating only daily (at most), and not more
often. You can choose a particular mirror in place of
\texttt{mirror.ctan.org} if there are problems; the
list of all CTAN mirrors with the status of each is at
\url{https://ctan.org/mirrors/mirmon}. Don't forget to add
\texttt{.../systems/texlive/tlnet} to the path.

\item\texttt{tlmgr update -all}\par 

Makes your local \TeX\ installation correspond to what is in
the default package repository.

\item\texttt{tlmgr update -self}\par 

Updates \texttt{tlmgr} itself (that is, the infrastructure
packages) if updates to it are present. If the
\texttt{-self} option is given together with either
\texttt{-all} or a list of packages, then \texttt{tlmgr}
will be updated first and, if this update succeeds, the
new version will be restarted to complete the rest of the
updates.

\item\texttt{tlmgr info fontspec}\par 

Displays detailed information about package
\texttt{fontspec}, such as the installation status and
description.

\item\texttt{tlmgr info -list fontspec}\par 

The list of files in package \texttt{fontspec} is
also displayed, including those for platform-specific
dependencies.

\item\texttt{tlmgr install fontspec}\par 

Installs the \texttt{fontspec} package (unless it is already
installed). By default all packages on which the given
package is dependent are also installed. Existing packages
are not touched.

\item\texttt{tlmgr search -file cabin}\par 

Search locally installed packages and display all filenames
containing \texttt{cabin}.

\end{description}

\clearpage

\section{Actions}
\label{Actions}

\subsection{The {\tt info} Action}
\label{info}

\paragraph{Usage:}

\begin{list}{}{}
\item \texttt{tlmgr info} 
\item \texttt{tlmgr info collections} 
\item \texttt{tlmgr info schemes}
\item \texttt{tlmgr info} \textsl{pkgs} 
\end{list}

With no argument, lists all packages available at the
package repository, prefixing those already installed with
\texttt{i}.

With the single word \texttt{collections} or
\texttt{schemes} as the argument, lists all the collections
and schemes, respectively, instead of all packages.

With any other arguments, displays information about each
of the \textsl{pkgs}: the name, category, short and long
description, sizes, installation status, and \TeX\,Live
revision number. If the package is not locally installed,
searches in the remote installation source.

For normal packages (not collections or schemes), the sizes
of the four groups of files (run/src/doc/bin) are shown
separately. For collections, the cumulative size is shown,
including all directly-dependent packages (but not dependent
collections). For schemes, the cumulative size is also
shown, including all directly-dependent collections and
packages.

If a package is not found locally or remotely, the
\texttt{search} action (see Section~\ref{search}) is used
and lists matching packages and files.

It also displays information taken from the \TeX\ Catalogue,
namely the package version, date, and license. Consider
these, especially the package version, as approximations
only, due to timing skew of the updates of the different
pieces. By contrast, the \texttt{revision} value comes
directly from TL and is reliable.


\paragraph{Options for \mdseries\texttt{info}:}

\begin{description}

\item\texttt{-list}\par 

If the option \texttt{-list} is given with a package, the
list of contained files is also shown, including those for
platform-specific dependencies. When given with schemes and
collections, \texttt{-list} outputs their dependencies in a
similar way.

\item\texttt{-only-installed}\par 

If this option is given, the installation source will not
be used; only locally installed packages, collections, or
schemes are listed.

\item\texttt{-only-remote}\par 

Only list packages from the remote repository. Useful when
checking what is available in a remote repository using
\begin{center}
\texttt{tlmgr -repo ... -only-remote info}. 
\end{center}

\end{description}

Note that \texttt{-only-installed} and \texttt{-only-remote}
cannot both be specified.

\clearpage

\subsection{The {\tt search} Action}
\label{search}

\paragraph{Usage:}
\begin{list}{}{}

\item \texttt{tlmgr search} \textsl{what} \end{list} By
default, search the names, short descriptions, and long
descriptions of all locally installed packages for the
argument \textsl{what}, interpreted as a (Perl) regular
expression.

\paragraph{Options for {\tt search}:}

\begin{description}

\item\texttt{-file}\par 

List all filenames containing \textsl{what}.

\item\texttt{-global}\par 

Search the \TeX\,Live Database of the installation medium,
instead of the local installation.

\item\texttt{-word}\par 

Restrict the search of package names and descriptions (but
not filenames) to match only full words. For example,
searching for \texttt{table} with this option will not
output a package containing the word \texttt{tables} (unless
it also contains the word \texttt{table} on its own).

\end{description}

\clearpage

\subsection{The {\tt install} Action}
\label{install}

\paragraph{Usage:}
\begin{list}{}{}
\item  \texttt{tlmgr install} \textsl{pkgs}
\end{list}

Install each of the \textsl{pkgs} (unless it is already
installed). By default all packages on which the given
package is dependent are also installed. Existing packages
are not touched; use the \texttt{update} action described in
Section~\ref{update} to get the latest version of a package.


\paragraph{Options for \mdseries\texttt{install}:}

\begin{description}

\item\texttt{-dry-run}\par 

Nothing is actually installed; instead, the actions to be
performed are written to the terminal.

\item\texttt{-reinstall}\par 

Reinstall a package (including dependencies for collections)
even if it already seems to be installed (i.e, is present in
the \TeX\,Live Package Database). This is useful to recover
from accidental removal of files in the hierarchy.

When re-installing, only dependencies on normal packages are
followed (i.e., not those of category Scheme or Collection).

\item\texttt{-with-doc}, \texttt{-with-src}\par 

The \texttt{install-tl} program provides the option of
omitting installation of all documentation and/or source
files. (By default, everything is installed.) After such an
installation, you may find that you want the documentation
or source files for a given package after all. You can
get them by using these options in conjunction with
\texttt{-reinstall}, as in 
\begin{center} 
  \texttt{tlmgr install -reinstall -with-doc -with-src} \textsl{pkgs}
\end{center}

\item\texttt{-no-depends}\par 

Do not install dependencies. (By default, installing a
package ensures that all dependencies of this package are
fulfilled.)

\end{description}

\par\noindent 
The \texttt{install} action does not
automatically add new symlinks in system directories; you
need to run
\begin{center}
  \texttt{tlmgr path add} 
\end{center}
yourself if you are using this feature and want new symlinks
added; see Section~\ref{path}.

\clearpage

\subsection{The {\tt update} Action}
\label{update}

\paragraph{Usage:}

\begin{list}{}{}
\item \texttt{tlmgr update} \textsl{pkgs} 
\end{list}
Updates the packages given as arguments to the latest
version available at the installation source. Either
\texttt{-all} or at least one package name must be
specified.

\paragraph{Options for {\tt update}:}

\begin{description}

\item\texttt{-all}\par 

Update all installed packages (except for \texttt{tlmgr}
itself). If updates to \texttt{tlmgr} itself are listed,
this gives an error, unless also the option \texttt{-force}
or \texttt{-self} is given. (See below.)

In addition to updating the installed packages, during
the update of a collection the local installation is (by
default) synchronized to the status of the collection on the
server, for both additions and removals.

This means that if a package has been removed on the
server (and thus has also been removed from the respective
collection), \texttt{tlmgr} will remove the package in the
local installation. This is called ``auto-remove'' and is
announced as such when using the option \texttt{-list}.

Analogously, if a package has been added to a collection
on the server that is also installed locally, it will
be added to the local installation. This is called
``auto-install'' and is announced as such when using the
option \texttt{-list}.

An exception to the collection dependency checks (including
the auto-installation of packages just mentioned) are
those that have been ``forcibly removed'' by you,
that is, you called \texttt{tlmgr remove -force} on
them. (See the \texttt{remove} action documentation.)
To reinstall any such forcibly removed packages use
\texttt{-reinstall-forcibly-removed}.

If you want to exclude some packages from the current update
run (e.g., due to a slow link), see the \texttt{-exclude}
option below.

\item\texttt{-self}\par 

Update \texttt{tlmgr} itself (that is, the infrastructure
packages) if updates to it are present. On Windows this
includes updates to the private Perl interpreter shipped
inside \TeX\,Live.

If this option is given together with either \texttt{-all}
or a list of packages, then \texttt{tlmgr} will be updated
first and, if this update succeeds, the new version will be
restarted to complete the rest of the updates.

\item\texttt{-dry-run}\par 

Nothing is actually installed; instead, the actions to
be performed are written to the terminal. This is a more
detailed report than using \texttt{-list}.

\item\texttt{-list} [\textsl{pkg}]\par 

Concisely list the packages which would be updated, newly
installed, or removed, without actually changing anything.
If \texttt{-all} is also given, all available updates are
listed. If \texttt{-self} is given, but not \texttt{-all},
only updates to the critical packages (\texttt{tlmgr},
\TeX\,Live infrastructure, Perl on Windows, etc.) are listed.

If neither \texttt{-all} nor \texttt{-self} is given, and
in addition no \textsl{pkg} is given, then \texttt{-all} is
assumed. Thus, \mbox{\texttt{tlmgr update -list}} is the
same as \mbox{\texttt{tlmgr update -list -all}}. If neither
\texttt{-all} nor \texttt{-self} is given, but specific
package names are given, those packages are checked for
updates.

\item\texttt{-exclude} \textsl{pkg}\par 

Exclude \textsl{pkg} from the update process. If this option
is given more than once, its arguments accumulate.

An argument \textsl{pkg} excludes both the package
\textsl{pkg} itself and any related platform-specific
packages. For example,

\begin{center}
  \texttt{tlmgr update -all -exclude a2ping}
\end{center}

will not update \texttt{a2ping}, \texttt{a2ping.i386-linux},
or any other \mbox{\texttt{a2ping}.xxx} package.

If this option specifies a package that would otherwise
be a candidate for auto-installation, auto-removal, or
reinstallation of a forcibly removed package, \texttt{tlmgr}
quits with an error message. Excludes are not supported in
these circumstances.



\item\texttt{-no-depends}\par 

If you call for updating a package, normally all depending
packages will also be checked for updates and updated if
necessary. This switch suppresses this behavior.

\end{description}

\noindent
If the package on the server is older than the package
already installed (e.g., if the selected mirror is out of
date), \texttt{tlmgr} does not downgrade. Also, packages for
uninstalled platforms are not installed.

This action does not automatically add or remove
new symlinks in system directories. You need to run
\texttt{tlmgr path} yourself if you are using this feature
and want new symlinks added; see Section~\ref{path}.

\clearpage

\subsection{The {\tt remove} Action}
\label{remove}

\paragraph{Usage:}
\begin{list}{}{}
\item  \texttt{tlmgr remove} \textsl{pkgs}
\end{list}

Remove each of the \textsl{pkgs}. Removing a collection
removes all package dependencies (unless \texttt{-nodepends}
is specified), but not any collection dependencies of that
collection. However, when removing a package, dependencies
are never removed.



\paragraph{Options for \mdseries\texttt{remove}:}

\begin{description}

\item\texttt{-dry-run}\par 

Nothing is actually removed; instead, the actions to be
performed are written to the terminal.

\item\texttt{-no-depends}\par 

Do not remove dependent packages.

\item\texttt{-all}\par 

Uninstalls all of \TeX\,Live, asking for confirmation unless
\texttt{-force} is also specified.

\end{description}

\par\noindent
The \texttt{remove} action does not automatically remove
symlinks in system directories; you need to run
\begin{center}
\texttt{tlmgr path remove} 
\end{center}
yourself if you are using this feature and want stale
symlinks removed; see Section~\ref{path}.

\begin{list}{}{}
 \item \texttt{tlmgr path [-w32mode=user|admin] add}
 \item \texttt{tlmgr path [--w32mode=user|admin] remove}
\end{list}

\clearpage

\subsection{The {\tt option} Action}
\label{option}

\paragraph{Usage:}

\begin{list}{}{}
\item \texttt{tlmgr option} 
\item \texttt{tlmgr option help} 
\item \texttt{tlmgr option} \textsl{key}
\item \texttt{tlmgr option} \textsl{key value}
\end{list}

The first form shows the global \TeX\,Live settings currently
saved with a short description and the \texttt{key}
used for changing it in parentheses. The second form is
similar, but also shows options which can be defined but
are not currently set to any value. In the third form, the
setting for \textsl{key} is displayed. In the fourth form,
\textsl{key} is set to \textsl{value}.

Some of the possible values for \textsl{key} are (run \texttt{tlmgr
option help} for the definitive list):

\begin{center}
\begin{small}
\begin{tabular}{@{\ttfamily}ll}
    repository &default package repository,\\
    docfiles & install documentation files,\\
    srcfiles & install source files,\\
    sys\_bin &  directory to which executables are linked by the \texttt{path} action\\
    sys\_man &  directory to which man pages are linked by the \texttt{path} action\\
    sys\_info&  directory to which info files are linked by the \texttt{path} action\\
    desktop\_integration & Windows-only: create Start menu shortcuts\\
    fileassocs& Windows-only: change file associations\\
    multiuser &Windows-only: install for all users\\
\end{tabular}
\end{small}
\end{center}

\noindent
One common use of \texttt{option} is to permanently change
the installation to get further updates from the Internet,
after originally installing from DVD\@. For example, you can
run
\begin{center}\ttfamily
   tlmgr option repository ctan
\end{center}
to use a nearby CTAN mirror for future updates.

The \texttt{docfiles} and \texttt{srcfiles} keys control the
installation of their respective file groups (documentation,
sources; grouping is approximate) per package. By default
both are enabled (\verb|1|). Either or both can be disabled
(set to \verb|0|) if disk space is limited or for minimal
testing installations, etc. When disabled, the respective
files are not downloaded at all.

The \verb|sys_bin|, \verb|sys_man|, and \verb|sys_info|
options are used on Unix systems to control the generation
of links for executables, info files and man pages. See the
\texttt{path} action in Section~\ref{path} for details.

The remaining options affect behavior on Windows installations.  

\begin{itemize}
  \item If \texttt{desktop\_integration} is set,
then some packages will install items in a sub-folder of the Start menu for \texttt{tlmgr gui},
documentation, etc.  
  \item If \texttt{fileassocs} is set, Windows file associations are made (see also the
\texttt{postaction} action).  
   \item If \texttt{multiuser} is set, then adaptions to the registry and the
menus are done for all users on the system instead of only the current user.  
\end{itemize}
All three of these options are on by default.

\clearpage

\subsection{The {\tt path} Action}
\label{path}

\paragraph{Usage:}

\begin{list}{}{}
 \item     \texttt{tlmgr path [-w32mode=user|admin] add}
 \item     \texttt{tlmgr path [--w32mode=user|admin] remove}
\end{list}

On Unix, adds or removes symlinks for executables, man
pages, and info pages in the system directories specified by
the respective options (see the \texttt{option} description
above). Does not change any initialization files, either
system or personal. Furthermore, any executables added
or removed by future updates are not taken care of
automatically; this command must be rerun as needed.

On Windows, the registry part where the binary directory is
added or removed is determined in the following way:
\begin{itemize}

\item If the user has admin rights, and the option
\texttt{-w32mode} is not given, the setting
\texttt{w32\_multi\_user} determines the location (i.e.,
if it is on the system path, otherwise the user path is
changed).

\item If the user has admin rights, and the option
\texttt{-w32mode} is given, this option determines the path
to be adjusted.

\item If the user does not have admin rights, and the
option \texttt{-w32mode} is not given, and the setting
\texttt{w32\_multi\_user} is off, the user path is changed,
while if the setting \texttt{w32\_multi\_user} is on, a
warning is issued that the caller does not have enough
privileges.

\item If the user does not have admin rights, and the option
\texttt{-w32mode} is given, it must be \texttt{user} and
the user path will be adjusted. If a user without admin
rights uses the option \texttt{-w32mode admin} a warning
is issued that the caller does not have enough privileges.
\end{itemize}


\clearpage

\clearpage
\section{Global Options}
\label{GlobalOptions}

\begin{description}

\item\texttt{-\relax-help}, \texttt{-help}, \texttt{-h}, \texttt{-?}\par

These options display reference documentation for any
action.

\item\texttt{-\relax-version}, \texttt{-version}\par

Displays version information about the \TeX\,Live release
and the \texttt{tlmgr} script itself. If \texttt{-v} is
also given, revision numbers for the loaded \TeX\,Live Perl
modules are shown as well.

\item\texttt{-q}\par  

Suppresses informational messages.

\item\texttt{-v}\par 

Displays debugging messages; can be repeated for more
output.

\item\texttt{-command-logfile} \textsl{file}\par

\texttt{tlmgr} logs the output of all programs invoked
(\verb|mktexlr|, \verb|mtxrun|, \verb|fmtutil|,
\verb|updmap|) to a log file, by default
\texttt{TEXMFSYSVAR/web2c/tlmgr-commands.log}. This option
allows you to specify a different \textsl{file} for the log.

\item\texttt{-package-logfile} \textsl{file}\par

\texttt{tlmgr} logs all package actions (\verb|install|,
\verb|remove|, \verb|update|, failed updates,
failed restores) to a log file, by default
\texttt{TEXMFSYSVAR/web2c/tlmgr.log}. This option allows you
to specify a different \textsl{file} for the log.

\item\texttt{-pause}\par 

This option makes \texttt{tlmgr} wait for user input before
exiting. Useful on Windows to avoid disappearing command
windows.


\end{description}


\end{document}