[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

  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.

    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.

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

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

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

  6. 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:

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

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

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:

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:

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]