2021-10-31 11:36:24 +00:00
|
|
|
# libbuild2-autoconf
|
|
|
|
|
|
|
|
GNU Autoconf emulation build system module for `build2`.
|
|
|
|
|
|
|
|
Specifically, this module provides an [`in`][module-in]-based rule for
|
2021-11-04 05:38:20 +00:00
|
|
|
processing `config.h.in` files. Besides the Autoconf special line flavor
|
|
|
|
(`#undef`), it also supports the CMake (`#cmakedefine`) and Meson
|
|
|
|
(`#mesondefine`) variants.
|
2021-10-31 11:36:24 +00:00
|
|
|
|
2021-11-04 05:38:20 +00:00
|
|
|
Similar to Autoconf, this module provides built-in support for a number of
|
2021-10-31 11:36:24 +00:00
|
|
|
common `HAVE_*` configuration options. However, the values of these options
|
2021-11-01 11:43:47 +00:00
|
|
|
are not discovered by dynamic probing, such as trying to compile a test
|
2021-11-04 05:38:20 +00:00
|
|
|
program to check if the feature is present. Instead, they are set to static
|
2021-11-05 07:05:38 +00:00
|
|
|
expected values based on the platform/compiler macro checks (see note at the
|
2021-11-04 05:38:20 +00:00
|
|
|
beginning of [Project Configuration][proj-config] for rationale).
|
|
|
|
|
2022-01-20 06:34:14 +00:00
|
|
|
See [`libbuild2/autoconf/checks/`][checks] for the list of available built-in
|
|
|
|
checks. Submit requests for new checks as issues. Submit implementations of
|
|
|
|
new checks (or any other improvements) as PRs or patches.
|
|
|
|
|
2021-11-04 05:38:20 +00:00
|
|
|
|
2021-11-05 07:05:38 +00:00
|
|
|
## Using in your projects
|
2021-11-04 05:38:20 +00:00
|
|
|
|
2021-11-05 07:05:38 +00:00
|
|
|
This module is part of the standard pre-installed `build2` modules and no
|
|
|
|
extra integration steps are required other than the `using` directive in
|
|
|
|
your `buildfile`. For example, for Autoconf `config.h.in`:
|
|
|
|
|
|
|
|
```
|
|
|
|
using autoconf
|
|
|
|
|
|
|
|
h{config}: in{config}
|
|
|
|
```
|
|
|
|
|
|
|
|
Or for CMake `config.h.cmake`:
|
|
|
|
|
|
|
|
```
|
|
|
|
using autoconf
|
|
|
|
|
|
|
|
h{config}: in{config.h.cmake}
|
|
|
|
```
|
|
|
|
|
|
|
|
The default falvor is `autoconf` but if the input file has the `.cmake` or
|
|
|
|
`.meson` extension, then the `cmake` or `meson` flavors are selected
|
|
|
|
automatically. If, however, the standard `config.h.in` file is re-used for
|
|
|
|
CMake/Meson, then the flavor must be specified explicitly with the
|
|
|
|
`autoconf.flavor` variable, for example:
|
|
|
|
|
|
|
|
```
|
|
|
|
using autoconf
|
|
|
|
|
|
|
|
h{config}: in{config}
|
|
|
|
{
|
|
|
|
autoconf.flavor = meson
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
Besides the built-in configuration options, custom substitutions can be
|
2022-09-02 08:45:23 +00:00
|
|
|
specified as `buildfile` variables or key-value pairs in the same way as with
|
|
|
|
the [`in`][module-in] module. For example, as `buildfile` variables:
|
2021-11-05 07:05:38 +00:00
|
|
|
|
2021-11-24 11:30:54 +00:00
|
|
|
```
|
|
|
|
/* config.h.in */
|
|
|
|
|
|
|
|
#define PACKAGE_NAME @PACKAGE_NAME@
|
|
|
|
#define PACKAGE_VERSION @PACKAGE_VERSION@
|
|
|
|
|
|
|
|
#undef HAVE_STRLCPY
|
|
|
|
#undef HAVE_STRLCAT
|
|
|
|
```
|
|
|
|
|
2021-11-05 07:05:38 +00:00
|
|
|
```
|
|
|
|
h{config}: in{config}
|
|
|
|
{
|
|
|
|
PACKAGE_NAME = $project
|
|
|
|
PACKAGE_VERSION = $version
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2022-09-02 08:45:23 +00:00
|
|
|
As key-value pairs in the `autoconf.substitutions` map (which is an alias for
|
|
|
|
the `in.substitutions` variable; see the [`in`][module-in] module for
|
|
|
|
details):
|
|
|
|
|
|
|
|
```
|
|
|
|
/* config.h.in */
|
|
|
|
|
|
|
|
#undef _GNU_SOURCE
|
|
|
|
#undef _POSIX_SOURCE
|
|
|
|
```
|
|
|
|
|
|
|
|
```
|
|
|
|
gnu_source = ($c.stdlib == 'glibc')
|
|
|
|
posix_source = ($c.target.class != 'windows' && !$gnu_source)
|
|
|
|
|
|
|
|
h{config}: in{config}
|
|
|
|
{
|
|
|
|
autoconf.substitutions = _GNU_SOURCE@$gnu_source
|
|
|
|
autoconf.substitutions += _POSIX_SOURCE@$posix_source
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
In particular, the `autoconf.substitutions` mechanism is the only way to have
|
|
|
|
substitutions that cannot be specified as `buildfile` variables because they
|
|
|
|
start with an underscore (and thus are reserved, as in the above example) or
|
|
|
|
refer to one of the predefined variables.
|
|
|
|
|
|
|
|
The custom substitutions can also be used to override the built-in checks, for
|
|
|
|
example:
|
2021-11-05 07:05:38 +00:00
|
|
|
|
|
|
|
```
|
|
|
|
h{config}: in{config}
|
|
|
|
{
|
|
|
|
HAVE_STRLCPY = true
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2022-04-24 10:57:44 +00:00
|
|
|
Note that an implementation of a check may depend on another check. As a
|
|
|
|
result, substitutions should not be conditional at the preprocessor level
|
|
|
|
(unless all the checks are part of the same condition). Nor should the
|
|
|
|
results of checks be adjusted until after the last check. For example:
|
|
|
|
|
|
|
|
```
|
|
|
|
#ifndef _WIN32
|
2022-05-25 12:47:46 +00:00
|
|
|
# cmakedefine HAVE_EXPLICIT_BZERO // Conditional substitution.
|
2022-04-24 10:57:44 +00:00
|
|
|
#endif
|
|
|
|
|
|
|
|
#cmakedefine HAVE_EXPLICIT_MEMSET // Shares implementation with BZERO.
|
|
|
|
|
|
|
|
#cmakedefine BYTE_ORDER
|
|
|
|
|
|
|
|
#if BYTE_ORDER == LITTLE_ENDIAN
|
|
|
|
# undef BYTE_ORDER // Adjusting the result.
|
|
|
|
#endif
|
|
|
|
|
|
|
|
#cmakedefine WORDS_BIGENDIAN // Based on BYTE_ORDER.
|
|
|
|
```
|
|
|
|
|
|
|
|
Below is the correct way to achieve the above semantics:
|
|
|
|
|
|
|
|
```
|
|
|
|
#cmakedefine HAVE_EXPLICIT_BZERO
|
|
|
|
#cmakedefine HAVE_EXPLICIT_MEMSET
|
|
|
|
|
|
|
|
#cmakedefine BYTE_ORDER
|
|
|
|
#cmakedefine WORDS_BIGENDIAN
|
|
|
|
|
|
|
|
#ifdef _WIN32
|
|
|
|
# undef HAVE_EXPLICIT_BZERO
|
|
|
|
#endif
|
|
|
|
|
|
|
|
#if BYTE_ORDER == LITTLE_ENDIAN
|
|
|
|
# undef BYTE_ORDER
|
|
|
|
#endif
|
|
|
|
```
|
|
|
|
|
2022-01-20 06:34:14 +00:00
|
|
|
The built-in checks can be prefixed in order to avoid clashes with similarly
|
2021-11-24 11:30:54 +00:00
|
|
|
named macros in other headers. This is an especially good idea if the
|
|
|
|
resulting header is public. To enable this, we specify the prefix with
|
|
|
|
the `autoconf.prefix` variable and then use the prefixed versions of
|
|
|
|
the options in the `config.h.in` file. For example:
|
|
|
|
|
|
|
|
```
|
|
|
|
/* config.h.in */
|
|
|
|
|
|
|
|
#undef LIBFOO_HAVE_STRLCPY
|
|
|
|
#undef LIBFOO_HAVE_STRLCAT
|
|
|
|
```
|
|
|
|
|
|
|
|
```
|
|
|
|
h{config}: in{config}
|
|
|
|
{
|
|
|
|
autoconf.prefix = LIBFOO_
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
Note that `autoconf.prefix` only affects the lookup of the built-in checks.
|
2022-01-20 06:34:14 +00:00
|
|
|
Custom substitutions and overrides of built-in checks must include the
|
2021-11-24 11:30:54 +00:00
|
|
|
prefix. For example:
|
|
|
|
|
|
|
|
```
|
|
|
|
h{config}: in{config}
|
|
|
|
{
|
|
|
|
autoconf.prefix = LIBFOO_
|
|
|
|
|
|
|
|
LIBFOO_HAVE_STRLCPY = true
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2022-01-20 06:34:14 +00:00
|
|
|
Note also that some built-in check names are *unprefixable*, usually because
|
|
|
|
they are standard macro names (for example, `BYTE_ORDER`) that on some
|
|
|
|
platforms come from system headers (for example, `<sys/endian.h>` on FreeBSD).
|
|
|
|
Such checks have `!` after their names on the first line of their
|
|
|
|
implementation files (for example, `// BYTE_ORDER!`).
|
|
|
|
|
2021-11-24 11:30:54 +00:00
|
|
|
|
2021-11-05 07:05:38 +00:00
|
|
|
## Adding new checks
|
|
|
|
|
|
|
|
To add a check for a new configuration option `<NAME>` simply create the
|
2022-01-20 06:34:14 +00:00
|
|
|
`<NAME>.h` header file (preserving the case) with the corresponding check and
|
|
|
|
place it into [`libbuild2/autoconf/checks/`][checks] (use existing checks for
|
|
|
|
inspiration).
|
2021-11-04 05:38:20 +00:00
|
|
|
|
|
|
|
The first line in this header file must be in the form:
|
|
|
|
|
|
|
|
```
|
2022-01-20 06:34:14 +00:00
|
|
|
// <NAME>[!] [: <BASE>...]
|
2021-11-04 05:38:20 +00:00
|
|
|
```
|
|
|
|
|
2022-01-20 06:34:14 +00:00
|
|
|
If the name is followed by the `!` modifier, then it is *unprefixable* (see
|
2022-01-20 08:58:44 +00:00
|
|
|
the previous section for details). The name can also be followed by `:` and a
|
2022-01-20 06:34:14 +00:00
|
|
|
list of base checks. Such checks are automatically inserted before the rest of
|
2022-04-24 10:09:02 +00:00
|
|
|
the lines in the resulting substitution. One notable check that you may want
|
|
|
|
to use as a base is [`BUILD2_AUTOCONF_LIBC_VERSION`][libc-version] (see
|
|
|
|
comments for details).
|
2022-01-20 06:34:14 +00:00
|
|
|
|
2021-11-04 05:38:20 +00:00
|
|
|
Subsequent lines should be C-style comments or preprocessor directives that
|
|
|
|
`#define` or `#undef` `<NAME>` depending on whether the feature is available
|
2021-11-05 07:05:38 +00:00
|
|
|
(though there can be idiosyncrasies; see `const.h`, for example). Note that
|
2021-11-04 05:38:20 +00:00
|
|
|
there should be no double-quotes or backslashes except for line
|
2022-01-20 06:34:14 +00:00
|
|
|
continuations. For example, to add a check for option `HAVE_BAR`, we could
|
|
|
|
create the `HAVE_BAR.h` header file with the following content:
|
2021-11-04 05:38:20 +00:00
|
|
|
|
|
|
|
```
|
2021-11-24 11:30:54 +00:00
|
|
|
// HAVE_BAR
|
2022-01-14 08:43:52 +00:00
|
|
|
|
|
|
|
#undef HAVE_BAR
|
|
|
|
|
|
|
|
/* No bar on Windows except with MinGW. */
|
2021-11-24 11:30:54 +00:00
|
|
|
#if !defined(_WIN32) || \
|
|
|
|
defined(__MINGW32__)
|
|
|
|
# define HAVE_BAR 1
|
2021-11-04 05:38:20 +00:00
|
|
|
#endif
|
|
|
|
```
|
2021-10-31 11:36:24 +00:00
|
|
|
|
2021-11-24 11:30:54 +00:00
|
|
|
Note also that the module implementation may need to replace `<NAME>` with its
|
2022-01-20 06:34:14 +00:00
|
|
|
prefixed version (unless it is unprefixable) if the `autoconf.prefix`
|
|
|
|
functionality is in use (see above). This is done by textually substituting
|
|
|
|
every occurrence of `<NAME>` that is separated on both left and right hand
|
|
|
|
sides (that is, both characters immediately before and after `<NAME>` are not
|
|
|
|
`[A-Za-z0-9_]`).
|
|
|
|
|
|
|
|
Within a file duplicate checks are automatically suppressed. And if multiple
|
|
|
|
files are involved, then the user is expected to employ the `autoconf.prefix`
|
|
|
|
functionality to avoid clashes across files. However, this does not help
|
|
|
|
unprefixable names and, as a result, such checks should be implemented in
|
|
|
|
ways that deal with duplication (for example, include guards).
|
2021-11-24 11:30:54 +00:00
|
|
|
|
2022-04-24 10:57:44 +00:00
|
|
|
The duplicate suppression is incompatible with conditional (at the
|
|
|
|
preprocessor level) checks, for example, assuming both `HAVE_EXPLICIT_*`
|
|
|
|
checks are based on `BUILD2_AUTOCONF_LIBC_VERSION`:
|
|
|
|
|
|
|
|
```
|
|
|
|
#ifndef _WIN32
|
|
|
|
# undef HAVE_EXPLICIT_BZERO
|
|
|
|
#endif
|
|
|
|
|
|
|
|
#undef HAVE_EXPLICIT_MEMSET
|
|
|
|
```
|
|
|
|
|
|
|
|
In this example, the `autoconf` module will omit the second copy of the
|
|
|
|
`BUILD2_AUTOCONF_LIBC_VERSION` check as part of the `HAVE_EXPLICIT_MEMSET`
|
|
|
|
substitution because it was already inserted as part of the
|
|
|
|
`HAVE_EXPLICIT_BZERO` substitution. But the first copy will not be
|
|
|
|
preprocessed on Windows.
|
|
|
|
|
|
|
|
While there is no bulletproof way to detect such situations (because the
|
2022-04-24 13:38:37 +00:00
|
|
|
unconditional check could be `BUILD2_AUTOCONF_LIBC_VERSION` itself; perhaps
|
|
|
|
we should only have private bases that are only accessed by the user via
|
|
|
|
derived public checks), it is a good idea for checks that are based on
|
|
|
|
other checks to verify that the base macros are in fact defined, for example:
|
2022-04-24 10:57:44 +00:00
|
|
|
|
|
|
|
```
|
|
|
|
// HAVE_EXPLICIT_BZERO : BUILD2_AUTOCONF_LIBC_VERSION
|
|
|
|
|
|
|
|
#ifndef BUILD2_AUTOCONF_LIBC_VERSION
|
|
|
|
# error BUILD2_AUTOCONF_LIBC_VERSION appears to be conditionally included
|
|
|
|
#endif
|
|
|
|
|
|
|
|
...
|
|
|
|
```
|
|
|
|
|
2021-10-31 11:36:24 +00:00
|
|
|
[module-in]: https://build2.org/build2/doc/build2-build-system-manual.xhtml#module-in
|
2021-11-04 05:38:20 +00:00
|
|
|
[proj-config]: https://build2.org/build2/doc/build2-build-system-manual.xhtml#proj-config
|
|
|
|
[checks]: https://github.com/build2/libbuild2-autoconf/tree/master/libbuild2-autoconf/libbuild2/autoconf/checks/
|
2022-04-24 10:09:02 +00:00
|
|
|
[libc-version]: https://github.com/build2/libbuild2-autoconf/tree/master/libbuild2-autoconf/libbuild2/autoconf/checks/BUILD2_AUTOCONF_LIBC_VERSION.h
|