autoheader

autoheader [OPTION]... [TEMPLATE-FILE]

-h, --help
    Display a help message and exit.

-V, --version
    Display version information and exit.

-v, --verbose
    Print verbose messages during execution.

-d, --debug
    Don't remove temporary files, useful for debugging.

-f, --force
    Force autoheader to overwrite existing output files, even if they appear up-to-date.

-i, --include=DIR
    Look for aclocal.m4 files in DIR as well. This directory is added to the search path.

-B, --prepend-include=DIR
    Similar to --include, but prepends DIR to the search path, giving it higher precedence.

-I, --localdir=DIR
    Look for auxiliary files in DIR. This is primarily for autoconf, but useful for consistency.

-C, --macrodir=DIR
    Search for Autoconf macros in DIR, usually refers to the system-wide macro directory.

-o, --output=FILE
    Write the output to FILE instead of the default config.h.in.

-t, --template=FILE
    Use FILE as the input template for the generated header, rather than the default acconfig.h if it exists, or internal data.

autoheader is a crucial utility within the GNU Autotools suite, specifically designed to help C/C++ projects maintain portability across diverse Unix-like systems.
Its primary function is to automatically generate a template for config.h.in, a header file that defines preprocessor macros based on the results of configuration checks performed by configure.
By scanning configure.ac (or aclocal.m4 files it includes) for AC_DEFINE, AC_CHECK_HEADERS, AC_CHECK_TYPES, AC_CHECK_FUNCS, and similar macros, autoheader extracts the necessary information.
It then produces config.h.in containing #undef or #cmakedefine directives for each feature, which are later replaced with #define by the configure script if the feature is found on the target system.
This automation significantly simplifies the process of adapting software to different environments, ensuring that applications use the correct system features while avoiding manual header file modifications.

autoheader relies on configure.ac to define the necessary checks. If configure.ac is incomplete or incorrect, the generated config.h.in will also be flawed.
It primarily handles #define directives for feature presence. Complex conditional compilation logic often needs to be handled within the source code itself using the generated definitions.
While autoheader can be run manually, it's typically invoked as part of autoreconf, which orchestrates the entire Autotools build system generation process. Running it in isolation without updating other Autotools components might lead to inconsistencies.

Typically, the full Autotools workflow involves: 1. Running aclocal (for aclocal.m4 and config.m4), 2. Running autoconf (for configure), 3. Running autoheader (for config.h.in), and optionally automake (for Makefile.in files). The autoreconf command conveniently executes these in the correct order, making it the most common way to invoke autoheader.

The .in suffix signifies that it's a template file. The configure script, when run by a user, reads this template, performs system checks, and then substitutes placeholders (like @HAVE_SOME_FEATURE@ or #undef SOME_FEATURE) with actual definitions (e.g., #define SOME_FEATURE 1) to create the final config.h in the build directory. This separation allows the source code to include config.h directly, while the build system handles its generation for the specific target environment.

autoheader is an integral part of the GNU Autotools suite, a set of programming tools designed to address the challenges of portability in software development, particularly for C and C++ projects.
Developed by the GNU project, Autotools emerged in the early 1990s with autoconf as its core component. autoheader was introduced to automate the generation of config.h.in files, complementing autoconf's ability to create configure scripts.
This allowed developers to define system-dependent features in a high-level configure.ac script, with autoheader translating these into a C header template. Its development paralleled the growth of open-source software and the increasing need for cross-platform compatibility, making it a standard tool for many Unix-like software distributions.

autoconf(1), aclocal(1), automake(1), autoreconf(1), libtool(1)