1MAKE(1P) POSIX Programmer's Manual MAKE(1P)
2
3
4
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 make — maintain, update, and regenerate groups of programs (DEVELOP‐
13 MENT)
14
16 make [-einpqrst] [-f makefile]... [-k|-S] [macro=value...]
17 [target_name...]
18
20 The make utility shall update files that are derived from other files.
21 A typical case is one where object files are derived from the corre‐
22 sponding source files. The make utility examines time relationships and
23 shall update those derived files (called targets) that have modified
24 times earlier than the modified times of the files (called prerequi‐
25 sites) from which they are derived. A description file (makefile) con‐
26 tains a description of the relationships between files, and the com‐
27 mands that need to be executed to update the targets to reflect changes
28 in their prerequisites. Each specification, or rule, shall consist of a
29 target, optional prerequisites, and optional commands to be executed
30 when a prerequisite is newer than the target. There are two types of
31 rule:
32
33 1. Inference rules, which have one target name with at least one
34 <period> ('.') and no <slash> ('/')
35
36 2. Target rules, which can have more than one target name
37
38 In addition, make shall have a collection of built-in macros and infer‐
39 ence rules that infer prerequisite relationships to simplify mainte‐
40 nance of programs.
41
42 To receive exactly the behavior described in this section, the user
43 shall ensure that a portable makefile shall:
44
45 * Include the special target .POSIX
46
47 * Omit any special target reserved for implementations (a leading
48 period followed by uppercase letters) that has not been specified
49 by this section
50
51 The behavior of make is unspecified if either or both of these condi‐
52 tions are not met.
53
55 The make utility shall conform to the Base Definitions volume of
56 POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines, except for
57 Guideline 9.
58
59 The following options shall be supported:
60
61 -e Cause environment variables, including those with null val‐
62 ues, to override macro assignments within makefiles.
63
64 -f makefile
65 Specify a different makefile. The argument makefile is a
66 pathname of a description file, which is also referred to as
67 the makefile. A pathname of '-' shall denote the standard
68 input. There can be multiple instances of this option, and
69 they shall be processed in the order specified. The effect of
70 specifying the same option-argument more than once is unspec‐
71 ified.
72
73 -i Ignore error codes returned by invoked commands. This mode is
74 the same as if the special target .IGNORE were specified
75 without prerequisites.
76
77 -k Continue to update other targets that do not depend on the
78 current target if a non-ignored error occurs while executing
79 the commands to bring a target up-to-date.
80
81 -n Write commands that would be executed on standard output, but
82 do not execute them. However, lines with a <plus-sign> ('+')
83 prefix shall be executed. In this mode, lines with an at-sign
84 ('@') character prefix shall be written to standard output.
85
86 -p Write to standard output the complete set of macro defini‐
87 tions and target descriptions. The output format is unspeci‐
88 fied.
89
90 -q Return a zero exit value if the target file is up-to-date;
91 otherwise, return an exit value of 1. Targets shall not be
92 updated if this option is specified. However, a makefile com‐
93 mand line (associated with the targets) with a <plus-sign>
94 ('+') prefix shall be executed.
95
96 -r Clear the suffix list and do not use the built-in rules.
97
98 -S Terminate make if an error occurs while executing the com‐
99 mands to bring a target up-to-date. This shall be the default
100 and the opposite of -k.
101
102 -s Do not write makefile command lines or touch messages (see
103 -t) to standard output before executing. This mode shall be
104 the same as if the special target .SILENT were specified
105 without prerequisites.
106
107 -t Update the modification time of each target as though a touch
108 target had been executed. Targets that have prerequisites but
109 no commands (see Target Rules), or that are already up-to-
110 date, shall not be touched in this manner. Write messages to
111 standard output for each target file indicating the name of
112 the file and that it was touched. Normally, the makefile com‐
113 mand lines associated with each target are not executed. How‐
114 ever, a command line with a <plus-sign> ('+') prefix shall be
115 executed.
116
117 Any options specified in the MAKEFLAGS environment variable shall be
118 evaluated before any options specified on the make utility command
119 line. If the -k and -S options are both specified on the make utility
120 command line or by the MAKEFLAGS environment variable, the last option
121 specified shall take precedence. If the -f or -p options appear in the
122 MAKEFLAGS environment variable, the result is undefined.
123
125 The following operands shall be supported:
126
127 target_name
128 Target names, as defined in the EXTENDED DESCRIPTION section.
129 If no target is specified, while make is processing the make‐
130 files, the first target that make encounters that is not a
131 special target or an inference rule shall be used.
132
133 macro=value
134 Macro definitions, as defined in Macros.
135
136 If the target_name and macro=value operands are intermixed on the make
137 utility command line, the results are unspecified.
138
140 The standard input shall be used only if the makefile option-argument
141 is '-'. See the INPUT FILES section.
142
144 The input file, otherwise known as the makefile, is a text file con‐
145 taining rules, macro definitions, include lines, and comments. See the
146 EXTENDED DESCRIPTION section.
147
149 The following environment variables shall affect the execution of make:
150
151 LANG Provide a default value for the internationalization vari‐
152 ables that are unset or null. (See the Base Definitions vol‐
153 ume of POSIX.1‐2017, Section 8.2, Internationalization Vari‐
154 ables for the precedence of internationalization variables
155 used to determine the values of locale categories.)
156
157 LC_ALL If set to a non-empty string value, override the values of
158 all the other internationalization variables.
159
160 LC_CTYPE Determine the locale for the interpretation of sequences of
161 bytes of text data as characters (for example, single-byte as
162 opposed to multi-byte characters in arguments and input
163 files).
164
165 LC_MESSAGES
166 Determine the locale that should be used to affect the format
167 and contents of diagnostic messages written to standard
168 error.
169
170 MAKEFLAGS
171 This variable shall be interpreted as a character string rep‐
172 resenting a series of option characters to be used as the
173 default options. The implementation shall accept both of the
174 following formats (but need not accept them when intermixed):
175
176 * The characters are option letters without the leading
177 <hyphen-minus> characters or <blank> separation used on a
178 make utility command line.
179
180 * The characters are formatted in a manner similar to a
181 portion of the make utility command line: options are
182 preceded by <hyphen-minus> characters and <blank>-sepa‐
183 rated as described in the Base Definitions volume of
184 POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
185 The macro=value macro definition operands can also be
186 included. The difference between the contents of MAKE‐
187 FLAGS and the make utility command line is that the con‐
188 tents of the variable shall not be subjected to the word
189 expansions (see Section 2.6, Word Expansions) associated
190 with parsing the command line values.
191
192 NLSPATH Determine the location of message catalogs for the processing
193 of LC_MESSAGES.
194
195 PROJECTDIR
196 Provide a directory to be used to search for SCCS files not
197 found in the current directory. In all of the following
198 cases, the search for SCCS files is made in the directory
199 SCCS in the identified directory. If the value of PROJECTDIR
200 begins with a <slash>, it shall be considered an absolute
201 pathname; otherwise, the value of PROJECTDIR is treated as a
202 user name and that user's initial working directory shall be
203 examined for a subdirectory src or source. If such a direc‐
204 tory is found, it shall be used. Otherwise, the value is used
205 as a relative pathname.
206
207 If PROJECTDIR is not set or has a null value, the search for
208 SCCS files shall be made in the directory SCCS in the current
209 directory.
210
211 The setting of PROJECTDIR affects all files listed in the
212 remainder of this utility description for files with a compo‐
213 nent named SCCS.
214
215 The value of the SHELL environment variable shall not be used as a
216 macro and shall not be modified by defining the SHELL macro in a make‐
217 file or on the command line. All other environment variables, including
218 those with null values, shall be used as macros, as defined in Macros.
219
221 If not already ignored, make shall trap SIGHUP, SIGTERM, SIGINT, and
222 SIGQUIT and remove the current target unless the target is a directory
223 or the target is a prerequisite of the special target .PRECIOUS or
224 unless one of the -n, -p, or -q options was specified. Any targets
225 removed in this manner shall be reported in diagnostic messages of
226 unspecified format, written to standard error. After this cleanup
227 process, if any, make shall take the standard action for all other sig‐
228 nals.
229
231 The make utility shall write all commands to be executed to standard
232 output unless the -s option was specified, the command is prefixed with
233 an at-sign, or the special target .SILENT has either the current target
234 as a prerequisite or has no prerequisites. If make is invoked without
235 any work needing to be done, it shall write a message to standard out‐
236 put indicating that no action was taken. If the -t option is present
237 and a file is touched, make shall write to standard output a message of
238 unspecified format indicating that the file was touched, including the
239 filename of the file.
240
242 The standard error shall be used only for diagnostic messages.
243
245 Files can be created when the -t option is present. Additional files
246 can also be created by the utilities invoked by make.
247
249 The make utility attempts to perform the actions required to ensure
250 that the specified targets are up-to-date. A target shall be considered
251 up-to-date if it exists and is newer than all of its dependencies, or
252 if it has already been made up-to-date by the current invocation of
253 make (regardless of the target's existence or age). A target may also
254 be considered up-to-date if it exists, is the same age as one or more
255 of its prerequisites, and is newer than the remaining prerequisites (if
256 any). The make utility shall treat all prerequisites as targets them‐
257 selves and recursively ensure that they are up-to-date, processing them
258 in the order in which they appear in the rule. The make utility shall
259 use the modification times of files to determine whether the corre‐
260 sponding targets are out-of-date.
261
262 To ensure that a target is up-to-date, make shall ensure that all of
263 the prerequisites of a target are up-to-date, then check to see if the
264 target itself is up-to-date. If the target is not up-to-date, the tar‐
265 get shall be made up-to-date by executing the rule's commands (if any).
266 If the target does not exist after the target has been successfully
267 made up-to-date, the target shall be treated as being newer than any
268 target for which it is a prerequisite.
269
270 If a target exists and there is neither a target rule nor an inference
271 rule for the target, the target shall be considered up-to-date. It
272 shall be an error if make attempts to ensure that a target is up-to-
273 date but the target does not exist and there is neither a target rule
274 nor an inference rule for the target.
275
276 Makefile Syntax
277 A makefile can contain rules, macro definitions (see Macros), include
278 lines, and comments. There are two kinds of rules: inference rules and
279 target rules. The make utility shall contain a set of built-in infer‐
280 ence rules. If the -r option is present, the built-in rules shall not
281 be used and the suffix list shall be cleared. Additional rules of both
282 types can be specified in a makefile. If a rule is defined more than
283 once, the value of the rule shall be that of the last one specified.
284 Macros can also be defined more than once, and the value of the macro
285 is specified in Macros. There are three kinds of comments: blank
286 lines, empty lines, and a <number-sign> ('#') and all following charac‐
287 ters up to the first unescaped <newline> character. Blank lines, empty
288 lines, and lines with <number-sign> ('#') as the first character on the
289 line are also known as comment lines.
290
291 By default, the following files shall be tried in sequence: ./makefile
292 and ./Makefile. If neither ./makefile or ./Makefile are found, other
293 implementation-defined files may also be tried. On XSI-conformant sys‐
294 tems, the additional files ./s.makefile, SCCS/s.makefile, ./s.Makefile,
295 and SCCS/s.Makefile shall also be tried.
296
297 The -f option shall direct make to ignore any of these default files
298 and use the specified argument as a makefile instead. If the '-' argu‐
299 ment is specified, standard input shall be used.
300
301 The term makefile is used to refer to any rules provided by the user,
302 whether in ./makefile or its variants, or specified by the -f option.
303
304 The rules in makefiles shall consist of the following types of lines:
305 target rules, including special targets (see Target Rules), inference
306 rules (see Inference Rules), macro definitions (see Macros), and com‐
307 ments.
308
309 Target and Inference Rules may contain command lines. Command lines
310 can have a prefix that shall be removed before execution (see Makefile
311 Execution).
312
313 When an escaped <newline> (one preceded by a <backslash>) is found any‐
314 where in the makefile except in a command line, an include line, or a
315 line immediately preceding an include line, it shall be replaced, along
316 with any leading white space on the following line, with a single
317 <space>. When an escaped <newline> is found in a command line in a
318 makefile, the command line shall contain the <backslash>, the <new‐
319 line>, and the next line, except that the first character of the next
320 line shall not be included if it is a <tab>. When an escaped <newline>
321 is found in an include line or in a line immediately preceding an
322 include line, the behavior is unspecified.
323
324 Include Lines
325 If the word include appears at the beginning of a line and is followed
326 by one or more <blank> characters, the string formed by the remainder
327 of the line shall be processed as follows to produce a pathname:
328
329 * The trailing <newline>, any <blank> characters immediately preced‐
330 ing a comment, and any comment shall be discarded. If the resulting
331 string contains any double-quote characters ('"') the behavior is
332 unspecified.
333
334 * The resulting string shall be processed for macro expansion (see
335 Macros).
336
337 * Any <blank> characters that appear after the first non-<blank>
338 shall be used as separators to divide the macro-expanded string
339 into fields. It is unspecified whether any other white-space char‐
340 acters are also used as separators. It is unspecified whether path‐
341 name expansion (see Section 2.13, Pattern Matching Notation) is
342 also performed.
343
344 * If the processing of separators and optional pathname expansion
345 results in either zero or two or more non-empty fields, the behav‐
346 ior is unspecified. If it results in one non-empty field, that
347 field is taken as the pathname.
348
349 If the pathname does not begin with a '/' it shall be treated as rela‐
350 tive to the current working directory of the process, not relative to
351 the directory containing the makefile. If the file does not exist in
352 this location, it is unspecified whether additional directories are
353 searched.
354
355 The contents of the file specified by the pathname shall be read and
356 processed as if they appeared in the makefile in place of the include
357 line. If the file ends with an escaped <newline> the behavior is
358 unspecified.
359
360 The file may itself contain further include lines. Implementations
361 shall support nesting of include files up to a depth of at least 16.
362
363 Makefile Execution
364 Makefile command lines shall be processed one at a time.
365
366 Makefile command lines can have one or more of the following prefixes:
367 a <hyphen-minus> ('-'), an at-sign ('@'), or a <plus-sign> ('+').
368 These shall modify the way in which make processes the command.
369
370 - If the command prefix contains a <hyphen-minus>, or the -i option
371 is present, or the special target .IGNORE has either the current
372 target as a prerequisite or has no prerequisites, any error found
373 while executing the command shall be ignored.
374
375 @ If the command prefix contains an at-sign and the make utility
376 command line -n option is not specified, or the -s option is
377 present, or the special target .SILENT has either the current
378 target as a prerequisite or has no prerequisites, the command
379 shall not be written to standard output before it is executed.
380
381 + If the command prefix contains a <plus-sign>, this indicates a
382 makefile command line that shall be executed even if -n, -q, or
383 -t is specified.
384
385 An execution line is built from the command line by removing any prefix
386 characters. Except as described under the at-sign prefix, the execution
387 line shall be written to the standard output, optionally preceded by a
388 <tab>. The execution line shall then be executed by a shell as if it
389 were passed as the argument to the system() interface, except that if
390 errors are not being ignored then the shell -e option shall also be in
391 effect. If errors are being ignored for the command (as a result of the
392 -i option, a '-' command prefix, or a .IGNORE special target), the
393 shell -e option shall not be in effect. The environment for the command
394 being executed shall contain all of the variables in the environment of
395 make.
396
397 By default, when make receives a non-zero status from the execution of
398 a command, it shall terminate with an error message to standard error.
399
400 Target Rules
401 Target rules are formatted as follows:
402
403
404 target [target...]: [prerequisite...][;command]
405 [<tab>command
406 <tab>command
407 ...]
408
409 line that does not begin with <tab>
410
411 Target entries are specified by a <blank>-separated, non-null list of
412 targets, then a <colon>, then a <blank>-separated, possibly empty list
413 of prerequisites. Text following a <semicolon>, if any, and all follow‐
414 ing lines that begin with a <tab>, are makefile command lines to be
415 executed to update the target. The first non-empty line that does not
416 begin with a <tab> or '#' shall begin a new entry. Any comment line may
417 begin a new entry.
418
419 Applications shall select target names from the set of characters con‐
420 sisting solely of periods, underscores, digits, and alphabetics from
421 the portable character set (see the Base Definitions volume of
422 POSIX.1‐2017, Section 6.1, Portable Character Set). Implementations
423 may allow other characters in target names as extensions. The interpre‐
424 tation of targets containing the characters '%' and '"' is implementa‐
425 tion-defined.
426
427 A target that has prerequisites, but does not have any commands, can be
428 used to add to the prerequisite list for that target. Only one target
429 rule for any given target can contain commands.
430
431 Lines that begin with one of the following are called special targets
432 and control the operation of make:
433
434 .DEFAULT If the makefile uses this special target, the application
435 shall ensure that it is specified with commands, but without
436 prerequisites. The commands shall be used by make if there
437 are no other rules available to build a target.
438
439 .IGNORE Prerequisites of this special target are targets themselves;
440 this shall cause errors from commands associated with them to
441 be ignored in the same manner as specified by the -i option.
442 Subsequent occurrences of .IGNORE shall add to the list of
443 targets ignoring command errors. If no prerequisites are
444 specified, make shall behave as if the -i option had been
445 specified and errors from all commands associated with all
446 targets shall be ignored.
447
448 .POSIX The application shall ensure that this special target is
449 specified without prerequisites or commands. If it appears as
450 the first non-comment line in the makefile, make shall
451 process the makefile as specified by this section; otherwise,
452 the behavior of make is unspecified.
453
454 .PRECIOUS Prerequisites of this special target shall not be removed if
455 make receives one of the asynchronous events explicitly
456 described in the ASYNCHRONOUS EVENTS section. Subsequent
457 occurrences of .PRECIOUS shall add to the list of precious
458 files. If no prerequisites are specified, all targets in the
459 makefile shall be treated as if specified with .PRECIOUS.
460
461 .SCCS_GET The application shall ensure that this special target is
462 specified without prerequisites. If this special target is
463 included in a makefile, the commands specified with this tar‐
464 get shall replace the default commands associated with this
465 special target (see Default Rules). The commands specified
466 with this target are used to get all SCCS files that are not
467 found in the current directory.
468
469 When source files are named in a dependency list, make shall
470 treat them just like any other target. Because the source
471 file is presumed to be present in the directory, there is no
472 need to add an entry for it to the makefile. When a target
473 has no dependencies, but is present in the directory, make
474 shall assume that that file is up-to-date. If, however, an
475 SCCS file named SCCS/s.source_file is found for a target
476 source_file, make compares the timestamp of the target file
477 with that of the SCCS/s.source_file to ensure the target is
478 up-to-date. If the target is missing, or if the SCCS file is
479 newer, make shall automatically issue the commands specified
480 for the .SCCS_GET special target to retrieve the most recent
481 version. However, if the target is writable by anyone, make
482 shall not retrieve a new version.
483
484 .SILENT Prerequisites of this special target are targets themselves;
485 this shall cause commands associated with them not to be
486 written to the standard output before they are executed. Sub‐
487 sequent occurrences of .SILENT shall add to the list of tar‐
488 gets with silent commands. If no prerequisites are specified,
489 make shall behave as if the -s option had been specified and
490 no commands or touch messages associated with any target
491 shall be written to standard output.
492
493 .SUFFIXES Prerequisites of .SUFFIXES shall be appended to the list of
494 known suffixes and are used in conjunction with the inference
495 rules (see Inference Rules). If .SUFFIXES does not have any
496 prerequisites, the list of known suffixes shall be cleared.
497
498 The special targets .IGNORE, .POSIX, .PRECIOUS, .SILENT, and .SUFFIXES
499 shall be specified without commands.
500
501 Targets with names consisting of a leading <period> followed by the
502 uppercase letters "POSIX" and then any other characters are reserved
503 for future standardization. Targets with names consisting of a leading
504 <period> followed by one or more uppercase letters are reserved for
505 implementation extensions.
506
507 Macros
508 Macro definitions are in the form:
509
510
511 string1 = [string2]
512
513 The macro named string1 is defined as having the value of string2,
514 where string2 is defined as all characters, if any, after the <equals-
515 sign>, up to a comment character ('#') or an unescaped <newline>. Any
516 <blank> characters immediately before or after the <equals-sign> shall
517 be ignored.
518
519 Applications shall select macro names from the set of characters con‐
520 sisting solely of periods, underscores, digits, and alphabetics from
521 the portable character set (see the Base Definitions volume of
522 POSIX.1‐2017, Section 6.1, Portable Character Set). A macro name shall
523 not contain an <equals-sign>. Implementations may allow other charac‐
524 ters in macro names as extensions.
525
526 Macros can appear anywhere in the makefile. Macro expansions using the
527 forms $(string1) or ${string1} shall be replaced by string2, as fol‐
528 lows:
529
530 * Macros in target lines shall be evaluated when the target line is
531 read.
532
533 * Macros in makefile command lines shall be evaluated when the com‐
534 mand is executed.
535
536 * Macros in the string before the <equals-sign> in a macro definition
537 shall be evaluated when the macro assignment is made.
538
539 * Macros after the <equals-sign> in a macro definition shall not be
540 evaluated until the defined macro is used in a rule or command, or
541 before the <equals-sign> in a macro definition.
542
543 The parentheses or braces are optional if string1 is a single charac‐
544 ter. The macro $$ shall be replaced by the single character '$'. If
545 string1 in a macro expansion contains a macro expansion, the results
546 are unspecified.
547
548 Macro expansions using the forms $(string1[:subst1=[subst2]]) or
549 ${string1[:subst1=[subst2]]} can be used to replace all occurrences of
550 subst1 with subst2 when the macro substitution is performed. The subst1
551 to be replaced shall be recognized when it is a suffix at the end of a
552 word in string1 (where a word, in this context, is defined to be a
553 string delimited by the beginning of the line, a <blank>, or a <new‐
554 line>). If string1 in a macro expansion contains a macro expansion,
555 the results are unspecified. If a <percent-sign> character appears as
556 part of subst1 or subst2 after any macros have been recursively
557 expanded, the results are unspecified.
558
559 Macro expansions in string1 of macro definition lines shall be evalu‐
560 ated when read. Macro expansions in string2 of macro definition lines
561 shall be performed when the macro identified by string1 is expanded in
562 a rule or command.
563
564 Macro definitions shall be taken from the following sources, in the
565 following logical order, before the makefile(s) are read.
566
567 1. Macros specified on the make utility command line, in the order
568 specified on the command line. It is unspecified whether the inter‐
569 nal macros defined in Internal Macros are accepted from this
570 source.
571
572 2. Macros defined by the MAKEFLAGS environment variable, in the order
573 specified in the environment variable. It is unspecified whether
574 the internal macros defined in Internal Macros are accepted from
575 this source.
576
577 3. The contents of the environment, excluding the MAKEFLAGS and SHELL
578 variables and including the variables with null values.
579
580 4. Macros defined in the inference rules built into make.
581
582 Macro definitions from these sources shall not override macro defini‐
583 tions from a lower-numbered source. Macro definitions from a single
584 source (for example, the make utility command line, the MAKEFLAGS envi‐
585 ronment variable, or the other environment variables) shall override
586 previous macro definitions from the same source.
587
588 Macros defined in the makefile(s) shall override macro definitions that
589 occur before them in the makefile(s) and macro definitions from source
590 4. If the -e option is not specified, macros defined in the makefile(s)
591 shall override macro definitions from source 3. Macros defined in the
592 makefile(s) shall not override macro definitions from source 1 or
593 source 2.
594
595 Before the makefile(s) are read, all of the make utility command line
596 options (except -f and -p) and make utility command line macro defini‐
597 tions (except any for the MAKEFLAGS macro), not already included in the
598 MAKEFLAGS macro, shall be added to the MAKEFLAGS macro, quoted in an
599 implementation-defined manner such that when MAKEFLAGS is read by
600 another instance of the make command, the original macro's value is
601 recovered. Other implementation-defined options and macros may also be
602 added to the MAKEFLAGS macro. If this modifies the value of the MAKE‐
603 FLAGS macro, or, if the MAKEFLAGS macro is modified at any subsequent
604 time, the MAKEFLAGS environment variable shall be modified to match the
605 new value of the MAKEFLAGS macro. The result of setting MAKEFLAGS in
606 the Makefile is unspecified.
607
608 Before the makefile(s) are read, all of the make utility command line
609 macro definitions (except the MAKEFLAGS macro or the SHELL macro) shall
610 be added to the environment of make. Other implementation-defined
611 variables may also be added to the environment of make. Macros defined
612 by the MAKEFLAGS environment variable and macros defined in the make‐
613 file(s) shall not be added to the environment of make if they are not
614 already in its environment. With the exception of SHELL (see below), it
615 is unspecified whether macros defined in these ways update the value of
616 an environment variable that already exists in the environment of make.
617
618 The SHELL macro shall be treated specially. It shall be provided by
619 make and set to the pathname of the shell command language interpreter
620 (see sh). The SHELL environment variable shall not affect the value of
621 the SHELL macro. If SHELL is defined in the makefile or is specified on
622 the command line, it shall replace the original value of the SHELL
623 macro, but shall not affect the SHELL environment variable. Other
624 effects of defining SHELL in the makefile or on the command line are
625 implementation-defined.
626
627 Inference Rules
628 Inference rules are formatted as follows:
629
630
631 target:
632 <tab>command
633 [<tab>command]
634 ...
635
636 line that does not begin with <tab> or #
637
638 The application shall ensure that the target portion is a valid target
639 name (see Target Rules) of the form .s2 or .s1.s2 (where .s1 and .s2
640 are suffixes that have been given as prerequisites of the .SUFFIXES
641 special target and s1 and s2 do not contain any <slash> or <period>
642 characters.) If there is only one <period> in the target, it is a sin‐
643 gle-suffix inference rule. Targets with two periods are double-suffix
644 inference rules. Inference rules can have only one target before the
645 <colon>.
646
647 The application shall ensure that the makefile does not specify prereq‐
648 uisites for inference rules; no characters other than white space shall
649 follow the <colon> in the first line, except when creating the empty
650 rule, described below. Prerequisites are inferred, as described below.
651
652 Inference rules can be redefined. A target that matches an existing
653 inference rule shall overwrite the old inference rule. An empty rule
654 can be created with a command consisting of simply a <semicolon> (that
655 is, the rule still exists and is found during inference rule search,
656 but since it is empty, execution has no effect). The empty rule can
657 also be formatted as follows:
658
659
660 rule: ;
661
662 where zero or more <blank> characters separate the <colon> and <semi‐
663 colon>.
664
665 The make utility uses the suffixes of targets and their prerequisites
666 to infer how a target can be made up-to-date. A list of inference rules
667 defines the commands to be executed. By default, make contains a built-
668 in set of inference rules. Additional rules can be specified in the
669 makefile.
670
671 The special target .SUFFIXES contains as its prerequisites a list of
672 suffixes that shall be used by the inference rules. The order in which
673 the suffixes are specified defines the order in which the inference
674 rules for the suffixes are used. New suffixes shall be appended to the
675 current list by specifying a .SUFFIXES special target in the makefile.
676 A .SUFFIXES target with no prerequisites shall clear the list of suf‐
677 fixes. An empty .SUFFIXES target followed by a new .SUFFIXES list is
678 required to change the order of the suffixes.
679
680 Normally, the user would provide an inference rule for each suffix.
681 The inference rule to update a target with a suffix .s1 from a prereq‐
682 uisite with a suffix .s2 is specified as a target .s2.s1. The internal
683 macros provide the means to specify general inference rules (see Inter‐
684 nal Macros).
685
686 When no target rule is found to update a target, the inference rules
687 shall be checked. The suffix of the target (.s1) to be built is com‐
688 pared to the list of suffixes specified by the .SUFFIXES special tar‐
689 gets. If the .s1 suffix is found in .SUFFIXES, the inference rules
690 shall be searched in the order defined for the first .s2.s1 rule whose
691 prerequisite file ($*.s2) exists. If the target is out-of-date with
692 respect to this prerequisite, the commands for that inference rule
693 shall be executed.
694
695 If the target to be built does not contain a suffix and there is no
696 rule for the target, the single suffix inference rules shall be
697 checked. The single-suffix inference rules define how to build a target
698 if a file is found with a name that matches the target name with one of
699 the single suffixes appended. A rule with one suffix .s2 is the defini‐
700 tion of how to build target from target.s2. The other suffix (.s1) is
701 treated as null.
702
703 A <tilde> ('~') in the above rules refers to an SCCS file in the cur‐
704 rent directory. Thus, the rule .c~.o would transform an SCCS C-lan‐
705 guage source file into an object file (.o). Because the s. of the
706 SCCS files is a prefix, it is incompatible with make's suffix point of
707 view. Hence, the '~' is a way of changing any file reference into an
708 SCCS file reference.
709
710 Libraries
711 If a target or prerequisite contains parentheses, it shall be treated
712 as a member of an archive library. For the lib(member.o) expression lib
713 refers to the name of the archive library and member.o to the member
714 name. The application shall ensure that the member is an object file
715 with the .o suffix. The modification time of the expression is the mod‐
716 ification time for the member as kept in the archive library; see ar.
717 The .a suffix shall refer to an archive library. The .s2.a rule shall
718 be used to update a member in the library from a file with a suffix
719 .s2.
720
721 Internal Macros
722 The make utility shall maintain five internal macros that can be used
723 in target and inference rules. In order to clearly define the meaning
724 of these macros, some clarification of the terms target rule, inference
725 rule, target, and prerequisite is necessary.
726
727 Target rules are specified by the user in a makefile for a particular
728 target. Inference rules are user-specified or make-specified rules for
729 a particular class of target name. Explicit prerequisites are those
730 prerequisites specified in a makefile on target lines. Implicit pre‐
731 requisites are those prerequisites that are generated when inference
732 rules are used. Inference rules are applied to implicit prerequisites
733 or to explicit prerequisites that do not have target rules defined for
734 them in the makefile. Target rules are applied to targets specified in
735 the makefile.
736
737 Before any target in the makefile is updated, each of its prerequisites
738 (both explicit and implicit) shall be updated. This shall be accom‐
739 plished by recursively processing each prerequisite. Upon recursion,
740 each prerequisite shall become a target itself. Its prerequisites in
741 turn shall be processed recursively until a target is found that has no
742 prerequisites, or further recursion would require applying two infer‐
743 ence rules one immediately after the other, at which point the recur‐
744 sion shall stop. As an extension, implementations may continue recur‐
745 sion when two or more successive inference rules need to be applied;
746 however, if there are multiple different chains of such rules that
747 could be used to create the target, it is unspecified which chain is
748 used. The recursion shall then back up, updating each target as it
749 goes.
750
751 In the definitions that follow, the word target refers to one of:
752
753 * A target specified in the makefile
754
755 * An explicit prerequisite specified in the makefile that becomes the
756 target when make processes it during recursion
757
758 * An implicit prerequisite that becomes a target when make processes
759 it during recursion
760
761 In the definitions that follow, the word prerequisite refers to one of
762 the following:
763
764 * An explicit prerequisite specified in the makefile for a particular
765 target
766
767 * An implicit prerequisite generated as a result of locating an
768 appropriate inference rule and corresponding file that matches the
769 suffix of the target
770
771 The five internal macros are:
772
773 $@ The $@ shall evaluate to the full target name of the current
774 target, or the archive filename part of a library archive tar‐
775 get. It shall be evaluated for both target and inference rules.
776
777 For example, in the .c.a inference rule, $@ represents the out-
778 of-date .a file to be built. Similarly, in a makefile target
779 rule to build lib.a from file.c, $@ represents the out-of-date
780 lib.a.
781
782 $% The $% macro shall be evaluated only when the current target is
783 an archive library member of the form libname(member.o). In
784 these cases, $@ shall evaluate to libname and $% shall evaluate
785 to member.o. The $% macro shall be evaluated for both target
786 and inference rules.
787
788 For example, in a makefile target rule to build lib.a(file.o),
789 $% represents file.o, as opposed to $@, which represents lib.a.
790
791 $? The $? macro shall evaluate to the list of prerequisites that
792 are newer than the current target. It shall be evaluated for
793 both target and inference rules.
794
795 For example, in a makefile target rule to build prog from
796 file1.o, file2.o, and file3.o, and where prog is not out-of-
797 date with respect to file1.o, but is out-of-date with respect
798 to file2.o and file3.o, $? represents file2.o and file3.o.
799
800 $< In an inference rule, the $< macro shall evaluate to the file‐
801 name whose existence allowed the inference rule to be chosen
802 for the target. In the .DEFAULT rule, the $< macro shall eval‐
803 uate to the current target name. The meaning of the $< macro
804 shall be otherwise unspecified.
805
806 For example, in the .c.a inference rule, $< represents the pre‐
807 requisite .c file.
808
809 $* The $* macro shall evaluate to the current target name with its
810 suffix deleted. It shall be evaluated at least for inference
811 rules.
812
813 For example, in the .c.a inference rule, $*.o represents the
814 out-of-date .o file that corresponds to the prerequisite .c
815 file.
816
817 Each of the internal macros has an alternative form. When an uppercase
818 'D' or 'F' is appended to any of the macros, the meaning shall be
819 changed to the directory part for 'D' and filename part for 'F'. The
820 directory part is the path prefix of the file without a trailing
821 <slash>; for the current directory, the directory part is '.'. When
822 the $? macro contains more than one prerequisite filename, the $(?D)
823 and $(?F) (or ${?D} and ${?F}) macros expand to a list of directory
824 name parts and filename parts respectively.
825
826 For the target lib(member.o) and the s2.a rule, the internal macros
827 shall be defined as:
828
829 $< member.s2
830
831 $* member
832
833 $@ lib
834
835 $? member.s2
836
837 $% member.o
838
839 Default Rules
840 The default rules for make shall achieve results that are the same as
841 if the following were used. Implementations that do not support the C-
842 Language Development Utilities option may omit CC, CFLAGS, YACC,
843 YFLAGS, LEX, LFLAGS, LDFLAGS, and the .c, .y, and .l inference rules.
844 Implementations that do not support FORTRAN may omit FC, FFLAGS, and
845 the .f inference rules. Implementations may provide additional macros
846 and rules.
847
848
849 SPECIAL TARGETS
850
851 .SCCS_GET: sccs $(SCCSFLAGS) get $(SCCSGETFLAGS) $@
852
853 .SUFFIXES: .o .c .y .l .a .sh .f .c~ .y~ .l~ .sh~ .f~
854
855 MACROS
856
857 MAKE=make
858 AR=ar
859 ARFLAGS=-rv
860 YACC=yacc
861 YFLAGS=
862 LEX=lex
863 LFLAGS=
864 LDFLAGS=
865 CC=c99
866 CFLAGS=-O 1
867 FC=fort77
868 FFLAGS=-O 1
869 GET=get
870 GFLAGS=
871 SCCSFLAGS=
872 SCCSGETFLAGS=-s
873
874 SINGLE SUFFIX RULES
875
876 .c:
877 $(CC) $(CFLAGS) $(LDFLAGS) -o $@ $<
878
879 .f:
880 $(FC) $(FFLAGS) $(LDFLAGS) -o $@ $<
881
882 .sh:
883 cp $< $@
884 chmod a+x $@
885
886 .c~:
887 $(GET) $(GFLAGS) -p $< > $*.c
888 $(CC) $(CFLAGS) $(LDFLAGS) -o $@ $*.c
889
890 .f~:
891 $(GET) $(GFLAGS) -p $< > $*.f
892 $(FC) $(FFLAGS) $(LDFLAGS) -o $@ $*.f
893
894 .sh~:
895 $(GET) $(GFLAGS) -p $< > $*.sh
896 cp $*.sh $@
897 chmod a+x $@
898
899 DOUBLE SUFFIX RULES
900
901 .c.o:
902 $(CC) $(CFLAGS) -c $<
903
904 .f.o:
905 $(FC) $(FFLAGS) -c $<
906
907 .y.o:
908 $(YACC) $(YFLAGS) $<
909 $(CC) $(CFLAGS) -c y.tab.c
910 rm -f y.tab.c
911 mv y.tab.o $@
912
913 .l.o:
914 $(LEX) $(LFLAGS) $<
915 $(CC) $(CFLAGS) -c lex.yy.c
916 rm -f lex.yy.c
917 mv lex.yy.o $@
918
919 .y.c:
920 $(YACC) $(YFLAGS) $<
921 mv y.tab.c $@
922
923 .l.c:
924 $(LEX) $(LFLAGS) $<
925 mv lex.yy.c $@
926
927 .c~.o:
928 $(GET) $(GFLAGS) -p $< > $*.c
929 $(CC) $(CFLAGS) -c $*.c
930
931 .f~.o:
932 $(GET) $(GFLAGS) -p $< > $*.f
933 $(FC) $(FFLAGS) -c $*.f
934
935 .y~.o:
936 $(GET) $(GFLAGS) -p $< > $*.y
937 $(YACC) $(YFLAGS) $*.y
938 $(CC) $(CFLAGS) -c y.tab.c
939 rm -f y.tab.c
940 mv y.tab.o $@
941
942 .l~.o:
943 $(GET) $(GFLAGS) -p $< > $*.l
944 $(LEX) $(LFLAGS) $*.l
945 $(CC) $(CFLAGS) -c lex.yy.c
946 rm -f lex.yy.c
947 mv lex.yy.o $@
948
949 .y~.c:
950 $(GET) $(GFLAGS) -p $< > $*.y
951 $(YACC) $(YFLAGS) $*.y
952 mv y.tab.c $@
953
954 .l~.c:
955 $(GET) $(GFLAGS) -p $< > $*.l
956 $(LEX) $(LFLAGS) $*.l
957 mv lex.yy.c $@
958
959 .c.a:
960 $(CC) -c $(CFLAGS) $<
961 $(AR) $(ARFLAGS) $@ $*.o
962 rm -f $*.o
963
964 .f.a:
965 $(FC) -c $(FFLAGS) $<
966 $(AR) $(ARFLAGS) $@ $*.o
967 rm -f $*.o
968
970 When the -q option is specified, the make utility shall exit with one
971 of the following values:
972
973 0 Successful completion.
974
975 1 The target was not up-to-date.
976
977 >1 An error occurred.
978
979 When the -q option is not specified, the make utility shall exit with
980 one of the following values:
981
982 0 Successful completion.
983
984 >0 An error occurred.
985
987 Default.
988
989 The following sections are informative.
990
992 If there is a source file (such as ./source.c) and there are two SCCS
993 files corresponding to it (./s.source.c and ./SCCS/s.source.c), on XSI-
994 conformant systems make uses the SCCS file in the current directory.
995 However, users are advised to use the underlying SCCS utilities (admin,
996 delta, get, and so on) or the sccs utility for all source files in a
997 given directory. If both forms are used for a given source file, future
998 developers are very likely to be confused.
999
1000 It is incumbent upon portable makefiles to specify the .POSIX special
1001 target in order to guarantee that they are not affected by local exten‐
1002 sions.
1003
1004 The -k and -S options are both present so that the relationship between
1005 the command line, the MAKEFLAGS variable, and the makefile can be con‐
1006 trolled precisely. If the k flag is passed in MAKEFLAGS and a command
1007 is of the form:
1008
1009
1010 $(MAKE) -S foo
1011
1012 then the default behavior is restored for the child make.
1013
1014 When the -n option is specified, it is always added to MAKEFLAGS. This
1015 allows a recursive make -n target to be used to see all of the action
1016 that would be taken to update target.
1017
1018 Because of widespread historical practice, interpreting a <number-sign>
1019 ('#') inside a variable as the start of a comment has the unfortunate
1020 side-effect of making it impossible to place a <number-sign> in a vari‐
1021 able, thus forbidding something like:
1022
1023
1024 CFLAGS = "-D COMMENT_CHAR='#'"
1025
1026 Many historical make utilities stop chaining together inference rules
1027 when an intermediate target is nonexistent. For example, it might be
1028 possible for a make to determine that both .y.c and .c.o could be used
1029 to convert a .y to a .o. Instead, in this case, make requires the use
1030 of a .y.o rule.
1031
1032 The best way to provide portable makefiles is to include all of the
1033 rules needed in the makefile itself. The rules provided use only fea‐
1034 tures provided by other parts of this volume of POSIX.1‐2017. The
1035 default rules include rules for optional commands in this volume of
1036 POSIX.1‐2017. Only rules pertaining to commands that are provided are
1037 needed in an implementation's default set.
1038
1039 Macros used within other macros are evaluated when the new macro is
1040 used rather than when the new macro is defined. Therefore:
1041
1042
1043 MACRO = value1
1044 NEW = $(MACRO)
1045 MACRO = value2
1046
1047 target:
1048 echo $(NEW)
1049
1050 would produce value2 and not value1 since NEW was not expanded until it
1051 was needed in the echo command line.
1052
1053 Some historical applications have been known to intermix target_name
1054 and macro=name operands on the command line, expecting that all of the
1055 macros are processed before any of the targets are dealt with. Conform‐
1056 ing applications do not do this, although some backwards-compatibility
1057 support may be included in some implementations.
1058
1059 The following characters in filenames may give trouble: '=', ':', '`',
1060 single-quote, and '@'. In include filenames, pattern matching charac‐
1061 ters and '"' should also be avoided, as they may be treated as special
1062 by some implementations.
1063
1064 For inference rules, the description of $< and $? seem similar. How‐
1065 ever, an example shows the minor difference. In a makefile containing:
1066
1067
1068 foo.o: foo.h
1069
1070 if foo.h is newer than foo.o, yet foo.c is older than foo.o, the built-
1071 in rule to make foo.o from foo.c is used, with $< equal to foo.c and $?
1072 equal to foo.h. If foo.c is also newer than foo.o, $< is equal to
1073 foo.c and $? is equal to foo.h foo.c.
1074
1075 As a consequence of the general rules for target updating, a useful
1076 special case is that if a target has no prerequisites and no commands,
1077 and the target of the rule is a nonexistent file, then make acts as if
1078 this target has been updated whenever its rule is run.
1079
1080 Note: This implies that all targets depending on this one will
1081 always have their commands run.
1082
1083 Shell command sequences like make; cp original copy; make may have
1084 problems on filesystems where the timestamp resolution is the minimum
1085 (1 second) required by the standard and where make considers identical
1086 timestamps to be up-to-date. Conversely, rules like copy: origi‐
1087 nal; cp -p original copy will result in redundant work on make imple‐
1088 mentations that consider identical timestamps to be out-of-date.
1089
1090 This standard does not specify precedence between macro definition and
1091 include directives. Thus, the behavior of:
1092
1093
1094 include =foo.mk
1095
1096 is unspecified. To define a variable named include, either the white
1097 space before the <equal-sign> should be removed, or another macro
1098 should be used, as in:
1099
1100
1101 INCLUDE_NAME = include
1102 $(INCLUDE_NAME) =foo.mk
1103
1104 On the other hand, if the intent is to include a file which starts with
1105 an <equal-sign>, either the filename should be changed to ./=foo.mk, or
1106 the makefile should be written as:
1107
1108
1109 INCLUDE_FILE = =foo.mk
1110 include $(INCLUDE_FILE)
1111
1113 1. The following command:
1114
1115
1116 make
1117
1118 makes the first target found in the makefile.
1119
1120 2. The following command:
1121
1122
1123 make junk
1124
1125 makes the target junk.
1126
1127 3. The following makefile says that pgm depends on two files, a.o and
1128 b.o, and that they in turn depend on their corresponding source
1129 files (a.c and b.c), and a common file incl.h:
1130
1131
1132 .POSIX:
1133 pgm: a.o b.o
1134 c99 a.o b.o -o pgm
1135 a.o: incl.h a.c
1136 c99 -c a.c
1137 b.o: incl.h b.c
1138 c99 -c b.c
1139
1140 4. An example for making optimized .o files from .c files is:
1141
1142
1143 .c.o:
1144 c99 -c -O 1 $*.c
1145
1146 or:
1147
1148
1149 .c.o:
1150 c99 -c -O 1 $<
1151
1152 5. The most common use of the archive interface follows. Here, it is
1153 assumed that the source files are all C-language source:
1154
1155
1156 lib: lib(file1.o) lib(file2.o) lib(file3.o)
1157 @echo lib is now up-to-date
1158
1159 The .c.a rule is used to make file1.o, file2.o, and file3.o and
1160 insert them into lib.
1161
1162 The treatment of escaped <newline> characters throughout the make‐
1163 file is historical practice. For example, the inference rule:
1164
1165
1166 .c.o\
1167 :
1168
1169 works, and the macro:
1170
1171
1172 f= bar baz\
1173 biz
1174 a:
1175 echo ==$f==
1176
1177 echoes "==bar baz biz==".
1178
1179 If $? were:
1180
1181
1182 /usr/include/stdio.h /usr/include/unistd.h foo.h
1183
1184 then $(?D) would be:
1185
1186
1187 /usr/include /usr/include .
1188
1189 and $(?F) would be:
1190
1191
1192 stdio.h unistd.h foo.h
1193
1194 6. The contents of the built-in rules can be viewed by running:
1195
1196
1197 make -p -f /dev/null 2>/dev/null
1198
1200 The make utility described in this volume of POSIX.1‐2017 is intended
1201 to provide the means for changing portable source code into executables
1202 that can be run on an POSIX.1‐2008-conforming system. It reflects the
1203 most common features present in System V and BSD makes.
1204
1205 Historically, the make utility has been an especially fertile ground
1206 for vendor and research organization-specific syntax modifications and
1207 extensions. Examples include:
1208
1209 * Syntax supporting parallel execution (such as from various multi-
1210 processor vendors, GNU, and others)
1211
1212 * Additional ``operators'' separating targets and their prerequisites
1213 (System V, BSD, and others)
1214
1215 * Specifying that command lines containing the strings "${MAKE}" and
1216 "$(MAKE)" are executed when the -n option is specified (GNU and
1217 System V)
1218
1219 * Modifications of the meaning of internal macros when referencing
1220 libraries (BSD and others)
1221
1222 * Using a single instance of the shell for all of the command lines
1223 of the target (BSD and others)
1224
1225 * Allowing <space> characters as well as <tab> characters to delimit
1226 command lines (BSD)
1227
1228 * Adding C preprocessor-style ``include'' and ``ifdef'' constructs
1229 (System V, GNU, BSD, and others)
1230
1231 * Remote execution of command lines (Sprite and others)
1232
1233 * Specifying additional special targets (BSD, System V, and most oth‐
1234 ers)
1235
1236 * Specifying an alternate shell to use to process commands.
1237
1238 Additionally, many vendors and research organizations have rethought
1239 the basic concepts of make, creating vastly extended, as well as com‐
1240 pletely new, syntaxes. Each of these versions of make fulfills the
1241 needs of a different community of users; it is unreasonable for this
1242 volume of POSIX.1‐2017 to require behavior that would be incompatible
1243 (and probably inferior) to historical practice for such a community.
1244
1245 In similar circumstances, when the industry has enough sufficiently
1246 incompatible formats as to make them irreconcilable, this volume of
1247 POSIX.1‐2017 has followed one or both of two courses of action. Com‐
1248 mands have been renamed (cksum, echo, and pax) and/or command line
1249 options have been provided to select the desired behavior (grep, od,
1250 and pax).
1251
1252 Because the syntax specified for the make utility is, by and large, a
1253 subset of the syntaxes accepted by almost all versions of make, it was
1254 decided that it would be counter-productive to change the name. And
1255 since the makefile itself is a basic unit of portability, it would not
1256 be completely effective to reserve a new option letter, such as make
1257 -P, to achieve the portable behavior. Therefore, the special target
1258 .POSIX was added to the makefile, allowing users to specify ``stan‐
1259 dard'' behavior. This special target does not preclude extensions in
1260 the make utility, nor does it preclude such extensions being used by
1261 the makefile specifying the target; it does, however, preclude any
1262 extensions from being applied that could alter the behavior of previ‐
1263 ously valid syntax; such extensions must be controlled via command line
1264 options or new special targets. It is incumbent upon portable makefiles
1265 to specify the .POSIX special target in order to guarantee that they
1266 are not affected by local extensions.
1267
1268 The portable version of make described in this reference page is not
1269 intended to be the state-of-the-art software generation tool and, as
1270 such, some newer and more leading-edge features have not been included.
1271 An attempt has been made to describe the portable makefile in a manner
1272 that does not preclude such extensions as long as they do not disturb
1273 the portable behavior described here.
1274
1275 When the -n option is specified, it is always added to MAKEFLAGS. This
1276 allows a recursive make -n target to be used to see all of the action
1277 that would be taken to update target.
1278
1279 The definition of MAKEFLAGS allows both the System V letter string and
1280 the BSD command line formats. The two formats are sufficiently differ‐
1281 ent to allow implementations to support both without ambiguity.
1282
1283 Early proposals stated that an ``unquoted'' <number-sign> was treated
1284 as the start of a comment. The make utility does not pay any attention
1285 to quotes. A <number-sign> starts a comment regardless of its surround‐
1286 ings.
1287
1288 The text about ``other implementation-defined pathnames may also be
1289 tried'' in addition to ./makefile and ./Makefile is to allow such
1290 extensions as SCCS/s.Makefile and other variations. It was made an
1291 implementation-defined requirement (as opposed to unspecified behavior)
1292 to highlight surprising implementations that might select something
1293 unexpected like /etc/Makefile. XSI-conformant systems also try
1294 ./s.makefile, SCCS/s.makefile, ./s.Makefile, and SCCS/s.Makefile.
1295
1296 Early proposals contained the macro NPROC as a means of specifying that
1297 make should use n processes to do the work required. While this feature
1298 is a valuable extension for many systems, it is not common usage and
1299 could require other non-trivial extensions to makefile syntax. This
1300 extension is not required by this volume of POSIX.1‐2017, but could be
1301 provided as a compatible extension. The macro PARALLEL is used by some
1302 historical systems with essentially the same meaning (but without using
1303 a name that is a common system limit value). It is suggested that
1304 implementors recognize the existing use of NPROC and/or PARALLEL as
1305 extensions to make.
1306
1307 The default rules are based on System V. The default CC= value is c99
1308 instead of cc because this volume of POSIX.1‐2017 does not standardize
1309 the utility named cc. Thus, every conforming application would be
1310 required to define CC=c99 to expect to run. There is no advantage con‐
1311 ferred by the hope that the makefile might hit the ``preferred'' com‐
1312 piler because this cannot be guaranteed to work. Also, since the porta‐
1313 ble makescript can only use the c99 options, no advantage is conferred
1314 in terms of what the script can do. It is a quality-of-implementation
1315 issue as to whether c99 is as valuable as cc.
1316
1317 The -d option to make is frequently used to produce debugging informa‐
1318 tion, but is too implementation-defined to add to this volume of
1319 POSIX.1‐2017.
1320
1321 The -p option is not passed in MAKEFLAGS on most historical implementa‐
1322 tions and to change this would cause many implementations to break
1323 without sufficiently increased portability.
1324
1325 Commands that begin with a <plus-sign> ('+') are executed even if the
1326 -n option is present. Based on the GNU version of make, the behavior of
1327 -n when the <plus-sign> prefix is encountered has been extended to
1328 apply to -q and -t as well. However, the System V convention of forcing
1329 command execution with -n when the command line of a target contains
1330 either of the strings "$(MAKE)" or "${MAKE}" has not been adopted. This
1331 functionality appeared in early proposals, but the danger of this
1332 approach was pointed out with the following example of a portion of a
1333 makefile:
1334
1335
1336 subdir:
1337 cd subdir; rm all_the_files; $(MAKE)
1338
1339 The loss of the System V behavior in this case is well-balanced by the
1340 safety afforded to other makefiles that were not aware of this situa‐
1341 tion. In any event, the command line <plus-sign> prefix can provide the
1342 desired functionality.
1343
1344 The double <colon> in the target rule format is supported in BSD sys‐
1345 tems to allow more than one target line containing the same target name
1346 to have commands associated with it. Since this is not functionality
1347 described in the SVID or XPG3 it has been allowed as an extension, but
1348 not mandated.
1349
1350 The default rules are provided with text specifying that the built-in
1351 rules shall be the same as if the listed set were used. The intent is
1352 that implementations should be able to use the rules without change,
1353 but will be allowed to alter them in ways that do not affect the pri‐
1354 mary behavior.
1355
1356 One point of discussion was whether to drop the default rules list from
1357 this volume of POSIX.1‐2017. They provide convenience, but do not
1358 enhance portability of applications. The prime benefit is in portabil‐
1359 ity of users who wish to type make command and have the command build
1360 from a command.c file.
1361
1362 The historical MAKESHELL feature, and related features provided by
1363 other make implementations, were omitted. In some implementations it is
1364 used to let a user override the shell to be used to run make commands.
1365 This was confusing; for a portable make, the shell should be chosen by
1366 the makefile writer. Further, a makefile writer cannot require an
1367 alternate shell to be used and still consider the makefile portable.
1368 While it would be possible to standardize a mechanism for specifying an
1369 alternate shell, existing implementations do not agree on such a mecha‐
1370 nism, and makefile writers can already invoke an alternate shell by
1371 specifying the shell name in the rule for a target; for example:
1372
1373
1374 python -c "foo"
1375
1376 The make utilities in most historical implementations process the pre‐
1377 requisites of a target in left-to-right order, and the makefile format
1378 requires this. It supports the standard idiom used in many makefiles
1379 that produce yacc programs; for example:
1380
1381
1382 foo: y.tab.o lex.o main.o
1383 $(CC) $(CFLAGS) -o $@ t.tab.o lex.o main.o
1384
1385 In this example, if make chose any arbitrary order, the lex.o might not
1386 be made with the correct y.tab.h. Although there may be better ways to
1387 express this relationship, it is widely used historically. Implementa‐
1388 tions that desire to update prerequisites in parallel should require an
1389 explicit extension to make or the makefile format to accomplish it, as
1390 described previously.
1391
1392 The algorithm for determining a new entry for target rules is partially
1393 unspecified. Some historical makes allow comment lines (including blank
1394 and empty lines) within the collection of commands marked by leading
1395 <tab> characters. A conforming makefile must ensure that each command
1396 starts with a <tab>, but implementations are free to ignore comments
1397 without triggering the start of a new entry.
1398
1399 The ASYNCHRONOUS EVENTS section includes having SIGTERM and SIGHUP,
1400 along with the more traditional SIGINT and SIGQUIT, remove the current
1401 target unless directed not to do so. SIGTERM and SIGHUP were added to
1402 parallel other utilities that have historically cleaned up their work
1403 as a result of these signals. When make receives any signal other than
1404 SIGQUIT, it is required to resend itself the signal it received so that
1405 it exits with a status that reflects the signal. The results from
1406 SIGQUIT are partially unspecified because, on systems that create core
1407 files upon receipt of SIGQUIT, the core from make would conflict with a
1408 core file from the command that was running when the SIGQUIT arrived.
1409 The main concern was to prevent damaged files from appearing up-to-date
1410 when make is rerun.
1411
1412 The .PRECIOUS special target was extended to affect all targets glob‐
1413 ally (by specifying no prerequisites). The .IGNORE and .SILENT special
1414 targets were extended to allow prerequisites; it was judged to be more
1415 useful in some cases to be able to turn off errors or echoing for a
1416 list of targets than for the entire makefile. These extensions to make
1417 in System V were made to match historical practice from the BSD make.
1418
1419 Macros are not exported to the environment of commands to be run. This
1420 was never the case in any historical make and would have serious conse‐
1421 quences. The environment is the same as the environment to make except
1422 that MAKEFLAGS and macros defined on the make command line are added,
1423 and except that macros defined by the MAKEFLAGS environment variable
1424 and macros defined in the makefile(s) may update the value of an exist‐
1425 ing environment variable (other than SHELL).
1426
1427 Some implementations do not use system() for all command lines, as
1428 required by the portable makefile format; as a performance enhancement,
1429 they select lines without shell metacharacters for direct execution by
1430 execve(). There is no requirement that system() be used specifically,
1431 but merely that the same results be achieved. The metacharacters typi‐
1432 cally used to bypass the direct execve() execution have been any of:
1433
1434
1435 = | ^ ( ) ; & < > * ? [ ] : $ ` ' " \ \n
1436
1437 The default in some advanced versions of make is to group all the com‐
1438 mand lines for a target and execute them using a single shell invoca‐
1439 tion; the System V method is to pass each line individually to a sepa‐
1440 rate shell. The single-shell method has the advantages in performance
1441 and the lack of a requirement for many continued lines. However, con‐
1442 verting to this newer method has caused portability problems with many
1443 historical makefiles, so the behavior with the POSIX makefile is speci‐
1444 fied to be the same as that of System V. It is suggested that the spe‐
1445 cial target .ONESHELL be used as an implementation extension to achieve
1446 the single-shell grouping for a target or group of targets.
1447
1448 Novice users of make have had difficulty with the historical need to
1449 start commands with a <tab>. Since it is often difficult to discern
1450 differences between <tab> and <space> characters on terminals or
1451 printed listings, confusing bugs can arise. In early proposals, an
1452 attempt was made to correct this problem by allowing leading <blank>
1453 characters instead of <tab> characters. However, implementors reported
1454 many makefiles that failed in subtle ways following this change, and it
1455 is difficult to implement a make that unambiguously can differentiate
1456 between macro and command lines. There is extensive historical prac‐
1457 tice of allowing leading <space> characters before macro definitions.
1458 Forcing macro lines into column 1 would be a significant backwards-com‐
1459 patibility problem for some makefiles. Therefore, historical practice
1460 was restored.
1461
1462 There is substantial variation in the handling of include lines by dif‐
1463 ferent implementations. However, there is enough commonality for the
1464 standard to be able to specify a minimum set of requirements that allow
1465 the feature to be used portably. Known variations have been explicitly
1466 called out as unspecified behavior in the description.
1467
1468 The System V dynamic dependency feature was not included. It would sup‐
1469 port:
1470
1471
1472 cat: $$@.c
1473
1474 that would expand to;
1475
1476
1477 cat: cat.c
1478
1479 This feature exists only in the new version of System V make and, while
1480 useful, is not in wide usage. This means that macros are expanded twice
1481 for prerequisites: once at makefile parse time and once at target
1482 update time.
1483
1484 Consideration was given to adding metarules to the POSIX make. This
1485 would make %.o: %.c the same as .c.o:. This is quite useful and avail‐
1486 able from some vendors, but it would cause too many changes to this
1487 make to support. It would have introduced rule chaining and new substi‐
1488 tution rules. However, the rules for target names have been set to
1489 reserve the '%' and '"' characters. These are traditionally used to
1490 implement metarules and quoting of target names, respectively. Imple‐
1491 mentors are strongly encouraged to use these characters only for these
1492 purposes.
1493
1494 A request was made to extend the suffix delimiter character from a
1495 <period> to any character. The metarules feature in newer makes solves
1496 this problem in a more general way. This volume of POSIX.1‐2017 is
1497 staying with the more conservative historical definition.
1498
1499 The standard output format for the -p option is not described because
1500 it is primarily a debugging option and because the format is not gener‐
1501 ally useful to programs. In historical implementations the output is
1502 not suitable for use in generating makefiles. The -p format has been
1503 variable across historical implementations. Therefore, the definition
1504 of -p was only to provide a consistently named option for obtaining
1505 make script debugging information.
1506
1507 Some historical implementations have not cleared the suffix list with
1508 -r.
1509
1510 Implementations should be aware that some historical applications have
1511 intermixed target_name and macro=value operands on the command line,
1512 expecting that all of the macros are processed before any of the tar‐
1513 gets are dealt with. Conforming applications do not do this, but some
1514 backwards-compatibility support may be warranted.
1515
1516 Empty inference rules are specified with a <semicolon> command rather
1517 than omitting all commands, as described in an early proposal. The lat‐
1518 ter case has no traditional meaning and is reserved for implementation
1519 extensions, such as in GNU make.
1520
1521 Earlier versions of this standard defined comment lines only as lines
1522 with '#' as the first character. Many places then talked about com‐
1523 ments, blank lines, and empty lines; but some places inadvertently only
1524 mentioned comments when blank lines and empty lines had also been
1525 accepted in all known implementations. The standard now defines comment
1526 lines to be blank lines, empty lines, and lines starting with a '#'
1527 character and explictily lists cases where blank lines and empty lines
1528 are not acceptable.
1529
1530 On most historic systems, the make utility considered a target with a
1531 prerequisite that had an identical timestamp as up-to-date. The HP-UX
1532 implementation of make treated it as out-of-date. The standard now
1533 allows either behavior, but implementations are encouraged to follow
1534 the example set by HP-UX. This is especially important on file systems
1535 where the timestamp resolution is the minimum (1 second) required by
1536 the standard. All implementations of make should make full use of the
1537 finest timestamp resolution available on the file systems holding tar‐
1538 gets and prerequisites to ensure that targets are up-to-date even for
1539 prerequisite files with timestamps that were updated within the same
1540 second. However, if the timestamp resolutions of the file systems con‐
1541 taining a target and a prerequisite are different, the timestamp with
1542 the more precise resolution should be rounded down to the resolution of
1543 the less precise timestamp for the comparison.
1544
1546 Some implementations of make include an export directive to add speci‐
1547 fied make variables to the environment. This may be considered for
1548 standardization in a future version.
1549
1550 A future version of this standard may require that macro expansions
1551 using the forms $(string1:[op]%[os]=[np][%][ns]) or
1552 ${string1:[op]%[os]=[np][%][ns]} are treated as pattern macro expan‐
1553 sions.
1554
1556 Chapter 2, Shell Command Language, ar, c99, get, lex, sccs, sh, yacc
1557
1558 The Base Definitions volume of POSIX.1‐2017, Section 6.1, Portable
1559 Character Set, Chapter 8, Environment Variables, Section 12.2, Utility
1560 Syntax Guidelines
1561
1562 The System Interfaces volume of POSIX.1‐2017, exec, system()
1563
1565 Portions of this text are reprinted and reproduced in electronic form
1566 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
1567 table Operating System Interface (POSIX), The Open Group Base Specifi‐
1568 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
1569 Electrical and Electronics Engineers, Inc and The Open Group. In the
1570 event of any discrepancy between this version and the original IEEE and
1571 The Open Group Standard, the original IEEE and The Open Group Standard
1572 is the referee document. The original Standard can be obtained online
1573 at http://www.opengroup.org/unix/online.html .
1574
1575 Any typographical or formatting errors that appear in this page are
1576 most likely to have been introduced during the conversion of the source
1577 files to man page format. To report such errors, see https://www.ker‐
1578 nel.org/doc/man-pages/reporting_bugs.html .
1579
1580
1581
1582IEEE/The Open Group 2017 MAKE(1P)