Amake: GNU Make with Automatic Dependency Analysis

GNU make

This file documents the GNU make utility, which determines automatically which pieces of a large program need to be recompiled, and issues the commands to recompile them.

This is Edition 0.70, last updated 1 April 2006, of the Amake: GNU Make with Automatic Dependency Analysis manual, for GNU make version 3.81.

Copyright © 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.

Copyright © 2009, 2010 Jim Buffenbarger.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover Texts being “A GNU Manual,” and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled “GNU Free Documentation License.”

(a) The FSF's Back-Cover Text is: “You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development.”

• Overview: Overview of make.
• Introduction: An introduction to make.
• Makefiles: Makefiles tell make what to do.
• Rules: Rules describe when a file must be remade.
• Commands: Commands say how to remake a file.
• Using Variables: You can use variables to avoid repetition.
• Conditionals: Use or ignore parts of the makefile based on the values of variables.
• Functions: Many powerful ways to manipulate text.
• Invoking make: How to invoke make on the command line.
• Implicit Rules: Use implicit rules to treat many files alike, based on their file names.
• Archives: How make can update library archives.
• Features: Features GNU make has over other makes.
• Amake Features: Automatic dependency analysis
• Missing: What GNU make lacks from other makes.
• Makefile Conventions: Conventions for writing makefiles for GNU programs.
• Quick Reference: A quick reference for experienced users.
• Error Messages: A list of common errors generated by make.
• Complex Makefile: A real example of a straightforward, but nontrivial, makefile.
• GNU Free Documentation License: License for copying this manual
• Concept Index: Index of Concepts
• Name Index: Index of Functions, Variables, & Directives

--- The Detailed Node Listing ---

Overview of make

• Preparing: Preparing and Running Make
• Reading: On Reading this Text
• Bugs: Problems and Bugs

An Introduction to Makefiles

• Rule Introduction: What a rule looks like.
• Simple Makefile: A Simple Makefile
• How Make Works: How make Processes This Makefile
• Variables Simplify: Variables Make Makefiles Simpler
• make Deduces: Letting make Deduce the Commands
• Combine By Prerequisite: Another Style of Makefile
• Cleanup: Rules for Cleaning the Directory

Writing Makefiles

• Makefile Contents: What makefiles contain.
• Makefile Names: How to name your makefile.
• Include: How one makefile can use another makefile.
• MAKEFILES Variable: The environment can specify extra makefiles.
• MAKEFILE_LIST Variable: Discover which makefiles have been read.
• Special Variables: Other special variables.
• Remaking Makefiles: How makefiles get remade.
• Overriding Makefiles: How to override part of one makefile with another makefile.
• Reading Makefiles: How makefiles are parsed.
• Secondary Expansion: How and when secondary expansion is performed.

Writing Rules

• Rule Example: An example explained.
• Rule Syntax: General syntax explained.
• Prerequisite Types: There are two types of prerequisites.
• Wildcards: Using wildcard characters such as `*'.
• Directory Search: Searching other directories for source files.
• Phony Targets: Using a target that is not a real file's name.
• Force Targets: You can use a target without commands or prerequisites to mark other targets as phony.
• Empty Targets: When only the date matters and the files are empty.
• Special Targets: Targets with special built-in meanings.
• Multiple Targets: When to make use of several targets in a rule.
• Multiple Rules: How to use several rules with the same target.
• Static Pattern: Static pattern rules apply to multiple targets and can vary the prerequisites according to the target name.
• Double-Colon: How to use a special kind of rule to allow several independent rules for one target.
• Automatic Prerequisites: How to automatically generate rules giving prerequisites from source files themselves.

Using Wildcard Characters in File Names

• Wildcard Examples: Several examples
• Wildcard Pitfall: Problems to avoid.
• Wildcard Function: How to cause wildcard expansion where it does not normally take place.

Searching Directories for Prerequisites

• General Search: Specifying a search path that applies to every prerequisite.
• Selective Search: Specifying a search path for a specified class of names.
• Search Algorithm: When and how search paths are applied.
• Commands/Search: How to write shell commands that work together with search paths.
• Implicit/Search: How search paths affect implicit rules.
• Libraries/Search: Directory search for link libraries.

Static Pattern Rules

• Static Usage: The syntax of static pattern rules.
• Static versus Implicit: When are they better than implicit rules?

Writing the Commands in Rules

• Command Syntax: Command syntax features and pitfalls.
• Echoing: How to control when commands are echoed.
• Execution: How commands are executed.
• Parallel: How commands can be executed in parallel.
• Errors: What happens after a command execution error.
• Interrupts: What happens when a command is interrupted.
• Recursion: Invoking make from makefiles.
• Sequences: Defining canned sequences of commands.
• Empty Commands: Defining useful, do-nothing commands.

Command Syntax

• Splitting Lines: Breaking long command lines for readability.
• Variables in Commands: Using make variables in commands.

Command Execution

• Choosing the Shell: How make chooses the shell used to run commands.

Recursive Use of make

• MAKE Variable: The special effects of using ‘$(MAKE)’.
• Variables/Recursion: How to communicate variables to a sub-make.
• Options/Recursion: How to communicate options to a sub-make.
• -w Option: How the ‘-w’ or ‘--print-directory’ option helps debug use of recursive make commands.

How to Use Variables

• Reference: How to use the value of a variable.
• Flavors: Variables come in two flavors.
• Advanced: Advanced features for referencing a variable.
• Values: All the ways variables get their values.
• Setting: How to set a variable in the makefile.
• Appending: How to append more text to the old value of a variable.
• Override Directive: How to set a variable in the makefile even if the user has set it with a command argument.
• Defining: An alternate way to set a variable to a verbatim string.
• Environment: Variable values can come from the environment.
• Target-specific: Variable values can be defined on a per-target basis.
• Pattern-specific: Target-specific variable values can be applied to a group of targets that match a pattern.

Advanced Features for Reference to Variables

• Substitution Refs: Referencing a variable with substitutions on the value.
• Computed Names: Computing the name of the variable to refer to.

Conditional Parts of Makefiles

• Conditional Example: Example of a conditional
• Conditional Syntax: The syntax of conditionals.
• Testing Flags: Conditionals that test flags.

Functions for Transforming Text

• Syntax of Functions: How to write a function call.
• Text Functions: General-purpose text manipulation functions.
• File Name Functions: Functions for manipulating file names.
• Conditional Functions: Functions that implement conditions.
• Foreach Function: Repeat some text with controlled variation.
• Call Function: Expand a user-defined function.
• Value Function: Return the un-expanded value of a variable.
• Eval Function: Evaluate the arguments as makefile syntax.
• Origin Function: Find where a variable got its value.
• Flavor Function: Find out the flavor of a variable.
• Shell Function: Substitute the output of a shell command.
• Make Control Functions: Functions that control how make runs.

How to Run make

• Makefile Arguments: How to specify which makefile to use.
• Goals: How to use goal arguments to specify which parts of the makefile to use.
• Instead of Execution: How to use mode flags to specify what kind of thing to do with the commands in the makefile other than simply execute them.
• Avoiding Compilation: How to avoid recompiling certain files.
• Overriding: How to override a variable to specify an alternate compiler and other things.
• Testing: How to proceed past some errors, to test compilation.
• Options Summary: Summary of Options

Using Implicit Rules

• Using Implicit: How to use an existing implicit rule to get the commands for updating a file.
• Catalogue of Rules: A list of built-in implicit rules.
• Implicit Variables: How to change what predefined rules do.
• Chained Rules: How to use a chain of implicit rules.
• Pattern Rules: How to define new implicit rules.
• Last Resort: How to define commands for rules which cannot find any.
• Suffix Rules: The old-fashioned style of implicit rule.
• Implicit Rule Search: The precise algorithm for applying implicit rules.

Defining and Redefining Pattern Rules

• Pattern Intro: An introduction to pattern rules.
• Pattern Examples: Examples of pattern rules.
• Automatic Variables: How to use automatic variables in the commands of implicit rules.
• Pattern Match: How patterns match.
• Match-Anything Rules: Precautions you should take prior to defining rules that can match any target file whatever.
• Canceling Rules: How to override or cancel built-in rules.

Using make to Update Archive Files

• Archive Members: Archive members as targets.
• Archive Update: The implicit rule for archive member targets.
• Archive Pitfalls: Dangers to watch out for when using archives.
• Archive Suffix Rules: You can write a special kind of suffix rule for updating archives.

Implicit Rule for Archive Member Targets

• Archive Symbols: How to update archive symbol directories.