texlive[46589] Build/source/doc: more doc on adding a program

commits+karl at tug.org commits+karl at tug.org
Sun Feb 11 00:28:32 CET 2018

Revision: 46589
Author:   karl
Date:     2018-02-11 00:28:32 +0100 (Sun, 11 Feb 2018)
Log Message:
more doc on adding a program

Modified Paths:

Modified: trunk/Build/source/doc/ChangeLog
--- trunk/Build/source/doc/ChangeLog	2018-02-10 22:52:29 UTC (rev 46588)
+++ trunk/Build/source/doc/ChangeLog	2018-02-10 23:28:32 UTC (rev 46589)
@@ -1,3 +1,9 @@
+2018-02-10  Karl Berry  <karl at freefriends.org>
+	* tlbuild.texi (Adding a new program module): more specifics
+	on our usual layout and new files.
+	(version): (February) 2018.
 2017-03-22  Karl Berry  <karl at tug.org>
 	* tlbuild.texi: we now default to gcc for ICU too.

Modified: trunk/Build/source/doc/Makefile.in
--- trunk/Build/source/doc/Makefile.in	2018-02-10 22:52:29 UTC (rev 46588)
+++ trunk/Build/source/doc/Makefile.in	2018-02-10 23:28:32 UTC (rev 46589)
@@ -122,6 +122,7 @@
 	$(top_srcdir)/m4/lt~obsolete.m4 $(top_srcdir)/tardate.ac \
 	$(top_srcdir)/version.ac \
 	$(top_srcdir)/utils/autosp/ac/withenable.ac \
+	$(top_srcdir)/utils/axodraw2/ac/withenable.ac \
 	$(top_srcdir)/utils/devnag/ac/withenable.ac \
 	$(top_srcdir)/utils/lacheck/ac/withenable.ac \
 	$(top_srcdir)/utils/m-tx/ac/withenable.ac \

Modified: trunk/Build/source/doc/build-tools.txt
--- trunk/Build/source/doc/build-tools.txt	2018-02-10 22:52:29 UTC (rev 46588)
+++ trunk/Build/source/doc/build-tools.txt	2018-02-10 23:28:32 UTC (rev 46589)
@@ -4,4 +4,4 @@
 flex 2.6.0
 ltmain.sh (GNU libtool) 2.4.6
 m4 (GNU M4) 1.4.18
-makeinfo (GNU texinfo) 6.4
+makeinfo (GNU texinfo) 6.5

Modified: trunk/Build/source/doc/tlbuild.texi
--- trunk/Build/source/doc/tlbuild.texi	2018-02-10 22:52:29 UTC (rev 46588)
+++ trunk/Build/source/doc/tlbuild.texi	2018-02-10 23:28:32 UTC (rev 46589)
@@ -1,14 +1,14 @@
 \input texinfo
 @setfilename tlbuild.info
- at set version 2017
- at set month-year April 2017
+ at set version 2018
+ at set month-year February 2018
 @set mytitle Building @TeX{} Live (@value{version})
 @settitle @value{mytitle}
 @macro TL
- at TeX{} Live
+ at TeX{}@tie{}Live
 @end macro
@@ -15,7 +15,7 @@
 This file documents the @TL{} build system and more.
-Copyright @copyright{} 2016--2017 Karl Berry.@*
+Copyright @copyright{} 2016--2018 Karl Berry.@*
 Copyright @copyright{} 2013--2015 Karl Berry & Peter Breitenlohner.
 Permission is granted to make and distribute verbatim copies of this
@@ -1372,8 +1372,8 @@
 their support files.
- at node Extending @TeX{} Live
- at section Extending @TeX{} Live
+ at node Extending @TL{}
+ at section Extending @TL{}
 @cindex extending @TL{}
 @cindex adding to @TL{}
@@ -1416,10 +1416,9 @@
 @pindex withenable.ac at r{, for new modules}
-In either case, apart from the program sources and build system
-(@file{configure.ac} and @file{Makefile.am}), the subdirectory
- at file{texk/@var{prog}} or @file{utils/@var{prog}} must provide a
-fragment @file{ac/withenable.ac} that contains the M4 macro
+In either case, the subdirectory @file{texk/@var{prog}} or
+ at file{utils/@var{prog}} must provide a fragment
+ at file{ac/withenable.ac} that contains the M4 macro
 @code{KPSE_ENABLE_PROG} defined in @file{m4/kpse-setup.m4} with
 @code{@var{prog}} as the mandatory first argument and three optional
@@ -1432,16 +1431,67 @@
 @code{native} if cross compilation is not possible, @code{x} if the
 program requires X11 libraries);
- at item and a comment added to the help text for the @code{configure}
+ at item a comment added to the help text for the @code{configure}
 option @code{--enable- at var{prog}} or @code{--disable- at var{prog}}.
 @end enumerate
 If the module requires specific configure options to be seen at the
-top-level, they should be defined in an additional fragment
+top level, they should be defined in an additional fragment
 @file{ac/@var{prog}.ac} included from @file{ac/withenable.ac} and
+Usually, the new program is maintained somewhere outside of @TL{}.  In
+that case, we put the upstream sources into a subdirectory
+ at file{@var{prog}-src} (e.g., @file{utils/newprog/newprog-src}).  We do
+not run @code{configure} in this original @code{...-src} directory,
+only in our own directory, but we do compile using the source files in
+ at code{...-src}.
+So, these are the files that we must generally create:
+ at table @file
+ at item ac/withenable.ac
+The @code{KPSE_ENABLE_PROG} call just explained.
+ at item configure.ac
+ at 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{}.
+ at item TLpatches/TL-Changes
+Actions taken after getting the original source tree; typically
+removal of derived or unused common files.
+ at 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.
+ at item ChangeLog
+Record all TL-specific changes, now and in the future.
+ at end table
+Then, run GNU @code{autoreconf} in the new directory (@pxref{Build
+system tools}).  After that works, @code{svn add} the necessary files,
+notably @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}.)
+Then, run the TL tool @code{reautoconf} in the top-level TL
+ at 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.
 @node Adding a new generic library module
 @subsection Adding a new generic library module

More information about the tex-live-commits mailing list