summaryrefslogtreecommitdiff
path: root/Build/source/doc/tlbuild-incl/install-tl.texi
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2021-02-25 19:22:25 +0000
committerKarl Berry <karl@freefriends.org>2021-02-25 19:22:25 +0000
commitad547a6b5986815fda458221149728d9d9ab1d87 (patch)
tree16296910eb3eca724371474ea9aea3994dc69614 /Build/source/doc/tlbuild-incl/install-tl.texi
parent947b43de3dd21d58ccc2ffadefc4441ea1c2a813 (diff)
restore Build,TODO from r57911
git-svn-id: svn://tug.org/texlive/trunk@57915 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Build/source/doc/tlbuild-incl/install-tl.texi')
-rw-r--r--Build/source/doc/tlbuild-incl/install-tl.texi577
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 $
+