1 files changed, 88 insertions, 0 deletions
diff --git a/config/README.md b/config/README.md
new file mode 100644
index 0000000..8459b77
--- /dev/null
+++ b/config/README.md
@@ -0,0 +1,88 @@
+# 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!