tlmgr 的介绍

发表于 2021-03-04 更新于 2022-02-24 分类于帮助文档， LaTeX 阅读次数：本文字数： 12k 阅读时长 ≈ 11 分钟

这篇文章是用来熟悉 TeX Live 自带的包管理器 tlmgr(TeX Live Manager) 的使用, 官方文档位于 TUG, 这个文档会不定期更新我看的懂的并且觉得有用的部分. 这是一个翻译文档, 关于 tlmgr 使用方法的简介已经完成, 欢迎提 issue 或者 PR 来帮我改进这份文档.

注意:

文档中被中括号[]框起来的为可选参数, 如 --gui [action],
被尖括号<>框起来的为必要参数, 如 tlmgr info <what>,
被 | 分割开的选项为 n 选 1, 如 backup [option] <pkg|-all>,
文档中的 "软件包" 有时不仅指被用在 \usepackage{} 中的软件包.
命令中带有 ... 的选项或参数意味着它们可以被填入不只一个内容, 如 install [option...] <pkg...> 说明你可以使用 tlmgr install --force --reinstall ctex, amsmath.

概要

tlmgr 管理着 TeX Live 中的软件包以及配置. 最新的文档以及测试版本的信息位于 https://tug.org/texlive/tlmgr.html .

TeX Live 由一些最高级别的 schemes 组成, 每一种 scheme 都是由不同的 collections 与 packages 组成, 其中 collection 是 packages 的集合, 而 packages 是包含了一些文件的包. Schemes 里一般既有 collections 也有 packages, 但是每一个 package 都属于且只属于一个 collection.

使用 tlmgr info collections 可以列出 collections 的信息.

❯❯ tlmgr info collections
i collection-basic: Essential programs and files
i collection-bibtexextra: BibTeX additional styles
i collection-binextra: TeX auxiliary programs
i collection-context: ConTeXt and packages
i collection-fontsextra: Additional fonts
i collection-fontsrecommended: Recommended fonts
i collection-fontutils: Graphics and font utilities
i collection-formatsextra: Additional formats
i collection-games: Games typesetting
i collection-humanities: Humanities packages
i collection-langarabic: Arabic
i collection-langchinese: Chinese
i collection-langcjk: Chinese/Japanese/Korean (base)
i collection-langcyrillic: Cyrillic
i collection-langczechslovak: Czech/Slovak
i collection-langenglish: US and UK English
i collection-langeuropean: Other European languages
i collection-langfrench: French
i collection-langgerman: German
i collection-langgreek: Greek
i collection-langitalian: Italian
i collection-langjapanese: Japanese
i collection-langkorean: Korean
i collection-langother: Other languages
i collection-langpolish: Polish
i collection-langportuguese: Portuguese
i collection-langspanish: Spanish
i collection-latex: LaTeX fundamental packages
i collection-latexextra: LaTeX additional packages
i collection-latexrecommended: LaTeX recommended packages
i collection-luatex: LuaTeX packages
i collection-mathscience: Mathematics, natural sciences, computer science packages
i collection-metapost: MetaPost and Metafont packages
i collection-music: Music packages
i collection-pictures: Graphics, pictures, diagrams
i collection-plaingeneric: Plain (La)TeX packages
i collection-pstricks: PSTricks
i collection-publishers: Publisher styles, theses, etc.
i collection-texworks: TeXworks editor; TL includes only the Windows binary
i collection-wintools: Windows-only support programs
i collection-xetex: XeTeX and packages

用 tlmgr info schemes 可以列出 schemes 的信息

❯❯ tlmgr info schemes
i scheme-basic: basic scheme (plain and latex)
i scheme-context: ConTeXt scheme
i scheme-full: full scheme (everything)
i scheme-gust: GUST TeX Live scheme
i scheme-infraonly: infrastructure-only scheme (no TeX at all)
i scheme-medium: medium scheme (small + more packages and languages)
i scheme-minimal: minimal scheme (plain only)
i scheme-small: small scheme (basic + xetex, metapost, a few languages)
i scheme-tetex: teTeX scheme (more than medium, but nowhere near full)

可以在 TeX Live 文档查看 TeX Live 的全部可用文档.

基本格式

tlmgr 使用的基本格式为:

1	tlmgr [option...] <action> [option...] [operand...]

例子

成功安装 TeX Live 后, 可以设置一些 tlmgr 上的常用配置:

`tlmgr option repository ctan`

告诉 tlmgr 它可以从一个附近的 CTAN 镜像去获取最近的更新, 这条命令还可以写成

1	tlmgr option repository http://mirror.ctan.org/systems/texlive/tlnet

其中 ctan 是 http://mirror.ctan.org/systems/texlive/tlnet 的别名.

注意 mirror.ctan.org 会被解析为多个不同的域名, 它们并不是完全同步的, 我们建议 (它们) 最多每天更新一次¹. 如果出现了问题, 我们建议您选择一个特定的镜像站. 全部的镜像站以及它们的状态会列在镜像站列表.

大陆地区镜像

大陆用户可以将源指定为国内的镜像站, 在 CTAN 上可以找到亚洲镜像列表 . 下面列举出截止至 2021-03-04 可用的镜像站²:

镜像名	镜像地址
阿里云	https://mirrors.aliyun.com/CTAN/systems/texlive/
北京交通大学	https://mirror.bjtu.edu.cn/ctan/systems/texlive/
北京理工大学	https://mirrors.bit.edu.cn/CTAN/systems/texlive/
北京外国语大学	https://mirrors.bfsu.edu.cn/CTAN/systems/texlive/
重庆大学	https://mirrors.cqu.edu.cn/CTAN/systems/texlive/
东莞理工学院	https://mirrors.dgut.edu.cn/CTAN/systems/texlive/
哈尔滨工业大学	https://mirrors.hit.edu.cn/CTAN/systems/texlive/
华为云	https://mirrors.huaweicloud.com/CTAN/systems/texlive/
华中科技大学	http://mirrors.hust.edu.cn/CTAN/systems/texlive/
兰州大学	https://mirror.lzu.edu.cn/CTAN/systems/texlive/
南京大学	https://mirrors.nju.edu.cn/CTAN/systems/texlive/
清华大学	https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/
上海交通大学	https://mirrors.sjtug.sjtu.edu.cn/ctan/systems/texlive/
上海科技大学	https://mirrors.geekpie.club/CTAN/systems/texlive/
腾讯云	https://mirrors.cloud.tencent.com/CTAN/systems/texlive/
中国科学技术大学	https://mirrors.ustc.edu.cn/CTAN/systems/texlive/

并用 tlmgr option repository <site>/tlnet 的方式进行设置.

`tlmgr update --list`

仅列出所有可以被升级的内容.

`tlmgr update --all`

将您本地的 TeX 安装内容与包管理库中的内容同步.

`tlmgr info <what>`

列出 <what> 的详细信息, 比如它的安装状态以及介绍. 例如, 使用

1	tlmgr info ctex

可以查看 ctex 宏集的详细信息:

package:     ctex
category:    Package
shortdesc:   LaTeX classes and packages for Chinese typesetting
longdesc:    ctex is a collection of macro packages and document classes for LaTeX Chinese typesetting.
installed:   Yes
revision:    56705
sizes:       src: 473k, doc: 1101k, run: 1749k
relocatable: No
cat-version: 2.5.5
cat-license: lppl1.3c
cat-topics:  chinese book-pub class
cat-contact-bugs: https://github.com/CTeX-org/ctex-kit/issues
cat-contact-home: http://www.ctex.org/HomePage
cat-contact-repository: https://github.com/CTeX-org/ctex-kit
collection:  collection-langchinese

对于 tlmgr 的更详细的用法, 请继续阅读.

选项 (OPTIONS)

下列 tlmgr 的选项是全局选项, 不是特定于某一个命令的 (action specific). 对于所有的选项, 无论是全局的还是命令特定的, 都可以在

1	tlmgr [option...] action [option...] [operand...]

的任意位置, 按任意顺序使用. 命令中第一个不是选项的变量将会成为这个命令的主要操作 (main action). 在所有的情况中 -option 与 --option 是等价的, = 可以放在一个选项名和它的值之间, 按 key=value 的格式使用.

`--repository <url|path>`

指定一个软件包的仓库, 可以是本地文件夹 <path> 或者网络位置 <url>. 这个设置会临时覆盖掉 TeX Live Package Database (TLPDB, 由文件 tlpkg/texlive.tlpdb 给出) 中默认的软件包仓库.

注意 --repository <url|path> 命令只会修改当前运行的仓库选择, 如果想长期修改仓库, 可以使用 option repository (见 option操作)

比如, 你可以这样选择一个特定的 CTAN 镜像

1	-repository http://ctan.example.org/its/ctan/dir/systems/texlive/tlnet

当然，我们必须指定一个真正的主机名及其特定的最高级的 CTAN 目录. 全部可用的 CTAN 镜像可以在镜像站列表处查看.

下面是一个使用本地目录的例子:

1	-repository /local/TL/repository

也可以使用 --repo 作为 --repository 的简化.

剩下是一些特定的网络下的设置, 略过.

`--gui [action]`

tlmgr 有两个 GUI 前端, tlshell 和 tlcockpit, 它们是由不同的程序启动的, 详情可以查看它们的文档.

与命令行界面一样, tlmgr 自己有一个图形界面. 我们可以用一个选项 -gui 来调用它. 如果后面还跟着一个操作 (action), 那么会直接在图形界面执行这个操作, 比如

1	tlmgr --gui update

会直接启动升级图形界面. 如果 -gui 后面没有跟着操作, 那么就直接打开 GUI 的主界面. 由于我不使用 GUI 界面, 这里就不对这一部分进行介绍, 详情可以参考 GUI FOR TLMGR

`--gui-lang <llcode>`

通常情况来说, GUI 会从计算机中获取你使用的语言. 如果它没成功, 或者你想指定一个语言的 GUI 界面, 可以设置:

语言	语言代码
英语	`en`, 默认
捷克语	`cs`
德语	`de`
法语	`fr`
意大利语	`it`
日语	`ja`
荷兰语	`nl`
波兰语	`pl`
巴西葡萄牙语	`pt_BR`
俄语	`ru`
斯洛伐克语	`sl`
塞尔维亚语	`sr`
乌克兰语	`uk`
越南语	`vi`
简体中文	`zh_CN`
繁体中文	`zh_TW`

`--command-logfile <file>`

将 tlmgr 调用的所有程序 (mktexlr, mtxrun, fmtutil, updmap) 的输出写入一个文件 <file> 中, 默认位置为

1	TEXMFSYSVAR/web2c/tlmgr-commands.log

`--debug-translation`

一个协助翻译的选项, 略过

`--machine-readable`

将标准输出写成一个更适合计算机解析的格式

`--package-logfile <file>`

tlmgr 将所有软件包操作 (install, remove, update, failed updates, failed restores) 写入一个单独的日志文件, 默认位置为

1	TEXMFSYSVAR/web2c/tlmgr.log

这个选项让你可以为日志文件指定另一个路径.

`--pause`

让 tlmgr 在退出之前等待用户输入, 在 Windows 上可以避免命令行的消失.

`--usermode`

在这次运行 tlmgr 时启用 user mode. 见 USER MODE

`--usertree <dir>`

在 <dir> 中创建 user mode 的树. 见 USER MODE

`--verify-repo=<none|main|all>`

没看懂

TeX Live 程序的标准选项也可以使用, 比如 --help/-h/-?, --version, -q (无提示信息), -v (显示调试信息)

操作 (ACTIONS)

`help`

显示一个帮助信息并退出, 与 --help 选项的作用相同, 实际就是打开一个与 tlmgr帮助文档相同的帮助信息.

`version`

给出版本信息, 与 --version 选项相同, 如果也使用了 -v 选项, 那么所使用模块的版本信息也会被打印.

`backup`

`backup [option..] <pkg...|-all>`

如果没有指定 --clean 选项, 那么这个操作会创建一个软件包 <pkg> 的备份, 如果使用了 -all 选项, 则创建一个全部软件包的备份.

备份文件的位置将由 --backupdir <dir> 指定, 前提是 <dir> 存在并且可写. 如果没有指定 --backupdir, 那么就使用 TLPDB 中设置的 backupdir, 如果二者皆空, 那么将不会创建备份.

安装程序将 backupdir 默认设置在了 TeX Live 根目录下的 ./tlpkg/backups 中, 所以如果没有额外的设置, backupdir 总是存在. 查看 option 以获得更多信息.

如果指定了 --clean 选项, 那么备份文件将被删除, 而不是被保存. 一个可选的整数值 N 可以指定在清理时保留的备份数. 如果没有指定 N, 那么将使用 autobackup 的值, autobackup 默认在 TLPDB 中为 1. 如果二者皆空, 那么将会报错. 查看 option 来获得更多关于删除备份文件的详细信息.

backup 操作的特定选项:

`--backupdir <dir>`

临时覆盖 TLPDB 中 backupdir 的值. 参数 <dir> 必须要指定, 这是备份文件存放的路径, 它必须要存在且可写

`--all`

如果没有指定 --clean 选项, 那么创建一个 TeX Live 安装过的所有软件包的备份, 这会消耗大量的存储空间与时间. 如果指定 --clean 选项, 所有的备份将被删除.

`--clean[=N]`

删除备份目录 backupdir 中的旧备份, 而不是创建备份. 可选参数整数值 N 会临时覆盖 TLPDB 中 autobackup 的值. 如果使用这个选项, 那么必须要指定 --all 或者一列软件包.

`--dry-run`

备份或删除的操作将被打印在终端而不真正进行备份或者删除, 如 tlmgr --dry-run backup ctex 会打印出

1
2
3

❯❯ tlmgr --dry-run backup ctex
would save current status of ctex to d:/texlive/2020/tlpkg/backups/ctex.r56705.tar.lz4
no action taken due to --dry-run

`candidate <pkg>`

显示软件包 <pkg> 的候选仓库 (candidate repository). 见 MULTIPLE REPOSITORY

`check [option...] <depends|excutes|files|runfiles|texmfdbs|all>`

执行安装的一致性 (consistency of installation) 的一个或者全部检查, 如果没发现问题, 那么将不会有输出. (如果想看看 tlmgr 做了什么, 可以用 tlmgr -v check)

`depends`

列出那些没有被安装, 但是作为安装集合的软件包的依赖, 以及哪些没有包含在任何集合中的软件包.

如果使用 tlmgr check collections, 同样会执行 tlmgr check depends, 因为旧版本的 tlmgr 就是这么做的.

1 2	❯❯ tlmgr check collections tlmgr.pl: "collections" check has been replaced by "depends".

`excutes`

检查 TeX Live 数据库中 execute指令引用的文件是否存在. Check that the files referred to by execute directives in the TeX Live Database are present.

`files`

检查列在 TLPDB (texlive.tlpdb) 是否真的存在, 列出不存在的软件包.

`runfiles`

列出在执行文件中出现多次的文件名, 除了已知的重复文件名.

`texmfdbs`

检查与 ls-R 相关的文件. 如果你已经定义了新的 TEXMF 树, 或者更改了 TEXMF 或 TEXMFDBS 变量, 那运行它也没什么坏处 (it can't hurt to run this). 它检查了

all items in TEXMFDBS have the !! prefix.
all items in TEXMFBDS have an ls-R file (if they exist at all).
all items in TEXMF with !! are listed in TEXMFDBS.
all items in TEXMF with an ls-R file are listed in TEXMFDBS.

这些没看懂.

check 操作的特定选项:

`--use-svn`

在检查 TL 的发展仓库(? development repository) 时, 用 svn status 输出代替文件列表. (This is run nightly).

`conf`, `dump-tlpdb`, `generate`, `gui`

略

`info`

`info [option...] [pkg...|collections|schemes]`

如果没有参数, 列出仓库中全部的可用软件包, 把哪些已经安装的用 i 作为前缀.

如果用 collections 或者 schemes, 列出所需的类型, 而不输出软件包名 .

如果用任何其他的参数, 那么就把参数看成软件包名 <pkg...>, 并列出它的信息: 名称 (name), 分类 (category), 简短以及详细的介绍 (short and long description), 大小 (size), 安装状态 (installation status), 以及 TeX Live 中它的修订号 (TeX Live revision number).

如果 <pkg...> 在本地与线上都没有找到, 那么将会搜索与它相关的软件包和文件.

它也会显示从 TeX Catalogue 上获取的信息, 比如软件包版本 (package version), 日期 (date), 和许可证 (license). 考虑这些，特别是软件包版本，获得的信息仅仅是近似的，这是由于不同部分更新的时间偏差造成的.

旧操作 show 与 list 已经被合并到这个操作中, 但是为了后续的兼容性这两个操作依然可用.

info 操作的特定选项:

`--list`

如果指定了 --list 选项, 并且跟了一个软件包 <pkg...>, 那么这个软件包的包含文件也会被展示, 比如执行文件, 源文件, 软件包文档等等, 包括平台特定的依赖包 (platform-specific dependencies)

如果跟的是 schemes 或 collections, 那么输出的内容与不加 --list 相同.

`--only-installed`

如果指定这个选项, 那么 tlmgr 只会从本地安装的软件包, collections, 或者 schemes 中寻找信息, 而不使用安装的源.

`--only-remote`

只列出在远端仓库的软件包. 这个选项比较适合配合 tlmgr --repo ... 使用, 来查看某个软件包在某远端仓库是否可用, 用 tlmgr --repo ... --only-remote info <pkg...> 即可. 注意 --only-installed 和 --only-remote 不能同时指定.

`--data <item1, item2,...>`

如果制定了 --data 选项, 那它的参数只能从以下内容中选择: name, category, localrev, remoterev, shortdesc, longdesc, installed, size, relocatable, depends, cat-version, cat-date, cat-license, 以及字段 cat-contact-* (见下), 这些内容中间要用逗号,隔开.

cat-* 字段全部从 TeX Catalogue 中获得. 对于每个字段都有两个变种, 带 l 前缀和带 r 前缀, 比如: lcat-version 与 rcat-version, 分别代表了本地和远端的信息. 如果不带 l 和 r 的选项, 那么就显示最近的一个, 通常来说是远端的信息.

按照这个写法, 那么 cat-contact-* 字段包括了 home, repository, support, bugs, announce, development, 每一个都可能为空, 或者含有一个 url 值, 比如可以用

1	tlmgr info --data cat-contact-home amsmath

查看 amsmath 软件包的主页, 可以得到

1 2	❯❯ tlmgr info --data cat-contact-home amsmath http://www.ams.org/tex/amslatex.html

关于新软件包的简短的介绍可以在 CTAN upload page 上查看.

`--json`

如果指定 --json 选项, 那么将会给出一个 JSON 格式的输出, 可以在 tlpkg/doc/JSON-formats.txt 查看格式信息, 格式定义在 TLPOBJINFO1. 如果 --json 和 --data 同时被指定, 那么 --json 的优先级会更高.

`init-usertree`

为所谓的 user mode magagement 建立一个 texmf 树, 无论是在默认的用户树 TEXMFHOME 下, 还是一个被 --usertree 指定的树下. 见 USER MODE.

`install [option...] <pkg...>`

安装每一个 <pkg...> 中提到的软件包, 如果它们没有被安装的话, 这个操作不会去动失敬存在的软件包, 如果想获得软件包的最新版本, 见 update 操作.

这个操作默认也会安装给定的 <pkg...> 的依赖文件. By default this also installs all packages on which the given pkgs are dependent.

下面是 install 操作特有的选项:

`--dry-run`

安装会发生的事情会被打印出来, 而不真进的行安装

`--file`

从给定的软件包文件中安装软件包, 而不从安装仓库进行安装. 这些文件必须是标准的 TeX Live 软件包文件 (含有 tlpobj 文件)³

`--force`

如果 tlmgr 本身或其他基本的部分正在升级, 那么 tlmgr 将会退出这次安装, 并且不会安装任何软件包. 如果给定了 --force 选项, 那么这次的安装依然会继续进行. 不推荐使用

`--no-dependens`

不安装软件包的依赖. (默认设置下, 安装一个软件包要满足它的所有依赖)

`--no-dependens-at-all`

略.

`--reinstall`

重新安装一个软件包 (包括它的依赖), 尽管它们看起来已经被安装了. 这个选项对于恢复在层级中不小心删除的软件包很有用.

当重新安装时, only dependencies on normal packages are followed. (i.e., not those of category Scheme or Collection)

`--with-doc` 与 `--with-src`

install-tl 给了一个 "不安装文档/源文件" 的选项, 但是我们不推荐使用这个选项. (默认状态下会安装所有的文件). 如果用了这个选项, 那么当你想获得软件包的文档或者源文件的时候, 可以使用这两个选项与 --reinstall, 比如用 fontspec 宏包为例:

1	tlmgr install --reinstall --with-doc --with-src fontspec

这个操作不会在系统目录中自动添加新的符号链接, 需要手动运行 tlmgr path add "path" option USER MODE MULTIPLE REPOSITORY

概要

基本格式

例子

tlmgr option repository ctan

大陆地区镜像

tlmgr update --list

tlmgr update --all

tlmgr info <what>

选项 (OPTIONS)

--repository <url|path>

--gui [action]

--gui-lang <llcode>

--command-logfile <file>

--debug-translation

--machine-readable

--package-logfile <file>

--pause

--usermode

--usertree <dir>

--verify-repo=<none|main|all>

操作 (ACTIONS)

help

version

backup

backup [option..] <pkg...|-all>

--backupdir <dir>

--all

--clean[=N]

--dry-run

candidate <pkg>

check [option...] <depends|excutes|files|runfiles|texmfdbs|all>

depends

excutes

files

runfiles

texmfdbs

--use-svn

conf, dump-tlpdb, generate, gui

info

info [option...] [pkg...|collections|schemes]

--list

--only-installed

--only-remote

--data <item1, item2,...>

--json

init-usertree

install [option...] <pkg...>

--dry-run

--file

--force

--no-dependens

--no-dependens-at-all

--reinstall

--with-doc 与 --with-src

`tlmgr option repository ctan`

`tlmgr update --list`

`tlmgr update --all`

`tlmgr info <what>`

`--repository <url|path>`

`--gui [action]`

`--gui-lang <llcode>`

`--command-logfile <file>`

`--debug-translation`

`--machine-readable`

`--package-logfile <file>`

`--pause`

`--usermode`

`--usertree <dir>`

`--verify-repo=<none|main|all>`

`help`

`version`

`backup`

`backup [option..] <pkg...|-all>`

`--backupdir <dir>`

`--all`

`--clean[=N]`

`--dry-run`

`candidate <pkg>`

`check [option...] <depends|excutes|files|runfiles|texmfdbs|all>`

`depends`

`excutes`

`files`

`runfiles`

`texmfdbs`

`--use-svn`

`conf`, `dump-tlpdb`, `generate`, `gui`

`info`

`info [option...] [pkg...|collections|schemes]`

`--list`

`--only-installed`

`--only-remote`

`--data <item1, item2,...>`

`--json`

`init-usertree`

`install [option...] <pkg...>`

`--dry-run`

`--file`

`--force`

`--no-dependens`

`--no-dependens-at-all`

`--reinstall`

`--with-doc` 与 `--with-src`