summaryrefslogtreecommitdiff
path: root/Build/source/doc/tlbuild.texi
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2020-11-28 22:38:51 +0000
committerKarl Berry <karl@freefriends.org>2020-11-28 22:38:51 +0000
commita15b98ee17678246556913f71f46e8b12c402b4a (patch)
tree447ae1df124a5c042a7a79f01aabb4c6d8f89c5b /Build/source/doc/tlbuild.texi
parent9751df8fcab071b412e307ff1aa3f27504179cbb (diff)
more on adding a new program
git-svn-id: svn://tug.org/texlive/trunk@57026 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Build/source/doc/tlbuild.texi')
-rw-r--r--Build/source/doc/tlbuild.texi75
1 files changed, 55 insertions, 20 deletions
diff --git a/Build/source/doc/tlbuild.texi b/Build/source/doc/tlbuild.texi
index 19f2c438cc0..63dbbca0fc6 100644
--- a/Build/source/doc/tlbuild.texi
+++ b/Build/source/doc/tlbuild.texi
@@ -2,7 +2,7 @@
@setfilename tlbuild.info
@set version 2020
-@set month-year March 2020
+@set month-year November 2020
@set mytitle Building @TeX{} Live (@value{version})
@settitle @value{mytitle}
@@ -1660,6 +1660,7 @@ the top level, they should be defined in an additional fragment
@file{ac/@var{prog}.ac} included from @file{ac/withenable.ac} and
@file{configure.ac}.
+@cindex @var{newprog-src}, original source subdirectory
Usually, the new program is maintained somewhere outside of @TL{}. In
that case, as above, we put the upstream sources into a subdirectory
@file{@var{prog}-src} (e.g., @file{utils/newprog/newprog-src}). We do
@@ -1667,49 +1668,83 @@ not typically run @code{configure} in this original @code{...-src}
directory, but only in our own directory; but we do compile using the
source files in @code{...-src}.
-So, to summarize the files that we must (usually) create:
+So, to summarize the files that must (usually) be created inside a new
+TL source directory (@file{texk/newprog} or @file{utils/newprog}):
-@table @file
+@ftable @file
@item ac/withenable.ac
The @code{KPSE_ENABLE_PROG} call just explained.
@item configure.ac
@itemx Makefile.am
By merging the contents of the original @file{configure.ac} (if
-provided) and a comparable program already in TL. There is no magic
-recipe, it's necessary to think about needs to be done in the original
-vs.@: in @TL{}.
+provided) and a comparable program already in TL. In the above
+example, one line that will be needed in @file{configure.ac} (can be
+added before the @code{AC_CONFIG_FILES} at the end) is:
+
+@example
+AC_SUBST([NEWPROG_TREE], [newprog-src])
+@end example
+
+@noindent and then use @code{@@NEWPROG_TREE@@} in
+@code{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 @TL{}. 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 @file{Build/source} tree for whatever you can think of to
+investigate how something is done. Most of the TL-specific macros are
+defined in @file{Build/source/m4/*}.
@item TLpatches/TL-Changes
-Actions taken after getting the original source tree; typically
+First actions taken after getting the original source tree; typically
removal of derived or unused common files.
@item TLpatches/patch-...
If any changes are needed to the original sources, record the patches
-here so they can be applied next time. And send them upstream so that
-perhaps they won't have to be.
+here so they can be applied next time. Also, send them upstream so
+that we don't have to maintain them forever.
@item ChangeLog
Record all TL-specific changes, now and in the future.
-@end table
+@end ftable
-Then, run GNU @code{autoreconf} in the new directory (@pxref{Build
-system tools}). After that works, @code{svn add} the necessary files,
+@pindex autoreconf@r{, for new program}
+After populating the new TL source directory (@file{.../newprog/}, in
+the above), run GNU @code{autoreconf} there (@pxref{Build system
+tools}). Once that works, if you are the one who's eventually going
+to commit the new package, @code{svn add} the necessary files,
including the generated @file{Makefile.in aclocal.m4 configure}, and
@code{svn:ignore} the Automake cache @file{autom4te.cache}. (This is
so people checking out the TL source tree do not have to run any
autotools, but can simply run @code{configure}.)
+@pindex reautoconf@r{, for new program}
Then, run the TL tool @code{reautoconf} in the top-level TL
-@code{source/} directory, to incorporate the new program into the
-build tree.
-
-Then, run (and rerun) a build until the program compiles and tests
-successfully, probably involving rerunning autoreconf in the source
-directory, @code{make} in the build directory, etc.
-
-After final success, don't forget to commit.
+@code{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 @file{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 @code{autoreconf} as needed in the new source directory
+(@code{Build/source/.../newprog}), then @code{make} in the
+corresponding build directory (@code{Build/work/.../newprog}), then
+@code{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.)
+
+@cindex engine, adding new
+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 @file{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.
@node Adding a new generic library module