diff options
Diffstat (limited to 'Build/source/doc/tlbuild-incl/install-tl.texi')
| -rw-r--r-- | Build/source/doc/tlbuild-incl/install-tl.texi | 577 |
1 files changed, 577 insertions, 0 deletions
diff --git a/Build/source/doc/tlbuild-incl/install-tl.texi b/Build/source/doc/tlbuild-incl/install-tl.texi new file mode 100644 index 00000000000..6e0e4d00997 --- /dev/null +++ b/Build/source/doc/tlbuild-incl/install-tl.texi @@ -0,0 +1,577 @@ +@node install-tl +@appendix install-tl + +@menu +* install-tl NAME:: +* install-tl SYNOPSIS:: +* install-tl DESCRIPTION:: +* install-tl REFERENCES:: +* install-tl OPTIONS:: +* install-tl PROFILES:: +* install-tl ENVIRONMENT VARIABLES:: +* install-tl AUTHORS AND COPYRIGHT:: +@end menu + +@node install-tl NAME +@appendixsec NAME + +install-tl - TeX Live cross-platform installer + +@node install-tl SYNOPSIS +@appendixsec SYNOPSIS + +install-tl [@emph{option}]... + +install-tl-windows.bat [@emph{option}]... + +install-tl-advanced.bat [@emph{option}]... + +@node install-tl DESCRIPTION +@appendixsec 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. + +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 the full documentation of TeX Live, see +@url{https://tug.org/texlive/doc}. + +@node install-tl OPTIONS +@appendixsec 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{=}. + +@table @asis +@item @strong{-gui} [[=]@emph{module}] +@anchor{install-tl @strong{-gui} [[=]@emph{module}]} + +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). Same as the +@code{-no-gui} option. + +@item @code{tcl} +@anchor{install-tl @code{tcl}} + +The Tcl/Tk user interface (default on Macs and Windows). It starts +with a small number of configuration options, roughly equivalent +to what the wizard option below offers, but a button @code{Advanced} +takes you to a screen with roughly the same options as the @code{perltk} +interface. + +@item @code{wizard} +@anchor{install-tl @code{wizard}} + +The wizard mode user interface, asking only minimal questions before +installing all of TeX Live. + +@item @code{expert} +@anchor{install-tl @code{expert}} + +A generic name for, currently, @code{perltk}; it may select a different GUI +in the future. + +@item @code{perltk} +@anchor{install-tl @code{perltk}} + +The expert GUI installer, providing access to more options. + +@end table + +The @code{perltk} and @code{wizard} modules require the Perl/Tk module +(@url{https://tug.org/texlive/distro.html#perltk}). if Perl/Tk is not +available, installation continues in text mode, except on Windows, +where all gui options except @code{text} are diverted to the default +@code{tcl} GUI. + +The @code{tcl} GUI requires Tcl/Tk. This is standard on Macs and is often +already installed on GNU/Linux. For Windows, TeX Live provides a Tcl/Tk +runtime. + +@item @strong{-no-gui} +@anchor{install-tl @strong{-no-gui}} + +Use the text mode installer (default except on Windows and Macs). + +@item @strong{-lang} @emph{llcode} +@anchor{install-tl @strong{-lang} @emph{llcode}} + +By default, the GUI tries to deduce your language from the +environment. The Tcl GUI uses the language detection built into +Tcl/Tk; the Perl/Tk GUIs use the @code{LC_MESSAGES} environment +variable. 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{http://mirror.ctan.org/systems/texlive/tlnet}; the chosen mirror is +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}, +@code{wizard} and @code{perltk} 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 (perhaps because +your platform was not supported by TeX Live out of the box), 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-translation} +@anchor{install-tl @strong{-debug-translation}} + +In the Perl/Tk GUI modes, this option reports any missing, or more +likely untranslated, messages to standard error. 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 and they must actually be +runnable, or installation will fail. @code{-force-arch} is a synonym. + +@item @strong{-help}, @strong{--help}, @strong{-?} +@anchor{install-tl @strong{-help}@comma{} @strong{--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 purposes). + +@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{Net::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{-portable} +@anchor{install-tl @strong{-portable}} + +Install for portable use, e.g., on a USB stick. Also selectable from +within the perltk and text installers. + +@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. You can change the scheme again before +the actual installation with the usual menu. The @emph{scheme} argument 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{-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{--version} +@anchor{install-tl @strong{-version}@comma{} @strong{--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 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. + +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, or an empty file, +which will take all 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 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. + +Besides @code{selected_scheme}, here is the list of 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 +the installation, so as to avoid unintentionally getting a default value +that could cause problems later. + +@verbatim + TEXDIR + TEXMFCONFIG + TEXMFVAR + TEXMFHOME + TEXMFLOCAL + TEXMFSYSCONFIG + TEXMFSYSVAR +@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. + +@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{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_IMPORT} +@anchor{install-tl @code{TEXLIVE_INSTALL_NO_IMPORT}} + +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_PREFIX} +@anchor{install-tl @code{TEXLIVE_INSTALL_PREFIX}} + +@item @code{TEXLIVE_INSTALL_TEXDIR} +@anchor{install-tl @code{TEXLIVE_INSTALL_TEXDIR}} + +@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}, while @code{TEXLIVE_INSTALL_TEXDIR} defaults to +the release directory within that prefix, e.g., +@code{/usr/local/texlive/2016}. All the defaults can be seen by running the +installer interactively and then typing @code{D} for the directory menu. + +@item @code{NOPERLDOC} +@anchor{install-tl @code{NOPERLDOC}} + +Don't try to run the @code{--help} message through @code{perldoc}. + +@end table + +@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 54143 2020-03-06 23:51:18Z karl $ + |