Алексей Махоткин

домашняя страница

configure. In and Version Control

Karl Fogel writes in “Using Version Control System” chapter of his book “Producing Open Source Software”:

Don’t keep generated files under version control. They are not truly editable data, since they are produced programmatically from other files. For example, some build systems create configure based on the template configure.in. To make a change to the configure, one would edit configure.in and then regenerate; thus, only the template configure.in is an “editable file.” Always version only the templates. If you version the result files as well, people will inevitably forget to regenerate when they commit a change to a template, and the resulting inconsistencies will cause no end of confusion.

I believe that this advice is only partially correct. Almost always there is one important use case for the repository: someone may want to check out current sources and build them on some unknown machine. Practice shows that you have to match all three versions of Automake, Autoconf, and Libtool almost exactly, or you will have random build errors which are very hard to diagnose and fix. So, you have to spare that unknown person from such pains.

So, we always add configure and Makefile.in files to the repository, although technically they are “generated” (from configure.ac and Makefile.am, respectively). To fix the problem with “people will forget to regenerate” you have to just always use --enable-maintainer-mode switch to ./configure, and those files will regenerate automatically the next time you run make. (Hopefully, you commit only if the thing at least compiles.)

Remember that lots of Autotools special files, such as config.cache and stamp-h*, must be added to ignore list of your SCM tool, so that you do not waste your attention.

This not only allows you to build from sources, but also make quick fixes, if they touch only existing source files, and do not require adjusting the build infrastructure. Obviously, most of the fixes would be from that category. If our unknown developer needs to add new file, or to change the dependency, or to add a clause to configure.ac, she will have to install the correct versions of Autotools (which should be exactly documented in your project’s developer documentation).

Of course, the above description is not applicable to “ordinary” generated files. If you have Docbook-based documentation, and you generate a bunch of HTML files from that, you should never add them to the repository. Only master .xml-files should be versioned.

Comments