mirror of
https://github.com/HDFGroup/hdf5.git
synced 2024-11-27 02:10:55 +08:00
89 lines
4.5 KiB
Markdown
89 lines
4.5 KiB
Markdown
# 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!
|