From 7f21b556cf6d5be0790a8873f81437ffa244d8d6 Mon Sep 17 00:00:00 2001 From: Hans Ulrich Niedermann Date: Mon, 19 Feb 2024 20:52:36 +0100 Subject: [PATCH] Complete the versioninfo.md documentation file Complete the description of the versioninfo mechanism, which commit 37997ba78a4f5d8e0153dfe238239067588d4d66 adds in an incomplete state. --- src/build-helpers/versioninfo.md | 53 ++++++++++++++++++++++++++++++-- 1 file changed, 50 insertions(+), 3 deletions(-) diff --git a/src/build-helpers/versioninfo.md b/src/build-helpers/versioninfo.md index 965e06b40..2e3ae9f71 100644 --- a/src/build-helpers/versioninfo.md +++ b/src/build-helpers/versioninfo.md @@ -116,19 +116,66 @@ The `versioninfo.sh` script then prints these items, one per line. The `build-helpers/versioninfo.m4` m4 include file -------------------------------------------------- -TODO: Write text. +This defines the two parts of the m4 code: + + * The m4 code which calls `versioninfo.sh`, parses its output, and + defines some m4 macros before `AC_INIT`: + + * The `versioninfo_items` macro describes the sequence of + versioninfo items printed in lines by the `versioninfo.sh` + script + + * The `versioninfo_init` macro runs the `versioninfo.sh` script + and parses its output, `m4_define`ing a `versioninfo_` + macro for each `ITEM` from `versioninfo_items` + + * The `versioninfo_stampfile` macro contains the name of the + stamp file which caches the versioninfo items for use in + tarballs. + + * The `versioninfo_init` macro is evaluated once, so that + `versioninfo.sh` is only run once as well. + + The m4 macros with the parsed results can then be evaluated using + `m4_defn(...)` both in the `AC_INIT(...)` invocation for the + `PACKAGE_VERSION`, and also later for defining + `AVRDUDE_FULL_VERSION` and git commit information. + + * The m4 code `AC_DEFUN`s the `VERSIONINFO_SETUP` macro, which in + turn defines `AC_SUBST` substitution and make variables for each + of the versioninfo items, and also defines a few + stubstitution-only (not make) variables for use in make rules in + `versioninfo.mk` and `GNUmakefile.in`, which write, read, parse, + and compare the versioninfo items as defined in + `versioninfo_items`. The `build-helpers/versioninfo.mk` Makefile include file -------------------------------------------------------- -TODO: Write text. +To be `include`d into the top-level `Makefile.am`, this does two things: + + * Hooks into the `dist` and `distcheck` targets to check the + recorded version information is the same one `versioninfo.sh` + would detect right now, and prevents builds with out of date + versioninfo items. + + * Writes the stamp file with the versioninfo data when creating a + dist tarball. The `configure.ac` file ----------------------- -TODO: Write text. +Before `AC_INIT`, uses m4 logic to evaluate what the `PACKAGE_VERSION` +should be. + +Expands the `VERSIONINFO_SETUP` macro both to run its content and to +force `aclocal` to pull in `versioninfo.m4` into `aclocal.m4` so that +the m4 code from `versioninfo.m4` is evaluated before `AC_INIT`. + +Evaluates the `AVRDUDE_FULL_VERSION` message and adds it as both a C +preprocessor macro and a autoconf substitution and make variable. The `GNUmakefile.in` and `GNUmakefile` files