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
http://tug.org/svn/texlive?view=revision&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:
--------------
trunk/Build/source/doc/ChangeLog
trunk/Build/source/doc/Makefile.in
trunk/Build/source/doc/build-tools.txt
trunk/Build/source/doc/tlbuild.texi
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
@copying
@@ -15,7 +15,7 @@
This file documents the @TL{} build system and more.
@noindent
-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}
@findex KPSE_ENABLE_PROG
-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
arguments:
@@ -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
@file{configure.ac}.
+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