hdf5/config/README.md

The config directory

Intro

HDF5 can be configured using both the GNU Autotools and CMake. We try to keep them in sync, but you can expect minor differences to crop up. Please create a GitHub issue for any differences noted. Note that with the Autotools, we do NOT check generated files into GitHub until release time, so you will need to generate configure, Makefile.in(s), etc. via autogen.sh in the project root if you want to build with that system.

Configuration information for the HDF5 library and tools is (unfortunately) spread across the repository. Basic library configuration will generally be found in configure.ac (Autotools) and the root's CMakeLists.txt (CMake). Each subdirectory of the project also has its own Makefile.am or CMake build and test files.

This directory contains a few important things:

• Autotools OS- and compiler-specific configuration
• CMake support files (in cmake)
• Warning files shared between the two systems (in *-warnings directories)
• CMake toolchain files (in toolchain)
• CMake sanitizer files (in sanitizer)

CMake will be documented elsewhere. This document focuses on the Autotools files and the shared warning files.

Autotools

An Autotools build will first use $host_cpu, $host_os, etc. to try to find a suitable platform file in config to source and start checking compilers. The code that does this is in configure.ac (search for host_os). For example, MacOS will source the apple file and FreeBSD will source the freebsd file. There are a bunch of Linux files, but they all eventually invoke linux-gnulibc1.

If you dig into one of these files, the way that they check for compilers is rather crude. Each OS script will simply source the various C, C++, and Fortran compiler files that are listed inside. Each compiler file checks the designated compiler's version output to see if there's a match, and if so, the flag processing proceeds, and a variable like cc_flags_set will be set at the end.

In case it's not obvious, the C files end in -flags, C++ in -cxxflags, and Fortran in -fflags.

When a compiler matches, the script will attempt to set the CFLAGS, etc. variables based on the platform and compiler's properties. There are typically a large number of flag categories (e.g., DEBUG_OPT_CFLAGS) that are conditionally appended to the canonical variables, like AM_FLAGS, by the remainder of the configure script.

For the major compilers, like Clang and gcc, there will be a section at the end where we append version-specific flags, mainly for warnings. These are imported via a function in the script (load_gnu_arguments() for gcc). See below for more detail.

Warnings files

Keeping the Autotools and CMake build files in sync has always been a bit of a struggle. One way that we help to ensure that the same flags are used in each build system is to import the warnings settings from text files that are maintained separately from the Autotools and CMake build files. We like to configure the compiler to be as crabby as possible so as to catch subtle bugs, so there are a LOT of warning flags for popular compilers like Clang and gcc.

We've located these files in config/*-warnings directories. Each file represents a compiler version and contains the warning flags we set, one to a line. Lines that start with # are considered comment lines. You'll also see developer and no-developer flavors of compiler version files. The former corresponds to "developer flags" that are usually either only semi-useful and/or generate a lot of (usually unfixable) noise. The latter corresponds to things that we want to ensure do NOT appear in non-developer builds of the library. These might involve a different level setting (-Wfoo=x) or something that gets incorporated in a "conglomerate" flag like -Wextra so we need to set -Wno-foo in non-developer builds. Developer warnings can be turned on via a configure option. You will also sometimes see error files. Those are files that include warnings that will be considered errors if you have enabled the "warnings as errors" configure option set. Now that the library is largely warning-free, these are less useful than in the past as you can now just set -Werror directly in many cases (our configure script is smart about not running configure checks with -Werror).

For anyone interested, we are always interested in improving both the OS and compiler files, so pull requests for those are always welcome, especially for platforms we don't have routine access to. If you are a compiler or platform expert/aficionado, please help us out!