TeXLive::TLPSRC -- TeX Live Package Source (.tlpsrc) module
use TeXLive::TLPSRC;
my $tlpsrc = TeXLive::TLPSRC->new(name => "foobar");
$tlpsrc->from_file("/some/tlpsrc/package.tlpsrc");
$tlpsrc->from_file("package");
$tlpsrc->writeout;
$tlpsrc->writeout(\*FILEHANDLE);The TeXLive::TLPSRC module handles TeX Live Package Source (.tlpsrc) files, which contain all (and only) the information which cannot be automatically derived from other sources, notably the TeX Live directory tree and the TeX Catalogue. In other words, .tlpsrc files are hand-maintained.
Often they are empty, when all information can be derived from the package name, which is (by default) the base name of the .tlpsrc file.
A tlpsrc file consists of lines of the form:
key value
where key can be one of: name category catalogue shortdesc longdesc depend execute postaction tlpsetvar runpattern srcpattern docpattern binpattern.
Continuation lines are supported via a trailing backslash. That is, if the .tlpsrc file contains two physical lines like this:
foo\
barthey are concatenated into foobar. The backslash and the newline are removed; no other whitespace is added or removed.
Comment lines begin with a # and continue to the end of the line. Within a line, a # that is preceded by whitespace is also a comment.
Blank lines are ignored.
The keys are described in the following sections.
nameidentifies the package; value must consist only of [-_a-zA-Z0-9], i.e., with what Perl considers a \w. It is optional; if not specified, the name of the .tlpsrc file will be used (with the .tlpsrc removed).
There are three exceptions to this rule:
where ARCH is a supported architecture-os combination. This has two uses. First, packages are split (automatically) into containers for the different architectures to make possible installations including only the necessary binaries. Second, one can add 'one-arch-only' packages, often used to deal with Windows peculiarities.
(notice the dot in the package name) These packages are core TeX Live packages. They are treated as usual packages in almost all respects, but have that extra dot to be sure they will never clash with any package that can possibly appear on CTAN. The only such package currently is texlive.infra, which contains tlmgr and other basic infrastructure functionality.
These packages are used for internal operation and storage containers for settings. 00texlive packages are never be split into separate arch-packages, and containers are never generated for these packages.
The full list of currently used packages of this type is:
This package contains configuration options for the TeX Live archive. If container_split_{doc,src}_files occurs in the depend lines the {doc,src} files are split into separate containers (.tar.xz) during container build time. Note that this has NO effect on the appearance within the texlive.tlpdb. It is only on container level. The container_format/XXXXX specifies the format, currently allowed is only "xz", which generates .tar.xz files. zip can be supported. release/NNNN specifies the release number as used in the installer.
This package serves a double purpose:
1. at installation time the present values are taken as default for the installer
2. on an installed system it serves as configuration file. Since we have to remember these settings for additional package installation, removal, etc.
This package collects some files which are not caught by any of the other TL packages. Its primary purpose is to make the file coverage check happy. The files here are not copied by the installer and containers are not built; they exist only in the TeX Live Master tree.
This package defines the files to go into the installer archives (install-tl-unx.tar.gz, install-tl.zip) built by the tl-make-installer script. Most of what's here is also included in the texlive.infra package -- ordinarily duplicates are not allowed, but in this case, 00texlive.installer is never used *except* to build the installer archives, so it's ok.
categoryidentifies the category into which this package belongs. This determines the default patterns applied. Possible categories are defined in TeXLive::TLConfig, currently Collection, Scheme, TLCore, Package, ConTeXt. Most packages fall into the Package category, and this is the default if not specified.
catalogueidentifies the name under which this package can be found in the TeX Catalogue. If not specified, the package name is used.
shortdescgives a one line description of the package. Later lines overwrite earlier, so there's no use in giving it more than once. If not specified, the default is taken from the TeX Catalogue, which suffices for almost all normal packages. Thus, in TeX Live, primarily used for collections and schemes.
longdescgives a long description of the package. Later lines are appended to earlier ones. As with shortdesc, if not specified, the default is taken from the TeX Catalogue, which suffices for almost all normal packages.
dependspecifies the list of dependencies, which are just other package names. All the depend lines contribute to the dependencies of the package. For example, latex.tlpsrc contains (among others):
depend latexconfig
depend latex-fonts
depend pdftexto ensure these packages are installed if the latex package is. The directive hard is an alias for depend, since that's we specified for the DEPENDS.txt files package authors can provide; see https://www.tug.org/texlive/pkgcontrib.html#deps.
executespecifies an install-time action to be executed. The following actions are supported:
execute addMap font.mapenables the font map file font.map in the updmap.cfg file.
execute addMixedMap font.mapenables the font map file font.map for Mixed mode in the updmap.cfg file.
execute AddHyphen name=texlang file=file [var...]activates the hyphenation pattern with name texlang and load the file file for that language. The additional variables var are: lefthyphenmin, righthyphenmin (both integers), synonyms (a comma-separated list of alias names for that hyphenation), databases (a comma-separated list of databases the entry should go in; currently recognized are: dat (language.dat), def (language.def) and lua (language.dat.lua)), file_patterns and file_exceptions (files with the patterns (resp. exceptions) in plain txt), and luaspecial (string).
The variable databases defaults to dat,def, or dat,def,lua if one of the keys file_patterns, file_exceptions or luaspecial is used.
execute AddFormat name=fmt engine=eng [var...]activates the format with name fmt based on the engine eng. The additional variables var are: mode which can only be equal to disable in which case the format will only be mentioned but disabled (prefixed with #!; patterns which gives the patterns file, if not present - is used; options which gives the additional options for the fmtutil.cnf file.
postactionspecifies a post-install or post-removal action to be executed. The difference to the execute statement is that postaction is concerned with system integration, i.e., adjusting things outside the installation directory, while execute touches only things within the installation.
The following actions are supported:
On W32 creates a shortcut either in the main TeX Live menu or on the desktop. See the documentation of TeXLive::TLWinGoo for details.
postaction filetype name=name cmd=cmdOn W32 associates the file type name with the command cmd.
postaction fileassoc extension=.ext filetype=nameOn W32 declares files with the extenstion .ext of file type name.
postaction script file=file [filew32=filew32]This postaction executes the given file with two arguments, the first being either the string install or remove, the second being the root of the installation.
If the filew32 argument is given this script is run on Windows systems instead of the one given via file.
tlpsetvar var valsets variable var to val. Order matters: the variable can be expanded with ${var}, only after it is defined. Characters allowed in the var name are -_a-zA-Z0-9.
For example, the Xindy program is not supported on all platforms, so we define a variable:
tlpsetvar no_xindy_platforms i386-solaris,x86_64-linuxmusl,x86_64-solaristhat can then by used in each binpattern needed:
binpattern f/!${no_xindy_platforms} bin/${ARCH}/texindy
binpattern f/!${no_xindy_platforms} bin/${ARCH}/tex2xindy
...(The binpattern details are below; here, just notice the variable definition and expansion.)
Ordinarily, variables can be used only within the .tlpsrc file where they are defined. There is one exception: global tlpsrc variables can be defined in the 00texlive.autopatterns.tlpsrc file (mentioned below); their names must start with global_, and can only be used in depend, execute, and ...pattern directives, another tlpsetvar. For example, our autopatterns.tlpsrc defines:
tlpsetvar global_latex_deps babel,cm,hyphen-base,latex-fontsAnd then any other .tlpsrc files can use it as ${global_latex_deps}; in this case, latex-bin.tlpsrc, latex-bin-dev.tlpsrc, platex.tlpsrc, and others (in execute AddFormat directives).
(src|run|doc|bin)pattern patternadds pattern (next section) to the respective list of patterns.
Patterns specify which files are to be included into a tlpobj at expansion time. Patterns are of the form
[PREFIX]TYPE[/[!]ARCHSPEC] PATwhere
PREFIX = + | +! | !
TYPE = t | f | d | r
ARCHSPEC = <list of architectures separated by comma>Simple patterns without PREFIX and ARCHSPEC specifications are explained first.
f pathincludes all files which match path where only the last component of path can contain the usual glob characters * and ? (but no others!). The special string ignore for path means to ignore this pattern (used to eliminate the auto-pattern matching).
d pathincludes all the files in and below the directory specified as path.
r regexpincludes all files matching the regexp /^regexp$/.
a name1 [<name2> ...]includes auto-generated patterns for each nameN as if the package itself would be named nameN. That is useful if a package (such as venturisadf) contains top-level directories named after different fonts.
t word1 ... wordN wordLincludes all the files in and below all directories of the form
word1/word2/.../wordN/.../any/dirs/.../wordL/i.e., all the first words but the last form the prefix of the path, then there can be an arbitrary number of subdirectories, followed by wordL as the final directory. This is primarily used in 00texlive.autopatterns.tlpsrc in a custom way, but here is the one real life example from a standard package, omega.tlpsrc:
runpattern t texmf-dist fonts omegamatches texmf-dist/fonts/**/omega, where ** matches any number of intervening subdirectories, e.g.:
texmf-dist/fonts/ofm/public/omega
texmf-dist/fonts/tfm/public/omega
texmf-dist/fonts/type1/public/omega+ and !If the PREFIX contains the symbol ! the meaning of the pattern is reversed, i.e., files matching this pattern are removed from the list of included files.
The prefix + means to append to the list of automatically synthesized patterns, instead of replacing them.
The + and ! prefixes can be combined. This is useful to exclude directories from the automatic pattern list. For example, graphics.tlpsrc contains this line:
docpattern +!d texmf-dist/doc/latex/tufte-latex/graphicsso that the subdirectory of the tufte-latex package that happens to be named "graphics" is not mistakenly included in the graphics package.
00texlive.autopatterns)If a given pattern section is empty or all the provided patterns have the prefix + (e.g., +f ...), then patterns such as the following, listed by type, are automatically added at expansion time. The list here contains examples, rather than being definitive; the added patterns are actually taken from 00texlive.autopatterns.tlpsrc. (That file also defines any global tlpsrc variables, as described above under "tlpsetvar").
runpatternFor category Package:
t texmf-dist I<topdir> %NAME%where %NAME% means the current package name, and topdir is one of: bibtex context dvips fonts makeindex metafont metapost mft omega scripts tex.
For category ConTeXt:
d texmf-dist/tex/context/third/%context-:NAME%
d texmf-dist/metapost/context/third/%context-:NAME%
f texmf-dist/tex/context/interface/third/*%context-:NAME%.xml(where %context-:NAME% is replaced by the package name with an initial context- is removed. E.g., if the package is called context-foobar the replacement in the above rules will be foobar.)
For other categories no patterns are automatically added to the list of runpatterns.
docpatternfor category TLCore:
t texmf-dist doc %NAME%
f texmf-dist/doc/man/man1/%NAME%.*for category Package:
t texmf-dist doc %NAME%
f texmf-dist/doc/man/man1/%NAME%.*for category ConTeXt:
d texmf-dist/doc/context/third/%context-:NAME%srcpatternfor category Package:
t texmf-dist source %NAME%for category ConTeXt:
d texmf-dist/source/context/third/%context-:NAME%(see above for the $NAME% construct)
binpatternNo binpatterns are ever automatically added.
The binpatterns have to deal with all the different architectures. To ease the writing of patterns, we have the following features:
Within a binpattern, the string ${ARCH} is automatically expanded to all available architectures.
bat/exe/dll/texlua for Windowsbinpatterns that match Windows, e.g., f bin/windows/foobar or f bin/${ARCH}/foobar, also match the files foobar.bat, foobar.cmd, foobar.dll, foobar.exe, and foobar.texlua.
In addition, foobar.exe.manifest and foobar.dll.manifest are matched.
The above two properties allows to capture the binaries for all architectures in one binpattern
binpattern f bin/${ARCH}/dvipsand would get bin/windows/dvips.exe into the runfiles for arch=windows.
This bat/exe/etc. expansion only works for patterns of the f type.
Sometimes files should be included into the list of binfiles of a package only for some architectures, or for all but some architectures. This can be done by specifying the list of architectures for which this pattern should be matched after the pattern specifier using a /:
binpattern f/windows tlpkg/bin/perl.exewill include the file tlpkg/bin/perl.exe only in the binfiles for the architecture windows. Another example:
binpattern f/arch1,arch2,arch3 path/$ARCH/foo/barThis will only try to match this pattern for arch1, arch2, and arch3.
Normally, a binpattern is matched against all possible architectures. If you want to exclude some architectures, instead of listing all the ones you want to include as above, you can prefix the list of architectures with a ! and these architectures will not be tested. Example:
binpattern f/!arch1,arch2 path/$ARCH/foo/barwill be matched against all architectures except arch1 and arch2.
For any of the above keys a function
$tlpsrc->keyis available, which returns the current value when called without an argument, and sets the respective value when called with an argument.
Arguments and return values for name, category, shortdesc, longdesc, catalogue are single scalars. Arguments and return values for depends, executes, and the various patterns are lists.
In addition, the _srcfile member refers to the filename for this TLPSRC object, if set (normally by from_file).
The following functions can be called for a TLPSRC object:
newThe constructor new returns a new TLPSRC object. The arguments to the new constructor can be in the usual hash representation for the different keys above:
$tlpsrc = TLPSRC->new(name => "foobar",
shortdesc => "The foobar package");from_file("filename")Reads a tlpsrc file from disk. filename can either be a full path (if it's readable, it's used), or just a package identifier such as plain. In the latter case, the directory searched is the tlpsrc sibling of the TeXLive package directory where TLPSRC.pm was found.
$tlpsrc=new TeXLive::TLPSRC;
$tlpsrc->from_file("/path/to/the/tlpsrc/somepkg.tlpsrc");
$tlpsrc->from_file("somepkg");writeoutwrites the textual representation of a TLPSRC object to stdout, or the filehandle if given:
$tlpsrc->writeout;
$tlpsrc->writeout(\*FILEHANDLE);make_tlpobj($tltree)creates a TLPOBJ object from a TLPSRC object and a TLTREE object. This function does the necessary work to expand the manual data and enrich it with the content from $tltree to a TLPOBJ object.
The other modules in Master/tlpkg/TeXLive/ (TeXLive::TLConfig and the rest), and the scripts in Master/tlpkg/bin/ (especially tl-update-tlpdb), the documentation in Master/tlpkg/doc/, etc.
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.