1.\" $NetBSD: make.1,v 1.263 2016/08/26 23:37:54 dholland Exp $ 2.\" 3.\" Copyright (c) 1990, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" from: @(#)make.1 8.4 (Berkeley) 3/19/94 31.\" 32.Dd August 26, 2016 33.Dt MAKE 1 34.Os 35.Sh NAME 36.Nm make 37.Nd maintain program dependencies 38.Sh SYNOPSIS 39.Nm 40.Op Fl BeikNnqrstWwX 41.Op Fl C Ar directory 42.Op Fl D Ar variable 43.Op Fl d Ar flags 44.Op Fl f Ar makefile 45.Op Fl I Ar directory 46.Op Fl J Ar private 47.Op Fl j Ar max_jobs 48.Op Fl m Ar directory 49.Op Fl T Ar file 50.Op Fl V Ar variable 51.Op Ar variable=value 52.Op Ar target ... 53.Sh DESCRIPTION 54.Nm 55is a program designed to simplify the maintenance of other programs. 56Its input is a list of specifications as to the files upon which programs 57and other files depend. 58If no 59.Fl f Ar makefile 60makefile option is given, 61.Nm 62will try to open 63.Ql Pa makefile 64then 65.Ql Pa Makefile 66in order to find the specifications. 67If the file 68.Ql Pa .depend 69exists, it is read (see 70.Xr mkdep 1 ) . 71.Pp 72This manual page is intended as a reference document only. 73For a more thorough description of 74.Nm 75and makefiles, please refer to 76.%T "PMake \- A Tutorial" . 77.Pp 78.Nm 79will prepend the contents of the 80.Va MAKEFLAGS 81environment variable to the command line arguments before parsing them. 82.Pp 83The options are as follows: 84.Bl -tag -width Ds 85.It Fl B 86Try to be backwards compatible by executing a single shell per command and 87by executing the commands to make the sources of a dependency line in sequence. 88.It Fl C Ar directory 89Change to 90.Ar directory 91before reading the makefiles or doing anything else. 92If multiple 93.Fl C 94options are specified, each is interpreted relative to the previous one: 95.Fl C Pa / Fl C Pa etc 96is equivalent to 97.Fl C Pa /etc . 98.It Fl D Ar variable 99Define 100.Ar variable 101to be 1, in the global context. 102.It Fl d Ar [-]flags 103Turn on debugging, and specify which portions of 104.Nm 105are to print debugging information. 106Unless the flags are preceded by 107.Ql \- 108they are added to the 109.Va MAKEFLAGS 110environment variable and will be processed by any child make processes. 111By default, debugging information is printed to standard error, 112but this can be changed using the 113.Ar F 114debugging flag. 115The debugging output is always unbuffered; in addition, if debugging 116is enabled but debugging output is not directed to standard output, 117then the standard output is line buffered. 118.Ar Flags 119is one or more of the following: 120.Bl -tag -width Ds 121.It Ar A 122Print all possible debugging information; 123equivalent to specifying all of the debugging flags. 124.It Ar a 125Print debugging information about archive searching and caching. 126.It Ar C 127Print debugging information about current working directory. 128.It Ar c 129Print debugging information about conditional evaluation. 130.It Ar d 131Print debugging information about directory searching and caching. 132.It Ar e 133Print debugging information about failed commands and targets. 134.It Ar F Ns Oo Sy \&+ Oc Ns Ar filename 135Specify where debugging output is written. 136This must be the last flag, because it consumes the remainder of 137the argument. 138If the character immediately after the 139.Ql F 140flag is 141.Ql \&+ , 142then the file will be opened in append mode; 143otherwise the file will be overwritten. 144If the file name is 145.Ql stdout 146or 147.Ql stderr 148then debugging output will be written to the 149standard output or standard error output file descriptors respectively 150(and the 151.Ql \&+ 152option has no effect). 153Otherwise, the output will be written to the named file. 154If the file name ends 155.Ql .%d 156then the 157.Ql %d 158is replaced by the pid. 159.It Ar f 160Print debugging information about loop evaluation. 161.It Ar "g1" 162Print the input graph before making anything. 163.It Ar "g2" 164Print the input graph after making everything, or before exiting 165on error. 166.It Ar "g3" 167Print the input graph before exiting on error. 168.It Ar j 169Print debugging information about running multiple shells. 170.It Ar l 171Print commands in Makefiles regardless of whether or not they are prefixed by 172.Ql @ 173or other "quiet" flags. 174Also known as "loud" behavior. 175.It Ar M 176Print debugging information about "meta" mode decisions about targets. 177.It Ar m 178Print debugging information about making targets, including modification 179dates. 180.It Ar n 181Don't delete the temporary command scripts created when running commands. 182These temporary scripts are created in the directory 183referred to by the 184.Ev TMPDIR 185environment variable, or in 186.Pa /tmp 187if 188.Ev TMPDIR 189is unset or set to the empty string. 190The temporary scripts are created by 191.Xr mkstemp 3 , 192and have names of the form 193.Pa makeXXXXXX . 194.Em NOTE : 195This can create many files in 196.Ev TMPDIR 197or 198.Pa /tmp , 199so use with care. 200.It Ar p 201Print debugging information about makefile parsing. 202.It Ar s 203Print debugging information about suffix-transformation rules. 204.It Ar t 205Print debugging information about target list maintenance. 206.It Ar V 207Force the 208.Fl V 209option to print raw values of variables. 210.It Ar v 211Print debugging information about variable assignment. 212.It Ar x 213Run shell commands with 214.Fl x 215so the actual commands are printed as they are executed. 216.El 217.It Fl e 218Specify that environment variables override macro assignments within 219makefiles. 220.It Fl f Ar makefile 221Specify a makefile to read instead of the default 222.Ql Pa makefile . 223If 224.Ar makefile 225is 226.Ql Fl , 227standard input is read. 228Multiple makefiles may be specified, and are read in the order specified. 229.It Fl I Ar directory 230Specify a directory in which to search for makefiles and included makefiles. 231The system makefile directory (or directories, see the 232.Fl m 233option) is automatically included as part of this list. 234.It Fl i 235Ignore non-zero exit of shell commands in the makefile. 236Equivalent to specifying 237.Ql Fl 238before each command line in the makefile. 239.It Fl J Ar private 240This option should 241.Em not 242be specified by the user. 243.Pp 244When the 245.Ar j 246option is in use in a recursive build, this option is passed by a make 247to child makes to allow all the make processes in the build to 248cooperate to avoid overloading the system. 249.It Fl j Ar max_jobs 250Specify the maximum number of jobs that 251.Nm 252may have running at any one time. 253The value is saved in 254.Va .MAKE.JOBS . 255Turns compatibility mode off, unless the 256.Ar B 257flag is also specified. 258When compatibility mode is off, all commands associated with a 259target are executed in a single shell invocation as opposed to the 260traditional one shell invocation per line. 261This can break traditional scripts which change directories on each 262command invocation and then expect to start with a fresh environment 263on the next line. 264It is more efficient to correct the scripts rather than turn backwards 265compatibility on. 266.It Fl k 267Continue processing after errors are encountered, but only on those targets 268that do not depend on the target whose creation caused the error. 269.It Fl m Ar directory 270Specify a directory in which to search for sys.mk and makefiles included 271via the 272.Ao Ar file Ac Ns -style 273include statement. 274The 275.Fl m 276option can be used multiple times to form a search path. 277This path will override the default system include path: /usr/share/mk. 278Furthermore the system include path will be appended to the search path used 279for 280.Qo Ar file Qc Ns -style 281include statements (see the 282.Fl I 283option). 284.Pp 285If a file or directory name in the 286.Fl m 287argument (or the 288.Ev MAKESYSPATH 289environment variable) starts with the string 290.Qq \&.../ 291then 292.Nm 293will search for the specified file or directory named in the remaining part 294of the argument string. 295The search starts with the current directory of 296the Makefile and then works upward towards the root of the file system. 297If the search is successful, then the resulting directory replaces the 298.Qq \&.../ 299specification in the 300.Fl m 301argument. 302If used, this feature allows 303.Nm 304to easily search in the current source tree for customized sys.mk files 305(e.g., by using 306.Qq \&.../mk/sys.mk 307as an argument). 308.It Fl n 309Display the commands that would have been executed, but do not 310actually execute them unless the target depends on the .MAKE special 311source (see below). 312.It Fl N 313Display the commands which would have been executed, but do not 314actually execute any of them; useful for debugging top-level makefiles 315without descending into subdirectories. 316.It Fl q 317Do not execute any commands, but exit 0 if the specified targets are 318up-to-date and 1, otherwise. 319.It Fl r 320Do not use the built-in rules specified in the system makefile. 321.It Fl s 322Do not echo any commands as they are executed. 323Equivalent to specifying 324.Ql Ic @ 325before each command line in the makefile. 326.It Fl T Ar tracefile 327When used with the 328.Fl j 329flag, 330append a trace record to 331.Ar tracefile 332for each job started and completed. 333.It Fl t 334Rather than re-building a target as specified in the makefile, create it 335or update its modification time to make it appear up-to-date. 336.It Fl V Ar variable 337Print 338.Nm Ns 's 339idea of the value of 340.Ar variable , 341in the global context. 342Do not build any targets. 343Multiple instances of this option may be specified; 344the variables will be printed one per line, 345with a blank line for each null or undefined variable. 346If 347.Ar variable 348contains a 349.Ql \&$ 350then the value will be expanded before printing. 351.It Fl W 352Treat any warnings during makefile parsing as errors. 353.It Fl w 354Print entering and leaving directory messages, pre and post processing. 355.It Fl X 356Don't export variables passed on the command line to the environment 357individually. 358Variables passed on the command line are still exported 359via the 360.Va MAKEFLAGS 361environment variable. 362This option may be useful on systems which have a small limit on the 363size of command arguments. 364.It Ar variable=value 365Set the value of the variable 366.Ar variable 367to 368.Ar value . 369Normally, all values passed on the command line are also exported to 370sub-makes in the environment. 371The 372.Fl X 373flag disables this behavior. 374Variable assignments should follow options for POSIX compatibility 375but no ordering is enforced. 376.El 377.Pp 378There are seven different types of lines in a makefile: file dependency 379specifications, shell commands, variable assignments, include statements, 380conditional directives, for loops, and comments. 381.Pp 382In general, lines may be continued from one line to the next by ending 383them with a backslash 384.Pq Ql \e . 385The trailing newline character and initial whitespace on the following 386line are compressed into a single space. 387.Sh FILE DEPENDENCY SPECIFICATIONS 388Dependency lines consist of one or more targets, an operator, and zero 389or more sources. 390This creates a relationship where the targets 391.Dq depend 392on the sources 393and are usually created from them. 394The exact relationship between the target and the source is determined 395by the operator that separates them. 396The three operators are as follows: 397.Bl -tag -width flag 398.It Ic \&: 399A target is considered out-of-date if its modification time is less than 400those of any of its sources. 401Sources for a target accumulate over dependency lines when this operator 402is used. 403The target is removed if 404.Nm 405is interrupted. 406.It Ic \&! 407Targets are always re-created, but not until all sources have been 408examined and re-created as necessary. 409Sources for a target accumulate over dependency lines when this operator 410is used. 411The target is removed if 412.Nm 413is interrupted. 414.It Ic \&:: 415If no sources are specified, the target is always re-created. 416Otherwise, a target is considered out-of-date if any of its sources has 417been modified more recently than the target. 418Sources for a target do not accumulate over dependency lines when this 419operator is used. 420The target will not be removed if 421.Nm 422is interrupted. 423.El 424.Pp 425Targets and sources may contain the shell wildcard values 426.Ql \&? , 427.Ql * , 428.Ql [] , 429and 430.Ql {} . 431The values 432.Ql \&? , 433.Ql * , 434and 435.Ql [] 436may only be used as part of the final 437component of the target or source, and must be used to describe existing 438files. 439The value 440.Ql {} 441need not necessarily be used to describe existing files. 442Expansion is in directory order, not alphabetically as done in the shell. 443.Sh SHELL COMMANDS 444Each target may have associated with it one or more lines of shell 445commands, normally 446used to create the target. 447Each of the lines in this script 448.Em must 449be preceded by a tab. 450(For historical reasons, spaces are not accepted.) 451While targets can appear in many dependency lines if desired, by 452default only one of these rules may be followed by a creation 453script. 454If the 455.Ql Ic \&:: 456operator is used, however, all rules may include scripts and the 457scripts are executed in the order found. 458.Pp 459Each line is treated as a separate shell command, unless the end of 460line is escaped with a backslash 461.Pq Ql \e 462in which case that line and the next are combined. 463.\" The escaped newline is retained and passed to the shell, which 464.\" normally ignores it. 465.\" However, the tab at the beginning of the following line is removed. 466If the first characters of the command are any combination of 467.Ql Ic @ , 468.Ql Ic + , 469or 470.Ql Ic \- , 471the command is treated specially. 472A 473.Ql Ic @ 474causes the command not to be echoed before it is executed. 475A 476.Ql Ic + 477causes the command to be executed even when 478.Fl n 479is given. 480This is similar to the effect of the .MAKE special source, 481except that the effect can be limited to a single line of a script. 482A 483.Ql Ic \- 484in compatibility mode 485causes any non-zero exit status of the command line to be ignored. 486.Pp 487When 488.Nm 489is run in jobs mode with 490.Fl j Ar max_jobs , 491the entire script for the target is fed to a 492single instance of the shell. 493In compatibility (non-jobs) mode, each command is run in a separate process. 494If the command contains any shell meta characters 495.Pq Ql #=|^(){};&<>*?[]:$`\e\en 496it will be passed to the shell; otherwise 497.Nm 498will attempt direct execution. 499If a line starts with 500.Ql Ic \- 501and the shell has ErrCtl enabled then failure of the command line 502will be ignored as in compatibility mode. 503Otherwise 504.Ql Ic \- 505affects the entire job; 506the script will stop at the first command line that fails, 507but the target will not be deemed to have failed. 508.Pp 509Makefiles should be written so that the mode of 510.Nm 511operation does not change their behavior. 512For example, any command which needs to use 513.Dq cd 514or 515.Dq chdir 516without potentially changing the directory for subsequent commands 517should be put in parentheses so it executes in a subshell. 518To force the use of one shell, escape the line breaks so as to make 519the whole script one command. 520For example: 521.Bd -literal -offset indent 522avoid-chdir-side-effects: 523 @echo Building $@ in `pwd` 524 @(cd ${.CURDIR} && ${MAKE} $@) 525 @echo Back in `pwd` 526 527ensure-one-shell-regardless-of-mode: 528 @echo Building $@ in `pwd`; \e 529 (cd ${.CURDIR} && ${MAKE} $@); \e 530 echo Back in `pwd` 531.Ed 532.Pp 533Since 534.Nm 535will 536.Xr chdir 2 537to 538.Ql Va .OBJDIR 539before executing any targets, each child process 540starts with that as its current working directory. 541.Sh VARIABLE ASSIGNMENTS 542Variables in make are much like variables in the shell, and, by tradition, 543consist of all upper-case letters. 544.Ss Variable assignment modifiers 545The five operators that can be used to assign values to variables are as 546follows: 547.Bl -tag -width Ds 548.It Ic \&= 549Assign the value to the variable. 550Any previous value is overridden. 551.It Ic \&+= 552Append the value to the current value of the variable. 553.It Ic \&?= 554Assign the value to the variable if it is not already defined. 555.It Ic \&:= 556Assign with expansion, i.e. expand the value before assigning it 557to the variable. 558Normally, expansion is not done until the variable is referenced. 559.Em NOTE : 560References to undefined variables are 561.Em not 562expanded. 563This can cause problems when variable modifiers are used. 564.It Ic \&!= 565Expand the value and pass it to the shell for execution and assign 566the result to the variable. 567Any newlines in the result are replaced with spaces. 568.El 569.Pp 570Any white-space before the assigned 571.Ar value 572is removed; if the value is being appended, a single space is inserted 573between the previous contents of the variable and the appended value. 574.Pp 575Variables are expanded by surrounding the variable name with either 576curly braces 577.Pq Ql {} 578or parentheses 579.Pq Ql () 580and preceding it with 581a dollar sign 582.Pq Ql \&$ . 583If the variable name contains only a single letter, the surrounding 584braces or parentheses are not required. 585This shorter form is not recommended. 586.Pp 587If the variable name contains a dollar, then the name itself is expanded first. 588This allows almost arbitrary variable names, however names containing dollar, 589braces, parenthesis, or whitespace are really best avoided! 590.Pp 591If the result of expanding a variable contains a dollar sign 592.Pq Ql \&$ 593the string is expanded again. 594.Pp 595Variable substitution occurs at three distinct times, depending on where 596the variable is being used. 597.Bl -enum 598.It 599Variables in dependency lines are expanded as the line is read. 600.It 601Variables in shell commands are expanded when the shell command is 602executed. 603.It 604.Dq .for 605loop index variables are expanded on each loop iteration. 606Note that other variables are not expanded inside loops so 607the following example code: 608.Bd -literal -offset indent 609 610.Dv .for i in 1 2 3 611a+= ${i} 612j= ${i} 613b+= ${j} 614.Dv .endfor 615 616all: 617 @echo ${a} 618 @echo ${b} 619 620.Ed 621will print: 622.Bd -literal -offset indent 6231 2 3 6243 3 3 625 626.Ed 627Because while ${a} contains 628.Dq 1 2 3 629after the loop is executed, ${b} 630contains 631.Dq ${j} ${j} ${j} 632which expands to 633.Dq 3 3 3 634since after the loop completes ${j} contains 635.Dq 3 . 636.El 637.Ss Variable classes 638The four different classes of variables (in order of increasing precedence) 639are: 640.Bl -tag -width Ds 641.It Environment variables 642Variables defined as part of 643.Nm Ns 's 644environment. 645.It Global variables 646Variables defined in the makefile or in included makefiles. 647.It Command line variables 648Variables defined as part of the command line. 649.It Local variables 650Variables that are defined specific to a certain target. 651.El 652.Pp 653Local variables are all built in and their values vary magically from 654target to target. 655It is not currently possible to define new local variables. 656The seven local variables are as follows: 657.Bl -tag -width ".ARCHIVE" -offset indent 658.It Va .ALLSRC 659The list of all sources for this target; also known as 660.Ql Va \&\*[Gt] . 661.It Va .ARCHIVE 662The name of the archive file; also known as 663.Ql Va \&! . 664.It Va .IMPSRC 665In suffix-transformation rules, the name/path of the source from which the 666target is to be transformed (the 667.Dq implied 668source); also known as 669.Ql Va \&\*[Lt] . 670It is not defined in explicit rules. 671.It Va .MEMBER 672The name of the archive member; also known as 673.Ql Va % . 674.It Va .OODATE 675The list of sources for this target that were deemed out-of-date; also 676known as 677.Ql Va \&? . 678.It Va .PREFIX 679The file prefix of the target, containing only the file portion, no suffix 680or preceding directory components; also known as 681.Ql Va * . 682The suffix must be one of the known suffixes declared with 683.Ic .SUFFIXES 684or it will not be recognized. 685.It Va .TARGET 686The name of the target; also known as 687.Ql Va @ . 688For compatibility with other makes this is an alias for 689.Ic .ARCHIVE 690in archive member rules. 691.El 692.Pp 693The shorter forms 694.Ql ( Va \*[Gt] , 695.Ql Va \&! , 696.Ql Va \*[Lt] , 697.Ql Va % , 698.Ql Va \&? , 699.Ql Va * , 700and 701.Ql Va @ ) 702are permitted for backward 703compatibility with historical makefiles and legacy POSIX make and are 704not recommended. 705.Pp 706Variants of these variables with the punctuation followed immediately by 707.Ql D 708or 709.Ql F , 710e.g. 711.Ql Va $(@D) , 712are legacy forms equivalent to using the 713.Ql :H 714and 715.Ql :T 716modifiers. 717These forms are accepted for compatibility with 718.At V 719makefiles and POSIX but are not recommended. 720.Pp 721Four of the local variables may be used in sources on dependency lines 722because they expand to the proper value for each target on the line. 723These variables are 724.Ql Va .TARGET , 725.Ql Va .PREFIX , 726.Ql Va .ARCHIVE , 727and 728.Ql Va .MEMBER . 729.Ss Additional built-in variables 730In addition, 731.Nm 732sets or knows about the following variables: 733.Bl -tag -width .MAKEOVERRIDES 734.It Va \&$ 735A single dollar sign 736.Ql \&$ , 737i.e. 738.Ql \&$$ 739expands to a single dollar 740sign. 741.It Va .ALLTARGETS 742The list of all targets encountered in the Makefile. 743If evaluated during 744Makefile parsing, lists only those targets encountered thus far. 745.It Va .CURDIR 746A path to the directory where 747.Nm 748was executed. 749Refer to the description of 750.Ql Ev PWD 751for more details. 752.It Va .INCLUDEDFROMDIR 753The directory of the file this Makefile was included from. 754.It Va .INCLUDEDFROMFILE 755The filename of the file this Makefile was included from. 756.It Ev MAKE 757The name that 758.Nm 759was executed with 760.Pq Va argv[0] . 761For compatibility 762.Nm 763also sets 764.Va .MAKE 765with the same value. 766The preferred variable to use is the environment variable 767.Ev MAKE 768because it is more compatible with other versions of 769.Nm 770and cannot be confused with the special target with the same name. 771.It Va .MAKE.DEPENDFILE 772Names the makefile (default 773.Ql Pa .depend ) 774from which generated dependencies are read. 775.It Va .MAKE.EXPAND_VARIABLES 776A boolean that controls the default behavior of the 777.Fl V 778option. 779.It Va .MAKE.EXPORTED 780The list of variables exported by 781.Nm . 782.It Va .MAKE.JOBS 783The argument to the 784.Fl j 785option. 786.It Va .MAKE.JOB.PREFIX 787If 788.Nm 789is run with 790.Ar j 791then output for each target is prefixed with a token 792.Ql --- target --- 793the first part of which can be controlled via 794.Va .MAKE.JOB.PREFIX . 795If 796.Va .MAKE.JOB.PREFIX 797is empty, no token is printed. 798.br 799For example: 800.Li .MAKE.JOB.PREFIX=${.newline}---${.MAKE:T}[${.MAKE.PID}] 801would produce tokens like 802.Ql ---make[1234] target --- 803making it easier to track the degree of parallelism being achieved. 804.It Ev MAKEFLAGS 805The environment variable 806.Ql Ev MAKEFLAGS 807may contain anything that 808may be specified on 809.Nm Ns 's 810command line. 811Anything specified on 812.Nm Ns 's 813command line is appended to the 814.Ql Ev MAKEFLAGS 815variable which is then 816entered into the environment for all programs which 817.Nm 818executes. 819.It Va .MAKE.LEVEL 820The recursion depth of 821.Nm . 822The initial instance of 823.Nm 824will be 0, and an incremented value is put into the environment 825to be seen by the next generation. 826This allows tests like: 827.Li .if ${.MAKE.LEVEL} == 0 828to protect things which should only be evaluated in the initial instance of 829.Nm . 830.It Va .MAKE.MAKEFILE_PREFERENCE 831The ordered list of makefile names 832(default 833.Ql Pa makefile , 834.Ql Pa Makefile ) 835that 836.Nm 837will look for. 838.It Va .MAKE.MAKEFILES 839The list of makefiles read by 840.Nm , 841which is useful for tracking dependencies. 842Each makefile is recorded only once, regardless of the number of times read. 843.It Va .MAKE.MODE 844Processed after reading all makefiles. 845Can affect the mode that 846.Nm 847runs in. 848It can contain a number of keywords: 849.Bl -hang -width missing-filemon=bf. 850.It Pa compat 851Like 852.Fl B , 853puts 854.Nm 855into "compat" mode. 856.It Pa meta 857Puts 858.Nm 859into "meta" mode, where meta files are created for each target 860to capture the command run, the output generated and if 861.Xr filemon 4 862is available, the system calls which are of interest to 863.Nm . 864The captured output can be very useful when diagnosing errors. 865.It Pa curdirOk= Ar bf 866Normally 867.Nm 868will not create .meta files in 869.Ql Va .CURDIR . 870This can be overridden by setting 871.Va bf 872to a value which represents True. 873.It Pa missing-meta= Ar bf 874If 875.Va bf 876is True, then a missing .meta file makes the target out-of-date. 877.It Pa missing-filemon= Ar bf 878If 879.Va bf 880is True, then missing filemon data makes the target out-of-date. 881.It Pa nofilemon 882Do not use 883.Xr filemon 4 . 884.It Pa env 885For debugging, it can be useful to include the environment 886in the .meta file. 887.It Pa verbose 888If in "meta" mode, print a clue about the target being built. 889This is useful if the build is otherwise running silently. 890The message printed the value of: 891.Va .MAKE.META.PREFIX . 892.It Pa ignore-cmd 893Some makefiles have commands which are simply not stable. 894This keyword causes them to be ignored for 895determining whether a target is out of date in "meta" mode. 896See also 897.Ic .NOMETA_CMP . 898.It Pa silent= Ar bf 899If 900.Va bf 901is True, when a .meta file is created, mark the target 902.Ic .SILENT . 903.El 904.It Va .MAKE.META.BAILIWICK 905In "meta" mode, provides a list of prefixes which 906match the directories controlled by 907.Nm . 908If a file that was generated outside of 909.Va .OBJDIR 910but within said bailiwick is missing, 911the current target is considered out-of-date. 912.It Va .MAKE.META.CREATED 913In "meta" mode, this variable contains a list of all the meta files 914updated. 915If not empty, it can be used to trigger processing of 916.Va .MAKE.META.FILES . 917.It Va .MAKE.META.FILES 918In "meta" mode, this variable contains a list of all the meta files 919used (updated or not). 920This list can be used to process the meta files to extract dependency 921information. 922.It Va .MAKE.META.IGNORE_PATHS 923Provides a list of path prefixes that should be ignored; 924because the contents are expected to change over time. 925The default list includes: 926.Ql Pa /dev /etc /proc /tmp /var/run /var/tmp 927.It Va .MAKE.META.IGNORE_PATTERNS 928Provides a list of patterns to match against pathnames. 929Ignore any that match. 930.It Va .MAKE.META.IGNORE_FILTER 931Provides a list of variable modifiers to apply to each pathname. 932Ignore if the expansion is an empty string. 933.It Va .MAKE.META.PREFIX 934Defines the message printed for each meta file updated in "meta verbose" mode. 935The default value is: 936.Dl Building ${.TARGET:H:tA}/${.TARGET:T} 937.It Va .MAKEOVERRIDES 938This variable is used to record the names of variables assigned to 939on the command line, so that they may be exported as part of 940.Ql Ev MAKEFLAGS . 941This behavior can be disabled by assigning an empty value to 942.Ql Va .MAKEOVERRIDES 943within a makefile. 944Extra variables can be exported from a makefile 945by appending their names to 946.Ql Va .MAKEOVERRIDES . 947.Ql Ev MAKEFLAGS 948is re-exported whenever 949.Ql Va .MAKEOVERRIDES 950is modified. 951.It Va .MAKE.PATH_FILEMON 952If 953.Nm 954was built with 955.Xr filemon 4 956support, this is set to the path of the device node. 957This allows makefiles to test for this support. 958.It Va .MAKE.PID 959The process-id of 960.Nm . 961.It Va .MAKE.PPID 962The parent process-id of 963.Nm . 964.It Va .MAKE.SAVE_DOLLARS 965value should be a boolean that controls whether 966.Ql $$ 967are preserved when doing 968.Ql := 969assignments. 970The default is true, for compatibility with other makes. 971If set to false, 972.Ql $$ 973becomes 974.Ql $ 975per normal evaluation rules. 976.It Va MAKE_PRINT_VAR_ON_ERROR 977When 978.Nm 979stops due to an error, it sets 980.Ql Va .ERROR_TARGET 981to the name of the target that failed, 982.Ql Va .ERROR_CMD 983to the commands of the failed target, 984and in "meta" mode, it also sets 985.Ql Va .ERROR_CWD 986to the 987.Xr getcwd 3 , 988and 989.Ql Va .ERROR_META_FILE 990to the path of the meta file (if any) describing the failed target. 991It then prints its name and the value of 992.Ql Va .CURDIR 993as well as the value of any variables named in 994.Ql Va MAKE_PRINT_VAR_ON_ERROR . 995.It Va .newline 996This variable is simply assigned a newline character as its value. 997This allows expansions using the 998.Cm \&:@ 999modifier to put a newline between 1000iterations of the loop rather than a space. 1001For example, the printing of 1002.Ql Va MAKE_PRINT_VAR_ON_ERROR 1003could be done as ${MAKE_PRINT_VAR_ON_ERROR:@v@$v='${$v}'${.newline}@}. 1004.It Va .OBJDIR 1005A path to the directory where the targets are built. 1006Its value is determined by trying to 1007.Xr chdir 2 1008to the following directories in order and using the first match: 1009.Bl -enum 1010.It 1011.Ev ${MAKEOBJDIRPREFIX}${.CURDIR} 1012.Pp 1013(Only if 1014.Ql Ev MAKEOBJDIRPREFIX 1015is set in the environment or on the command line.) 1016.It 1017.Ev ${MAKEOBJDIR} 1018.Pp 1019(Only if 1020.Ql Ev MAKEOBJDIR 1021is set in the environment or on the command line.) 1022.It 1023.Ev ${.CURDIR} Ns Pa /obj. Ns Ev ${MACHINE} 1024.It 1025.Ev ${.CURDIR} Ns Pa /obj 1026.It 1027.Pa /usr/obj/ Ns Ev ${.CURDIR} 1028.It 1029.Ev ${.CURDIR} 1030.El 1031.Pp 1032Variable expansion is performed on the value before it's used, 1033so expressions such as 1034.Dl ${.CURDIR:S,^/usr/src,/var/obj,} 1035may be used. 1036This is especially useful with 1037.Ql Ev MAKEOBJDIR . 1038.Pp 1039.Ql Va .OBJDIR 1040may be modified in the makefile via the special target 1041.Ql Ic .OBJDIR . 1042In all cases, 1043.Nm 1044will 1045.Xr chdir 2 1046to the specified directory if it exists, and set 1047.Ql Va .OBJDIR 1048and 1049.Ql Ev PWD 1050to that directory before executing any targets. 1051. 1052.It Va .PARSEDIR 1053A path to the directory of the current 1054.Ql Pa Makefile 1055being parsed. 1056.It Va .PARSEFILE 1057The basename of the current 1058.Ql Pa Makefile 1059being parsed. 1060This variable and 1061.Ql Va .PARSEDIR 1062are both set only while the 1063.Ql Pa Makefiles 1064are being parsed. 1065If you want to retain their current values, assign them to a variable 1066using assignment with expansion: 1067.Pq Ql Cm \&:= . 1068.It Va .PATH 1069A variable that represents the list of directories that 1070.Nm 1071will search for files. 1072The search list should be updated using the target 1073.Ql Va .PATH 1074rather than the variable. 1075.It Ev PWD 1076Alternate path to the current directory. 1077.Nm 1078normally sets 1079.Ql Va .CURDIR 1080to the canonical path given by 1081.Xr getcwd 3 . 1082However, if the environment variable 1083.Ql Ev PWD 1084is set and gives a path to the current directory, then 1085.Nm 1086sets 1087.Ql Va .CURDIR 1088to the value of 1089.Ql Ev PWD 1090instead. 1091This behavior is disabled if 1092.Ql Ev MAKEOBJDIRPREFIX 1093is set or 1094.Ql Ev MAKEOBJDIR 1095contains a variable transform. 1096.Ql Ev PWD 1097is set to the value of 1098.Ql Va .OBJDIR 1099for all programs which 1100.Nm 1101executes. 1102.It Ev .TARGETS 1103The list of targets explicitly specified on the command line, if any. 1104.It Ev VPATH 1105Colon-separated 1106.Pq Dq \&: 1107lists of directories that 1108.Nm 1109will search for files. 1110The variable is supported for compatibility with old make programs only, 1111use 1112.Ql Va .PATH 1113instead. 1114.El 1115.Ss Variable modifiers 1116Variable expansion may be modified to select or modify each word of the 1117variable (where a 1118.Dq word 1119is white-space delimited sequence of characters). 1120The general format of a variable expansion is as follows: 1121.Pp 1122.Dl ${variable[:modifier[:...]]} 1123.Pp 1124Each modifier begins with a colon, 1125which may be escaped with a backslash 1126.Pq Ql \e . 1127.Pp 1128A set of modifiers can be specified via a variable, as follows: 1129.Pp 1130.Dl modifier_variable=modifier[:...] 1131.Dl ${variable:${modifier_variable}[:...]} 1132.Pp 1133In this case the first modifier in the modifier_variable does not 1134start with a colon, since that must appear in the referencing 1135variable. 1136If any of the modifiers in the modifier_variable contain a dollar sign 1137.Pq Ql $ , 1138these must be doubled to avoid early expansion. 1139.Pp 1140The supported modifiers are: 1141.Bl -tag -width EEE 1142.It Cm \&:E 1143Replaces each word in the variable with its suffix. 1144.It Cm \&:H 1145Replaces each word in the variable with everything but the last component. 1146.It Cm \&:M Ns Ar pattern 1147Select only those words that match 1148.Ar pattern . 1149The standard shell wildcard characters 1150.Pf ( Ql * , 1151.Ql \&? , 1152and 1153.Ql Oo Oc ) 1154may 1155be used. 1156The wildcard characters may be escaped with a backslash 1157.Pq Ql \e . 1158As a consequence of the way values are split into words, matched, 1159and then joined, a construct like 1160.Dl ${VAR:M*} 1161will normalize the inter-word spacing, removing all leading and 1162trailing space, and converting multiple consecutive spaces 1163to single spaces. 1164. 1165.It Cm \&:N Ns Ar pattern 1166This is identical to 1167.Ql Cm \&:M , 1168but selects all words which do not match 1169.Ar pattern . 1170.It Cm \&:O 1171Order every word in variable alphabetically. 1172To sort words in 1173reverse order use the 1174.Ql Cm \&:O:[-1..1] 1175combination of modifiers. 1176.It Cm \&:Ox 1177Randomize words in variable. 1178The results will be different each time you are referring to the 1179modified variable; use the assignment with expansion 1180.Pq Ql Cm \&:= 1181to prevent such behavior. 1182For example, 1183.Bd -literal -offset indent 1184LIST= uno due tre quattro 1185RANDOM_LIST= ${LIST:Ox} 1186STATIC_RANDOM_LIST:= ${LIST:Ox} 1187 1188all: 1189 @echo "${RANDOM_LIST}" 1190 @echo "${RANDOM_LIST}" 1191 @echo "${STATIC_RANDOM_LIST}" 1192 @echo "${STATIC_RANDOM_LIST}" 1193.Ed 1194may produce output similar to: 1195.Bd -literal -offset indent 1196quattro due tre uno 1197tre due quattro uno 1198due uno quattro tre 1199due uno quattro tre 1200.Ed 1201.It Cm \&:Q 1202Quotes every shell meta-character in the variable, so that it can be passed 1203safely through recursive invocations of 1204.Nm . 1205.It Cm \&:R 1206Replaces each word in the variable with everything but its suffix. 1207.It Cm \&:gmtime 1208The value is a format string for 1209.Xr strftime 3 , 1210using the current 1211.Xr gmtime 3 . 1212.It Cm \&:hash 1213Compute a 32-bit hash of the value and encode it as hex digits. 1214.It Cm \&:localtime 1215The value is a format string for 1216.Xr strftime 3 , 1217using the current 1218.Xr localtime 3 . 1219.It Cm \&:tA 1220Attempt to convert variable to an absolute path using 1221.Xr realpath 3 , 1222if that fails, the value is unchanged. 1223.It Cm \&:tl 1224Converts variable to lower-case letters. 1225.It Cm \&:ts Ns Ar c 1226Words in the variable are normally separated by a space on expansion. 1227This modifier sets the separator to the character 1228.Ar c . 1229If 1230.Ar c 1231is omitted, then no separator is used. 1232The common escapes (including octal numeric codes), work as expected. 1233.It Cm \&:tu 1234Converts variable to upper-case letters. 1235.It Cm \&:tW 1236Causes the value to be treated as a single word 1237(possibly containing embedded white space). 1238See also 1239.Ql Cm \&:[*] . 1240.It Cm \&:tw 1241Causes the value to be treated as a sequence of 1242words delimited by white space. 1243See also 1244.Ql Cm \&:[@] . 1245.Sm off 1246.It Cm \&:S No \&/ Ar old_string No \&/ Ar new_string No \&/ Op Cm 1gW 1247.Sm on 1248Modify the first occurrence of 1249.Ar old_string 1250in the variable's value, replacing it with 1251.Ar new_string . 1252If a 1253.Ql g 1254is appended to the last slash of the pattern, all occurrences 1255in each word are replaced. 1256If a 1257.Ql 1 1258is appended to the last slash of the pattern, only the first word 1259is affected. 1260If a 1261.Ql W 1262is appended to the last slash of the pattern, 1263then the value is treated as a single word 1264(possibly containing embedded white space). 1265If 1266.Ar old_string 1267begins with a caret 1268.Pq Ql ^ , 1269.Ar old_string 1270is anchored at the beginning of each word. 1271If 1272.Ar old_string 1273ends with a dollar sign 1274.Pq Ql \&$ , 1275it is anchored at the end of each word. 1276Inside 1277.Ar new_string , 1278an ampersand 1279.Pq Ql \*[Am] 1280is replaced by 1281.Ar old_string 1282(without any 1283.Ql ^ 1284or 1285.Ql \&$ ) . 1286Any character may be used as a delimiter for the parts of the modifier 1287string. 1288The anchoring, ampersand and delimiter characters may be escaped with a 1289backslash 1290.Pq Ql \e . 1291.Pp 1292Variable expansion occurs in the normal fashion inside both 1293.Ar old_string 1294and 1295.Ar new_string 1296with the single exception that a backslash is used to prevent the expansion 1297of a dollar sign 1298.Pq Ql \&$ , 1299not a preceding dollar sign as is usual. 1300.Sm off 1301.It Cm \&:C No \&/ Ar pattern No \&/ Ar replacement No \&/ Op Cm 1gW 1302.Sm on 1303The 1304.Cm \&:C 1305modifier is just like the 1306.Cm \&:S 1307modifier except that the old and new strings, instead of being 1308simple strings, are an extended regular expression (see 1309.Xr regex 3 ) 1310string 1311.Ar pattern 1312and an 1313.Xr ed 1 Ns \-style 1314string 1315.Ar replacement . 1316Normally, the first occurrence of the pattern 1317.Ar pattern 1318in each word of the value is substituted with 1319.Ar replacement . 1320The 1321.Ql 1 1322modifier causes the substitution to apply to at most one word; the 1323.Ql g 1324modifier causes the substitution to apply to as many instances of the 1325search pattern 1326.Ar pattern 1327as occur in the word or words it is found in; the 1328.Ql W 1329modifier causes the value to be treated as a single word 1330(possibly containing embedded white space). 1331Note that 1332.Ql 1 1333and 1334.Ql g 1335are orthogonal; the former specifies whether multiple words are 1336potentially affected, the latter whether multiple substitutions can 1337potentially occur within each affected word. 1338.Pp 1339As for the 1340.Cm \&:S 1341modifier, the 1342.Ar pattern 1343and 1344.Ar replacement 1345are subjected to variable expansion before being parsed as 1346regular expressions. 1347.It Cm \&:T 1348Replaces each word in the variable with its last component. 1349.It Cm \&:u 1350Remove adjacent duplicate words (like 1351.Xr uniq 1 ) . 1352.Sm off 1353.It Cm \&:\&? Ar true_string Cm \&: Ar false_string 1354.Sm on 1355If the variable name (not its value), when parsed as a .if conditional 1356expression, evaluates to true, return as its value the 1357.Ar true_string , 1358otherwise return the 1359.Ar false_string . 1360Since the variable name is used as the expression, \&:\&? must be the 1361first modifier after the variable name itself - which will, of course, 1362usually contain variable expansions. 1363A common error is trying to use expressions like 1364.Dl ${NUMBERS:M42:?match:no} 1365which actually tests defined(NUMBERS), 1366to determine is any words match "42" you need to use something like: 1367.Dl ${"${NUMBERS:M42}" != \&"\&":?match:no} . 1368.It Ar :old_string=new_string 1369This is the 1370.At V 1371style variable substitution. 1372It must be the last modifier specified. 1373If 1374.Ar old_string 1375or 1376.Ar new_string 1377do not contain the pattern matching character 1378.Ar % 1379then it is assumed that they are 1380anchored at the end of each word, so only suffixes or entire 1381words may be replaced. 1382Otherwise 1383.Ar % 1384is the substring of 1385.Ar old_string 1386to be replaced in 1387.Ar new_string . 1388.Pp 1389Variable expansion occurs in the normal fashion inside both 1390.Ar old_string 1391and 1392.Ar new_string 1393with the single exception that a backslash is used to prevent the 1394expansion of a dollar sign 1395.Pq Ql \&$ , 1396not a preceding dollar sign as is usual. 1397.Sm off 1398.It Cm \&:@ Ar temp Cm @ Ar string Cm @ 1399.Sm on 1400This is the loop expansion mechanism from the OSF Development 1401Environment (ODE) make. 1402Unlike 1403.Cm \&.for 1404loops expansion occurs at the time of 1405reference. 1406Assign 1407.Ar temp 1408to each word in the variable and evaluate 1409.Ar string . 1410The ODE convention is that 1411.Ar temp 1412should start and end with a period. 1413For example. 1414.Dl ${LINKS:@.LINK.@${LN} ${TARGET} ${.LINK.}@} 1415.Pp 1416However a single character variable is often more readable: 1417.Dl ${MAKE_PRINT_VAR_ON_ERROR:@v@$v='${$v}'${.newline}@} 1418.It Cm \&:U Ns Ar newval 1419If the variable is undefined 1420.Ar newval 1421is the value. 1422If the variable is defined, the existing value is returned. 1423This is another ODE make feature. 1424It is handy for setting per-target CFLAGS for instance: 1425.Dl ${_${.TARGET:T}_CFLAGS:U${DEF_CFLAGS}} 1426If a value is only required if the variable is undefined, use: 1427.Dl ${VAR:D:Unewval} 1428.It Cm \&:D Ns Ar newval 1429If the variable is defined 1430.Ar newval 1431is the value. 1432.It Cm \&:L 1433The name of the variable is the value. 1434.It Cm \&:P 1435The path of the node which has the same name as the variable 1436is the value. 1437If no such node exists or its path is null, then the 1438name of the variable is used. 1439In order for this modifier to work, the name (node) must at least have 1440appeared on the rhs of a dependency. 1441.Sm off 1442.It Cm \&:\&! Ar cmd Cm \&! 1443.Sm on 1444The output of running 1445.Ar cmd 1446is the value. 1447.It Cm \&:sh 1448If the variable is non-empty it is run as a command and the output 1449becomes the new value. 1450.It Cm \&::= Ns Ar str 1451The variable is assigned the value 1452.Ar str 1453after substitution. 1454This modifier and its variations are useful in 1455obscure situations such as wanting to set a variable when shell commands 1456are being parsed. 1457These assignment modifiers always expand to 1458nothing, so if appearing in a rule line by themselves should be 1459preceded with something to keep 1460.Nm 1461happy. 1462.Pp 1463The 1464.Ql Cm \&:: 1465helps avoid false matches with the 1466.At V 1467style 1468.Cm \&:= 1469modifier and since substitution always occurs the 1470.Cm \&::= 1471form is vaguely appropriate. 1472.It Cm \&::?= Ns Ar str 1473As for 1474.Cm \&::= 1475but only if the variable does not already have a value. 1476.It Cm \&::+= Ns Ar str 1477Append 1478.Ar str 1479to the variable. 1480.It Cm \&::!= Ns Ar cmd 1481Assign the output of 1482.Ar cmd 1483to the variable. 1484.It Cm \&:\&[ Ns Ar range Ns Cm \&] 1485Selects one or more words from the value, 1486or performs other operations related to the way in which the 1487value is divided into words. 1488.Pp 1489Ordinarily, a value is treated as a sequence of words 1490delimited by white space. 1491Some modifiers suppress this behavior, 1492causing a value to be treated as a single word 1493(possibly containing embedded white space). 1494An empty value, or a value that consists entirely of white-space, 1495is treated as a single word. 1496For the purposes of the 1497.Ql Cm \&:[] 1498modifier, the words are indexed both forwards using positive integers 1499(where index 1 represents the first word), 1500and backwards using negative integers 1501(where index \-1 represents the last word). 1502.Pp 1503The 1504.Ar range 1505is subjected to variable expansion, and the expanded result is 1506then interpreted as follows: 1507.Bl -tag -width index 1508.\" :[n] 1509.It Ar index 1510Selects a single word from the value. 1511.\" :[start..end] 1512.It Ar start Ns Cm \&.. Ns Ar end 1513Selects all words from 1514.Ar start 1515to 1516.Ar end , 1517inclusive. 1518For example, 1519.Ql Cm \&:[2..-1] 1520selects all words from the second word to the last word. 1521If 1522.Ar start 1523is greater than 1524.Ar end , 1525then the words are output in reverse order. 1526For example, 1527.Ql Cm \&:[-1..1] 1528selects all the words from last to first. 1529.\" :[*] 1530.It Cm \&* 1531Causes subsequent modifiers to treat the value as a single word 1532(possibly containing embedded white space). 1533Analogous to the effect of 1534\&"$*\&" 1535in Bourne shell. 1536.\" :[0] 1537.It 0 1538Means the same as 1539.Ql Cm \&:[*] . 1540.\" :[*] 1541.It Cm \&@ 1542Causes subsequent modifiers to treat the value as a sequence of words 1543delimited by white space. 1544Analogous to the effect of 1545\&"$@\&" 1546in Bourne shell. 1547.\" :[#] 1548.It Cm \&# 1549Returns the number of words in the value. 1550.El \" :[range] 1551.El 1552.Sh INCLUDE STATEMENTS, CONDITIONALS AND FOR LOOPS 1553Makefile inclusion, conditional structures and for loops reminiscent 1554of the C programming language are provided in 1555.Nm . 1556All such structures are identified by a line beginning with a single 1557dot 1558.Pq Ql \&. 1559character. 1560Files are included with either 1561.Cm \&.include Aq Ar file 1562or 1563.Cm \&.include Pf \*q Ar file Ns \*q . 1564Variables between the angle brackets or double quotes are expanded 1565to form the file name. 1566If angle brackets are used, the included makefile is expected to be in 1567the system makefile directory. 1568If double quotes are used, the including makefile's directory and any 1569directories specified using the 1570.Fl I 1571option are searched before the system 1572makefile directory. 1573For compatibility with other versions of 1574.Nm 1575.Ql include file ... 1576is also accepted. 1577.Pp 1578If the include statement is written as 1579.Cm .-include 1580or as 1581.Cm .sinclude 1582then errors locating and/or opening include files are ignored. 1583.Pp 1584If the include statement is written as 1585.Cm .dinclude 1586not only are errors locating and/or opening include files ignored, 1587but stale dependencies within the included file will be ignored 1588just like 1589.Va .MAKE.DEPENDFILE . 1590.Pp 1591Conditional expressions are also preceded by a single dot as the first 1592character of a line. 1593The possible conditionals are as follows: 1594.Bl -tag -width Ds 1595.It Ic .error Ar message 1596The message is printed along with the name of the makefile and line number, 1597then 1598.Nm 1599will exit. 1600.It Ic .export Ar variable ... 1601Export the specified global variable. 1602If no variable list is provided, all globals are exported 1603except for internal variables (those that start with 1604.Ql \&. ) . 1605This is not affected by the 1606.Fl X 1607flag, so should be used with caution. 1608For compatibility with other 1609.Nm 1610programs 1611.Ql export variable=value 1612is also accepted. 1613.Pp 1614Appending a variable name to 1615.Va .MAKE.EXPORTED 1616is equivalent to exporting a variable. 1617.It Ic .export-env Ar variable ... 1618The same as 1619.Ql .export , 1620except that the variable is not appended to 1621.Va .MAKE.EXPORTED . 1622This allows exporting a value to the environment which is different from that 1623used by 1624.Nm 1625internally. 1626.It Ic .export-literal Ar variable ... 1627The same as 1628.Ql .export-env , 1629except that variables in the value are not expanded. 1630.It Ic .info Ar message 1631The message is printed along with the name of the makefile and line number. 1632.It Ic .undef Ar variable 1633Un-define the specified global variable. 1634Only global variables may be un-defined. 1635.It Ic .unexport Ar variable ... 1636The opposite of 1637.Ql .export . 1638The specified global 1639.Va variable 1640will be removed from 1641.Va .MAKE.EXPORTED . 1642If no variable list is provided, all globals are unexported, 1643and 1644.Va .MAKE.EXPORTED 1645deleted. 1646.It Ic .unexport-env 1647Unexport all globals previously exported and 1648clear the environment inherited from the parent. 1649This operation will cause a memory leak of the original environment, 1650so should be used sparingly. 1651Testing for 1652.Va .MAKE.LEVEL 1653being 0, would make sense. 1654Also note that any variables which originated in the parent environment 1655should be explicitly preserved if desired. 1656For example: 1657.Bd -literal -offset indent 1658.Li .if ${.MAKE.LEVEL} == 0 1659PATH := ${PATH} 1660.Li .unexport-env 1661.Li .export PATH 1662.Li .endif 1663.Pp 1664.Ed 1665Would result in an environment containing only 1666.Ql Ev PATH , 1667which is the minimal useful environment. 1668Actually 1669.Ql Ev .MAKE.LEVEL 1670will also be pushed into the new environment. 1671.It Ic .warning Ar message 1672The message prefixed by 1673.Ql Pa warning: 1674is printed along with the name of the makefile and line number. 1675.It Ic \&.if Oo \&! Oc Ns Ar expression Op Ar operator expression ... 1676Test the value of an expression. 1677.It Ic .ifdef Oo \&! Oc Ns Ar variable Op Ar operator variable ... 1678Test the value of a variable. 1679.It Ic .ifndef Oo \&! Oc Ns Ar variable Op Ar operator variable ... 1680Test the value of a variable. 1681.It Ic .ifmake Oo \&! Oc Ns Ar target Op Ar operator target ... 1682Test the target being built. 1683.It Ic .ifnmake Oo \&! Ns Oc Ar target Op Ar operator target ... 1684Test the target being built. 1685.It Ic .else 1686Reverse the sense of the last conditional. 1687.It Ic .elif Oo \&! Ns Oc Ar expression Op Ar operator expression ... 1688A combination of 1689.Ql Ic .else 1690followed by 1691.Ql Ic .if . 1692.It Ic .elifdef Oo \&! Oc Ns Ar variable Op Ar operator variable ... 1693A combination of 1694.Ql Ic .else 1695followed by 1696.Ql Ic .ifdef . 1697.It Ic .elifndef Oo \&! Oc Ns Ar variable Op Ar operator variable ... 1698A combination of 1699.Ql Ic .else 1700followed by 1701.Ql Ic .ifndef . 1702.It Ic .elifmake Oo \&! Oc Ns Ar target Op Ar operator target ... 1703A combination of 1704.Ql Ic .else 1705followed by 1706.Ql Ic .ifmake . 1707.It Ic .elifnmake Oo \&! Oc Ns Ar target Op Ar operator target ... 1708A combination of 1709.Ql Ic .else 1710followed by 1711.Ql Ic .ifnmake . 1712.It Ic .endif 1713End the body of the conditional. 1714.El 1715.Pp 1716The 1717.Ar operator 1718may be any one of the following: 1719.Bl -tag -width "Cm XX" 1720.It Cm \&|\&| 1721Logical OR. 1722.It Cm \&\*[Am]\*[Am] 1723Logical 1724.Tn AND ; 1725of higher precedence than 1726.Dq \&|\&| . 1727.El 1728.Pp 1729As in C, 1730.Nm 1731will only evaluate a conditional as far as is necessary to determine 1732its value. 1733Parentheses may be used to change the order of evaluation. 1734The boolean operator 1735.Ql Ic \&! 1736may be used to logically negate an entire 1737conditional. 1738It is of higher precedence than 1739.Ql Ic \&\*[Am]\*[Am] . 1740.Pp 1741The value of 1742.Ar expression 1743may be any of the following: 1744.Bl -tag -width defined 1745.It Ic defined 1746Takes a variable name as an argument and evaluates to true if the variable 1747has been defined. 1748.It Ic make 1749Takes a target name as an argument and evaluates to true if the target 1750was specified as part of 1751.Nm Ns 's 1752command line or was declared the default target (either implicitly or 1753explicitly, see 1754.Va .MAIN ) 1755before the line containing the conditional. 1756.It Ic empty 1757Takes a variable, with possible modifiers, and evaluates to true if 1758the expansion of the variable would result in an empty string. 1759.It Ic exists 1760Takes a file name as an argument and evaluates to true if the file exists. 1761The file is searched for on the system search path (see 1762.Va .PATH ) . 1763.It Ic target 1764Takes a target name as an argument and evaluates to true if the target 1765has been defined. 1766.It Ic commands 1767Takes a target name as an argument and evaluates to true if the target 1768has been defined and has commands associated with it. 1769.El 1770.Pp 1771.Ar Expression 1772may also be an arithmetic or string comparison. 1773Variable expansion is 1774performed on both sides of the comparison, after which the integral 1775values are compared. 1776A value is interpreted as hexadecimal if it is 1777preceded by 0x, otherwise it is decimal; octal numbers are not supported. 1778The standard C relational operators are all supported. 1779If after 1780variable expansion, either the left or right hand side of a 1781.Ql Ic == 1782or 1783.Ql Ic "!=" 1784operator is not an integral value, then 1785string comparison is performed between the expanded 1786variables. 1787If no relational operator is given, it is assumed that the expanded 1788variable is being compared against 0 or an empty string in the case 1789of a string comparison. 1790.Pp 1791When 1792.Nm 1793is evaluating one of these conditional expressions, and it encounters 1794a (white-space separated) word it doesn't recognize, either the 1795.Dq make 1796or 1797.Dq defined 1798expression is applied to it, depending on the form of the conditional. 1799If the form is 1800.Ql Ic .ifdef , 1801.Ql Ic .ifndef , 1802or 1803.Ql Ic .if 1804the 1805.Dq defined 1806expression is applied. 1807Similarly, if the form is 1808.Ql Ic .ifmake 1809or 1810.Ql Ic .ifnmake , the 1811.Dq make 1812expression is applied. 1813.Pp 1814If the conditional evaluates to true the parsing of the makefile continues 1815as before. 1816If it evaluates to false, the following lines are skipped. 1817In both cases this continues until a 1818.Ql Ic .else 1819or 1820.Ql Ic .endif 1821is found. 1822.Pp 1823For loops are typically used to apply a set of rules to a list of files. 1824The syntax of a for loop is: 1825.Pp 1826.Bl -tag -compact -width Ds 1827.It Ic \&.for Ar variable Oo Ar variable ... Oc Ic in Ar expression 1828.It Aq make-rules 1829.It Ic \&.endfor 1830.El 1831.Pp 1832After the for 1833.Ic expression 1834is evaluated, it is split into words. 1835On each iteration of the loop, one word is taken and assigned to each 1836.Ic variable , 1837in order, and these 1838.Ic variables 1839are substituted into the 1840.Ic make-rules 1841inside the body of the for loop. 1842The number of words must come out even; that is, if there are three 1843iteration variables, the number of words provided must be a multiple 1844of three. 1845.Sh COMMENTS 1846Comments begin with a hash 1847.Pq Ql \&# 1848character, anywhere but in a shell 1849command line, and continue to the end of an unescaped new line. 1850.Sh SPECIAL SOURCES (ATTRIBUTES) 1851.Bl -tag -width .IGNOREx 1852.It Ic .EXEC 1853Target is never out of date, but always execute commands anyway. 1854.It Ic .IGNORE 1855Ignore any errors from the commands associated with this target, exactly 1856as if they all were preceded by a dash 1857.Pq Ql \- . 1858.\" .It Ic .INVISIBLE 1859.\" XXX 1860.\" .It Ic .JOIN 1861.\" XXX 1862.It Ic .MADE 1863Mark all sources of this target as being up-to-date. 1864.It Ic .MAKE 1865Execute the commands associated with this target even if the 1866.Fl n 1867or 1868.Fl t 1869options were specified. 1870Normally used to mark recursive 1871.Nm Ns s . 1872.It Ic .META 1873Create a meta file for the target, even if it is flagged as 1874.Ic .PHONY , 1875.Ic .MAKE , 1876or 1877.Ic .SPECIAL . 1878Usage in conjunction with 1879.Ic .MAKE 1880is the most likely case. 1881In "meta" mode, the target is out-of-date if the meta file is missing. 1882.It Ic .NOMETA 1883Do not create a meta file for the target. 1884Meta files are also not created for 1885.Ic .PHONY , 1886.Ic .MAKE , 1887or 1888.Ic .SPECIAL 1889targets. 1890.It Ic .NOMETA_CMP 1891Ignore differences in commands when deciding if target is out of date. 1892This is useful if the command contains a value which always changes. 1893If the number of commands change, though, the target will still be out of date. 1894The same effect applies to any command line that uses the variable 1895.Va .OODATE , 1896which can be used for that purpose even when not otherwise needed or desired: 1897.Bd -literal -offset indent 1898 1899skip-compare-for-some: 1900 @echo this will be compared 1901 @echo this will not ${.OODATE:M.NOMETA_CMP} 1902 @echo this will also be compared 1903 1904.Ed 1905The 1906.Cm \&:M 1907pattern suppresses any expansion of the unwanted variable. 1908.It Ic .NOPATH 1909Do not search for the target in the directories specified by 1910.Ic .PATH . 1911.It Ic .NOTMAIN 1912Normally 1913.Nm 1914selects the first target it encounters as the default target to be built 1915if no target was specified. 1916This source prevents this target from being selected. 1917.It Ic .OPTIONAL 1918If a target is marked with this attribute and 1919.Nm 1920can't figure out how to create it, it will ignore this fact and assume 1921the file isn't needed or already exists. 1922.It Ic .PHONY 1923The target does not 1924correspond to an actual file; it is always considered to be out of date, 1925and will not be created with the 1926.Fl t 1927option. 1928Suffix-transformation rules are not applied to 1929.Ic .PHONY 1930targets. 1931.It Ic .PRECIOUS 1932When 1933.Nm 1934is interrupted, it normally removes any partially made targets. 1935This source prevents the target from being removed. 1936.It Ic .RECURSIVE 1937Synonym for 1938.Ic .MAKE . 1939.It Ic .SILENT 1940Do not echo any of the commands associated with this target, exactly 1941as if they all were preceded by an at sign 1942.Pq Ql @ . 1943.It Ic .USE 1944Turn the target into 1945.Nm Ns 's 1946version of a macro. 1947When the target is used as a source for another target, the other target 1948acquires the commands, sources, and attributes (except for 1949.Ic .USE ) 1950of the 1951source. 1952If the target already has commands, the 1953.Ic .USE 1954target's commands are appended 1955to them. 1956.It Ic .USEBEFORE 1957Exactly like 1958.Ic .USE , 1959but prepend the 1960.Ic .USEBEFORE 1961target commands to the target. 1962.It Ic .WAIT 1963If 1964.Ic .WAIT 1965appears in a dependency line, the sources that precede it are 1966made before the sources that succeed it in the line. 1967Since the dependents of files are not made until the file itself 1968could be made, this also stops the dependents being built unless they 1969are needed for another branch of the dependency tree. 1970So given: 1971.Bd -literal 1972x: a .WAIT b 1973 echo x 1974a: 1975 echo a 1976b: b1 1977 echo b 1978b1: 1979 echo b1 1980 1981.Ed 1982the output is always 1983.Ql a , 1984.Ql b1 , 1985.Ql b , 1986.Ql x . 1987.br 1988The ordering imposed by 1989.Ic .WAIT 1990is only relevant for parallel makes. 1991.El 1992.Sh SPECIAL TARGETS 1993Special targets may not be included with other targets, i.e. they must be 1994the only target specified. 1995.Bl -tag -width .BEGINx 1996.It Ic .BEGIN 1997Any command lines attached to this target are executed before anything 1998else is done. 1999.It Ic .DEFAULT 2000This is sort of a 2001.Ic .USE 2002rule for any target (that was used only as a 2003source) that 2004.Nm 2005can't figure out any other way to create. 2006Only the shell script is used. 2007The 2008.Ic .IMPSRC 2009variable of a target that inherits 2010.Ic .DEFAULT Ns 's 2011commands is set 2012to the target's own name. 2013.It Ic .DELETE_ON_ERROR 2014If this target is present in the makefile, it globally causes make to 2015delete targets whose commands fail. 2016(By default, only targets whose commands are interrupted during 2017execution are deleted. 2018This is the historical behavior.) 2019This setting can be used to help prevent half-finished or malformed 2020targets from being left around and corrupting future rebuilds. 2021.It Ic .END 2022Any command lines attached to this target are executed after everything 2023else is done. 2024.It Ic .ERROR 2025Any command lines attached to this target are executed when another target fails. 2026The 2027.Ic .ERROR_TARGET 2028variable is set to the target that failed. 2029See also 2030.Ic MAKE_PRINT_VAR_ON_ERROR . 2031.It Ic .IGNORE 2032Mark each of the sources with the 2033.Ic .IGNORE 2034attribute. 2035If no sources are specified, this is the equivalent of specifying the 2036.Fl i 2037option. 2038.It Ic .INTERRUPT 2039If 2040.Nm 2041is interrupted, the commands for this target will be executed. 2042.It Ic .MAIN 2043If no target is specified when 2044.Nm 2045is invoked, this target will be built. 2046.It Ic .MAKEFLAGS 2047This target provides a way to specify flags for 2048.Nm 2049when the makefile is used. 2050The flags are as if typed to the shell, though the 2051.Fl f 2052option will have 2053no effect. 2054.\" XXX: NOT YET!!!! 2055.\" .It Ic .NOTPARALLEL 2056.\" The named targets are executed in non parallel mode. 2057.\" If no targets are 2058.\" specified, then all targets are executed in non parallel mode. 2059.It Ic .NOPATH 2060Apply the 2061.Ic .NOPATH 2062attribute to any specified sources. 2063.It Ic .NOTPARALLEL 2064Disable parallel mode. 2065.It Ic .NO_PARALLEL 2066Synonym for 2067.Ic .NOTPARALLEL , 2068for compatibility with other pmake variants. 2069.It Ic .OBJDIR 2070The source is a new value for 2071.Ql Va .OBJDIR . 2072If it exists, 2073.Nm 2074will 2075.Xr chdir 2 2076to it and update the value of 2077.Ql Va .OBJDIR . 2078.It Ic .ORDER 2079The named targets are made in sequence. 2080This ordering does not add targets to the list of targets to be made. 2081Since the dependents of a target do not get built until the target itself 2082could be built, unless 2083.Ql a 2084is built by another part of the dependency graph, 2085the following is a dependency loop: 2086.Bd -literal 2087\&.ORDER: b a 2088b: a 2089.Ed 2090.Pp 2091The ordering imposed by 2092.Ic .ORDER 2093is only relevant for parallel makes. 2094.\" XXX: NOT YET!!!! 2095.\" .It Ic .PARALLEL 2096.\" The named targets are executed in parallel mode. 2097.\" If no targets are 2098.\" specified, then all targets are executed in parallel mode. 2099.It Ic .PATH 2100The sources are directories which are to be searched for files not 2101found in the current directory. 2102If no sources are specified, any previously specified directories are 2103deleted. 2104If the source is the special 2105.Ic .DOTLAST 2106target, then the current working 2107directory is searched last. 2108.It Ic .PATH. Ns Va suffix 2109Like 2110.Ic .PATH 2111but applies only to files with a particular suffix. 2112The suffix must have been previously declared with 2113.Ic .SUFFIXES . 2114.It Ic .PHONY 2115Apply the 2116.Ic .PHONY 2117attribute to any specified sources. 2118.It Ic .PRECIOUS 2119Apply the 2120.Ic .PRECIOUS 2121attribute to any specified sources. 2122If no sources are specified, the 2123.Ic .PRECIOUS 2124attribute is applied to every 2125target in the file. 2126.It Ic .SHELL 2127Sets the shell that 2128.Nm 2129will use to execute commands. 2130The sources are a set of 2131.Ar field=value 2132pairs. 2133.Bl -tag -width hasErrCtls 2134.It Ar name 2135This is the minimal specification, used to select one of the built-in 2136shell specs; 2137.Ar sh , 2138.Ar ksh , 2139and 2140.Ar csh . 2141.It Ar path 2142Specifies the path to the shell. 2143.It Ar hasErrCtl 2144Indicates whether the shell supports exit on error. 2145.It Ar check 2146The command to turn on error checking. 2147.It Ar ignore 2148The command to disable error checking. 2149.It Ar echo 2150The command to turn on echoing of commands executed. 2151.It Ar quiet 2152The command to turn off echoing of commands executed. 2153.It Ar filter 2154The output to filter after issuing the 2155.Ar quiet 2156command. 2157It is typically identical to 2158.Ar quiet . 2159.It Ar errFlag 2160The flag to pass the shell to enable error checking. 2161.It Ar echoFlag 2162The flag to pass the shell to enable command echoing. 2163.It Ar newline 2164The string literal to pass the shell that results in a single newline 2165character when used outside of any quoting characters. 2166.El 2167Example: 2168.Bd -literal 2169\&.SHELL: name=ksh path=/bin/ksh hasErrCtl=true \e 2170 check="set \-e" ignore="set +e" \e 2171 echo="set \-v" quiet="set +v" filter="set +v" \e 2172 echoFlag=v errFlag=e newline="'\en'" 2173.Ed 2174.It Ic .SILENT 2175Apply the 2176.Ic .SILENT 2177attribute to any specified sources. 2178If no sources are specified, the 2179.Ic .SILENT 2180attribute is applied to every 2181command in the file. 2182.It Ic .STALE 2183This target gets run when a dependency file contains stale entries, having 2184.Va .ALLSRC 2185set to the name of that dependency file. 2186.It Ic .SUFFIXES 2187Each source specifies a suffix to 2188.Nm . 2189If no sources are specified, any previously specified suffixes are deleted. 2190It allows the creation of suffix-transformation rules. 2191.Pp 2192Example: 2193.Bd -literal 2194\&.SUFFIXES: .o 2195\&.c.o: 2196 cc \-o ${.TARGET} \-c ${.IMPSRC} 2197.Ed 2198.El 2199.Sh ENVIRONMENT 2200.Nm 2201uses the following environment variables, if they exist: 2202.Ev MACHINE , 2203.Ev MACHINE_ARCH , 2204.Ev MAKE , 2205.Ev MAKEFLAGS , 2206.Ev MAKEOBJDIR , 2207.Ev MAKEOBJDIRPREFIX , 2208.Ev MAKESYSPATH , 2209.Ev PWD , 2210and 2211.Ev TMPDIR . 2212.Pp 2213.Ev MAKEOBJDIRPREFIX 2214and 2215.Ev MAKEOBJDIR 2216may only be set in the environment or on the command line to 2217.Nm 2218and not as makefile variables; 2219see the description of 2220.Ql Va .OBJDIR 2221for more details. 2222.Sh FILES 2223.Bl -tag -width /usr/share/mk -compact 2224.It .depend 2225list of dependencies 2226.It Makefile 2227list of dependencies 2228.It makefile 2229list of dependencies 2230.It sys.mk 2231system makefile 2232.It /usr/share/mk 2233system makefile directory 2234.El 2235.Sh COMPATIBILITY 2236The basic make syntax is compatible between different versions of make; 2237however the special variables, variable modifiers and conditionals are not. 2238.Ss Older versions 2239An incomplete list of changes in older versions of 2240.Nm : 2241.Pp 2242The way that .for loop variables are substituted changed after 2243.Nx 5.0 2244so that they still appear to be variable expansions. 2245In particular this stops them being treated as syntax, and removes some 2246obscure problems using them in .if statements. 2247.Pp 2248The way that parallel makes are scheduled changed in 2249.Nx 4.0 2250so that .ORDER and .WAIT apply recursively to the dependent nodes. 2251The algorithms used may change again in the future. 2252.Ss Other make dialects 2253Other make dialects (GNU make, SVR4 make, POSIX make, etc.) do not 2254support most of the features of 2255.Nm 2256as described in this manual. 2257Most notably: 2258.Bl -bullet -offset indent 2259.It 2260The 2261.Ic .WAIT 2262and 2263.Ic .ORDER 2264declarations and most functionality pertaining to parallelization. 2265(GNU make supports parallelization but lacks these features needed to 2266control it effectively.) 2267.It 2268Directives, including for loops and conditionals and most of the 2269forms of include files. 2270(GNU make has its own incompatible and less powerful syntax for 2271conditionals.) 2272.It 2273All built-in variables that begin with a dot. 2274.It 2275Most of the special sources and targets that begin with a dot, 2276with the notable exception of 2277.Ic .PHONY , 2278.Ic .PRECIOUS , 2279and 2280.Ic .SUFFIXES . 2281.It 2282Variable modifiers, except for the 2283.Dl :old=new 2284string substitution, which does not portably support globbing with 2285.Ql % 2286and historically only works on declared suffixes. 2287.It 2288The 2289.Ic $> 2290variable even in its short form; most makes support this functionality 2291but its name varies. 2292.El 2293.Pp 2294Some features are somewhat more portable, such as assignment with 2295.Ic += , 2296.Ic ?= , 2297and 2298.Ic != . 2299The 2300.Ic .PATH 2301functionality is based on an older feature 2302.Ic VPATH 2303found in GNU make and many versions of SVR4 make; however, 2304historically its behavior is too ill-defined (and too buggy) to rely 2305upon. 2306.Pp 2307The 2308.Ic $@ 2309and 2310.Ic $< 2311variables are more or less universally portable, as is the 2312.Ic $(MAKE) 2313variable. 2314Basic use of suffix rules (for files only in the current directory, 2315not trying to chain transformations together, etc.) is also reasonably 2316portable. 2317.Sh SEE ALSO 2318.Xr mkdep 1 2319.Sh HISTORY 2320A 2321.Nm 2322command appeared in 2323.At v7 . 2324This 2325.Nm 2326implementation is based on Adam De Boor's pmake program which was written 2327for Sprite at Berkeley. 2328It was designed to be a parallel distributed make running jobs on different 2329machines using a daemon called 2330.Dq customs . 2331.Pp 2332Historically the target/dependency 2333.Dq FRC 2334has been used to FoRCe rebuilding (since the target/dependency 2335does not exist... unless someone creates an 2336.Dq FRC 2337file). 2338.Sh BUGS 2339The 2340.Nm 2341syntax is difficult to parse without actually acting of the data. 2342For instance finding the end of a variable use should involve scanning each 2343the modifiers using the correct terminator for each field. 2344In many places 2345.Nm 2346just counts {} and () in order to find the end of a variable expansion. 2347.Pp 2348There is no way of escaping a space character in a filename. 2349