NAME

TeXLive::TLPDB -- TeX Live Package Database (texlive.tlpdb) module

SYNOPSIS

use TeXLive::TLPDB;

TeXLive::TLPDB->new ();
TeXLive::TLPDB->new (root => "/path/to/texlive/installation/root");

$tlpdb->root("/path/to/root/of/texlive/installation");
$tlpdb->copy;
$tlpdb->from_file($filename);
$tlpdb->writeout;
$tlpdb->writeout(FILEHANDLE);
$tlpdb->as_json;
$tlpdb->save;
$tlpdb->media;
$tlpdb->available_architectures();
$tlpdb->add_tlpobj($tlpobj);
$tlpdb->needed_by($pkg);
$tlpdb->remove_tlpobj($pkg);
$tlpdb->get_package("packagename");
$tlpdb->list_packages ( [$tag] );
$tlpdb->expand_dependencies(["-only-arch",] $totlpdb, @list);
$tlpdb->expand_dependencies(["-no-collections",] $totlpdb, @list);
$tlpdb->find_file("filename");
$tlpdb->collections;
$tlpdb->schemes;
$tlpdb->updmap_cfg_lines;
$tlpdb->fmtutil_cnf_lines;
$tlpdb->language_dat_lines;
$tlpdb->language_def_lines;
$tlpdb->language_lua_lines;
$tlpdb->package_revision("packagename");
$tlpdb->location;
$tlpdb->platform;
$tlpdb->is_verified;
$tlpdb->verification_status;
$tlpdb->config_src_container;
$tlpdb->config_doc_container;
$tlpdb->config_container_format;
$tlpdb->config_release;
$tlpdb->config_minrelease;
$tlpdb->config_revision;
$tlpdb->config_frozen;
$tlpdb->options;
$tlpdb->option($key, [$value]);
$tlpdb->reset_options();
$tlpdb->add_default_options();
$tlpdb->settings;
$tlpdb->setting($key, [$value]);
$tlpdb->setting([-clear], $key, [$value]);
$tlpdb->sizes_of_packages($opt_src, $opt_doc, $ref_arch_list [, @packs ]);
$tlpdb->sizes_of_packages_with_deps($opt_src, $opt_doc, $ref_arch_list [, @packs ]);
$tlpdb->install_package($pkg, $dest_tlpdb);
$tlpdb->remove_package($pkg, %options);
$tlpdb->install_package_files($file [, $file ]);

TeXLive::TLPDB->listdir([$dir]);
$tlpdb->generate_listfiles([$destdir]);

$tlpdb->make_virtual;
$tlpdb->is_virtual;
$tlpdb->virtual_add_tlpdb($tlpdb, $tag);
$tlpdb->virtual_remove_tlpdb($tag);
$tlpdb->virtual_get_tags();
$tlpdb->virtual_get_tlpdb($tag);
$tlpdb->virtual_get_package($pkg, $tag);
$tlpdb->candidates($pkg);
$tlpdb->virtual_candidate($pkg);
$tlpdb->virtual_pinning( [ $pin_file_TLConfFile ] );

DESCRIPTION

TeXLive::TLPDB->new
TeXLive::TLPDB->new( [root => "$path"] )

TeXLive::TLPDB->new creates a new TLPDB object. If the argument root is given it will be initialized from the respective location starting at $path. If $path begins with http://, https://, ftp://, scp://, ssh:// or user@host:, the respective file is downloaded. The $path can also start with file:/ in which case it is treated as a file on the filesystem in the usual way.

Returns an object of type TeXLive::TLPDB, or undef if the root was given but no package could be read from that location.

$tlpdb->add_tlpobj($tlpobj)

The add_tlpobj adds an object of the type TLPOBJ to the TLPDB.

$tlpdb->needed_by($pkg)

Returns an array of package names depending on $pkg.

$tlpdb->remove_tlpobj($pkg)

Remove the package named $pkg from the tlpdb. Gives a warning if the package is not present

$tlpdb->from_file($filename, @args)

The from_file function initializes the TLPDB if the root was not given at generation time. See TLPDB::new for more information.

It returns the actual number of packages (TLPOBJs) read from $filename, and zero if there are problems (and gives warnings).

$tlpdb->writeout
$tlpdb->writeout(FILEHANDLE)

The writeout function writes the database to STDOUT, or the file handle given as argument.

$tlpdb->as_json

The as_json function returns a JSON UTF8 encoded representation of the database, that is a JSON array of packages. If the database is virtual, a JSON array where each element is a hash with two keys, tag giving the tag of the sub-database, and tlpdb giving the JSON of the database.

$tlpdb->save

The save functions saves the TLPDB to the file which has been set as location. If the location is undefined, die.

$tlpdb->media

Returns the media code the respective installation resides on.

$tlpdb->available_architectures

The available_architectures functions returns the list of available architectures as set in the options section (i.e., using setting("available_architectures"))

$tlpdb->get_package("pkgname")

The get_package function returns a reference to the TLPOBJ object corresponding to the pkgname, or undef.

$tlpdb->media_of_package($pkg [, $tag])

returns the media type of the package. In the virtual case a tag can be given and the media of that repository is used, otherwise the media of the virtual candidate is given.

$tlpdb->list_packages

The list_packages function returns the list of all included packages.

By default, for virtual tlpdbs only packages that are installable are listed. That means, packages that are only in subsidiary repositories but are not specifically pinned to it cannot be installed and are thus not listed. Adding "-all" argument lists also these packages.

Finally, if there is another argument, the tlpdb must be virtual, and the argument must specify a tag/name of a sub-tlpdb. In this case all packages (without exceptions) from this repository are returned.

$tlpdb->expand_dependencies(["control",] $tlpdb, ($pkgs))

If the first argument is the string "-only-arch", expands only dependencies of the form .ARCH.

If the first argument is "-no-collections", then dependencies between "same-level" packages (scheme onto scheme, collection onto collection, package onto package) are ignored.

-only-arch and -no-collections cannot be specified together; has to be one or the other.

The next (or first) argument is the target TLPDB, then a list of packages.

In the virtual case, if a package name is tagged with @repository-tag then all the dependencies will still be expanded between all included databases. Only in case of .ARCH dependencies the repository-tag is sticky.

We return a list of package names, the closure of the package list with respect to the depends operator. (Sorry, that was for mathematicians.)

$tlpdb->find_file("filename")

The find_file returns a list of packages:filename containing a file named filename.

$tlpdb->collections

The collections function returns a list of all collection names.

$tlpdb->schemes

The schemes function returns a list of all scheme names.

$tlpdb->package_revision("packagename")

The package_revision function returns the revision number of the package named in the first argument.

$tlpdb->generate_packagelist

The generate_packagelist prints TeX Live package names in the object database, together with their revisions, to the file handle given in the first (optional) argument, or STDOUT by default. It also outputs all available architectures as packages with revision number -1.

$tlpdb->generate_listfiles
$tlpdb->generate_listfiles($destdir)

The generate_listfiles generates the list files for the old installers. This function will probably go away.

$tlpdb->root([ "/path/to/installation" ])

The function root allows to read and set the root of the installation.

$tlpdb->location

Return the location of the actual texlive.tlpdb file used. This is a read-only function; you cannot change the root of the TLPDB using this function.

See 00texlive.installation.tlpsrc for a description of the special value __MASTER.

$tlpdb->platform

returns the platform of this installation.

$tlpdb->is_verified

Returns 0/1 depending on whether the tlpdb was verified by checking the cryptographic signature.

$tlpdb->verification_status

Returns the id of the verification status. To obtain a textual representation us %TLCrypto::VerificationStatusDescription.

$tlpdb->listdir

The function listdir allows to read and set the packages variable specifying where generated list files are created.

$tlpdb->config_src_container

Returns 1 if the texlive config option for src files splitting on container level is set. See Options below.

$tlpdb->config_doc_container

Returns 1 if the texlive config option for doc files splitting on container level is set. See Options below.

$tlpdb->config_container_format

Returns the currently set default container format. See Options below.

$tlpdb->config_release

Returns the currently set release. See Options below.

$tlpdb->config_minrelease

Returns the currently allowed minimal release. See Options below.

$tlpdb->config_frozen

Returns true if the location is frozen.

$tlpdb->config_revision

Returns the currently set revision. See Options below.

$tlpdb->sizes_of_packages_with_deps ( $opt_src, $opt_doc, $ref_arch_list, [ @packs ] )
$tlpdb->sizes_of_packages ( $opt_src, $opt_doc, $ref_arch_list, [ @packs ] )

These functions return a reference to a hash with package names as keys and the sizes in bytes as values. The sizes are computed for the list of package names given as the fourth argument, or all packages if not specified. The difference between the two functions is that the _with_deps gives the size of packages including the size of all depending sizes.

If anything has been computed one additional key is synthesized, __TOTAL__, which contains the total size of all packages under consideration. In the case of _with_deps this total computation does not count packages multiple times, even if they appear multiple times as dependencies.

If the third argument is a reference to a list of architectures, then only the sizes for the binary packages for these architectures are used, otherwise all sizes for all architectures are summed.

$tlpdb->install_package_files($f [, $f])

Install a package from a package file, i.e. a .tar.xz. Returns the number of packages actually installed successfully.

$tlpdb->install_package($pkg, $dest_tlpdb [, $tag])

Installs the package $pkg into $dest_tlpdb. If $tag is present and the tlpdb is virtual, tries to install $pkg from the repository tagged with $tag.

<< $tlpdb->remove_package($pkg, %options) >>

Removes a single package with all the files and the entry in the db; warns if the package does not exist.

$tlpdb->option($key [, $val]) =item $tlpdb->setting($key [, $val])

Need to be documented

$tlpdb->options

Returns a reference to a hash with option names.

$tlpdb->format_definitions

This function returns a list of references to hashes where each hash represents a parsed AddFormat line.

$tlpdb->fmtutil_cnf_lines

The function fmtutil_cnf_lines returns the list of a fmtutil.cnf file containing only those formats present in the installation.

Every format listed in the tlpdb but listed in the arguments will not be included in the list of lines returned.

$tlpdb->updmap_cfg_lines ( [@disabled_maps] )

The function updmap_cfg_lines returns the list of a updmap.cfg file containing only those maps present in the installation.

A map file mentioned in the tlpdb but listed in the arguments will not be included in the list of lines returned.

$tlpdb->language_dat_lines ( [@disabled_hyphen_names] )

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

Every hyphenation pattern listed in the tlpdb but listed in the arguments will not be included in the list of lines returned.

$tlpdb->language_def_lines ( [@disabled_hyphen_names] )

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

Every hyphenation pattern listed in the tlpdb but listed in the arguments will not be included in the list of lines returned.

$tlpdb->language_lua_lines ( [@disabled_hyphen_names] )

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

Every hyphenation pattern listed in the tlpdb but listed in the arguments will not be included in the list of lines returned.

VIRTUAL DATABASES

The purpose of virtual databases is to collect several data sources and present them in one way. The normal functions will always return the best candidate for the set of functions.

More docs to be written someday, maybe.

$tlpdb->candidates ( $pkg )

Returns the list of candidates for the given package in the format

tag/revision

If the returned list is empty, then the database was not virtual and no install candidate was found.

If the returned list contains undef as first element, the database is virtual, and no install candidate was found.

The remaining elements in the list are all repositories that provide that package.

Note that there might not be an install candidate, but still the package is provided by a sub-repository. This can happen if a package is present only in the sub-repository and there is no explicit pin for that package in the pinning file.

$tlpdb->candidate ( )

Returns either a list of four undef, if no install candidate is found, or the following information on the install candidate as list: the tag name of the repository, the revision number of the package in the candidate repository, the tlpobj of the package in the candidate repository, and the candidate repository's TLPDB itself.

$tlpdb->virtual_pinning ( [ $pinfile_TLConfFile] )

Sets or returns the TLConfFile object for the pinning data.

OPTIONS

Options regarding the full TeX Live installation to be described are saved in a package 00texlive.config as values of depend lines. This special package 00texlive.config does not contain any files, only depend lines which set one or more of the following options:

container_split_src_files/[01]
container_split_doc_files/[01]

These options specify that at container generation time the source and documentation files for a package have been put into a separate container named package.source.extension and package.doc.extension.

container_format/format

This option specifies a format for containers. The currently supported formats are xz and zip. But note that zip is untested.

release/relspec

This option specifies the current release. The first four characters must be a year.

minrelease/relspec

This option specifies the minimum release for which this repository is valid.

To set these options the respective lines should be added to 00texlive.config.tlpsrc.

SEE ALSO

The modules TeXLive::TLPSRC, TeXLive::TLPOBJ, TeXLive::TLTREE, TeXLive::TLUtils, etc., and the documentation in the repository: Master/tlpkg/doc/.

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.