Editing Make (software) (section)

==Makefile==
{{Anchor|makefile}}
{{Infobox file format
|name=Makefile
|uniform type=public.make-source<ref>{{cite web |url=https://developer.apple.com/documentation/uniformtypeidentifiers/uttype/3750150-makefile |title=makefile |work=Apple Developer Documentation: Uniform Type Identifiers |publisher=[[Apple Inc]] |access-date=2023-05-22 |archive-date=2023-05-22 |archive-url=https://web.archive.org/web/20230522155039/https://developer.apple.com/documentation/uniformtypeidentifiers/uttype/3750150-makefile |url-status=live }}</ref>
}}

The '''makefile''' language is partially [[declarative programming]] where end conditions are described but the order in which actions are to be taken is not.<ref>Adams, P. and Solomon, M., 1993, An overview of the CAPITL software development environment. In International Workshop on Software Configuration Management (pp. 1-34). Berlin, Heidelberg: Springer Berlin Heidelberg.</ref><ref>[http://phoenix.labri.fr/wiki/doku.php?id=an_overview_on_dsls an overview on dsls] {{webarchive |url=https://web.archive.org/web/20071023021126/http://phoenix.labri.fr/wiki/doku.php?id=an_overview_on_dsls |date=October 23, 2007 }}, 2007/02/27, phoenix wiki</ref><ref>[http://lists.w3.org/Archives/Public/www-ws-arch/2002Aug/0105.html Re: Choreography and REST] {{webarchive |url=https://web.archive.org/web/20160912144047/http://lists.w3.org/Archives/Public/www-ws-arch/2002Aug/0105.html |date=September 12, 2016 }},  from Christopher B Ferris on 2002-08-09</ref><ref>[http://www.robots.ox.ac.uk/~tgtjr/makefiles.html Target Junior Makefiles] {{webarchive |url=https://web.archive.org/web/20100107082837/http://www.robots.ox.ac.uk/~tgtjr/makefiles.html |date=January 7, 2010 }}, Andrew W. Fitzgibbon and William A. Hoffman</ref> This type of programming can be confusing to programmers used to [[imperative programming]].

Makefiles can contain the following constructs:<ref>[https://www.gnu.org/software/make/manual/html_node/Makefile-Contents.html 3.1 What Makefiles Contain] {{Webarchive|url=https://web.archive.org/web/20210505100531/https://www.gnu.org/software/make/manual/html_node/Makefile-Contents.html |date=2021-05-05 }}, ''GNU make'', [[Free Software Foundation]]</ref>

* ''Explicit rule'': defines when and how to update a target, listing ''prerequisites'' (dependent targets) and commands that define the update action, called the ''recipe'' 
* ''Implicit rule'': defines when and how to remake a class of files based on their names, including how a target depends on a file with a name similar to the target and an update recipe
* ''Variable definition'': associates a text value with a name that can be substituted into later text
* ''Directive'': instruction to do something special such as include another makefile
* ''[[Comment (computer programming)|Comment]]'': line starting with {{code|#}}

===Rules===

Each rule begins with a ''dependency line'' which consists of the rule's [[Orientation (graph theory)|target]] name followed by a colon (:), and optionally a list of targets (also known as prerequisites) on which the rule's target depends.<ref>{{cite web|url=https://www.gnu.org/software/make/manual/html_node/Prerequisite-Types.html|title=Prerequisite Types (GNU make)|website=GNU.org|publisher=[[GNU Project]]|access-date=15 December 2020|archive-date=2 December 2020|archive-url=https://web.archive.org/web/20201202083734/https://www.gnu.org/software/make/manual/html_node/Prerequisite-Types.html|url-status=live}}</ref>

 target [target ...]: [component ...]
 {{keypress|TAB}}[command 1]
 	   .
 	   .
 	   .
 {{keypress|TAB}}[command n]

Usually a rule has a single target, rather than multiple.

A dependency line may be followed by a recipe: a series of [[Tab character|TAB]] indented command lines that define how to generate the target from the components (i.e. source files). If any prerequisite has a more recent timestamp than the target file or the target does not exist as a file, the recipe is performed.

The first command may appear on the same line after the prerequisites, separated by a semicolon,
<syntaxhighlight lang="make">
targets: prerequisites ; command
</syntaxhighlight>
for example,
<syntaxhighlight lang="make">
hello: ; @echo "hello"
</syntaxhighlight>

Each command line must begin with a tab character. Even though a [[space character|space]] is also [[Whitespace (computer science)|whitespace]], Make requires tab. Since this often leads to confusion and mistakes, this aspect of makefile syntax is subject to criticism. [[Eric S. Raymond]] describes it as "one of the worst design botches in the history of Unix"<ref name="esr">"Chapter 15. Tools: make: Automating Your Recipes", ''The Art of Unix Programming'', [[Eric S. Raymond]] 2003</ref> and ''[[The Unix-Haters Handbook]]'' said "using tabs as part of the syntax is like one of those pungee [sic] stick traps in [[The Green Berets (film)|''The Green Berets'']]". Feldman explains the choice as caused by a [[Technical debt|workaround]] for an early implementation difficulty, and preserved by a desire for [[backward compatibility]] with the very first users:

{{blockquote|Why the tab in column 1? [[Yacc]] was new, [[Lex (software)|Lex]] was brand new. I hadn't tried either, so I figured this would be a good excuse to learn. After getting myself snarled up with my first stab at Lex, I just did something simple with the pattern newline-tab. It worked, it stayed. And then a few weeks later I had a user population of about a dozen, most of them friends, and I didn't want to screw up my embedded base. The rest, sadly, is history.|Stuart Feldman<ref name="esr"/>}}

GNU Make since version 3.82 allows the choice of any symbol (one character) as the recipe prefix using the .RECIPEPREFIX special variable:
<syntaxhighlight lang="make">
.RECIPEPREFIX := :
all:
:@echo "recipe prefix symbol is set to '$(.RECIPEPREFIX)'"
</syntaxhighlight>

Each command is executed in a separate [[Unix shell|shell]]. Since operating systems use different shells, this can lead to unportable makefiles. For example, GNU Make (all POSIX Makes) executes commands with [[/bin/sh]] by default, where [[Unix]] commands like [[cp (Unix)|cp]] are normally used. In contrast, Microsoft's ''nmake'' executes commands with cmd.exe where [[Batch file|batch]] commands like [[copy (command)|copy]] are available but not necessarily cp.

Since a recipe is optional, the dependency line can consist solely of components that refer to other targets:
<syntaxhighlight lang="make">
realclean: clean distclean
</syntaxhighlight>

The following example rule is evaluated when Make updates target file.txt via {{code|make file.txt}}. If file.html is newer than file.txt or file.txt does not exist, then the command is run to generate file.txt from file.html.

<syntaxhighlight lang="make">
file.txt: file.html
	lynx -dump file.html > file.txt
</syntaxhighlight>

A command can have one or more of the following prefixes (after the tab):
* [[hyphen-minus|minus]] (-) specifies to ignore an error from the command
* [[at sign|at]] (@) specifies to ''not'' output the command before it is executed
* [[plus sign|plus]] (+) specifies to execute the command even if Make is invoked in "do not execute" mode

Ignoring errors and silencing echo can alternatively be obtained via the special targets {{code|.IGNORE}} and {{code|.SILENT}}.<ref name=SUS>{{man|1|make|SUS}}</ref>

Microsoft's NMAKE has predefined rules that can be omitted from these makefiles, e.g. {{code|c.obj   $(CC)$(CFLAGS)|lang=make}}.

===Macros===

A makefile can define and use macros. Macros are usually referred to as ''variables'' when they hold simple string definitions, like {{code|1=CC=clang|lang=make}}. Macros in makefiles may be overridden in the [[command-line argument]]s passed to the Make utility. [[Environment variables]] are also available as macros.

For example, the macro {{code|CC}} is frequently used in makefiles to refer to the location of a [[C (programming language)|C]] compiler. If used consistently throughout the makefile, then the compiler used can be changed by changing the value of the macro rather than changing each rule command that invokes the compiler.

Macros are commonly named in [[all-caps]]:

<syntaxhighlight lang="make">
MACRO = definition
</syntaxhighlight>

A macro value can consist of other macro values. The value of macro is expanded on each use [[lazy evaluation|lazily]].

A macro is used by expanding either via $''NAME'' or $(''NAME''). The latter is safer since omitting the parentheses leads to Make interpreting the next letter after the {{code|$}} as the entire variable name. An equivalent form uses curly braces rather than parentheses, i.e. {{code|${} }}, which is the style used in [[BSD]].

<syntaxhighlight lang="make">
NEW_MACRO = $(MACRO)-$(MACRO2)
</syntaxhighlight>

Macros can be composed of shell commands by using the [[command substitution]] operator <code>!=</code>.<ref>{{Cite web |url=https://pubs.opengroup.org/onlinepubs/9799919799/utilities/make.html |title=Make |access-date=2024-10-29 |archive-date=2024-10-05 |archive-url=https://web.archive.org/web/20241005234028/https://pubs.opengroup.org/onlinepubs/9799919799/utilities/make.html |url-status=live }}</ref>

<syntaxhighlight lang="make">
YYYYMMDD != date
</syntaxhighlight>

The command-line syntax for overriding a macro is:

<syntaxhighlight lang="bash">
make MACRO="value" [MACRO="value" ...] TARGET [TARGET ...]
</syntaxhighlight>

Makefiles can access predefined ''internal macros'', with {{code|?}} and {{code|@}} being common.

<syntaxhighlight lang="make">
target: component1 component2
	# echo components YOUNGER than TARGET
	echo $? 
	# echo TARGET name
	echo $@ 
</syntaxhighlight>

A common syntax when defining macros, which works on BSD and GNU Make, is to use {{mono|1=+=}}, {{mono|1=?=}}, and {{mono|1=!=}} instead of the equal sign ({{mono|1==}}).<ref>{{man|1|make|FreeBSD}}</ref>

===Suffix rules===

Suffix rules have "targets" with names in the form {{code|.FROM.TO}} and are used to launch actions based on file extension. In the command lines of suffix rules, POSIX specifies<ref name=posix-macros /> that the internal macro {{code|$<}} refers to the first prerequisite and {{code|$@}} refers to the target. In this example, which converts any HTML file into text, the shell redirection token {{code|>}} is part of the command line, whereas {{code|$<}} is a macro referring to the HTML file:

<syntaxhighlight lang="make">
.SUFFIXES: .txt .html

# From .html to .txt
.html.txt:
	lynx -dump $<   >   $@
</syntaxhighlight>

When called from the command line, the example above expands:

<syntaxhighlight lang="console">
$ make -n file.txt
lynx -dump file.html > file.txt
</syntaxhighlight>

===Pattern rules ===

Suffix rules cannot have any prerequisites of their own.<ref>{{cite web|url=https://www.gnu.org/software/make/manual/html_node/Suffix-Rules.html#Suffix-Rules|title=GNU make manual: suffix rules|publisher=Free Software Foundation|access-date=2014-05-24|archive-date=2014-05-22|archive-url=https://web.archive.org/web/20140522130224/http://www.gnu.org/software/make/manual/html_node/Suffix-Rules.html#Suffix-Rules|url-status=live}}</ref> If they have any, they are treated as normal files with unusual names, not as suffix rules. GNU Make supports suffix rules for compatibility with old makefiles but otherwise encourages usage of ''pattern rules''.<ref>{{cite web|url=https://www.gnu.org/software/make/manual/html_node/Pattern-Rules.html#Pattern-Rules|title=GNU make manual: pattern rules|publisher=Free Software Foundation|access-date=2014-05-24|archive-date=2014-05-28|archive-url=https://web.archive.org/web/20140528170600/http://www.gnu.org/software/make/manual/html_node/Pattern-Rules.html#Pattern-Rules|url-status=live}}</ref>

A pattern rule looks like an ordinary rule, except that its target contains exactly one  {{code|%}} character within the string. The target is considered a pattern for matching file names: the {{code|%}} can match any substring of zero or more characters,<ref>[http://www.lehman.cuny.edu/cgi-bin/man-cgi?make+1 See section ''Pattern Matching Rules'' in the SunPro man page]  {{webarchive|url=https://web.archive.org/web/20140529103302/http://www.lehman.cuny.edu/cgi-bin/man-cgi?make%201 |date=May 29, 2014 }}</ref> while other characters match only themselves. The prerequisites likewise use {{code|%}} to show how their names relate to the target name.

The example above of a suffix rule would look like the following pattern rule:
<syntaxhighlight lang="make">
# From %.html to %.txt
%.txt : %.html 
	lynx -dump $< > $@
</syntaxhighlight>

===Comment===

Single-line [[comment (programming)|comment]]s are started with the [[hash symbol]] (#).

===Directive===

A directive specifies special behavior such as [[include directive|including]] another makefile.

===Line continuation===

[[Line continuation]] is indicated with a backslash {{code|\}} character at the end of a line.

    target: component \
            component
    {{keypress|TAB}}command ;          \
    {{keypress|TAB}}command |          \
    {{keypress|TAB}}piped-command