NAME

TeXLive::TLPOBJ -- TeX Live Package Object (.tlpobj) module

SYNOPSIS

  use TeXLive::TLPOBJ;

  my $tlpobj = TeXLive::TLPOBJ->new(name => "foobar");

DESCRIPTION

The TeXLive::TLPOBJ module provide access to TeX Live Package Object (.tlpobj) files, which describe a self-contained TL package.

FILE SPECIFICATION

See TeXLive::TLPSRC documentation for the general syntax and specification. The differences are:

The various *pattern keys are invalid.
Instead, there are respective *files keys described below. All the *files keys are followed by a list of files in the given category, one per line, each line indented by one space.
Several new keys beginning with catalogue- specify information automatically taken from the TeX Catalogue.
A new key revision is defined (automatically computed), which specifies the maximum of all the last-changed revisions of files contained in the package, plus possible other changes. By default, Catalogue-only changes do not change the revision.
A new key relocated, either 0 or 1, which indicates that this packages has been relocated, i.e., in the containers the initial texmf-dist directory has been stripped off and replaced with static string RELOC.
srcfiles, runfiles, binfiles, docfiles each of these items contains addition the sum of sizes of the single files (in units of TeXLive::TLConfig::BlockSize blocks, currently 4k).
  srcfiles size=NNNNNN
  runfiles size=NNNNNN
docfiles

The docfiles line itself is similar to the srcfiles and runfiles lines above:

  docfiles size=NNNNNN

But the lines listing the files are allowed to have additional tags, (which in practice come from the TeX Catalogue)

  /------- excerpt from achemso.tlpobj
  |...
  |docfiles size=220
  | texmf-dist/doc/latex/achemso/achemso.pdf details="Package documentation" language="en"
  |...

Currently only the tags details and language are supported. These additional information can be accessed via the docfiledata function returning a hash with the respective files (including path) as key.

binfiles

Since binfiles can be different for different architectures, a single tlpobj file can, and typically does, contain binfiles lines for all available architectures. The architecture is specified on the binfiles using the arch=XXX tag. Thus, binfiles lines look like

  binfiles arch=XXXX size=NNNNN

Here is an excerpt from the representation of the dvipsk package, with | characters inserted to show the indentation:

  |name dvipsk
  |category TLCore
  |revision 52851
  |docfiles size=285
  | texmf-dist/doc/dvips/dvips.html
  | ...
  |runfiles size=93
  | texmf-dist/dvips/base/color.pro
  | ...
  | texmf-dist/scripts/pkfix/pkfix.pl
  |binfiles arch=i386-solaris size=87
  | bin/i386-solaris/afm2tfm
  | bin/i386-solaris/dvips
  |binfiles arch=win32 size=51
  | bin/win32/afm2tfm.exe
  | bin/win32/dvips.exe
  |...

PACKAGE VARIABLES

TeXLive::TLPOBJ has one package-wide variable, containerdir, which is where generated container files are saved (if not otherwise specified).

  TeXLive::TLPOBJ->containerdir("path/to/container/dir");

MEMBER ACCESS FUNCTIONS

For any of the keys a function

  $tlpobj->key

is available, which returns the current value when called without an argument, and sets the respective value when called with an argument. For the TeX Catalogue Data the function

  $tlpobj->cataloguedata

returns and takes as argument a hash.

Arguments and return values for name, category, shortdesc, longdesc, catalogue, revision are single scalars.

Arguments and return values for depends, executes are lists.

Arguments and return values for docfiles, runfiles, srcfiles are lists.

Arguments and return values for binfiles is a hash with the architectures as keys.

Arguments and return values for docfiledata is a hash with the full file names of docfiles as key, and the value is again a hash.

The size values are handled with these functions:

  $tlpobj->docsize
  $tlpobj->runsize
  $tlpobj->srcsize
  $tlpobj->binsize("arch1" => size1, "arch2" => size2, ...)

which set or get the current value of the respective sizes. Note that also the binsize function returns (and takes as argument) a hash with the architectures as keys, similar to the runfiles functions (see above).

Futhermore, if the tlpobj is contained ina tlpdb which describes a media where the files are distributed in packed format (usually as .tar.xz), there are 6 more possible keys:

  $tlpobj->containersize
  $tlpobj->doccontainersize
  $tlpobj->srccontainersize
  $tlpobj->containerchecksum
  $tlpobj->doccontainerchecksum
  $tlpobj->srccontainerchecksum

describing the respective sizes and checksums in bytes and as hex string, resp. The latter two are only present if src/doc file container splitting is activated for that install medium.

OTHER FUNCTIONS

The following functions can be called for a TLPOBJ 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:

  $tlpobj=TLPOBJ->new(name => "foobar", shortdesc => "The foobar package");
from_file("filename")

reads a tlpobj file.

  $tlpobj = new TLPOBJ;
  $tlpobj->from_file("path/to/the/tlpobj/file");
from_fh($filehandle[, $multi])

read the textual representation of a TLPOBJ from an already opened file handle. If $multi is undef (i.e., not given) then multiple tlpobj in the same file are treated as errors. If $multi is defined, then returns after reading one tlpobj.

Returns 1 if it found a tlpobj, otherwise 0.

writeout

writes the textual representation of a TLPOBJ object to stdout, or the filehandle if given:

  $tlpsrc->writeout;
  $tlpsrc->writeout(\*FILEHANDLE);
writeout_simple

debugging function for comparison with tpm/tlps, will go away.

as_json

returns the representation of the TLPOBJ in JSON format.

common_texmf_tree

if all files of the package are from the same texmf tree, this tree is returned, otherwise an undefined value. That is also a check whether a package is relocatable.

make_container($type,$instroot, [ destdir = $destdir, containername => $containername, relative => 0|1, user => 0|1 ])>

creates a container file of the all files in the TLPOBJ in $destdir (if not defined then TLPOBJ->containerdir is used).

The $type variable specifies the type of container to be used. Currently only zip or xz are allowed, and generate zip files and tar.xz files, respectively.

The file name of the created container file is $containername.extension, where extension is either .zip or .tar.xz, depending on the setting of $type. If no $containername is specified the package name is used.

All container files also contain the respective TLPOBJ file in tlpkg/tlpobj/$name.tlpobj.

The argument $instroot specifies the root of the installation from which the files should be taken.

If the argument $relative is passed and true (perlish true) AND the packages does not span multiple texmf trees (i.e., all the first path components of all files are the same) then a relative packages is created, i.e., the first path component is stripped. In this case the tlpobj file is placed into the root of the installation.

This is used to distribute packages which can be installed in any arbitrary texmf tree (of other distributions, too).

If user is present and true, no extra arguments for container generation are passed to tar (to make sure that user tar doesn't break).

Return values are the size, the checksum, and the full name of the container.

recompute_sizes($tltree)

recomputes the sizes based on the information present in $tltree.

recompute_revision($tltree [, $revtlpsrc ])

recomputes the revision based on the information present in $tltree. The optional argument $rectlpsrc can be an additional revision number which is taken into account. $tlpsrc-make_tlpobj> adds the revision number of the tlpsrc file here so that collections (which do not contain files) also have revision number.

update_from_catalogue($texcatalogue)

adds information from a TeXCatalogue object (currently license, version, url, and updates docfiles with details and languages tags if present in the Catalogue).

split_bin_package

splits off the binfiles of TLPOBJ into new independent TLPOBJ with the original name plus ".arch" for every arch for which binfiles are present. The original package is changed in two respects: the binfiles are removed (since they are now in the single name.arch packages), and an additional depend on "name.ARCH" is added. Note that the ARCH is a placeholder.

srcfiles_package
docfiles_package

splits off the srcfiles or docfiles of TLPOBJ into new independent TLPOBJ with the original name plus ".sources". The source/doc files are not removed from the original package, since these functions are only used for the creation of split containers.

is_arch_dependent

returns 1 if there are binfiles, otherwise 0.

total_size

If no argument is given returns the sum of srcsize, docsize, runsize.

If arguments are given, they are assumed to be architecture names, and it returns the above plus the sum of sizes of binsize for those architectures.

is_meta_package

Returns true if the package is a meta package as defined in TLConfig (Currently Collection and Scheme).

clear_{src,run,doc,bin}files

Removes all the src/run/doc/binfiles from the TLPOBJ.

{add,remove}_{src,run,doc}files(@files)

adds or removes files to the respective list of files.

{add,remove}_binfiles($arch, @files)

adds or removes files from the list of binfiles for the given architecture.

{add,remove}_files($type, $files)

adds or removes files for the given type (only for run, src, doc).

contains_file($filename)

returns the list of files matching $filename which are contained in the package. If $filename contains a / the matching is only anchored at the end with $. Otherwise it is prefix with a / and anchored at the end.

all_files

returns a list of all files of all types. However, binary files won't be found until dependencies have been expanded via (most likely) TeXLive::TLPDB::expand_dependencies. For a more or less standalone example, see the find_old_files function in the script Master/tlpkg/libexec/place.

allbinfiles

returns a list of all binary files.

$tlpobj->format_definitions

The function format_definitions returns a list of references to hashes where each hash is a format definition.

$tlpobj->fmtutil_cnf_lines

The function fmtutil_cnf_lines returns the lines for fmtutil.cnf for this package.

$tlpobj->updmap_cfg_lines

The function updmap_cfg_lines returns the list lines for updmap.cfg for the given package.

$tlpobj->language_dat_lines

The function language_dat_lines returns the list of all lines for language.dat that can be generated from the tlpobj

$tlpobj->language_def_lines

The function language_def_lines returns the list of all lines for language.def that can be generated from the tlpobj.

$tlpobj->language_lua_lines

The function language_lua_lines returns the list of all lines for language.dat.lua that can be generated from the tlpobj.

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.