diff options
Diffstat (limited to 'Build/source/README.hacking')
| -rw-r--r-- | Build/source/README.hacking | 187 |
1 files changed, 0 insertions, 187 deletions
diff --git a/Build/source/README.hacking b/Build/source/README.hacking deleted file mode 100644 index ff893aa6490..00000000000 --- a/Build/source/README.hacking +++ /dev/null @@ -1,187 +0,0 @@ -Copyright (C) 2009-2014 Peter Breitenlohner <tex-live@tug.org> -You may freely use, modify and/or distribute this file. - - Modifying the TeX Live (TL) build system - ======================================== - -1. Currently used versions of tools -=================================== - -In general, we use the latest released versions of GNU build tools. We -install these directly from the original GNU releases (e.g., by building -them with configure --prefix=/usr/local/gnu and having -/usr/local/gnu/bin first in our PATH). - -autoconf (GNU Autoconf) 2.69 - -automake (GNU automake) 1.14.1 - -ltmain.sh (GNU libtool) 2.4.2 - -bison (GNU Bison) 3.0.2 - -flex 2.5.39 - -m4 (GNU M4) 1.4.17 - -makeinfo (GNU texinfo) 5.2 - -2. Updating the TL build system -=============================== - -When anything in the TL build system (configure.ac and Makefile.am files -with their fragments or M4 macros in m4/) has been modified you have to -rebuild the coresponding configure, Makefile.in, config.h or c-auto.h, or -other generated files. You should use the versions mentioned above. This -is most easily done automatically using maintainer-mode. - -The files in the SVN repository are all up to date, but some of them may be -rebuilt in maintainer-mode due to their timestamps (this is somewhat tedious -to avoid due to SVN's handling of timestamps). - -Alternatively, you can run the 'reautoconf' script from the top-level. - -The 'config.guess', 'config.sub', etc. files for most packages are kept -centrally in build-aux/, sourced from GNU Gnulib -(http://www.gnu.org/software/gnulib), which in turn pulls them from -their ultimate upstream source repository. There are, however, -independent copies in, e.g., libs/freetype2/freetype-*/builds/unix/, and -similar places. The 'reautoconf' script does not take care of those, -but a TL cron job does keep them in sync (nightly). - -3. Extending the TL build system -================================ - -3.1 Adding a new program directory ----------------------------------- - -To add a new program directory utils/Util/ (not using Kpathsea) or -texk/Prog/ (possibly using Kpathsea and Ptexenc) you must add the directory -Util to the M4 list kpse_utils_pkgs or Prog to the M4 list kpse_texk_pkgs -defined in m4/kpse-pkgs.m4. In addition you must create a configure.ac -fragment utils/Util/ac/withenable.ac or texk/Prog/ac/withenable.ac defining -any required libraries from the TL tree and whether this new program is to -be built by default (in the absence of the corresponding -'--enable-Util/Prog' or '--disable-Util/Prog' configure options). - -If a program in texk/Prog/ or utils/Util/ requires specific configure -options to be seen at the top-level, they should be defined in an -additional configure.ac fragment texk/Prog/ac/Prog.ac or -utils/Util/ac/Util.ac (included from texk/Prog/ac/withenable.ac and -texk/Prog/configure.ac or utils/Util/ac/withenable.ac and -utils/Util/configure.ac) as, e.g., for texk/web2c/, texk/xdvik/, and -utils/xindy/. - -As an example, the file texk/dvipdfmx/ac/withenable.ac contains - KPSE_ENABLE_PROG([dvipdfmx], [kpathsea libpng]) -where KPSE_ENABLE_PROG, defined in m4/kpse-setup.m4, has one required -argument -- the name of the subdirectory -- and three optional arguments: a -list of required TL libraries (zlib is implied by libpng and need not be -mentioned), a list of options ('disable' if this program is not to be built -by default, 'native' if cross compilation is not possible, 'x' if this -program requires X11), and a comment added to the help text for the disable -or enable configure option for this program. - -3.2 Adding a new generic library directory ------------------------------------------- - -To add a new generic library directory libs/Lib/ you must add the directory -Lib to the M4 list kpse_libs_pkgs defined in m4/kpse-pkgs.m4. In addition -you must create a configure.ac fragment libs/Lib/ac/withenable.ac defining -any required libraries from the TL tree and whether an installed (system) -version of this library can be used. If that is the case, another -configure.ac fragment libs/Lib/ac/Lib.ac should specify a small program as -test for a system version to be acceptable. Finally you must create a file -m4/kpse-Lib-flags.m4 defining the M4 macro KPSE_LIB_FLAGS (where 'LIB' is a -sanitized uppercase version of 'Lib') setting up the Make variables -LIB_INCLUDES, LIB_LIBS, and LIB_DEPEND with the required values for -CPPFLAGS, LDADD, and dependencies, as well as LIB_RULE with a (multiline) -Make rule to rebuild that library when necessary. - -If a system version of the library can be used, another M4 macro -KPSE_LIB_SYSTEM_FLAGS in m4/kpse-Lib-flags.m4 must define values for -LIB_INCLUDES and LIB_LIBS, and you must add the line -'AC_REQUIRE([KPSE_LIB_SYSTEM_FLAGS])' to the definition of the M4 macro -KPSE_ALL_SYSTEM_FLAGS in m4/kpse-pkgs.m4. In many cases LIB_INCLUDES and -LIB_LIBS are constructed from values for the configure options -'--with-Lib-includes' and/or '--with-Lib-libdir'; alternatively they may -result from running pkg-config, freetype-config, or similar. - -As an example, the file libs/libpng/ac/withenable.ac contains - KPSE_WITH_LIB([libpng], [zlib]) -where KPSE_WITH_LIB, defined in m4/kpse-setup.m4, has one required argument --- the name of the subdirectory -- and two optional arguments: a list of -required TL libraries, and a list of options ('tree' if only the library -from the TL tree can be used). The file libs/libpng/ac/libpng.ac contains - KPSE_TRY_LIB([libpng], - [#include <png.h>], - [png_structp png; png_voidp io; png_rw_ptr fn; - png_set_read_fn(png, io, fn);]) -where KPSE_TRY_LIB, defined in m4/kpse-setup.m4, has three required -arguments -- the name of the subdirectory and two AC_LANG_PROGRAM arguments. -This causes the configure script to compile and link the C program - #include <png.h> - int main () - { png_structp png; png_voidp io; png_rw_ptr fn; - png_set_read_fn(png, io, fn); - return 0; } -as sanity check for using an installed PNG library. The analogous macro -KPSE_TRY_LIBXX uses the C++ compiler. - -3.3 Adding a new TeX specific library directory ------------------------------------------------ - -To add a new TeX specific library directory texk/Lib/ proceed as for a -generic library (described above) with these exceptions: - -(*) Add the directory Lib to the M4 list kpse_texlibs_pkgs (also defined in -m4/kpse-pkgs.m4) instead of kpse_libs_pkgs. - -(*) The configure.ac fragment libs/Lib/ac/withenable.ac must use -KPSE_WITH_TEXLIB instead of KPSE_WITH_LIB. - -(*) The new library must not depend on any generic libraries. - -4. Using libraries from the TL tree -=================================== - -The TL build system provides Autoconf macros for all libraries in the TL -tree. A program requiring additional libraries must use standard Autoconf -and Automake features (such as AC_ARG_WITH to specify their installation -directories, AC_CHECK_LIB and AC_CHECK_FUNCS for library functions, -AC_CHECK_HEADERS for header files). - -4.1 configure.ac ----------------- - -In order to use, e.g., libpng (either an installed version or from the TL -tree) configure.ac must use KPSE_ZLIB_FLAGS and KPSE_LIBPNG_FLAGS. As a -consequence the Make variables LIBPNG_DEPEND, LIBPNG_INCLUDES, LIBPNG_LIBS, -and LIBPNG_RULE (and analogous ZLIB_* variables) will be defined. - -A program may wish to examine features of the PNG library. To do so -configure.ac must use - KPSE_ADD_FLAGS([zlib]) -followed by test for zlib features (if any) and - KPSE_ADD_FLAGS([libpng]) -followed by tests for libpng features. These macros temporarily add -appropriate values to CPPFLAGS and LIBS. The tests must be terminated by - KPSE_RESTORE_FLAGS -in order to restore CPPFLAGS and LIBS to their former values. - -4.2 Makefile.am ---------------- - -In order to use, e.g., libpng (and zlib) the Make variables mentioned above -must be used in Makefile.am as follows - -$(LIBPNG_INCLUDES) $(ZLIB_INCLUDES) must be added to AM_CPPFLAGS (or target -specific target_CPPFLAGS). - -$(LIBPNG_LIBS) $(ZLIB_LIBS) must be added to LDADD or target_LDADD. - -$(LIBPNG_DEPEND) $(ZLIB_DEPEND) should be added to target_DEPENDENCIES such -that rebuilding zlib and/or libpng causes the target to be rebuilt. - -Two lines containing @ZLIB_RULE@ and @LIBPNG_RULE@ create the rules required -to (re-)build zlib and libpng when necessary. |