TeX Live package contributions

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

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

Basic requirements

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

2. a) 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 (e.g., LPPL'd macro support for a proprietary font). That doesn't help the free software world, and would rightly be rejected by free distros in any case.

   b) We very strongly recommend using an existing license; devising your own will certainly 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.

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

4. If you haven't uploaded your package to CTAN, please do that. Virtually all TL packages come from CTAN and that is by far the easiest place for us to update from. It's beneficial for the TeX world as a whole for CTAN to be as comprehensive as possible.

5. The @ character cannot be used in any filenames. Our tools are not prepared to handle this, and since it's trivial to avoid we'd rather not spend time on it.

6. The package should not create (the likelihood of) any new runtime filename conflicts; in other words, all names should be reasonably expected to remain unique; using the package name as a prefix is usually the best approach. In addition to conflicts in the TeX tree, new executables should have names that are reasonably distinctive, and 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 the file foo.pdf. If this is not possible for whatever reason, please use foo-doc.pdf. In any event, please do not name it literally manual.pdf; that generic name does not help users. As mentioned above, please include all sources to the documentation.

If you use .dtx files, 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. For TL, we generally don't want to regenerate documentation, but do need to generate derived files.

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 be sure and 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).

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 this: 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, almost certainly via Automake. The entire TeX Live source tree is based on Automake. In particular, building in a directory other than the source directory (a standard feature of the GNU autotools), must be supported, as this is our standard build method (much more info: TeX Live build manual).

Packages containing executables written in a scripting language are easier to deal with.

• We recommend using either Perl or (especially) TeXLua, for the simple reason that we provide those interpreters in TeX Live itself, including on Windows. Unix shell scripts will not be generally usable on Windows. (A couple of the Perl packages in TL: bundledoc, texfot; and TeXLua packages: epspdf, cachepic.)
• For other languages (Python, Ruby, shell scripts), it is up to the end-users to install everything necessary. (A couple of the Python packages in TL: lilyglyphs, dviasm. A Ruby package: match_parens.)
• Java: ironically, given its design goals, Java turns out to be less portable in practice than nearly anything else, and has additional complications; we don't recommend it. (Some Java packages do exist in TL, though, such as arara and texosquery.)

Whatever the scripting language, the first line must use #!/usr/bin/env name, rather than hardwiring any path to the interpreter.

If your program needs to search for files, please use Kpathsea to find them. If your package is written in a scripting language and needs to search for files, using the kpsewhich executable may be convenient.

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. (This is what Kpathsea searches give you.) Otherwise, it cannot be included in TeX Live, because TL can be installed anywhere on a system.

Please make any executables do something reasonable with the options --help and --version. (No need to support other variants or other long options.) Again, see the GNU standards.

Please write a Unix man page, however brief. The afm2tfm.1 man page may serve as a starting point, being very short but including all the usual sections. Alternatively, GNU help2man can convert your --help message to a man page; and for Perl scripts, pod2man may be convenient.

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