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.
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.
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.
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.
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.
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.
More on Type 1 fonts: if your fonts support the TS1 (TeX Symbol) encoding, please declare the appropriate (sub)encoding. LaTeX news #39 (p.4) goes into this in detail; in short, you can run latex checkencodingsubset.tex and it will prompt for a font name.
If your package includes source files that have to be compiled into binary executables, such as C (recommended) or C++ (extra pain), it is necessary to use the GNU configuration standards, as 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. It is good to include any and all tests, infrastructure scripts and Makefiles, and anything else someone else working on the package would find useful.
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:
--help
and --version
. (No need to
support other variants or long options in general.) See the GNU standards.
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')
TeX has a method (\write18) for executing subprocesses. By default, only a few explicitly-specified programs are allowed to be run this way, since it is an obvious security risk. The list of about a dozen allowed programs (kpsewhich, makeindex, repstopdf, etc.), is defined in texmf.cnf.
If you wish to provide a new program to be added to the allowed list, it must follow several rules:
In general, a user should be able to safely run a TeX document that invokes your program and be sure that nothing outside the current (known output) directory is writable.
If you have a program to propose that meets these criteria, please email the source to tlsecurity@tug.org. Please describe what it does, how it works, and why the criteria are met. Runnable test cases, in whatever form, to show that the possible exploits are protected against, are extremely helpful and appreciated.
One aspect can vary: the Kpathsea library and kpsewhich program use a string-based approach (e.g., if a path contains the string "/../" it is disallowed). It's also ok, perhaps even preferable, to resolve symlinks and .. references and check the final result; the minted package does it this way.
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.