Brian Gough’s Notes

Here’s a list of pre-release checks I’ve found useful over the years. Most of them should apply to any package, but they’ve been used for a C library (“libfoo” in the examples below, with exported header files foo/*.h and source files src/*.c).

• Make sure all internal functions are static, and all exported functions & variables prefixed with foo_ or FOO_. Here’s a command for checking this:

  nm -A -g -P *.a  | perl -a -n -e 'print if $F[1] !~ /foo_/ && $F[2] ne "U"'

• Make sure config.h is used consistently – it should be present in source files, but not in any exported headers.

  grep config.h foo/*.h    --- shouldn't match anything
  grep -L config.h src/*.c   --- gives files not using config.h

• Make a master header file of all exported headers and try compiling it to test for conflicts between different header files.

  cat foo/*.h > tmp.c
  gcc tmp.c

• Check that the library passes “make check” with various options. Some good ones are:

  -O3
  -mfpmath=sse -msse2
  -funsigned-char (to simulate Power/ARM)
  -std=c89 -ansi -pedantic (now that GCC uses c99 by default instead of c89)

• Test with valgrind. You can run all the tests under valgrind with the TESTS_ENVIRONMENT variable

   $ TESTS_ENVIRONMENT="valgrind --tool=memcheck" make check

  This only works if configure was run with –disable-shared, because otherwise the shared library libtool shell-scripts themselves are run under valgrind.

  Regarding memory leaks, the GNU coding standards say “Memory leak detectors such as valgrind can be useful, but don’t complicate a program merely to avoid their false alarms. For example, if memory is used until just before a process exits, don’t free it simply to silence a leak detector.”

  For libraries I’ve found it’s very helpful (actually, essential) to have a test suite that is leak-free. Then if any test program exits with memory still allocated it indicates a problem. This is how I have caught any memory leaks during development.

• Do make distcheck the local copy of install-sh provided by automake, in addition to /usr/bin/install. Depending on the end user’s environment, either of these could end up being used.

  make distcheck # will use /usr/bin/install
  make distcheck INSTALL=$HOME/foo/install-sh  # absolute location of install-sh

  When you do “make install” yourself, it will probably use /usr/bin/install since that is present on GNU/Linux systems. If so, you would not detect any problem with the install-sh shipped in your package – for example, if it had got corrupted for some reason (e.g. a stray edit or in my case, after doing a repository conversion I somehow ended up with my working directory containing the first ever version of install-sh that was checked in – which dated from 1994 – it didn’t work properly on modern systems, but I never noticed that because I was always using /usr/bin/install).

• Try running the build and make check with a memory limit to be sure that excessive memory is not required to do the compilation.

  ulimit -v 65536  #  some reasonable memory limit
  make
  make check

• Check that the texinfo manual works for postscript/pdf

  make dvi  # or make pdf

  It’s easy to miss a diagram or other texinput file that is needed by texi2dvi but not by makeinfo.