Back to Commands

aclocal

developmentlinux
The aclocal command is one of the most frequently used commands in Linux/Unix-like operating systems. aclocal The aclocal command is part of the GNU Autotools suite. It generates an aclocal.m4 file by scanning configure.ac or configure.in for uses of autoconf macros and collecting the required macro definitions into a single file for use with autoconf.
See ExamplesView Syntax

Quick Reference

Command Name:

aclocal

Category:

development

Platform:

linux

Basic Usage:

aclocal [options] [arguments]

Common Use Cases

  • 1

    Autotools setup

    Generate aclocal.m4 files containing needed macro definitions for autoconf

  • 2

    Open source development

    Prepare the build system for C/C++ projects that use the GNU Autotools

  • 3

    Custom macro integration

    Include project-specific macros from m4 directories into the build system

  • 4

    Cross-platform compatibility

    Collect platform detection and feature testing macros for configure scripts

Syntax

aclocal [OPTION]...

Options

Option Description
-I DIR, --acdir=DIR Add directory DIR to the list of directories to search for .m4 macro files
--automake-acdir=DIR Directory holding automake-provided .m4 macro files
--system-acdir=DIR Directory holding system-wide third-party .m4 macro files
-o FILE, --output=FILE Write output to FILE instead of aclocal.m4
--print-ac-dir Print the directory where the system-wide third-party .m4 files are stored
--print-automake-acdir Print the directory where automake's .m4 files are stored
--verbose, -v Print names of files being processed and macro definitions found
--force, -f Always overwrite output file
--install Copy third-party files to a local directory
--dry-run Only pretend to do actions
--warnings=CATEGORY Report warnings falling in CATEGORY [syntax]
--help Display help information and exit
--version Output version information and exit

Examples

How to Use These Examples

The examples below show common ways to use the aclocal command. Try them in your terminal to see the results. You can copy any example by clicking on the code block.

Basic Examples:

Generate aclocal.m4 from configure.ac
aclocal
Generate aclocal.m4 with specific directories
aclocal -I /usr/local/share/aclocal
Generate aclocal.m4 with system directories
aclocal --system-acdir=/usr/share/aclocal
Generate aclocal.m4 with custom macro directory
aclocal -I m4

Advanced Examples:

Generate aclocal.m4 with verbose output
aclocal --verbose
Generate aclocal.m4 with debug information
aclocal --debug
Generate aclocal.m4 with specific output file
aclocal --output=my-aclocal.m4
Generate aclocal.m4 with multiple include directories
aclocal -I m4 -I /usr/local/share/aclocal -I /usr/share/aclocal
Generate aclocal.m4 and install to system directory
aclocal --install --system-acdir=/usr/share/aclocal

Try It Yourself

Practice makes perfect! The best way to learn is by trying these examples on your own system with real files.

Understanding Syntax

Pay attention to the syntax coloring: commands, options, and file paths are highlighted differently.

Notes

What is aclocal?

The aclocal command is a tool in the GNU Autotools suite that scans a project's configure.ac (or the older configure.in) file for macro calls and gathers the relevant macro definitions into a single aclocal.m4 file, which is then used by autoconf to generate the configure script.

Build System Integration:

Aclocal is typically used in this sequence during the build system setup:

  1. Run aclocal to create aclocal.m4
  2. Run autoconf to generate configure from configure.ac and aclocal.m4
  3. Run automake to generate Makefile.in from Makefile.am
  4. Run ./configure to generate Makefile from Makefile.in

Macro Search Path:

Aclocal searches for macros in the following locations, in order:

  • Directories specified with -I or --acdir options
  • The directory specified by --automake-acdir (automake's own macro directory)
  • The directory specified by --system-acdir (system-wide third-party macros)

Common M4 Directories:

Standard locations for m4 macro files include:

  • /usr/share/aclocal/ - System-wide macros
  • /usr/local/share/aclocal/ - Local system-wide macros
  • m4/ - Project-specific macros (convention)

Macro File Extensions:

Aclocal recognizes macro files with the following extensions:

  • .m4 - Standard M4 macro files
  • .m4.in - M4 macro templates

Important Notes:

  • Aclocal is typically run by autoreconf when setting up a project's build system
  • The aclocal.m4 file should not be edited manually as it is automatically generated
  • Project-specific macros should be placed in a separate directory (typically m4/) and included with -I m4
  • Modern projects often use autoreconf -i which runs aclocal, autoconf, and other tools in the correct order
  • Aclocal is part of automake, not autoconf, despite its primary purpose of supporting autoconf

Tips & Tricks

1

Use the -I dir option to add a directory to the search path

2

Use the -m option to specify the m4 executable

3

Use the -v option to display verbose output

4

Use the -h option to display help

5

Use the -V option to display version information

Common Use Cases

Autotools setup

Generate aclocal.m4 files containing needed macro definitions for autoconf

Open source development

Prepare the build system for C/C++ projects that use the GNU Autotools

Custom macro integration

Include project-specific macros from m4 directories into the build system

Cross-platform compatibility

Collect platform detection and feature testing macros for configure scripts

Build system maintenance

Update macro definitions when adding new features that require configuration checks

Related Commands

These commands are frequently used alongside aclocal or serve similar purposes:

autoconf
automake
autoreconf
libtool
autoscan
autoheader
m4
Explore All Commands

Use Cases

1

Autotools setup

Generate aclocal.m4 files containing needed macro definitions for autoconf

2

Open source development

Prepare the build system for C/C++ projects that use the GNU Autotools

3

Custom macro integration

Include project-specific macros from m4 directories into the build system

4

Cross-platform compatibility

Collect platform detection and feature testing macros for configure scripts

5

Build system maintenance

Update macro definitions when adding new features that require configuration checks

Learn By Doing

The best way to learn Linux commands is by practicing. Try out these examples in your terminal to build muscle memory and understand how the aclocal command works in different scenarios.

See ExamplesTry Lab Exercises
$ aclocal
View All Commands