Provided by: texlive-base_2023.20230613-3_all bug

NAME

       install-tl - TeX Live cross-platform installer

SYNOPSIS

       install-tl [option]...

       install-tl-windows.bat [option]...

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
       <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.

REFERENCES

       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>.

EXAMPLES

       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:

       "install-tl --paper=letter"
           Initialize paper size setting. The only values allowed are "letter" and (the default)
           "a4".

       "install-tl --scheme" scheme
           Initialize the installation scheme; the default is "full".  For a list of schemes, see
           the interactive "S" menu.

       "install-tl --no-interaction"
           Perform the installation immediately after parsing options, without entering the
           interactive menu.

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

       Full documentation follows.

OPTIONS

       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).

       -gui [[=]module]
       -no-gui
           If no module is given, starts the Tcl/Tk (see below) GUI installer.

           If module is given loads the given installer module. Currently the following modules
           are supported:

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

           "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 "Advanced" takes you to a screen with roughly the same options as the
               former "perltk" interface.

           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.

       -lang 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).

       -repository 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 "tlmgr" has the details (<https://tug.org/texlive/doc/tlmgr.html#OPTIONS>).

           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.

       -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 "text" and "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.

       -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.

       -custom-bin 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 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 path are copied
           over to "bin/custom/" under your installation directory and this "bin/custom/"
           directory is what will be added to the path for the post-install actions. To install
           multiple custom binary sets, manually rename "custom" before doing each.

           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>.

       -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.

       -debug-setup-vars
           Print final values of directory variables; for more debugging information on how they
           were set, also specify "-v".

       -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.

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

       -help, --help, -?
           Display this help and exit. (This help is also on the web at
           <https://tug.org/texlive/doc/install-tl.html>). Sometimes the "perldoc" and/or "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 "NOPERLDOC"
           environment variable and "perldoc" will not be used.

       -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 "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.

       -init-from-profile profile_file
           Similar to -profile (see "PROFILES" below), but only initializes the installation
           configuration from profile_file and then starts a normal interactive session.
           Environment variables are not ignored.

       -logfile file
           Write both all messages (informational, debugging, warnings) to 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, "/usr/local/texlive/YYYY/install-tl.log" for
           the YYYY release.

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

       -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.

       -no-doc-install
       -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 "tlmgr":

             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/>.

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

       -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.

       -no-persistent-downloads
       -persistent-downloads
           For network installs, activating this option makes the installer try to set up a
           persistent connection using the "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 "wget" if this is not possible.  To disable usage of LWP and persistent
           connections, use "-no-persistent-downloads".

       -no-verify-downloads
           By default, if a GnuPG "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 "tlmgr" documentation, e.g.,
           <https://tug.org/texlive/doc/tlmgr.html#CRYPTOGRAPHIC-VERIFICATION>

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

       -paper "a4"|"letter"
           Set the default paper size for all TeX Live programs, as specified.  The default is
           "a4". The paper size can be set after installation with the "tlmgr paper" command.

       -portable
           Install for portable use, e.g., on a USB stick.  See the "instopt_portable"
           description below for details.

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

       -profile profile_file
           Load profile_file and do the installation with no user interaction, that is, a batch
           (unattended) install.  Environment variables are ignored. See "PROFILES" below.

       -q  Omit normal informational messages.

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

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

           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>.

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

       -texmflocal dir
           Specify the "TEXMFLOCAL" directory; the default is "/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 "-texdir" option changes this, putting "TEXMFLOCAL" under the main tree. The
           "-texmflocal" option can be used to specify an explicit directory.

           Anything installed here must follow the TeX directory structure (TDS), e.g.,
           "TEXMFHOME/tex/latex/mypkg/mypkg.sty". TDS reference: <https://tug.org/tds>.

       -texmfhome dir
           Specify the "TEXMFHOME" directory; the default is "~/texmf", except on Macs, where it
           is "~/Library/texmf". Analogously to "TEXMFLOCAL", the "-texuserdir" option changes
           this default.

           Also as with "TEXMFLOCAL", anything installed here must follow the TDS.

       -texmfsysconfig dir
       -texmfsysvar dir
           Specify the "TEXMFSYSCONFIG" and "TEXMFSYSVAR" system directories.

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

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

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

PROFILES

       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_")

       "instopt_adjustpath" (default 0 on Unix, 1 on Windows)
           Adjust "PATH" environment variable.

       "instopt_adjustrepo" (default 1)
           Set remote repository to a multiplexed CTAN mirror after installation; see
           "-repository" above.

       "instopt_letter" (default 0)
           Set letter size paper as the default, instead of a4.

       "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 "TEXMFHOME", "TEXMFCONFIG", "TEXMFVAR"
           to be identical to the system directories "TEXMFLOCAL", "TEXMFSYSCONFIG",
           "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.

       "instopt_write18_restricted" (default 1)
           Enable "\write18" for a restricted set of programs.

       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>.

ENVIRONMENT VARIABLES

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

       "NOPERLDOC"
           Don't try to run the "--help" message through "perldoc".

       "TEXLIVE_DOWNLOADER"
       "TL_DOWNLOAD_PROGRAM"
       "TL_DOWNLOAD_ARGS"
           These override the normal choice of a download program; see the "tlmgr" documentation,
           e.g., <https://tug.org/texlive/doc/tlmgr.html#ENVIRONMENT-VARIABLES>.

       "TEXLIVE_INSTALL_ENV_NOCHECK"
           Omit the check for environment variables containing the string "tex".  People
           developing TeX-related software are likely to have many such variables.

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

       "TEXLIVE_INSTALL_NO_DISKCHECK"
           If set to 1, omit free disk space check. By default, if a POSIX-compliant "df" program
           (supporting "-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 "df").

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

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

       "TEXLIVE_INSTALL_PAPER"
           Set the default paper size for all relevant programs; must be either "letter" or "a4".
           The default is "a4".

       "TEXLIVE_INSTALL_PREFIX"
       "TEXLIVE_INSTALL_TEXMFCONFIG"
       "TEXLIVE_INSTALL_TEXMFVAR"
       "TEXLIVE_INSTALL_TEXMFHOME"
       "TEXLIVE_INSTALL_TEXMFLOCAL"
       "TEXLIVE_INSTALL_TEXMFSYSCONFIG"
       "TEXLIVE_INSTALL_TEXMFSYSVAR"
           Specify the respective directories. "TEXLIVE_INSTALL_PREFIX" defaults to
           "/usr/local/texlive". All the defaults can be seen by running the installer
           interactively and then typing "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.

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.

         +----------------+--------------------------------------+--------------+------------------+
         |    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>.

BUGS

       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.

AUTHORS AND COPYRIGHT

       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 66578 2023-03-12 17:33:10Z karl $