Updating configure tests, Makefiles, etc.

Introduction

In order to avoid an explicit dependence on the GNU "autotools" (automake, autoconf, libtool, and friends) packages, we have elected to commit build system files, such as configure, Makefile.in, etc. to the repository. This has the nice end result of allowing libmesh to be easily built on operating systems (like MacOS) that don't come with these tools installed by default, but it also requires a bit more effort/understanding of the build system to be able to update said configuration files.

Setup

1. Before editing configure.ac or any of the m4 files, you will first need to ensure that you are using the same version of the autotools that was used to generate the current versions of all the build files. (Unless you are actually upgrading the versions of automake/autconf/libtool etc., in which case you can disregard this section.) The libmesh source distribution comes with source tarballs of the autotools currently in use by the library. To build them, simply run:

   ./bootstrap --build-autotools
   

   from the top level of the git clone. We strongly recommend working with a git clone rather than a tarball distribution if you are editing the build configuration files!

2. Once the correct versions of the autotools are built, you will need to ensure they are in your PATH before any other autotools packages you may have installed on your system. You can use modules to handle this PATH manipulation generically, or simply issue the command:

   export PATH=$LIBMESH_ROOT/contrib/autotools/bin:$PATH
   

   in the current shell and/or add it to the appropriate login (.bash_profile, etc.) configuration file.

3. You can test the libmesh autotools build and installation by running ./bootstrap in the top level of the repository. As long as you have not changed configure.ac or any of the m4 files, you should see no changes to the committed build files as a result of running ./bootstrap. If you see that many of the Makefile.in files have changed, check to make sure that the libmesh-specific autotools are in your PATH, and send an email/open an issue on GitHub if you require additional help.

Usage

After following the setup instructions, you can begin editing and writing your own configure test. Most of the libmesh-specific configure tests are in the m4 directory. The tests themselves are written in a combination of /bin/sh and m4, a general-purpose macro processor.

As with all shell programming, whitespace characters are syntactically important, variables are created in a global namespace, and there is a difference between an unset variable and a variable which is set to the empty string. Coding by copy and paste is usually the best approach for writing new configure tests, but there is also the autoconf-archive which has many pre-existing scripts for configuring standard software packages that should be preferred if possible.

The m4 files in libmesh are loosely organized into individual tests (metis.m4, petsc.m4, glpk.m4, etc.) and composite test files that individual tests (libmesh_core_features.m4, libmesh_optional_packages.m4, etc.) The order in which the tests are called is controlled by these composite files and, at the root, configure.ac itself. When the results of one test depend on another, it is important to ensure that they are called in the correct order. This can be done by inspecting configure.ac and the other composite test files, and by looking at the output of configure, but is often a trial-and-error process.