NAME

TeXLive::TLPSRC -- TeX Live Package Source (.tlpsrc) module

SYNOPSIS

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

DESCRIPTION

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.

FILE SPECIFICATION

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\
bar

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

Blank lines are ignored.

The keys are described in the following sections.

name

identifies 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:

name.ARCH

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.

texlivesome.thing

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

00texlivesomething

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:

00texlive.config

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.

00texlive.installation

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.

00texlive.image

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.

00texlive.installer

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.

category

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

catalogue

identifies the name under which this package can be found in the TeX Catalogue. If not specified, the package name is used.

shortdesc

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

longdesc

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

depend

specifies 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 pdftex

to ensure these packages are installed if the latex package is.

execute

specifies an install-time action to be executed. The following actions are supported:

execute addMap font.map

enables the font map file font.map in the updmap.cfg file.

execute addMixedMap font.map

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

postaction

specifies 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:

postaction shortcut name=name type=menu|desktop icon=path cmd=cmd args=args hide=0|1

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=cmd

On W32 associates the file type name with the command cmd.

postaction fileassoc extension=.ext filetype=name

On 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 val

sets 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-solaris

that 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_ (plus super-special wndws), 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-fonts

And 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 pattern

adds pattern (next section) to the respective list of patterns.

PATTERNS

Patterns specify which files are to be included into a tlpobj at expansion time. Patterns are of the form

[PREFIX]TYPE[/[!]ARCHSPEC] PAT

where

PREFIX = + | +! | !
TYPE = t | f | d | r
ARCHSPEC = <list of architectures separated by comma>

Simple patterns without PREFIX and ARCHSPEC specifications are explained first.

f path

includes 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 path

includes all the files in and below the directory specified as path.

r regexp

includes 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 wordL

includes 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 omega

matches 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

Special patterns

Prefix characters: + 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/graphics

so that the subdirectory of the tufte-latex package that happens to be named "graphics" is not mistakenly included in the graphics package.

Auto-generated patterns (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").

runpattern

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

docpattern

for 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%
srcpattern

for category Package:

t texmf-dist source %NAME%

for category ConTeXt:

d texmf-dist/source/context/third/%context-:NAME%

(see above for the $NAME% construct)

binpattern

No binpatterns are ever automatically added.

Special treatment of binpatterns

The binpatterns have to deal with all the different architectures. To ease the writing of patterns, we have the following features:

Architecture expansion

Within a binpattern, the string ${ARCH} is automatically expanded to all available architectures.

bat/exe/dll/texlua for Windows

binpatterns that match Windows, e.g., f bin/win32/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}/dvips

and would get bin/win32/dvips.exe into the runfiles for arch=win32.

This bat/exe/etc. expansion only works for patterns of the f type.

ARCHSPEC specification of a pattern

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/win32 tlpkg/bin/perl.exe

will include the file tlpkg/bin/perl.exe only in the binfiles for the architecture win32. Another example:

binpattern f/arch1,arch2,arch3 path/$ARCH/foo/bar

This 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/bar

will be matched against all architectures except arch1 and arch2.

MEMBER ACCESS FUNCTIONS

For any of the above keys a function

$tlpsrc->key

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

OTHER FUNCTIONS

The following functions can be called for a TLPSRC object:

new

The 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");
writeout

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

SEE ALSO

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.

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.