summaryrefslogtreecommitdiff
path: root/Build/source/doc
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2018-02-10 23:28:32 +0000
committerKarl Berry <karl@freefriends.org>2018-02-10 23:28:32 +0000
commit6e760293ed5b28dda13d89aed6668de70aeab94b (patch)
tree1346e126ffdbc0dd1ac7298f6abddb8f48df659b /Build/source/doc
parent1815321fcb78cc64b4e2cff1ef05c50f6a9de4c3 (diff)
more doc on adding a program
git-svn-id: svn://tug.org/texlive/trunk@46589 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Build/source/doc')
-rw-r--r--Build/source/doc/ChangeLog6
-rw-r--r--Build/source/doc/Makefile.in1
-rw-r--r--Build/source/doc/build-tools.txt2
-rw-r--r--Build/source/doc/tlbuild.texi74
4 files changed, 70 insertions, 13 deletions
diff --git a/Build/source/doc/ChangeLog b/Build/source/doc/ChangeLog
index a7f9c30d901..a3b45a264a5 100644
--- a/Build/source/doc/ChangeLog
+++ b/Build/source/doc/ChangeLog
@@ -1,3 +1,9 @@
+2018-02-10 Karl Berry <karl@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@tug.org>
* tlbuild.texi: we now default to gcc for ICU too.
diff --git a/Build/source/doc/Makefile.in b/Build/source/doc/Makefile.in
index 9063339a847..5ebf66f3804 100644
--- a/Build/source/doc/Makefile.in
+++ b/Build/source/doc/Makefile.in
@@ -122,6 +122,7 @@ am__aclocal_m4_deps = $(top_srcdir)/m4/kpse-cairo-flags.m4 \
$(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 \
diff --git a/Build/source/doc/build-tools.txt b/Build/source/doc/build-tools.txt
index ef31ecee77d..b87f7b85f23 100644
--- a/Build/source/doc/build-tools.txt
+++ b/Build/source/doc/build-tools.txt
@@ -4,4 +4,4 @@ bison (GNU Bison) 3.0.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
diff --git a/Build/source/doc/tlbuild.texi b/Build/source/doc/tlbuild.texi
index bb4a9fc6bda..3a60e29a47d 100644
--- a/Build/source/doc/tlbuild.texi
+++ b/Build/source/doc/tlbuild.texi
@@ -1,21 +1,21 @@
\input texinfo
@setfilename tlbuild.info
-@set version 2017
-@set month-year April 2017
+@set version 2018
+@set month-year February 2018
@set mytitle Building @TeX{} Live (@value{version})
@settitle @value{mytitle}
@macro TL
-@TeX{} Live
+@TeX{}@tie{}Live
@end macro
@copying
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 @@ installed independently, but are included on the TL DVD together with
their support files.
-@node Extending @TeX{} Live
-@section Extending @TeX{} Live
+@node Extending @TL{}
+@section Extending @TL{}
@cindex extending @TL{}
@cindex adding to @TL{}
@@ -1416,10 +1416,9 @@ its name @file{@var{prog}} to the M4 list @code{kpse_utils_pkgs} in
@pindex withenable.ac@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
-@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
+@file{utils/@var{prog}} must provide a fragment
+@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,15 +1431,66 @@ built without the configure option @code{--enable-@var{prog}},
@code{native} if cross compilation is not possible, @code{x} if the
program requires X11 libraries);
-@item and a comment added to the help text for the @code{configure}
+@item a comment added to the help text for the @code{configure}
option @code{--enable-@var{prog}} or @code{--disable-@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
+@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
+@code{...-src}.
+
+So, these are the files that we must generally create:
+
+@table @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{}.
+
+@item TLpatches/TL-Changes
+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.
+
+@item ChangeLog
+Record all TL-specific changes, now and in the future.
+
+@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
+@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