1.\" $NetBSD: make.1,v 1.249 2015/06/05 07:33:40 wiz 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 June 4, 2015 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 filesystem. 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 @ . 688.El 689.Pp 690The shorter forms 691.Ql ( Va \*[Gt] , 692.Ql Va \&! , 693.Ql Va \*[Lt] , 694.Ql Va % , 695.Ql Va \&? , 696.Ql Va * , 697and 698.Ql Va @ ) 699are permitted for backward 700compatibility with historical makefiles and legacy POSIX make and are 701not recommended. 702.Pp 703Variants of these variables with the punctuation followed immediately by 704.Ql D 705or 706.Ql F , 707e.g. 708.Ql Va $(@D) , 709are legacy forms equivalent to using the 710.Ql :H 711and 712.Ql :T 713modifiers. 714These forms are accepted for compatibility with 715.At V 716makefiles and POSIX but are not recommended. 717.Pp 718Four of the local variables may be used in sources on dependency lines 719because they expand to the proper value for each target on the line. 720These variables are 721.Ql Va .TARGET , 722.Ql Va .PREFIX , 723.Ql Va .ARCHIVE , 724and 725.Ql Va .MEMBER . 726.Ss Additional built-in variables 727In addition, 728.Nm 729sets or knows about the following variables: 730.Bl -tag -width .MAKEOVERRIDES 731.It Va \&$ 732A single dollar sign 733.Ql \&$ , 734i.e. 735.Ql \&$$ 736expands to a single dollar 737sign. 738.It Va .ALLTARGETS 739The list of all targets encountered in the Makefile. 740If evaluated during 741Makefile parsing, lists only those targets encountered thus far. 742.It Va .CURDIR 743A path to the directory where 744.Nm 745was executed. 746Refer to the description of 747.Ql Ev PWD 748for more details. 749.It Va .INCLUDEDFROMDIR 750The directory of the file this Makefile was included from. 751.It Va .INCLUDEDFROMFILE 752The filename of the file this Makefile was included from. 753.It Ev MAKE 754The name that 755.Nm 756was executed with 757.Pq Va argv[0] . 758For compatibility 759.Nm 760also sets 761.Va .MAKE 762with the same value. 763The preferred variable to use is the environment variable 764.Ev MAKE 765because it is more compatible with other versions of 766.Nm 767and cannot be confused with the special target with the same name. 768.It Va .MAKE.ALWAYS_PASS_JOB_QUEUE 769Tells 770.Nm 771whether to pass the descriptors of the job token queue 772even if the target is not tagged with 773.Ic .MAKE 774The default is 775.Ql Pa yes 776for backwards compatability with 777.Fx 9.0 778and earlier. 779.It Va .MAKE.DEPENDFILE 780Names the makefile (default 781.Ql Pa .depend ) 782from which generated dependencies are read. 783.It Va .MAKE.EXPAND_VARIABLES 784A boolean that controls the default behavior of the 785.Fl V 786option. 787.It Va .MAKE.EXPORTED 788The list of variables exported by 789.Nm . 790.It Va .MAKE.JOBS 791The argument to the 792.Fl j 793option. 794.It Va .MAKE.JOB.PREFIX 795If 796.Nm 797is run with 798.Ar j 799then output for each target is prefixed with a token 800.Ql --- target --- 801the first part of which can be controlled via 802.Va .MAKE.JOB.PREFIX . 803If 804.Va .MAKE.JOB.PREFIX 805is empty, no token is printed. 806.br 807For example: 808.Li .MAKE.JOB.PREFIX=${.newline}---${.MAKE:T}[${.MAKE.PID}] 809would produce tokens like 810.Ql ---make[1234] target --- 811making it easier to track the degree of parallelism being achieved. 812.It Ev MAKEFLAGS 813The environment variable 814.Ql Ev MAKEFLAGS 815may contain anything that 816may be specified on 817.Nm Ns 's 818command line. 819Anything specified on 820.Nm Ns 's 821command line is appended to the 822.Ql Ev MAKEFLAGS 823variable which is then 824entered into the environment for all programs which 825.Nm 826executes. 827.It Va .MAKE.LEVEL 828The recursion depth of 829.Nm . 830The initial instance of 831.Nm 832will be 0, and an incremented value is put into the environment 833to be seen by the next generation. 834This allows tests like: 835.Li .if ${.MAKE.LEVEL} == 0 836to protect things which should only be evaluated in the initial instance of 837.Nm . 838.It Va .MAKE.MAKEFILE_PREFERENCE 839The ordered list of makefile names 840(default 841.Ql Pa makefile , 842.Ql Pa Makefile ) 843that 844.Nm 845will look for. 846.It Va .MAKE.MAKEFILES 847The list of makefiles read by 848.Nm , 849which is useful for tracking dependencies. 850Each makefile is recorded only once, regardless of the number of times read. 851.It Va .MAKE.MODE 852Processed after reading all makefiles. 853Can affect the mode that 854.Nm 855runs in. 856It can contain a number of keywords: 857.Bl -hang -width ignore-cmd 858.It Pa compat 859Like 860.Fl B , 861puts 862.Nm 863into "compat" mode. 864.It Pa meta 865Puts 866.Nm 867into "meta" mode, where meta files are created for each target 868to capture the command run, the output generated and if 869.Xr filemon 4 870is available, the system calls which are of interest to 871.Nm . 872The captured output can be very useful when diagnosing errors. 873.It Pa curdirOk= Ar bf 874Normally 875.Nm 876will not create .meta files in 877.Ql Va .CURDIR . 878This can be overridden by setting 879.Va bf 880to a value which represents True. 881.It Pa env 882For debugging, it can be useful to inlcude the environment 883in the .meta file. 884.It Pa verbose 885If in "meta" mode, print a clue about the target being built. 886This is useful if the build is otherwise running silently. 887The message printed the value of: 888.Va .MAKE.META.PREFIX . 889.It Pa ignore-cmd 890Some makefiles have commands which are simply not stable. 891This keyword causes them to be ignored for 892determining whether a target is out of date in "meta" mode. 893See also 894.Ic .NOMETA_CMP . 895.It Pa silent= Ar bf 896If 897.Va bf 898is True, when a .meta file is created, mark the target 899.Ic .SILENT . 900.El 901.It Va .MAKE.META.BAILIWICK 902In "meta" mode, provides a list of prefixes which 903match the directories controlled by 904.Nm . 905If a file that was generated outside of 906.Va .OBJDIR 907but within said bailiwick is missing, 908the current target is considered out-of-date. 909.It Va .MAKE.META.CREATED 910In "meta" mode, this variable contains a list of all the meta files 911updated. 912If not empty, it can be used to trigger processing of 913.Va .MAKE.META.FILES . 914.It Va .MAKE.META.FILES 915In "meta" mode, this variable contains a list of all the meta files 916used (updated or not). 917This list can be used to process the meta files to extract dependency 918information. 919.It Va .MAKE.META.IGNORE_PATHS 920Provides a list of path prefixes that should be ignored; 921because the contents are expected to change over time. 922The default list includes: 923.Ql Pa /dev /etc /proc /tmp /var/run /var/tmp 924.It Va .MAKE.META.PREFIX 925Defines the message printed for each meta file updated in "meta verbose" mode. 926The default value is: 927.Dl Building ${.TARGET:H:tA}/${.TARGET:T} 928.It Va .MAKEOVERRIDES 929This variable is used to record the names of variables assigned to 930on the command line, so that they may be exported as part of 931.Ql Ev MAKEFLAGS . 932This behaviour can be disabled by assigning an empty value to 933.Ql Va .MAKEOVERRIDES 934within a makefile. 935Extra variables can be exported from a makefile 936by appending their names to 937.Ql Va .MAKEOVERRIDES . 938.Ql Ev MAKEFLAGS 939is re-exported whenever 940.Ql Va .MAKEOVERRIDES 941is modified. 942.It Va .MAKE.PATH_FILEMON 943If 944.Nm 945was built with 946.Xr filemon 4 947support, this is set to the path of the device node. 948This allows makefiles to test for this support. 949.It Va .MAKE.PID 950The process-id of 951.Nm . 952.It Va .MAKE.PPID 953The parent process-id of 954.Nm . 955.It Va MAKE_PRINT_VAR_ON_ERROR 956When 957.Nm 958stops due to an error, it prints its name and the value of 959.Ql Va .CURDIR 960as well as the value of any variables named in 961.Ql Va MAKE_PRINT_VAR_ON_ERROR . 962.It Va .newline 963This variable is simply assigned a newline character as its value. 964This allows expansions using the 965.Cm \&:@ 966modifier to put a newline between 967iterations of the loop rather than a space. 968For example, the printing of 969.Ql Va MAKE_PRINT_VAR_ON_ERROR 970could be done as ${MAKE_PRINT_VAR_ON_ERROR:@v@$v='${$v}'${.newline}@}. 971.It Va .OBJDIR 972A path to the directory where the targets are built. 973Its value is determined by trying to 974.Xr chdir 2 975to the following directories in order and using the first match: 976.Bl -enum 977.It 978.Ev ${MAKEOBJDIRPREFIX}${.CURDIR} 979.Pp 980(Only if 981.Ql Ev MAKEOBJDIRPREFIX 982is set in the environment or on the command line.) 983.It 984.Ev ${MAKEOBJDIR} 985.Pp 986(Only if 987.Ql Ev MAKEOBJDIR 988is set in the environment or on the command line.) 989.It 990.Ev ${.CURDIR} Ns Pa /obj. Ns Ev ${MACHINE} 991.It 992.Ev ${.CURDIR} Ns Pa /obj 993.It 994.Pa /usr/obj/ Ns Ev ${.CURDIR} 995.It 996.Ev ${.CURDIR} 997.El 998.Pp 999Variable expansion is performed on the value before it's used, 1000so expressions such as 1001.Dl ${.CURDIR:S,^/usr/src,/var/obj,} 1002may be used. 1003This is especially useful with 1004.Ql Ev MAKEOBJDIR . 1005.Pp 1006.Ql Va .OBJDIR 1007may be modified in the makefile via the special target 1008.Ql Ic .OBJDIR . 1009In all cases, 1010.Nm 1011will 1012.Xr chdir 2 1013to the specified directory if it exists, and set 1014.Ql Va .OBJDIR 1015and 1016.Ql Ev PWD 1017to that directory before executing any targets. 1018. 1019.It Va .PARSEDIR 1020A path to the directory of the current 1021.Ql Pa Makefile 1022being parsed. 1023.It Va .PARSEFILE 1024The basename of the current 1025.Ql Pa Makefile 1026being parsed. 1027This variable and 1028.Ql Va .PARSEDIR 1029are both set only while the 1030.Ql Pa Makefiles 1031are being parsed. 1032If you want to retain their current values, assign them to a variable 1033using assignment with expansion: 1034.Pq Ql Cm \&:= . 1035.It Va .PATH 1036A variable that represents the list of directories that 1037.Nm 1038will search for files. 1039The search list should be updated using the target 1040.Ql Va .PATH 1041rather than the variable. 1042.It Ev PWD 1043Alternate path to the current directory. 1044.Nm 1045normally sets 1046.Ql Va .CURDIR 1047to the canonical path given by 1048.Xr getcwd 3 . 1049However, if the environment variable 1050.Ql Ev PWD 1051is set and gives a path to the current directory, then 1052.Nm 1053sets 1054.Ql Va .CURDIR 1055to the value of 1056.Ql Ev PWD 1057instead. 1058This behaviour is disabled if 1059.Ql Ev MAKEOBJDIRPREFIX 1060is set or 1061.Ql Ev MAKEOBJDIR 1062contains a variable transform. 1063.Ql Ev PWD 1064is set to the value of 1065.Ql Va .OBJDIR 1066for all programs which 1067.Nm 1068executes. 1069.It Ev .TARGETS 1070The list of targets explicitly specified on the command line, if any. 1071.It Ev VPATH 1072Colon-separated 1073.Pq Dq \&: 1074lists of directories that 1075.Nm 1076will search for files. 1077The variable is supported for compatibility with old make programs only, 1078use 1079.Ql Va .PATH 1080instead. 1081.El 1082.Ss Variable modifiers 1083Variable expansion may be modified to select or modify each word of the 1084variable (where a 1085.Dq word 1086is white-space delimited sequence of characters). 1087The general format of a variable expansion is as follows: 1088.Pp 1089.Dl ${variable[:modifier[:...]]} 1090.Pp 1091Each modifier begins with a colon, 1092which may be escaped with a backslash 1093.Pq Ql \e . 1094.Pp 1095A set of modifiers can be specified via a variable, as follows: 1096.Pp 1097.Dl modifier_variable=modifier[:...] 1098.Dl ${variable:${modifier_variable}[:...]} 1099.Pp 1100In this case the first modifier in the modifier_variable does not 1101start with a colon, since that must appear in the referencing 1102variable. 1103If any of the modifiers in the modifier_variable contain a dollar sign 1104.Pq Ql $ , 1105these must be doubled to avoid early expansion. 1106.Pp 1107The supported modifiers are: 1108.Bl -tag -width EEE 1109.It Cm \&:E 1110Replaces each word in the variable with its suffix. 1111.It Cm \&:H 1112Replaces each word in the variable with everything but the last component. 1113.It Cm \&:M Ns Ar pattern 1114Select only those words that match 1115.Ar pattern . 1116The standard shell wildcard characters 1117.Pf ( Ql * , 1118.Ql \&? , 1119and 1120.Ql Oo Oc ) 1121may 1122be used. 1123The wildcard characters may be escaped with a backslash 1124.Pq Ql \e . 1125As a consequence of the way values are split into words, matched, 1126and then joined, a construct like 1127.Dl ${VAR:M*} 1128will normalise the inter-word spacing, removing all leading and 1129trailing space, and converting multiple consecutive spaces 1130to single spaces. 1131. 1132.It Cm \&:N Ns Ar pattern 1133This is identical to 1134.Ql Cm \&:M , 1135but selects all words which do not match 1136.Ar pattern . 1137.It Cm \&:O 1138Order every word in variable alphabetically. 1139To sort words in 1140reverse order use the 1141.Ql Cm \&:O:[-1..1] 1142combination of modifiers. 1143.It Cm \&:Ox 1144Randomize words in variable. 1145The results will be different each time you are referring to the 1146modified variable; use the assignment with expansion 1147.Pq Ql Cm \&:= 1148to prevent such behaviour. 1149For example, 1150.Bd -literal -offset indent 1151LIST= uno due tre quattro 1152RANDOM_LIST= ${LIST:Ox} 1153STATIC_RANDOM_LIST:= ${LIST:Ox} 1154 1155all: 1156 @echo "${RANDOM_LIST}" 1157 @echo "${RANDOM_LIST}" 1158 @echo "${STATIC_RANDOM_LIST}" 1159 @echo "${STATIC_RANDOM_LIST}" 1160.Ed 1161may produce output similar to: 1162.Bd -literal -offset indent 1163quattro due tre uno 1164tre due quattro uno 1165due uno quattro tre 1166due uno quattro tre 1167.Ed 1168.It Cm \&:Q 1169Quotes every shell meta-character in the variable, so that it can be passed 1170safely through recursive invocations of 1171.Nm . 1172.It Cm \&:R 1173Replaces each word in the variable with everything but its suffix. 1174.It Cm \&:gmtime 1175The value is a format string for 1176.Xr strftime 3 , 1177using the current 1178.Xr gmtime 3 . 1179.It Cm \&:hash 1180Compute a 32bit hash of the value and encode it as hex digits. 1181.It Cm \&:localtime 1182The value is a format string for 1183.Xr strftime 3 , 1184using the current 1185.Xr localtime 3 . 1186.It Cm \&:tA 1187Attempt to convert variable to an absolute path using 1188.Xr realpath 3 , 1189if that fails, the value is unchanged. 1190.It Cm \&:tl 1191Converts variable to lower-case letters. 1192.It Cm \&:ts Ns Ar c 1193Words in the variable are normally separated by a space on expansion. 1194This modifier sets the separator to the character 1195.Ar c . 1196If 1197.Ar c 1198is omitted, then no separator is used. 1199The common escapes (including octal numeric codes), work as expected. 1200.It Cm \&:tu 1201Converts variable to upper-case letters. 1202.It Cm \&:tW 1203Causes the value to be treated as a single word 1204(possibly containing embedded white space). 1205See also 1206.Ql Cm \&:[*] . 1207.It Cm \&:tw 1208Causes the value to be treated as a sequence of 1209words delimited by white space. 1210See also 1211.Ql Cm \&:[@] . 1212.Sm off 1213.It Cm \&:S No \&/ Ar old_string No \&/ Ar new_string No \&/ Op Cm 1gW 1214.Sm on 1215Modify the first occurrence of 1216.Ar old_string 1217in the variable's value, replacing it with 1218.Ar new_string . 1219If a 1220.Ql g 1221is appended to the last slash of the pattern, all occurrences 1222in each word are replaced. 1223If a 1224.Ql 1 1225is appended to the last slash of the pattern, only the first word 1226is affected. 1227If a 1228.Ql W 1229is appended to the last slash of the pattern, 1230then the value is treated as a single word 1231(possibly containing embedded white space). 1232If 1233.Ar old_string 1234begins with a caret 1235.Pq Ql ^ , 1236.Ar old_string 1237is anchored at the beginning of each word. 1238If 1239.Ar old_string 1240ends with a dollar sign 1241.Pq Ql \&$ , 1242it is anchored at the end of each word. 1243Inside 1244.Ar new_string , 1245an ampersand 1246.Pq Ql \*[Am] 1247is replaced by 1248.Ar old_string 1249(without any 1250.Ql ^ 1251or 1252.Ql \&$ ) . 1253Any character may be used as a delimiter for the parts of the modifier 1254string. 1255The anchoring, ampersand and delimiter characters may be escaped with a 1256backslash 1257.Pq Ql \e . 1258.Pp 1259Variable expansion occurs in the normal fashion inside both 1260.Ar old_string 1261and 1262.Ar new_string 1263with the single exception that a backslash is used to prevent the expansion 1264of a dollar sign 1265.Pq Ql \&$ , 1266not a preceding dollar sign as is usual. 1267.Sm off 1268.It Cm \&:C No \&/ Ar pattern No \&/ Ar replacement No \&/ Op Cm 1gW 1269.Sm on 1270The 1271.Cm \&:C 1272modifier is just like the 1273.Cm \&:S 1274modifier except that the old and new strings, instead of being 1275simple strings, are an extended regular expression (see 1276.Xr regex 3 ) 1277string 1278.Ar pattern 1279and an 1280.Xr ed 1 Ns \-style 1281string 1282.Ar replacement . 1283Normally, the first occurrence of the pattern 1284.Ar pattern 1285in each word of the value is substituted with 1286.Ar replacement . 1287The 1288.Ql 1 1289modifier causes the substitution to apply to at most one word; the 1290.Ql g 1291modifier causes the substitution to apply to as many instances of the 1292search pattern 1293.Ar pattern 1294as occur in the word or words it is found in; the 1295.Ql W 1296modifier causes the value to be treated as a single word 1297(possibly containing embedded white space). 1298Note that 1299.Ql 1 1300and 1301.Ql g 1302are orthogonal; the former specifies whether multiple words are 1303potentially affected, the latter whether multiple substitutions can 1304potentially occur within each affected word. 1305.Pp 1306As for the 1307.Cm \&:S 1308modifier, the 1309.Ar pattern 1310and 1311.Ar replacement 1312are subjected to variable expansion before being parsed as 1313regular expressions. 1314.It Cm \&:T 1315Replaces each word in the variable with its last component. 1316.It Cm \&:u 1317Remove adjacent duplicate words (like 1318.Xr uniq 1 ) . 1319.Sm off 1320.It Cm \&:\&? Ar true_string Cm \&: Ar false_string 1321.Sm on 1322If the variable name (not its value), when parsed as a .if conditional 1323expression, evaluates to true, return as its value the 1324.Ar true_string , 1325otherwise return the 1326.Ar false_string . 1327Since the variable name is used as the expression, \&:\&? must be the 1328first modifier after the variable name itself - which will, of course, 1329usually contain variable expansions. 1330A common error is trying to use expressions like 1331.Dl ${NUMBERS:M42:?match:no} 1332which actually tests defined(NUMBERS), 1333to determine is any words match "42" you need to use something like: 1334.Dl ${"${NUMBERS:M42}" != \&"\&":?match:no} . 1335.It Ar :old_string=new_string 1336This is the 1337.At V 1338style variable substitution. 1339It must be the last modifier specified. 1340If 1341.Ar old_string 1342or 1343.Ar new_string 1344do not contain the pattern matching character 1345.Ar % 1346then it is assumed that they are 1347anchored at the end of each word, so only suffixes or entire 1348words may be replaced. 1349Otherwise 1350.Ar % 1351is the substring of 1352.Ar old_string 1353to be replaced in 1354.Ar new_string . 1355.Pp 1356Variable expansion occurs in the normal fashion inside both 1357.Ar old_string 1358and 1359.Ar new_string 1360with the single exception that a backslash is used to prevent the 1361expansion of a dollar sign 1362.Pq Ql \&$ , 1363not a preceding dollar sign as is usual. 1364.Sm off 1365.It Cm \&:@ Ar temp Cm @ Ar string Cm @ 1366.Sm on 1367This is the loop expansion mechanism from the OSF Development 1368Environment (ODE) make. 1369Unlike 1370.Cm \&.for 1371loops expansion occurs at the time of 1372reference. 1373Assign 1374.Ar temp 1375to each word in the variable and evaluate 1376.Ar string . 1377The ODE convention is that 1378.Ar temp 1379should start and end with a period. 1380For example. 1381.Dl ${LINKS:@.LINK.@${LN} ${TARGET} ${.LINK.}@} 1382.Pp 1383However a single character variable is often more readable: 1384.Dl ${MAKE_PRINT_VAR_ON_ERROR:@v@$v='${$v}'${.newline}@} 1385.It Cm \&:U Ns Ar newval 1386If the variable is undefined 1387.Ar newval 1388is the value. 1389If the variable is defined, the existing value is returned. 1390This is another ODE make feature. 1391It is handy for setting per-target CFLAGS for instance: 1392.Dl ${_${.TARGET:T}_CFLAGS:U${DEF_CFLAGS}} 1393If a value is only required if the variable is undefined, use: 1394.Dl ${VAR:D:Unewval} 1395.It Cm \&:D Ns Ar newval 1396If the variable is defined 1397.Ar newval 1398is the value. 1399.It Cm \&:L 1400The name of the variable is the value. 1401.It Cm \&:P 1402The path of the node which has the same name as the variable 1403is the value. 1404If no such node exists or its path is null, then the 1405name of the variable is used. 1406In order for this modifier to work, the name (node) must at least have 1407appeared on the rhs of a dependency. 1408.Sm off 1409.It Cm \&:\&! Ar cmd Cm \&! 1410.Sm on 1411The output of running 1412.Ar cmd 1413is the value. 1414.It Cm \&:sh 1415If the variable is non-empty it is run as a command and the output 1416becomes the new value. 1417.It Cm \&::= Ns Ar str 1418The variable is assigned the value 1419.Ar str 1420after substitution. 1421This modifier and its variations are useful in 1422obscure situations such as wanting to set a variable when shell commands 1423are being parsed. 1424These assignment modifiers always expand to 1425nothing, so if appearing in a rule line by themselves should be 1426preceded with something to keep 1427.Nm 1428happy. 1429.Pp 1430The 1431.Ql Cm \&:: 1432helps avoid false matches with the 1433.At V 1434style 1435.Cm \&:= 1436modifier and since substitution always occurs the 1437.Cm \&::= 1438form is vaguely appropriate. 1439.It Cm \&::?= Ns Ar str 1440As for 1441.Cm \&::= 1442but only if the variable does not already have a value. 1443.It Cm \&::+= Ns Ar str 1444Append 1445.Ar str 1446to the variable. 1447.It Cm \&::!= Ns Ar cmd 1448Assign the output of 1449.Ar cmd 1450to the variable. 1451.It Cm \&:\&[ Ns Ar range Ns Cm \&] 1452Selects one or more words from the value, 1453or performs other operations related to the way in which the 1454value is divided into words. 1455.Pp 1456Ordinarily, a value is treated as a sequence of words 1457delimited by white space. 1458Some modifiers suppress this behaviour, 1459causing a value to be treated as a single word 1460(possibly containing embedded white space). 1461An empty value, or a value that consists entirely of white-space, 1462is treated as a single word. 1463For the purposes of the 1464.Ql Cm \&:[] 1465modifier, the words are indexed both forwards using positive integers 1466(where index 1 represents the first word), 1467and backwards using negative integers 1468(where index \-1 represents the last word). 1469.Pp 1470The 1471.Ar range 1472is subjected to variable expansion, and the expanded result is 1473then interpreted as follows: 1474.Bl -tag -width index 1475.\" :[n] 1476.It Ar index 1477Selects a single word from the value. 1478.\" :[start..end] 1479.It Ar start Ns Cm \&.. Ns Ar end 1480Selects all words from 1481.Ar start 1482to 1483.Ar end , 1484inclusive. 1485For example, 1486.Ql Cm \&:[2..-1] 1487selects all words from the second word to the last word. 1488If 1489.Ar start 1490is greater than 1491.Ar end , 1492then the words are output in reverse order. 1493For example, 1494.Ql Cm \&:[-1..1] 1495selects all the words from last to first. 1496.\" :[*] 1497.It Cm \&* 1498Causes subsequent modifiers to treat the value as a single word 1499(possibly containing embedded white space). 1500Analogous to the effect of 1501\&"$*\&" 1502in Bourne shell. 1503.\" :[0] 1504.It 0 1505Means the same as 1506.Ql Cm \&:[*] . 1507.\" :[*] 1508.It Cm \&@ 1509Causes subsequent modifiers to treat the value as a sequence of words 1510delimited by white space. 1511Analogous to the effect of 1512\&"$@\&" 1513in Bourne shell. 1514.\" :[#] 1515.It Cm \&# 1516Returns the number of words in the value. 1517.El \" :[range] 1518.El 1519.Sh INCLUDE STATEMENTS, CONDITIONALS AND FOR LOOPS 1520Makefile inclusion, conditional structures and for loops reminiscent 1521of the C programming language are provided in 1522.Nm . 1523All such structures are identified by a line beginning with a single 1524dot 1525.Pq Ql \&. 1526character. 1527Files are included with either 1528.Cm \&.include Aq Ar file 1529or 1530.Cm \&.include Pf \*q Ar file Ns \*q . 1531Variables between the angle brackets or double quotes are expanded 1532to form the file name. 1533If angle brackets are used, the included makefile is expected to be in 1534the system makefile directory. 1535If double quotes are used, the including makefile's directory and any 1536directories specified using the 1537.Fl I 1538option are searched before the system 1539makefile directory. 1540For compatibility with other versions of 1541.Nm 1542.Ql include file ... 1543is also accepted. 1544If the include statement is written as 1545.Cm .-include 1546or as 1547.Cm .sinclude 1548then errors locating and/or opening include files are ignored. 1549.Pp 1550Conditional expressions are also preceded by a single dot as the first 1551character of a line. 1552The possible conditionals are as follows: 1553.Bl -tag -width Ds 1554.It Ic .error Ar message 1555The message is printed along with the name of the makefile and line number, 1556then 1557.Nm 1558will exit. 1559.It Ic .export Ar variable ... 1560Export the specified global variable. 1561If no variable list is provided, all globals are exported 1562except for internal variables (those that start with 1563.Ql \&. ) . 1564This is not affected by the 1565.Fl X 1566flag, so should be used with caution. 1567For compatibility with other 1568.Nm 1569programs 1570.Ql export variable=value 1571is also accepted. 1572.Pp 1573Appending a variable name to 1574.Va .MAKE.EXPORTED 1575is equivalent to exporting a variable. 1576.It Ic .export-env Ar variable ... 1577The same as 1578.Ql .export , 1579except that the variable is not appended to 1580.Va .MAKE.EXPORTED . 1581This allows exporting a value to the environment which is different from that 1582used by 1583.Nm 1584internally. 1585.It Ic .info Ar message 1586The message is printed along with the name of the makefile and line number. 1587.It Ic .undef Ar variable 1588Un-define the specified global variable. 1589Only global variables may be un-defined. 1590.It Ic .unexport Ar variable ... 1591The opposite of 1592.Ql .export . 1593The specified global 1594.Va variable 1595will be removed from 1596.Va .MAKE.EXPORTED . 1597If no variable list is provided, all globals are unexported, 1598and 1599.Va .MAKE.EXPORTED 1600deleted. 1601.It Ic .unexport-env 1602Unexport all globals previously exported and 1603clear the environment inherited from the parent. 1604This operation will cause a memory leak of the original environment, 1605so should be used sparingly. 1606Testing for 1607.Va .MAKE.LEVEL 1608being 0, would make sense. 1609Also note that any variables which originated in the parent environment 1610should be explicitly preserved if desired. 1611For example: 1612.Bd -literal -offset indent 1613.Li .if ${.MAKE.LEVEL} == 0 1614PATH := ${PATH} 1615.Li .unexport-env 1616.Li .export PATH 1617.Li .endif 1618.Pp 1619.Ed 1620Would result in an environment containing only 1621.Ql Ev PATH , 1622which is the minimal useful environment. 1623Actually 1624.Ql Ev .MAKE.LEVEL 1625will also be pushed into the new environment. 1626.It Ic .warning Ar message 1627The message prefixed by 1628.Ql Pa warning: 1629is printed along with the name of the makefile and line number. 1630.It Ic \&.if Oo \&! Oc Ns Ar expression Op Ar operator expression ... 1631Test the value of an expression. 1632.It Ic .ifdef Oo \&! Oc Ns Ar variable Op Ar operator variable ... 1633Test the value of a variable. 1634.It Ic .ifndef Oo \&! Oc Ns Ar variable Op Ar operator variable ... 1635Test the value of a variable. 1636.It Ic .ifmake Oo \&! Oc Ns Ar target Op Ar operator target ... 1637Test the target being built. 1638.It Ic .ifnmake Oo \&! Ns Oc Ar target Op Ar operator target ... 1639Test the target being built. 1640.It Ic .else 1641Reverse the sense of the last conditional. 1642.It Ic .elif Oo \&! Ns Oc Ar expression Op Ar operator expression ... 1643A combination of 1644.Ql Ic .else 1645followed by 1646.Ql Ic .if . 1647.It Ic .elifdef Oo \&! Oc Ns Ar variable Op Ar operator variable ... 1648A combination of 1649.Ql Ic .else 1650followed by 1651.Ql Ic .ifdef . 1652.It Ic .elifndef Oo \&! Oc Ns Ar variable Op Ar operator variable ... 1653A combination of 1654.Ql Ic .else 1655followed by 1656.Ql Ic .ifndef . 1657.It Ic .elifmake Oo \&! Oc Ns Ar target Op Ar operator target ... 1658A combination of 1659.Ql Ic .else 1660followed by 1661.Ql Ic .ifmake . 1662.It Ic .elifnmake Oo \&! Oc Ns Ar target Op Ar operator target ... 1663A combination of 1664.Ql Ic .else 1665followed by 1666.Ql Ic .ifnmake . 1667.It Ic .endif 1668End the body of the conditional. 1669.El 1670.Pp 1671The 1672.Ar operator 1673may be any one of the following: 1674.Bl -tag -width "Cm XX" 1675.It Cm \&|\&| 1676Logical OR. 1677.It Cm \&\*[Am]\*[Am] 1678Logical 1679.Tn AND ; 1680of higher precedence than 1681.Dq \&|\&| . 1682.El 1683.Pp 1684As in C, 1685.Nm 1686will only evaluate a conditional as far as is necessary to determine 1687its value. 1688Parentheses may be used to change the order of evaluation. 1689The boolean operator 1690.Ql Ic \&! 1691may be used to logically negate an entire 1692conditional. 1693It is of higher precedence than 1694.Ql Ic \&\*[Am]\*[Am] . 1695.Pp 1696The value of 1697.Ar expression 1698may be any of the following: 1699.Bl -tag -width defined 1700.It Ic defined 1701Takes a variable name as an argument and evaluates to true if the variable 1702has been defined. 1703.It Ic make 1704Takes a target name as an argument and evaluates to true if the target 1705was specified as part of 1706.Nm Ns 's 1707command line or was declared the default target (either implicitly or 1708explicitly, see 1709.Va .MAIN ) 1710before the line containing the conditional. 1711.It Ic empty 1712Takes a variable, with possible modifiers, and evaluates to true if 1713the expansion of the variable would result in an empty string. 1714.It Ic exists 1715Takes a file name as an argument and evaluates to true if the file exists. 1716The file is searched for on the system search path (see 1717.Va .PATH ) . 1718.It Ic target 1719Takes a target name as an argument and evaluates to true if the target 1720has been defined. 1721.It Ic commands 1722Takes a target name as an argument and evaluates to true if the target 1723has been defined and has commands associated with it. 1724.El 1725.Pp 1726.Ar Expression 1727may also be an arithmetic or string comparison. 1728Variable expansion is 1729performed on both sides of the comparison, after which the integral 1730values are compared. 1731A value is interpreted as hexadecimal if it is 1732preceded by 0x, otherwise it is decimal; octal numbers are not supported. 1733The standard C relational operators are all supported. 1734If after 1735variable expansion, either the left or right hand side of a 1736.Ql Ic == 1737or 1738.Ql Ic "!=" 1739operator is not an integral value, then 1740string comparison is performed between the expanded 1741variables. 1742If no relational operator is given, it is assumed that the expanded 1743variable is being compared against 0 or an empty string in the case 1744of a string comparison. 1745.Pp 1746When 1747.Nm 1748is evaluating one of these conditional expressions, and it encounters 1749a (white-space separated) word it doesn't recognize, either the 1750.Dq make 1751or 1752.Dq defined 1753expression is applied to it, depending on the form of the conditional. 1754If the form is 1755.Ql Ic .ifdef , 1756.Ql Ic .ifndef , 1757or 1758.Ql Ic .if 1759the 1760.Dq defined 1761expression is applied. 1762Similarly, if the form is 1763.Ql Ic .ifmake 1764or 1765.Ql Ic .ifnmake , the 1766.Dq make 1767expression is applied. 1768.Pp 1769If the conditional evaluates to true the parsing of the makefile continues 1770as before. 1771If it evaluates to false, the following lines are skipped. 1772In both cases this continues until a 1773.Ql Ic .else 1774or 1775.Ql Ic .endif 1776is found. 1777.Pp 1778For loops are typically used to apply a set of rules to a list of files. 1779The syntax of a for loop is: 1780.Pp 1781.Bl -tag -compact -width Ds 1782.It Ic \&.for Ar variable Oo Ar variable ... Oc Ic in Ar expression 1783.It Aq make-rules 1784.It Ic \&.endfor 1785.El 1786.Pp 1787After the for 1788.Ic expression 1789is evaluated, it is split into words. 1790On each iteration of the loop, one word is taken and assigned to each 1791.Ic variable , 1792in order, and these 1793.Ic variables 1794are substituted into the 1795.Ic make-rules 1796inside the body of the for loop. 1797The number of words must come out even; that is, if there are three 1798iteration variables, the number of words provided must be a multiple 1799of three. 1800.Sh COMMENTS 1801Comments begin with a hash 1802.Pq Ql \&# 1803character, anywhere but in a shell 1804command line, and continue to the end of an unescaped new line. 1805.Sh SPECIAL SOURCES (ATTRIBUTES) 1806.Bl -tag -width .IGNOREx 1807.It Ic .EXEC 1808Target is never out of date, but always execute commands anyway. 1809.It Ic .IGNORE 1810Ignore any errors from the commands associated with this target, exactly 1811as if they all were preceded by a dash 1812.Pq Ql \- . 1813.\" .It Ic .INVISIBLE 1814.\" XXX 1815.\" .It Ic .JOIN 1816.\" XXX 1817.It Ic .MADE 1818Mark all sources of this target as being up-to-date. 1819.It Ic .MAKE 1820Execute the commands associated with this target even if the 1821.Fl n 1822or 1823.Fl t 1824options were specified. 1825Normally used to mark recursive 1826.Nm Ns s . 1827.It Ic .META 1828Create a meta file for the target, even if it is flagged as 1829.Ic .PHONY , 1830.Ic .MAKE , 1831or 1832.Ic .SPECIAL . 1833Usage in conjunction with 1834.Ic .MAKE 1835is the most likely case. 1836In "meta" mode, the target is out-of-date if the meta file is missing. 1837.It Ic .NOMETA 1838Do not create a meta file for the target. 1839Meta files are also not created for 1840.Ic .PHONY , 1841.Ic .MAKE , 1842or 1843.Ic .SPECIAL 1844targets. 1845.It Ic .NOMETA_CMP 1846Ignore differences in commands when deciding if target is out of date. 1847This is useful if the command contains a value which always changes. 1848If the number of commands change, though, the target will still be out of date. 1849The same effect applies to any command line that uses the variable 1850.Va .OODATE , 1851which can be used for that purpose even when not otherwise needed or desired: 1852.Bd -literal -offset indent 1853 1854skip-compare-for-some: 1855 @echo this will be compared 1856 @echo this will not ${.OODATE:M.NOMETA_CMP} 1857 @echo this will also be compared 1858 1859.Ed 1860The 1861.Cm \&:M 1862pattern suppresses any expansion of the unwanted variable. 1863.It Ic .NOPATH 1864Do not search for the target in the directories specified by 1865.Ic .PATH . 1866.It Ic .NOTMAIN 1867Normally 1868.Nm 1869selects the first target it encounters as the default target to be built 1870if no target was specified. 1871This source prevents this target from being selected. 1872.It Ic .OPTIONAL 1873If a target is marked with this attribute and 1874.Nm 1875can't figure out how to create it, it will ignore this fact and assume 1876the file isn't needed or already exists. 1877.It Ic .PHONY 1878The target does not 1879correspond to an actual file; it is always considered to be out of date, 1880and will not be created with the 1881.Fl t 1882option. 1883Suffix-transformation rules are not applied to 1884.Ic .PHONY 1885targets. 1886.It Ic .PRECIOUS 1887When 1888.Nm 1889is interrupted, it normally removes any partially made targets. 1890This source prevents the target from being removed. 1891.It Ic .RECURSIVE 1892Synonym for 1893.Ic .MAKE . 1894.It Ic .SILENT 1895Do not echo any of the commands associated with this target, exactly 1896as if they all were preceded by an at sign 1897.Pq Ql @ . 1898.It Ic .USE 1899Turn the target into 1900.Nm Ns 's 1901version of a macro. 1902When the target is used as a source for another target, the other target 1903acquires the commands, sources, and attributes (except for 1904.Ic .USE ) 1905of the 1906source. 1907If the target already has commands, the 1908.Ic .USE 1909target's commands are appended 1910to them. 1911.It Ic .USEBEFORE 1912Exactly like 1913.Ic .USE , 1914but prepend the 1915.Ic .USEBEFORE 1916target commands to the target. 1917.It Ic .WAIT 1918If 1919.Ic .WAIT 1920appears in a dependency line, the sources that precede it are 1921made before the sources that succeed it in the line. 1922Since the dependents of files are not made until the file itself 1923could be made, this also stops the dependents being built unless they 1924are needed for another branch of the dependency tree. 1925So given: 1926.Bd -literal 1927x: a .WAIT b 1928 echo x 1929a: 1930 echo a 1931b: b1 1932 echo b 1933b1: 1934 echo b1 1935 1936.Ed 1937the output is always 1938.Ql a , 1939.Ql b1 , 1940.Ql b , 1941.Ql x . 1942.br 1943The ordering imposed by 1944.Ic .WAIT 1945is only relevant for parallel makes. 1946.El 1947.Sh SPECIAL TARGETS 1948Special targets may not be included with other targets, i.e. they must be 1949the only target specified. 1950.Bl -tag -width .BEGINx 1951.It Ic .BEGIN 1952Any command lines attached to this target are executed before anything 1953else is done. 1954.It Ic .DEFAULT 1955This is sort of a 1956.Ic .USE 1957rule for any target (that was used only as a 1958source) that 1959.Nm 1960can't figure out any other way to create. 1961Only the shell script is used. 1962The 1963.Ic .IMPSRC 1964variable of a target that inherits 1965.Ic .DEFAULT Ns 's 1966commands is set 1967to the target's own name. 1968.It Ic .END 1969Any command lines attached to this target are executed after everything 1970else is done. 1971.It Ic .ERROR 1972Any command lines attached to this target are executed when another target fails. 1973The 1974.Ic .ERROR_TARGET 1975variable is set to the target that failed. 1976See also 1977.Ic MAKE_PRINT_VAR_ON_ERROR . 1978.It Ic .IGNORE 1979Mark each of the sources with the 1980.Ic .IGNORE 1981attribute. 1982If no sources are specified, this is the equivalent of specifying the 1983.Fl i 1984option. 1985.It Ic .INTERRUPT 1986If 1987.Nm 1988is interrupted, the commands for this target will be executed. 1989.It Ic .MAIN 1990If no target is specified when 1991.Nm 1992is invoked, this target will be built. 1993.It Ic .MAKEFLAGS 1994This target provides a way to specify flags for 1995.Nm 1996when the makefile is used. 1997The flags are as if typed to the shell, though the 1998.Fl f 1999option will have 2000no effect. 2001.\" XXX: NOT YET!!!! 2002.\" .It Ic .NOTPARALLEL 2003.\" The named targets are executed in non parallel mode. 2004.\" If no targets are 2005.\" specified, then all targets are executed in non parallel mode. 2006.It Ic .NOPATH 2007Apply the 2008.Ic .NOPATH 2009attribute to any specified sources. 2010.It Ic .NOTPARALLEL 2011Disable parallel mode. 2012.It Ic .NO_PARALLEL 2013Synonym for 2014.Ic .NOTPARALLEL , 2015for compatibility with other pmake variants. 2016.It Ic .OBJDIR 2017The source is a new value for 2018.Ql Va .OBJDIR . 2019If it exists, 2020.Nm 2021will 2022.Xr chdir 2 2023to it and update the value of 2024.Ql Va .OBJDIR . 2025.It Ic .ORDER 2026The named targets are made in sequence. 2027This ordering does not add targets to the list of targets to be made. 2028Since the dependents of a target do not get built until the target itself 2029could be built, unless 2030.Ql a 2031is built by another part of the dependency graph, 2032the following is a dependency loop: 2033.Bd -literal 2034\&.ORDER: b a 2035b: a 2036.Ed 2037.Pp 2038The ordering imposed by 2039.Ic .ORDER 2040is only relevant for parallel makes. 2041.\" XXX: NOT YET!!!! 2042.\" .It Ic .PARALLEL 2043.\" The named targets are executed in parallel mode. 2044.\" If no targets are 2045.\" specified, then all targets are executed in parallel mode. 2046.It Ic .PATH 2047The sources are directories which are to be searched for files not 2048found in the current directory. 2049If no sources are specified, any previously specified directories are 2050deleted. 2051If the source is the special 2052.Ic .DOTLAST 2053target, then the current working 2054directory is searched last. 2055.It Ic .PATH. Ns Va suffix 2056Like 2057.Ic .PATH 2058but applies only to files with a particular suffix. 2059The suffix must have been previously declared with 2060.Ic .SUFFIXES . 2061.It Ic .PHONY 2062Apply the 2063.Ic .PHONY 2064attribute to any specified sources. 2065.It Ic .PRECIOUS 2066Apply the 2067.Ic .PRECIOUS 2068attribute to any specified sources. 2069If no sources are specified, the 2070.Ic .PRECIOUS 2071attribute is applied to every 2072target in the file. 2073.It Ic .SHELL 2074Sets the shell that 2075.Nm 2076will use to execute commands. 2077The sources are a set of 2078.Ar field=value 2079pairs. 2080.Bl -tag -width hasErrCtls 2081.It Ar name 2082This is the minimal specification, used to select one of the builtin 2083shell specs; 2084.Ar sh , 2085.Ar ksh , 2086and 2087.Ar csh . 2088.It Ar path 2089Specifies the path to the shell. 2090.It Ar hasErrCtl 2091Indicates whether the shell supports exit on error. 2092.It Ar check 2093The command to turn on error checking. 2094.It Ar ignore 2095The command to disable error checking. 2096.It Ar echo 2097The command to turn on echoing of commands executed. 2098.It Ar quiet 2099The command to turn off echoing of commands executed. 2100.It Ar filter 2101The output to filter after issuing the 2102.Ar quiet 2103command. 2104It is typically identical to 2105.Ar quiet . 2106.It Ar errFlag 2107The flag to pass the shell to enable error checking. 2108.It Ar echoFlag 2109The flag to pass the shell to enable command echoing. 2110.It Ar newline 2111The string literal to pass the shell that results in a single newline 2112character when used outside of any quoting characters. 2113.El 2114Example: 2115.Bd -literal 2116\&.SHELL: name=ksh path=/bin/ksh hasErrCtl=true \e 2117 check="set \-e" ignore="set +e" \e 2118 echo="set \-v" quiet="set +v" filter="set +v" \e 2119 echoFlag=v errFlag=e newline="'\en'" 2120.Ed 2121.It Ic .SILENT 2122Apply the 2123.Ic .SILENT 2124attribute to any specified sources. 2125If no sources are specified, the 2126.Ic .SILENT 2127attribute is applied to every 2128command in the file. 2129.It Ic .STALE 2130This target gets run when a dependency file contains stale entries, having 2131.Va .ALLSRC 2132set to the name of that dependency file. 2133.It Ic .SUFFIXES 2134Each source specifies a suffix to 2135.Nm . 2136If no sources are specified, any previously specified suffixes are deleted. 2137It allows the creation of suffix-transformation rules. 2138.Pp 2139Example: 2140.Bd -literal 2141\&.SUFFIXES: .o 2142\&.c.o: 2143 cc \-o ${.TARGET} \-c ${.IMPSRC} 2144.Ed 2145.El 2146.Sh ENVIRONMENT 2147.Nm 2148uses the following environment variables, if they exist: 2149.Ev MACHINE , 2150.Ev MACHINE_ARCH , 2151.Ev MAKE , 2152.Ev MAKEFLAGS , 2153.Ev MAKEOBJDIR , 2154.Ev MAKEOBJDIRPREFIX , 2155.Ev MAKESYSPATH , 2156.Ev PWD , 2157and 2158.Ev TMPDIR . 2159.Pp 2160.Ev MAKEOBJDIRPREFIX 2161and 2162.Ev MAKEOBJDIR 2163may only be set in the environment or on the command line to 2164.Nm 2165and not as makefile variables; 2166see the description of 2167.Ql Va .OBJDIR 2168for more details. 2169.Sh FILES 2170.Bl -tag -width /usr/share/mk -compact 2171.It .depend 2172list of dependencies 2173.It Makefile 2174list of dependencies 2175.It makefile 2176list of dependencies 2177.It sys.mk 2178system makefile 2179.It /usr/share/mk 2180system makefile directory 2181.El 2182.Sh COMPATIBILITY 2183The basic make syntax is compatible between different versions of make; 2184however the special variables, variable modifiers and conditionals are not. 2185.Ss Older versions 2186An incomplete list of changes in older versions of 2187.Nm : 2188.Pp 2189The way that .for loop variables are substituted changed after 2190.Nx 5.0 2191so that they still appear to be variable expansions. 2192In particular this stops them being treated as syntax, and removes some 2193obscure problems using them in .if statements. 2194.Pp 2195The way that parallel makes are scheduled changed in 2196.Nx 4.0 2197so that .ORDER and .WAIT apply recursively to the dependent nodes. 2198The algorithms used may change again in the future. 2199.Ss Other make dialects 2200Other make dialects (GNU make, SVR4 make, POSIX make, etc.) do not 2201support most of the features of 2202.Nm 2203as described in this manual. 2204Most notably: 2205.Bl -bullet -offset indent 2206.It 2207The 2208.Ic .WAIT 2209and 2210.Ic .ORDER 2211declarations and most functionality pertaining to parallelization. 2212(GNU make supports parallelization but lacks these features needed to 2213control it effectively.) 2214.It 2215Directives, including for loops and conditionals and most of the 2216forms of include files. 2217(GNU make has its own incompatible and less powerful syntax for 2218conditionals.) 2219.It 2220All built-in variables that begin with a dot. 2221.It 2222Most of the special sources and targets that begin with a dot, 2223with the notable exception of 2224.Ic .PHONY , 2225.Ic .PRECIOUS , 2226and 2227.Ic .SUFFIXES . 2228.It 2229Variable modifiers, except for the 2230.Dl :old=new 2231string substitution, which does not portably support globbing with 2232.Ql % 2233and historically only works on declared suffixes. 2234.It 2235The 2236.Ic $> 2237variable even in its short form; most makes support this functionality 2238but its name varies. 2239.El 2240.Pp 2241Some features are somewhat more portable, such as assignment with 2242.Ic += , 2243.Ic ?= , 2244and 2245.Ic != . 2246The 2247.Ic .PATH 2248functionality is based on an older feature 2249.Ic VPATH 2250found in GNU make and many versions of SVR4 make; however, 2251historically its behavior is too ill-defined (and too buggy) to rely 2252upon. 2253.Pp 2254The 2255.Ic $@ 2256and 2257.Ic $< 2258variables are more or less universally portable, as is the 2259.Ic $(MAKE) 2260variable. 2261Basic use of suffix rules (for files only in the current directory, 2262not trying to chain transformations together, etc.) is also reasonably 2263portable. 2264.Sh SEE ALSO 2265.Xr mkdep 1 2266.Sh HISTORY 2267A 2268.Nm 2269command appeared in 2270.At v7 . 2271This 2272.Nm 2273implementation is based on Adam De Boor's pmake program which was written 2274for Sprite at Berkeley. 2275It was designed to be a parallel distributed make running jobs on different 2276machines using a daemon called 2277.Dq customs . 2278.Pp 2279Historically the target/dependency 2280.Dq FRC 2281has been used to FoRCe rebuilding (since the target/dependency 2282does not exist... unless someone creates an 2283.Dq FRC 2284file). 2285.Sh BUGS 2286The 2287.Nm 2288syntax is difficult to parse without actually acting of the data. 2289For instance finding the end of a variable use should involve scanning each 2290the modifiers using the correct terminator for each field. 2291In many places 2292.Nm 2293just counts {} and () in order to find the end of a variable expansion. 2294.Pp 2295There is no way of escaping a space character in a filename. 2296