aclocal

aclocal [OPTION]...

--automake-name=prog
    Specify the name of the `automake` program to use instead of the default.

--force, -f
    Force the regeneration of `aclocal.m4` even if `configure.ac` is older.

--help
    Print a summary of the options and exit.

-I dir
    Add directory dir to the list of directories to be searched for `.m4` files. This option can be used multiple times.

--output=file
    Write the generated `aclocal.m4` content to file instead of the default `aclocal.m4`.

--print-ac-dir
    Print the system-wide Autoconf macro directory and exit.

--system-macro-file=file
    Use file as the system-wide `aclocal.m4`. This overrides the default system-wide macro file.

--verbose
    Print verbose processing information.

--version
    Print the version number and exit.

The `aclocal` command is a crucial part of the GNU Autotools suite, specifically designed to assist in preparing a package for configuration by Autoconf. Its primary function is to generate the `aclocal.m4` file.

This file contains definitions for M4 macros that are either built-in to Automake, found in external `.m4` files specified via `AC_MACRO_DIRS`, or are custom macros required by the `configure.ac` (or `configure.in`) script. `aclocal` scans `configure.ac` and `Makefile.am` files to identify all used Automake and custom macros, then collects their definitions from various sources, including the system-wide Autoconf macro directory and user-specified directories.

By collecting these definitions into a single `aclocal.m4` file, `aclocal` ensures that all necessary macros are available for Autoconf to successfully generate the final `configure` script. This automation greatly simplifies the process of making software packages portable and configurable across different Unix-like systems.

`aclocal` does not generate the `configure` script itself; it prepares the macro definitions required by `autoconf` for that purpose.
The order of `-I` (include) directories can be important if there are duplicate macro names across different directories.
It requires a `configure.ac` file to exist in the current directory (or specified path) to scan for macro usage.

The `aclocal.m4` file is a crucial intermediary. It serves as a repository for all non-standard and Automake-specific M4 macros that the `configure.ac` script needs. By centralizing these definitions, `aclocal` simplifies the process for Autoconf, which then only needs to process a single, self-contained macro file along with `configure.ac` to generate the final `configure` script. This modularity helps in maintaining a clean and manageable `configure.ac` file.

While `aclocal` is often run implicitly by `automake`, it's `aclocal` that performs the actual scanning and aggregation of macros used by both `configure.ac` and `Makefile.am` files. Automake uses the output of `aclocal` to generate `Makefile.in` files, further demonstrating the tight integration within the Autotools build system.

aclocal is an integral component of the GNU Autotools suite, which originated in the mid-1990s to standardize the build process for open-source projects. Its development was driven by the need to simplify the management of complex M4 macros required for configuring software across diverse Unix-like environments. Initially a simpler script, it evolved alongside Automake to automatically detect and collect macro dependencies, thereby streamlining the process of generating `configure` scripts. Its role has remained consistent: to ensure that all necessary Autoconf and Automake macros are correctly aggregated, making projects easier to build and maintain for developers worldwide.

autoconf(1), automake(1), libtoolize(1), m4(1)