19.8.3 Using the package version during the build ¶

The unoptimized way ¶

Once propagated through config.status, the value of $(VERSION) can appear anywhere in built files. For built files that are distributed (that is, not erased by “make distclean”), it is important to add a dependency in the Makefile.am, so that the file gets rebuilt:

built-file: $(top_builddir)/config.status

For files that are erased by “make distclean”, this is not really necessary, because

• In the main workflow, where the developer changes the version only between “make distclean” and “./configure”, the built files have been remade.
• Most .o files depend on config.h, which is rebuilt when configure runs.

Thus, only in packages that don’t use Gnulib would a dependency such as

hello-hello.$(OBJEXT): $(top_builddir)/config.status

be needed.

The optimized way ¶

Notice that config.status usually changes much more often than the version number. Therefore, for built files which depend only on $(VERSION) and not on other variables, the following optimized technique can be used.

The technique consists of keeping a file named $(top_srcdir)/.version, which is a timestamp file. Its modification time represents the last time the value of $(VERSION) was changed. Its contents is an undocumented implementation detail.

With such a file, the dependency in Makefile.am becomes:

built-file: $(top_srcdir)/.version

In order to prepare for using $(top_srcdir)/.version, three modifications in the package are needed:

• In the top-level configure.ac file, add an invocation of the macro gl_CONFIG_VERSION_STAMP, near the end (before AC_OUTPUT). This macro is defined in file m4/version-stamp.m4, part of the Gnulib module version-stamp.
• In the top-level Makefile.am, add:

  EXTRA_DIST += $(top_srcdir)/.version
  BUILT_SOURCES += $(top_srcdir)/.version
  

  so that the file .version will be present in tarballs and so that “make maintainer-clean” will erase it.

• Add .version to the package’s top-level .gitignore file.