| INSTALL-TL(1) | User Contributed Perl Documentation | INSTALL-TL(1) |
install-tl - TeX Live cross-platform installer
install-tl [option]...
install-tl-windows.bat [option]...
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 <https://tug.org/texlive/acquire.html>.
The basic idea of TeX Live installation is for you to choose one of the top-level schemes, each of which is defined as a different set of collections and 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 "tlmgr" (reference just below) after the initial installation is complete.
The default is "scheme-full", which installs everything, and this is highly recommended.
Post-installation configuration, package updates, and more, are handled through tlmgr(1), the TeX Live Manager (<https://tug.org/texlive/tlmgr.html>).
The most up-to-date version of this installer documentation is on the Internet at <https://tug.org/texlive/doc/install-tl.html>.
For step-by-step instructions, see <https://tug.org/texlive/quickinstall.html>.
For the full documentation of TeX Live, see <https://tug.org/texlive/doc>.
With no options, "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:
Full documentation follows.
As usual, all options can be specified in any order, and with either a leading "-" or "--". An argument value can be separated from its option by either a space or "=".
The options relating to customization of the installation can also be selected in the interactive installation menus (GUI or text).
If module is given loads the given installer module. Currently the following modules are supported:
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.
For installation, the default is to pick a mirror automatically, using <https://mirror.ctan.org/systems/texlive/tlnet>; the chosen mirror is then used for the entire download. You can use the special argument "ctan" as an abbreviation for this. (See <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.
For more information on custom binaries, see <https://tug.org/texlive/custom-bin.html>. For general information on building TeX Live, see <https://tug.org/texlive/build.html>.
If this option is not given, the installer will create a log file in the root of the writable installation tree, for example, "/usr/local/texlive/YYYY/install-tl.log" for the YYYY release.
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.
tlmgr option docfiles 1
tlmgr option srcfiles 1
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 "fontspec" package as the example):
tlmgr install --reinstall --with-doc --with-src fontspec
The source files mentioned here are those relating to TeX packages, such as ".dtx" files. The sources that are compiled to make the binaries are available separately: see <https://tug.org/texlive/svn/>.
This option is turned on by default, and the installation program will fall back to using "wget" if this is not possible. To disable usage of LWP and persistent connections, use "-no-persistent-downloads".
There is a brief summary of these directories trees at "DIRECTORY TREES" below; for details on the trees set up by default, and their intended usage, see the main TeX Live documentation at <https://tug.org/texlive/doc>.
Anything installed here must follow the TeX directory structure (TDS), e.g., "TEXMFHOME/tex/latex/mypkg/mypkg.sty". TDS reference: <https://tug.org/tds>.
Also as with "TEXMFLOCAL", anything installed here must follow the TDS.
A 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 "tlpkg/texlive.profile". In addition, from the text menu one can select "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 "-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 "tlmgr" to work at the package level.
Within a profile file, each line consists of
variable [value]
except for comment lines starting with "#". The possible variable names are listed below. Values, when present, are either 0 or 1 for booleans, or strings (which must be specified without any quote characters). Leading whitespace is ignored.
If the variable "selected_scheme" is defined and 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
selected_scheme scheme-small
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 "S" menu in the text installer, or equivalent.
In addition to "selected_scheme", here are the other variable names supported in a profile:
collection options (prefix "collection-")
Collections are specified with a variable name with the prefix "collection-" followed by a collection name; there is no value. For instance, "collection-basic". The collections are described in the "C" menu.
Schemes and collections (and packages) are ultimately defined by the files in the "tlpkg/tlpsrc/" source directory.
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.
TEXDIR TEXMFLOCAL TEXMFSYSCONFIG TEXMFSYSVAR TEXMFCONFIG TEXMFVAR TEXMFHOME
installer options (prefix "instopt_")
In addition, on Windows, it disables the desktop integration, path adjustment, and file associations actions usually performed.
tlpdb options (prefix "tlpdbopt_")
The definitive list is given in "tlpkg/TeXLive/TLConfig.pm", in the hash %TeXLive::TLConfig::TLPDBOptions, together with explanations. All items given there except for "tlpdbopt_location" can be specified. Here is the current list:
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
platform options (prefix "binary_")
For each supported platform in TeX Live (directories under "bin/"), the variable "binary_"PLATFORM can be set with value 1. For example:
binary_x86_64-linux 1
If no "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 "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 <https://tug.org/texlive/doc>.
For ease in scripting and debugging, "install-tl" looks for the following environment variables. They are not of interest for normal user installations.
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.
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.
+----------------+--------------------------------------+--------------+------------------+ | 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 | +----------------+--------------------------------------+--------------+------------------+
In addition, as mentioned in the previous section, each tree has an environment variable "TEXLIVE_INSTALL_"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 "OPTIONS".
For the user trees, the default value uses "~", and this is left as a literal "~" in "texmf.cnf". That way, each user can have their own "TEXMFHOME", etc., as intended. On the other hand, for the system trees, if "~" is used during the installation, this is assumed to simply be a typing shorthand, and the expanded home directory is written in "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 <https://tug.org/texlive/doc>.
The "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 "install-tl" and the infrastructure, resulting in (probably) inscrutable Perl errors. The way forward is to run "install-tl" out of the installer package ("install-tl-unx.tar.gz" or "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 "install-tl" to adjust options or installed packages in an existing installed tree. Use "tlmgr" instead.
This script and its documentation were written for the TeX Live distribution (<https://tug.org/texlive>) and both are licensed under the GNU General Public License Version 2 or later.
$Id: install-tl 63919 2022-07-17 17:49:31Z karl $
| 2022-07-17 | perl v5.34.0 |