Contributing packages - TeX Live

[an error occurred while processing this directive] Contributing packages - TeX Live - TeX Users Group

TeX Live package contributions

This page gives some information about contributing packages to TeX Live (TL), and how to make integrating your package easier for the TL maintainers.

If you have questions, or if you find that a package is installed incorrectly in TL, please email the public tex-live mailing list.

On this page: requirements - normal TeX packages - complex TeX packages - executables - dependencies.

Basic requirements

a) First, the package must be free (as in freedom) software, available under, for example, the LaTeX Project Public License or GNU General Public License. Please state the license explicitly in your package's source code, README, and/or other documentation. Those licenses (and others) contain instructions for how to apply them to your code.
b) We very strongly recommend using an existing license; devising your own will delay any inclusion in TeX Live. We also strongly recommend using a clause “or any later version” with any license. The licensing conditions for TeX Live go into more detail about what is and isn't acceptable.
The package must be useful in itself, or useful in conjunction with free software. In other words, we won't install a package that exists only to support something nonfree, even when it is free itself; for example, LPPL'd macro support for a proprietary font. (Such would be rightly rejected by free distros in any case.)
If a package is generally distributable but contains a few separable files with the nonfree software support, we may remove just those files from the installation in TL and distribute the remainder; in this case, a file README.TEXLIVE will be created listing the files removed. If you, as the package maintainer, notice this and prefer to have the package removed from TL completely, email us and we will comply.
The source for any generated documentation files (e.g., pdf) must also be available for the generated documentation to be included in TeX Live. We won't refuse to install the package itself, but we must refrain from installing generated documentation when there is no source. Free documentation is as important as free software.
If you haven't uploaded your package to CTAN, please do that. As a general rule, TL will not install any new packages that do not come from CTAN. It is by far the easiest place for us to update from, and it is beneficial for the TeX world as a whole for CTAN to be as comprehensive as possible.
The @ character cannot be used in any filenames, source or generated. Our tools are not prepared to handle this, and since it's trivial to avoid we'd rather not spend time on it. Other special ASCII characters (quotes, whitespace, etc.), and anything outside 7-bit ASCII, should likewise be avoided.
a) The package should not create (the likelihood of) any new runtime filename conflicts; in other words, the names of all files which are read by TeX and friends should be reasonably expected to remain unique in perpetuity. Using the package name as a prefix is usually the best approach. This applies to files within the tex//, scripts//, and other subdirectories, but not source// or doc//.
b) New executables should have names that are globally distinctive and descriptive, not just within the TeX world. Most executables will end up being installed in system-wide directories as part of operating system distributions.

We don't include packages in the experimental or obsolete trees on CTAN unless the author explicitly requests it. All other packages that meet the above criteria are fair game by default, and we try to install any new ones (that don't require compilation; see below) within a few days of their appearance on CTAN. If you find qualifying packages missing in TL, feel free to email tex-live@tug.org. Ones that have been looked at and excluded are (tersely) listed in the ctan2tds script.

TeX-world packages - normal

Standard (La)TeX packages with a .ins file, .dtx, README, etc., don't need any special treatment; they can just have all the files at the top level. The TL scripts more or less automatically translate the CTAN package into the TDS arrangement used in TL.

It is best for the documentation for a package foo to be in a file named foo-doc.pdf, foo-manual.pdf, or some such (see the suffix_list in texdoc.cnf); foo.pdf is also ok, but can often be confused with typeset code listings. In any event, please do not name it literally “manual.pdf”; that generic name does not help users. Regardless of the name, as mentioned above, please include all sources to the documentation.

Also, if you use .dtx files or otherwise provide a typeset code listing, please distribute that as foo-code.pdf or similar, not just foo.pdf. That causes lots of confusion to both humans and software.

Also if you use .dtx files, on the technical side, please provide a way to generate the derived .sty (or any other) runtime files without regenerating the documentation, typically by using different engines for the different purposes (e.g., etex vs. latex). To import into TL, we don't want to regenerate documentation, but do need to generate derived files.

In terminal output, please reserve the prefix *** for actual errors that indicate something is wrong, not just informational messages like “move the .sty to the runtime”.

Special case: if you are making a LaTeX package containing .tex files which should be installed in the runtime tex/ subtree (that is, are not documentation), please state this in your README, and ideally in the package announcement as well.

TeX-world packages - complex

Some packages are complex. If your package has many files in many different places, and especially if it does not follow normal naming conventions, distributing it as subdirectories of a texmf tree, with your files in the TDS places, can be useful. This can be done by uploading to CTAN a .tds.zip file along with the main tree (see the “In parallel…” item on that CTAN page).

However, if your package is not very large, or you are not extremely well-acquainted with the TDS, please don't worry about this. A .tds.zip file is never a requirement, nor even a recommendation; it causes more trouble than it solves when the TDS organization is not correct, which can happen all too easily.

Nevertheless, if you do make a .tds.zip: as a rule of thumb for LaTeX packages, only .dtx and .ins files go in source/; general auxiliary files can go in doc/. For packages that include Type1 fonts, please include .tfm files and .map files.

Packages with executables

If your package includes source files that actually have to be compiled into binary executables, such as C (recommended) or C++ (extra pain), it is necessary to use the GNU configuration standards, implemented with Automake. The entire TeX Live source tree is based on Automake, and its option names, variables, and other conventions and features must be supported. Much more info about this is in the TeX Live build manual.

Packages containing executables written in a scripting language are easier to deal with. Some comments on languages:

We recommend using either Perl or (especially) TeXLua, for the simple reason that we provide those interpreters in TeX Live itself, including on Windows. (A couple of the Perl packages in TL: bundledoc, texfot; and TeXLua packages: epspdf, l3build.)
For other languages (Python, Ruby, shell scripts), it is up to the end-users to install everything necessary. Unix shell scripts will generally not be usable on Windows. (A couple of the Python packages in TL: lilyglyphs, dviasm; a Ruby package: match_parens.)
Java requires a wrapper shell script, and it is desirable to accommodate old runtimes, since they are prevalent. (Some Java packages in TL: arara, texosquery.)

Regardless of the scripting language, a couple notes on running scripts:

TL does not generally provide modules or packages for any language. It is up to the user to install any needed core or third-party packages (e.g., via the OS packaging mechanism, or CPAN for Perl, etc.). Therefore, as a script author, it is desirable for you to minimize (eliminate) such dependencies.
TL does not provide any interpreters, either, with the exception of Lua, in the form of the texlua program maintained as part of LuaTeX. (A few core Lua modules are built into that binary.) A second exception: we provide a Perl binary for Windows, along with enough modules to run the TL infrastructure programs such as install-tl and tlmgr, but it is not a full Perl and does not provide modules needed to run third-party scripts.

Also independent of the scripting language, to be installable in TL in the first place, a couple of requirements must be met:

The upload to CTAN must contain the runnable script itself, or something from which the script can be easily derived (e.g., a .dtx file). For example, it must not require running setup.py for Python packages, either by the TL maintainers or (completely out of the question) by TL users.
To emphasize what's been stated above, the script must be named reasonably uniquely. Scripts, unlike TeX files, will typically end up getting installed in OS-wide binary directories, and thus must be unique across the entire operating system world, not just the TeX world. Three character names are not going to work; four character names are borderline but may be acceptable if they are sufficiently obscure; descriptive names are preferred to abbreviations.
As a consequence, and again to repeat what's above, any auxiliary files should contain the package name as a prefix in the filename; e.g., myscript-subs.pl. Ambiguous names are the bane of our TeX world and must be avoided.

In addition, again independent of the scripting language, certain conventions should be followed for the new script to be usable. We do not rigorously check these requirements and won't refuse to install a script that does not follow them, but failing to do will cause trouble for users:

The first line should use #!/usr/bin/env name, rather than hardwiring any path to the interpreter.
In general, whether the executable is compiled or a script, it must be self-locating at runtime. That is, it must be able to find all its support files elsewhere in the install tree, relative to its own location. Otherwise, it cannot work in TeX Live, because TL can be installed anywhere on a user's system. Usually, the user-level script will be installed in texmf-dist/scripts/PKGNAME/, with any auxiliary files needed at runtime also in that directory, with a symlink in the bin/PLATFORM/* dirs for the users to execute. (Our wrapper for Windows supports most languages other than shell scripts.)
If your program needs to search for files, please use Kpathsea to find them, one way or another. If your package is written in a scripting language and needs to search for files, using the kpsewhich executable may be convenient. Looking directly for files is one option; if (especially) the files are not uniquely named, you can also get the location of the texmf-dist tree with kpsewhich -var-value TEXMFMAIN and find what you need in your own code.
Please make any executables do something reasonable with the options --help and --version. (No need to support other variants or long options in general.) See the GNU standards.
Please write a Unix man page, however brief. The afm2tfm.1 man page may serve as a starting point, as it is short but includes all the usual sections. Alternatively, GNU help2man can convert your --help message (if sufficiently informative and formatted) to a man page. For Perl scripts, pod2man may be convenient.

To summarize much of the above info in a different way: the zip file uploaded to CTAN for a package foobar should unpack into a directory foobar/ containing something like the following:

foobar/LICENSE.txt # or COPYING or other common names
foobar/README.txt  # or .md; state the license and where to report bugs
foobar/VERSION_0_1 # optional, but nice to see version number from file listing
foobar/foobar.1    # man page
foobar/foobar.pdf  # documentation, from the man page or otherwise
foobar/foobar.tex  # if doc separate from the man page, include source
foobar/foobar      # the executable itself,
                   #   starting with '#!/usr/bin/env INTERPRETER')

Dependencies on other packages

In general, TL does not try to track package dependencies, since there is no reliable way to detect dependencies automatically. (That would mean installing packages during the TeX run, as MiKTeX does, and there are complications with doing this in TL.)

However, if you as the package author wish to tell us about dependencies, we will install them. We do not request this, and do not particularly recommend it, but since people have asked us, we've defined the following mechanism. Packages doing this must be uploaded to CTAN.

Provide a file named DEPENDS.txt (with that capitalization and extension) at the top level of your CTAN upload (sibling to your README file). A four-line example:

dep1
hard dep2
hard dep3 dep4
soft xedep # XeTeX only

The intent is for the file to be automatically processed. So its syntax must adhere to the following:

Whitespace is ASCII space (0x20) and tab (0x09).
Lines are terminated with ASCII linefeed (0x0a) possibly preceded by ASCII return (0x0d).
Blank lines are ignored.
Leading and trailing whitespace on a line are ignored.
Multiple whitespace characters are the same as one.
Comments begin with # and continue to the end of line.
Each non-blank line therefore consists of one or more whitespace-separated words.
If the first word on a line is hard, soft, or package, all subsequent words are the arguments.
If a line has only one word, hard is assumed (first line of example above).
The arguments must be valid package names, as defined by CTAN. For example, that means they consist of all lowercase ASCII letters a-z, ASCII numbers 0-9, dash, underscore (very occasionally), and nothing else. If this is different from the TL package name, use the CTAN name anyway; we will convert, one way or another. If the package does not exist in TL at all, the depends file will be ignored.
The hard directive means the following package(s) are always required. These will be converted into dependencies for tlmgr.
The soft directive means the following package(s) may be needed, but are not required. As in the example above, perhaps they are only needed when running XeTeX (or some other specific engine). These must be listed as soft because not every installation wants or needs (for example) XeTeX. Similarly with packages that are only conditionally required, e.g., if some option to your package is specified. As far as tlmgr goes, soft dependencies are currently ignored, but they may serve as useful documentation. Your choice.
The package directive must be followed by exactly one more word, and that word is the package name for which any following dependencies are applied. This is only useful in the extremely unusual case of two or more packages being distributed from a single CTAN directory; it's best to leave it out in the normal case.
A DEPENDS.txt file is not required to have any directives. An empty or comment-only file is valid, though meaningless :).

If experience shows that changes are necessary, we may extend the syntax in the future, but don't expect to ever need to make an incompatible change.

If you have questions or suggestions about any of this, please email tex-live@tug.org.

$Date: 2024/02/06 16:37:16 $; TeX Live; [an error occurred while processing this directive]