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 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. Some comments on languages:
- We recommend using either Perl or
TeXLua, because those interpreters are
provided 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/05/17 15:59:59 $;
TeX Live;
TUG home page;
join TUG/renew membership;
webmaster;
facebook;
x;
mastodon.