tlbuild: Adding a new program module
6.6.1 Adding a new program module
---------------------------------
A TeX-specific program module in a subdirectory 'texk/PROG' may use the
TeX-specific libraries and is included by adding its name 'PROG' to the
M4 list 'kpse_texk_pkgs' defined in 'm4/kpse-pkgs.m4'.
A generic program module in a subdirectory 'utils/PROG' must not use
the TeX-specific libraries and is included by adding its name 'PROG' to
the M4 list 'kpse_utils_pkgs' in 'm4/kpse-pkgs.m4'.
In either case, the subdirectory 'texk/PROG' or 'utils/PROG' must
provide a fragment 'ac/withenable.ac' that contains the M4 macro
'KPSE_ENABLE_PROG' defined in 'm4/kpse-setup.m4' with 'PROG' as the
mandatory first argument and three optional arguments:
1. a list of required libraries from the TL tree;
2. a list of options: 'disable' if this module is not to be built
without the configure option '--enable-PROG', 'native' if cross
compilation is not possible, 'x' if the program requires X11
libraries;
3. a comment added to the help text for the 'configure' option
'--enable-PROG' or '--disable-PROG'.
If the module requires specific 'configure' options to be seen at the
top level, they should be defined in an additional fragment 'ac/PROG.ac'
included from 'ac/withenable.ac' and 'configure.ac'.
Usually, the new program is maintained somewhere outside of TeX Live.
In that case, as above, we put the upstream sources into a subdirectory
'PROG-src' (e.g., 'utils/newprog/newprog-src'). We do not typically run
'configure' in this original '...-src' directory, but only in our own
directory; but we do compile using the source files in '...-src'.
So, to summarize the files that must (usually) be created inside a
new TL source directory ('texk/newprog' or 'utils/newprog'):
'ac/withenable.ac'
The 'KPSE_ENABLE_PROG' call just explained.
'configure.ac'
'Makefile.am'
By merging the contents of the original 'configure.ac' (if
provided) and a comparable program already in TL. In the above
example, one line that will be needed in 'configure.ac' (can be
added before the 'AC_CONFIG_FILES' at the end) is:
AC_SUBST([NEWPROG_TREE], [newprog-src])
and then use '@NEWPROG_TREE@' in 'Makefile.am' where needed.
In general, there is no magic recipe for this part of the job.
It's necessary to think about what needs to be done in the original
vs. in TeX Live. It's useful to look at the setup for the most
comparable programs already in TL that you can find. It's also
useful to grep the entire 'Build/source' tree for whatever you can
think of to investigate how something is done. Most of the
TL-specific macros are defined in 'Build/source/m4/*'.
'TLpatches/TL-Changes'
First actions taken after getting the original source tree;
typically removal of derived or unused common files.
'TLpatches/patch-...'
If any changes are needed to the original sources, record the
patches here so they can be applied next time. Also, send them
upstream so that we don't have to maintain them forever.
'ChangeLog'
Record all TL-specific changes, now and in the future.
After populating the new TL source directory ('.../newprog/', in the
above), run GNU 'autoreconf' there (⇒Build system tools). Once
that works, if you are the one who's eventually going to commit the new
package, 'svn add' the necessary files, including the generated
'Makefile.in aclocal.m4 configure', and 'svn:ignore' the Automake cache
'autom4te.cache'. (This is so people checking out the TL source tree do
not have to run any autotools, but can simply run 'configure'.)
To reiterate: do not fail to commit the generated 'configure' and
other files. The m4 code in 'kpse-pkgs.m4' uses the existence of
'configure' to determine whether to descend into (and configure) a given
subdirectory.
Then, run the TL tool 'reautoconf' in the top-level TL
'Build/source/' directory, to incorporate the new program into the build
tree. It is good to then rebuild the whole tree (e.g., using TL's
'Build/Build' script) to get all the necessary files generated.
It will probably fail. So then you need to keep at it until the
program compiles and tests successfully. The most efficient way is to
rerun 'autoreconf' as needed in the new source directory
('Build/source/.../newprog'), then 'make' in the corresponding build
directory ('Build/work/.../newprog'), then 'make check', etc. In the
end, also make sure that the whole tree builds from scratch.
After final success, don't forget to commit. (Or email the TL
maintainers with the patch.)
Caveat: adding a new TeX engine is not completely different, but it's
not all that similar, either. In that case, the work is done inside a
new subdirectory of 'texk/web2c/'. Many things are common to all the
engines, other things need to be copied and possibly modified for each
one, yet others are unique to each. No general recipe is possible.
Info Catalog
tlbuild: Extending TeX Live
tlbuild: Adding a new generic library module