1.\" $NetBSD: make.1,v 1.179 2010/06/30 01:03: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 June 30, 2010 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 BeikNnqrstWX 41.Bk -words 42.Op Fl C Ar directory 43.Ek 44.Bk -words 45.Op Fl D Ar variable 46.Ek 47.Bk -words 48.Op Fl d Ar flags 49.Ek 50.Bk -words 51.Op Fl f Ar makefile 52.Ek 53.Bk -words 54.Op Fl I Ar directory 55.Ek 56.Bk -words 57.Op Fl J Ar private 58.Ek 59.Bk -words 60.Op Fl j Ar max_jobs 61.Ek 62.Bk -words 63.Op Fl m Ar directory 64.Ek 65.Bk -words 66.Op Fl T Ar file 67.Ek 68.Bk -words 69.Op Fl V Ar variable 70.Ek 71.Op Ar variable=value 72.Bk -words 73.Op Ar target ... 74.Ek 75.Sh DESCRIPTION 76.Nm 77is a program designed to simplify the maintenance of other programs. 78Its input is a list of specifications as to the files upon which programs 79and other files depend. 80If no 81.Fl f Ar makefile 82makefile option is given, 83.Nm 84will try to open 85.Ql Pa makefile 86then 87.Ql Pa Makefile 88in order to find the specifications. 89If the file 90.Ql Pa .depend 91exists, it is read (see 92.Xr mkdep 1 ) . 93.Pp 94This manual page is intended as a reference document only. 95For a more thorough description of 96.Nm 97and makefiles, please refer to 98.%T "Make \- A Tutorial" . 99.Pp 100.Nm 101will prepend the contents of the 102.Va MAKEFLAGS 103environment variable to the command line arguments before parsing them. 104.Pp 105The options are as follows: 106.Bl -tag -width Ds 107.It Fl B 108Try to be backwards compatible by executing a single shell per command and 109by executing the commands to make the sources of a dependency line in sequence. 110.It Fl C Ar directory 111Change to 112.Ar directory 113before reading the makefiles or doing anything else. 114If multiple 115.Fl C 116options are specified, each is interpreted relative to the previous one: 117.Fl C Pa / Fl C Pa etc 118is equivalent to 119.Fl C Pa /etc . 120.It Fl D Ar variable 121Define 122.Ar variable 123to be 1, in the global context. 124.It Fl d Ar [-]flags 125Turn on debugging, and specify which portions of 126.Nm 127are to print debugging information. 128Unless the flags are preceded by 129.Ql - 130they are added to the 131.Va MAKEFLAGS 132environment variable and will be processed by any child make processes. 133By default, debugging information is printed to standard error, 134but this can be changed using the 135.Ar F 136debugging flag. 137The debugging output is always unbuffered; in addition, if debugging 138is enabled but debugging output is not directed to standard output, 139then the standard output is line buffered. 140.Ar Flags 141is one or more of the following: 142.Bl -tag -width Ds 143.It Ar A 144Print all possible debugging information; 145equivalent to specifying all of the debugging flags. 146.It Ar a 147Print debugging information about archive searching and caching. 148.It Ar C 149Print debugging information about current working directory. 150.It Ar c 151Print debugging information about conditional evaluation. 152.It Ar d 153Print debugging information about directory searching and caching. 154.It Ar e 155Print debugging information about failed commands and targets. 156.It Ar F Ns Oo Sy \&+ Oc Ns Ar filename 157Specify where debugging output is written. 158This must be the last flag, because it consumes the remainder of 159the argument. 160If the character immediately after the 161.Ql F 162flag is 163.Ql \&+ , 164then the file will be opened in append mode; 165otherwise the file will be overwritten. 166If the file name is 167.Ql stdout 168or 169.Ql stderr 170then debugging output will be written to the 171standard output or standard error output file descriptors respectively 172(and the 173.Ql \&+ 174option has no effect). 175Otherwise, the output will be written to the named file. 176If the file name ends 177.Ql .%d 178then the 179.Ql %d 180is replaced by the pid. 181.It Ar f 182Print debugging information about loop evaluation. 183.It Ar "g1" 184Print the input graph before making anything. 185.It Ar "g2" 186Print the input graph after making everything, or before exiting 187on error. 188.It Ar "g3" 189Print the input graph before exiting on error. 190.It Ar j 191Print debugging information about running multiple shells. 192.It Ar l 193Print commands in Makefiles regardless of whether or not they are prefixed by 194.Ql @ 195or other "quiet" flags. 196Also known as "loud" behavior. 197.It Ar m 198Print debugging information about making targets, including modification 199dates. 200.It Ar n 201Don't delete the temporary command scripts created when running commands. 202These temporary scripts are created in the directory 203referred to by the 204.Ev TMPDIR 205environment variable, or in 206.Pa /tmp 207if 208.Ev TMPDIR 209is unset or set to the empty string. 210The temporary scripts are created by 211.Xr mkstemp 3 , 212and have names of the form 213.Pa makeXXXXXX . 214.Em NOTE : 215This can create many files in 216.Ev TMPDIR 217or 218.Pa /tmp , 219so use with care. 220.It Ar p 221Print debugging information about makefile parsing. 222.It Ar s 223Print debugging information about suffix-transformation rules. 224.It Ar t 225Print debugging information about target list maintenance. 226.It Ar v 227Print debugging information about variable assignment. 228.It Ar x 229Run shell commands with 230.Fl x 231so the actual commands are printed as they are executed. 232.El 233.It Fl e 234Specify that environment variables override macro assignments within 235makefiles. 236.It Fl f Ar makefile 237Specify a makefile to read instead of the default 238.Ql Pa makefile . 239If 240.Ar makefile 241is 242.Ql Fl , 243standard input is read. 244Multiple makefiles may be specified, and are read in the order specified. 245.It Fl I Ar directory 246Specify a directory in which to search for makefiles and included makefiles. 247The system makefile directory (or directories, see the 248.Fl m 249option) is automatically included as part of this list. 250.It Fl i 251Ignore non-zero exit of shell commands in the makefile. 252Equivalent to specifying 253.Ql Fl 254before each command line in the makefile. 255.It Fl J Ar private 256This option should 257.Em not 258be specified by the user. 259.Pp 260When the 261.Ar j 262option is in use in a recursive build, this option is passed by a make 263to child makes to allow all the make processes in the build to 264cooperate to avoid overloading the system. 265.It Fl j Ar max_jobs 266Specify the maximum number of jobs that 267.Nm 268may have running at any one time. 269Turns compatibility mode off, unless the 270.Ar B 271flag is also specified. 272When compatibility mode is off, all commands associated with a 273target are executed in a single shell invocation as opposed to the 274traditional one shell invocation per line. 275This can break traditional scripts which change directories on each 276command invocation and then expect to start with a fresh environment 277on the next line. 278It is more efficient to correct the scripts rather than turn backwards 279compatibility on. 280.It Fl k 281Continue processing after errors are encountered, but only on those targets 282that do not depend on the target whose creation caused the error. 283.It Fl m Ar directory 284Specify a directory in which to search for sys.mk and makefiles included 285via the 286.Ao Ar file Ac Ns -style 287include statement. 288The 289.Fl m 290option can be used multiple times to form a search path. 291This path will override the default system include path: /usr/share/mk. 292Furthermore the system include path will be appended to the search path used 293for 294.Qo Ar file Qc Ns -style 295include statements (see the 296.Fl I 297option). 298.Pp 299If a file or directory name in the 300.Fl m 301argument (or the 302.Ev MAKESYSPATH 303environment variable) starts with the string 304.Qq \&.../ 305then 306.Nm 307will search for the specified file or directory named in the remaining part 308of the argument string. 309The search starts with the current directory of 310the Makefile and then works upward towards the root of the filesystem. 311If the search is successful, then the resulting directory replaces the 312.Qq \&.../ 313specification in the 314.Fl m 315argument. 316If used, this feature allows 317.Nm 318to easily search in the current source tree for customized sys.mk files 319(e.g., by using 320.Qq \&.../mk/sys.mk 321as an argument). 322.It Fl n 323Display the commands that would have been executed, but do not 324actually execute them unless the target depends on the .MAKE special 325source (see below). 326.It Fl N 327Display the commands which would have been executed, but do not 328actually execute any of them; useful for debugging top-level makefiles 329without descending into subdirectories. 330.It Fl q 331Do not execute any commands, but exit 0 if the specified targets are 332up-to-date and 1, otherwise. 333.It Fl r 334Do not use the built-in rules specified in the system makefile. 335.It Fl s 336Do not echo any commands as they are executed. 337Equivalent to specifying 338.Ql Ic @ 339before each command line in the makefile. 340.It Fl T Ar tracefile 341When used with the 342.Fl j 343flag, 344append a trace record to 345.Ar tracefile 346for each job started and completed. 347.It Fl t 348Rather than re-building a target as specified in the makefile, create it 349or update its modification time to make it appear up-to-date. 350.It Fl V Ar variable 351Print 352.Nm Ns 's 353idea of the value of 354.Ar variable , 355in the global context. 356Do not build any targets. 357Multiple instances of this option may be specified; 358the variables will be printed one per line, 359with a blank line for each null or undefined variable. 360If 361.Ar variable 362contains a 363.Ql \&$ 364then the value will be expanded before printing. 365.It Fl W 366Treat any warnings during makefile parsing as errors. 367.It Fl X 368Don't export variables passed on the command line to the environment 369individually. 370Variables passed on the command line are still exported 371via the 372.Va MAKEFLAGS 373environment variable. 374This option may be useful on systems which have a small limit on the 375size of command arguments. 376.It Ar variable=value 377Set the value of the variable 378.Ar variable 379to 380.Ar value . 381Normally, all values passed on the command line are also exported to 382sub-makes in the environment. 383The 384.Fl X 385flag disables this behavior. 386Variable assignments should follow options for POSIX compatibility 387but no ordering is enforced. 388.El 389.Pp 390There are seven different types of lines in a makefile: file dependency 391specifications, shell commands, variable assignments, include statements, 392conditional directives, for loops, and comments. 393.Pp 394In general, lines may be continued from one line to the next by ending 395them with a backslash 396.Pq Ql \e . 397The trailing newline character and initial whitespace on the following 398line are compressed into a single space. 399.Sh FILE DEPENDENCY SPECIFICATIONS 400Dependency lines consist of one or more targets, an operator, and zero 401or more sources. 402This creates a relationship where the targets 403.Dq depend 404on the sources 405and are usually created from them. 406The exact relationship between the target and the source is determined 407by the operator that separates them. 408The three operators are as follows: 409.Bl -tag -width flag 410.It Ic \&: 411A target is considered out-of-date if its modification time is less than 412those of any of its sources. 413Sources for a target accumulate over dependency lines when this operator 414is used. 415The target is removed if 416.Nm 417is interrupted. 418.It Ic \&! 419Targets are always re-created, but not until all sources have been 420examined and re-created as necessary. 421Sources for a target accumulate over dependency lines when this operator 422is used. 423The target is removed if 424.Nm 425is interrupted. 426.It Ic \&:: 427If no sources are specified, the target is always re-created. 428Otherwise, a target is considered out-of-date if any of its sources has 429been modified more recently than the target. 430Sources for a target do not accumulate over dependency lines when this 431operator is used. 432The target will not be removed if 433.Nm 434is interrupted. 435.El 436.Pp 437Targets and sources may contain the shell wildcard values 438.Ql \&? , 439.Ql * , 440.Ql [] , 441and 442.Ql {} . 443The values 444.Ql \&? , 445.Ql * , 446and 447.Ql [] 448may only be used as part of the final 449component of the target or source, and must be used to describe existing 450files. 451The value 452.Ql {} 453need not necessarily be used to describe existing files. 454Expansion is in directory order, not alphabetically as done in the shell. 455.Sh SHELL COMMANDS 456Each target may have associated with it a series of shell commands, normally 457used to create the target. 458Each of the commands in this script 459.Em must 460be preceded by a tab. 461While any target may appear on a dependency line, only one of these 462dependencies may be followed by a creation script, unless the 463.Ql Ic \&:: 464operator is used. 465.Pp 466If the first characters of the command line 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 \- 484causes any non-zero exit status of the command line to be ignored. 485.Sh VARIABLE ASSIGNMENTS 486Variables in make are much like variables in the shell, and, by tradition, 487consist of all upper-case letters. 488.Ss Variable assignment modifiers 489The five operators that can be used to assign values to variables are as 490follows: 491.Bl -tag -width Ds 492.It Ic \&= 493Assign the value to the variable. 494Any previous value is overridden. 495.It Ic \&+= 496Append the value to the current value of the variable. 497.It Ic \&?= 498Assign the value to the variable if it is not already defined. 499.It Ic \&:= 500Assign with expansion, i.e. expand the value before assigning it 501to the variable. 502Normally, expansion is not done until the variable is referenced. 503.Em NOTE : 504References to undefined variables are 505.Em not 506expanded. 507This can cause problems when variable modifiers are used. 508.It Ic \&!= 509Expand the value and pass it to the shell for execution and assign 510the result to the variable. 511Any newlines in the result are replaced with spaces. 512.El 513.Pp 514Any white-space before the assigned 515.Ar value 516is removed; if the value is being appended, a single space is inserted 517between the previous contents of the variable and the appended value. 518.Pp 519Variables are expanded by surrounding the variable name with either 520curly braces 521.Pq Ql {} 522or parentheses 523.Pq Ql () 524and preceding it with 525a dollar sign 526.Pq Ql \&$ . 527If the variable name contains only a single letter, the surrounding 528braces or parentheses are not required. 529This shorter form is not recommended. 530.Pp 531If the variable name contains a dollar, then the name itself is expanded first. 532This allows almost arbitrary variable names, however names containing dollar, 533braces, parenthesis, or whitespace are really best avoided! 534.Pp 535If the result of expanding a variable contains a dollar sign 536.Pq Ql \&$ 537the string is expanded again. 538.Pp 539Variable substitution occurs at three distinct times, depending on where 540the variable is being used. 541.Bl -enum 542.It 543Variables in dependency lines are expanded as the line is read. 544.It 545Variables in shell commands are expanded when the shell command is 546executed. 547.It 548.Dq .for 549loop index variables are expanded on each loop iteration. 550Note that other variables are not expanded inside loops so 551the following example code: 552.Bd -literal -offset indent 553 554.Dv .for i in 1 2 3 555a+= ${i} 556j= ${i} 557b+= ${j} 558.Dv .endfor 559 560all: 561 @echo ${a} 562 @echo ${b} 563 564.Ed 565will print: 566.Bd -literal -offset indent 5671 2 3 5683 3 3 569 570.Ed 571Because while ${a} contains 572.Dq 1 2 3 573after the loop is executed, ${b} 574contains 575.Dq ${j} ${j} ${j} 576which expands to 577.Dq 3 3 3 578since after the loop completes ${j} contains 579.Dq 3 . 580.El 581.Ss Variable classes 582The four different classes of variables (in order of increasing precedence) 583are: 584.Bl -tag -width Ds 585.It Environment variables 586Variables defined as part of 587.Nm Ns 's 588environment. 589.It Global variables 590Variables defined in the makefile or in included makefiles. 591.It Command line variables 592Variables defined as part of the command line. 593.It Local variables 594Variables that are defined specific to a certain target. 595The seven local variables are as follows: 596.Bl -tag -width ".ARCHIVE" 597.It Va .ALLSRC 598The list of all sources for this target; also known as 599.Ql Va \&\*[Gt] . 600.It Va .ARCHIVE 601The name of the archive file. 602.It Va .IMPSRC 603In suffix-transformation rules, the name/path of the source from which the 604target is to be transformed (the 605.Dq implied 606source); also known as 607.Ql Va \&\*[Lt] . 608It is not defined in explicit rules. 609.It Va .MEMBER 610The name of the archive member. 611.It Va .OODATE 612The list of sources for this target that were deemed out-of-date; also 613known as 614.Ql Va \&? . 615.It Va .PREFIX 616The file prefix of the target, containing only the file portion, no suffix 617or preceding directory components; also known as 618.Ql Va * . 619.It Va .TARGET 620The name of the target; also known as 621.Ql Va @ . 622.El 623.Pp 624The shorter forms 625.Ql Va @ , 626.Ql Va \&? , 627.Ql Va \&\*[Lt] , 628.Ql Va \&\*[Gt] , 629and 630.Ql Va * 631are permitted for backward 632compatibility with historical makefiles and are not recommended. 633The six variables 634.Ql Va "@F" , 635.Ql Va "@D" , 636.Ql Va "\*[Lt]F" , 637.Ql Va "\*[Lt]D" , 638.Ql Va "*F" , 639and 640.Ql Va "*D" 641are permitted for compatibility with 642.At V 643makefiles and are not recommended. 644.Pp 645Four of the local variables may be used in sources on dependency lines 646because they expand to the proper value for each target on the line. 647These variables are 648.Ql Va .TARGET , 649.Ql Va .PREFIX , 650.Ql Va .ARCHIVE , 651and 652.Ql Va .MEMBER . 653.El 654.Ss Additional built-in variables 655In addition, 656.Nm 657sets or knows about the following variables: 658.Bl -tag -width .MAKEOVERRIDES 659.It Va \&$ 660A single dollar sign 661.Ql \&$ , 662i.e. 663.Ql \&$$ 664expands to a single dollar 665sign. 666.It Va .ALLTARGETS 667The list of all targets encountered in the Makefile. 668If evaluated during 669Makefile parsing, lists only those targets encountered thus far. 670.It Va .CURDIR 671A path to the directory where 672.Nm 673was executed. 674Refer to the description of 675.Ql Ev PWD 676for more details. 677.It Ev MAKE 678The name that 679.Nm 680was executed with 681.Pq Va argv[0] . 682For compatibility 683.Nm 684also sets 685.Va .MAKE 686with the same value. 687The preferred variable to use is the environment variable 688.Ev MAKE 689because it is more compatible with other versions of 690.Nm 691and cannot be confused with the special target with the same name. 692.It Va .MAKE.DEPENDFILE 693Names the makefile (default 694.Ql Pa .depend ) 695from which generated dependencies are read. 696.It Va .MAKE.EXPORTED 697The list of variables exported by 698.Nm . 699.It Va .MAKE.JOBS 700The argument to the 701.Fl j 702option. 703.It Va .MAKE.JOB.PREFIX 704If 705.Nm 706is run with 707.Ar j 708then output for each target is prefixed with a token 709.Ql --- target --- 710the first part of which can be controlled via 711.Va .MAKE.JOB.PREFIX . 712.br 713For example: 714.Li .MAKE.JOB.PREFIX=${.newline}---${.MAKE:T}[${.MAKE.PID}] 715would produce tokens like 716.Ql ---make[1234] target --- 717making it easier to track the degree of parallelism being achieved. 718.It Ev MAKEFLAGS 719The environment variable 720.Ql Ev MAKEFLAGS 721may contain anything that 722may be specified on 723.Nm Ns 's 724command line. 725Anything specified on 726.Nm Ns 's 727command line is appended to the 728.Ql Ev MAKEFLAGS 729variable which is then 730entered into the environment for all programs which 731.Nm 732executes. 733.It Va .MAKE.LEVEL 734The recursion depth of 735.Nm . 736The initial instance of 737.Nm 738will be 0, and an incremented value is put into the environment 739to be seen by the next generation. 740This allows tests like: 741.Li .if ${.MAKE.LEVEL} == 0 742to protect things which should only be evaluated in the initial instance of 743.Nm . 744.It Va .MAKE.MAKEFILE_PREFERENCE 745The ordered list of makefile names 746(default 747.Ql Pa makefile , 748.Ql Pa Makefile ) 749that 750.Nm 751will look for. 752.It Va .MAKE.MAKEFILES 753The list of makefiles read by 754.Nm , 755which is useful for tracking dependencies. 756Each makefile is recorded only once, regardless of the number of times read. 757.It Va .MAKE.MODE 758Processed after reading all makefiles. 759Can affect the mode that 760.Nm 761runs in. 762Currently just 763.Ql Pa compat 764mode. 765.It Va .MAKEOVERRIDES 766This variable is used to record the names of variables assigned to 767on the command line, so that they may be exported as part of 768.Ql Ev MAKEFLAGS . 769This behaviour can be disabled by assigning an empty value to 770.Ql Va .MAKEOVERRIDES 771within a makefile. 772Extra variables can be exported from a makefile 773by appending their names to 774.Ql Va .MAKEOVERRIDES . 775.Ql Ev MAKEFLAGS 776is re-exported whenever 777.Ql Va .MAKEOVERRIDES 778is modified. 779.It Va .MAKE.PID 780The process-id of 781.Nm . 782.It Va .MAKE.PPID 783The parent process-id of 784.Nm . 785.It Va MAKE_PRINT_VAR_ON_ERROR 786When 787.Nm 788stops due to an error, it prints its name and the value of 789.Ql Va .CURDIR 790as well as the value of any variables named in 791.Ql Va MAKE_PRINT_VAR_ON_ERROR . 792.It Va .newline 793This variable is simply assigned a newline character as its value. 794This allows expansions using the 795.Cm \&:@ 796modifier to put a newline between 797iterations of the loop rather than a space. 798For example, the printing of 799.Ql Va MAKE_PRINT_VAR_ON_ERROR 800could be done as ${MAKE_PRINT_VAR_ON_ERROR:@v@$v='${$v}'${.newline}@}. 801.It Va .OBJDIR 802A path to the directory where the targets are built. 803Its value is determined by trying to 804.Xr chdir 2 805to the following directories in order and using the first match: 806.Bl -enum 807.It 808.Ev ${MAKEOBJDIRPREFIX}${.CURDIR} 809.Pp 810(Only if 811.Ql Ev MAKEOBJDIRPREFIX 812is set in the environment or on the command line.) 813.It 814.Ev ${MAKEOBJDIR} 815.Pp 816(Only if 817.Ql Ev MAKEOBJDIR 818is set in the environment or on the command line.) 819.It 820.Ev ${.CURDIR} Ns Pa /obj. Ns Ev ${MACHINE} 821.It 822.Ev ${.CURDIR} Ns Pa /obj 823.It 824.Pa /usr/obj/ Ns Ev ${.CURDIR} 825.It 826.Ev ${.CURDIR} 827.El 828.Pp 829Variable expansion is performed on the value before it's used, 830so expressions such as 831.Dl ${.CURDIR:S,^/usr/src,/var/obj,} 832may be used. 833This is especially useful with 834.Ql Ev MAKEOBJDIR . 835.Pp 836.Ql Va .OBJDIR 837may be modified in the makefile as a global variable. 838In all cases, 839.Nm 840will 841.Xr chdir 2 842to 843.Ql Va .OBJDIR 844and set 845.Ql Ev PWD 846to that directory before executing any targets. 847. 848.It Va .PARSEDIR 849A path to the directory of the current 850.Ql Pa Makefile 851being parsed. 852.It Va .PARSEFILE 853The basename of the current 854.Ql Pa Makefile 855being parsed. 856This variable and 857.Ql Va .PARSEDIR 858are both set only while the 859.Ql Pa Makefiles 860are being parsed. 861.It Va .PATH 862A variable that represents the list of directories that 863.Nm 864will search for files. 865The search list should be updated using the target 866.Ql Va .PATH 867rather than the variable. 868.It Ev PWD 869Alternate path to the current directory. 870.Nm 871normally sets 872.Ql Va .CURDIR 873to the canonical path given by 874.Xr getcwd 3 . 875However, if the environment variable 876.Ql Ev PWD 877is set and gives a path to the current directory, then 878.Nm 879sets 880.Ql Va .CURDIR 881to the value of 882.Ql Ev PWD 883instead. 884This behaviour is disabled if 885.Ql Ev MAKEOBJDIRPREFIX 886is set or 887.Ql Ev MAKEOBJDIR 888contains a variable transform. 889.Ql Ev PWD 890is set to the value of 891.Ql Va .OBJDIR 892for all programs which 893.Nm 894executes. 895.It Ev .TARGETS 896The list of targets explicitly specified on the command line, if any. 897.It Ev VPATH 898Colon-separated 899.Pq Dq \&: 900lists of directories that 901.Nm 902will search for files. 903The variable is supported for compatibility with old make programs only, 904use 905.Ql Va .PATH 906instead. 907.El 908.Ss Variable modifiers 909Variable expansion may be modified to select or modify each word of the 910variable (where a 911.Dq word 912is white-space delimited sequence of characters). 913The general format of a variable expansion is as follows: 914.Pp 915.Dl ${variable[:modifier[:...]]} 916.Pp 917Each modifier begins with a colon, 918which may be escaped with a backslash 919.Pq Ql \e . 920.Pp 921A set of modifiers can be specified via a variable, as follows: 922.Pp 923.Dl modifier_variable=modifier[:...] 924.Dl ${variable:${modifier_variable}[:...]} 925.Pp 926In this case the first modifier in the modifier_variable does not 927start with a colon, since that must appear in the referencing 928variable. 929If any of the modifiers in the modifier_variable contain a dollar sign 930.Pq Ql $ , 931these must be doubled to avoid early expansion. 932.Pp 933The supported modifiers are: 934.Bl -tag -width EEE 935.It Cm \&:E 936Replaces each word in the variable with its suffix. 937.It Cm \&:H 938Replaces each word in the variable with everything but the last component. 939.It Cm \&:M Ns Ar pattern 940Select only those words that match 941.Ar pattern . 942The standard shell wildcard characters 943.Pf ( Ql * , 944.Ql \&? , 945and 946.Ql Oo Oc ) 947may 948be used. 949The wildcard characters may be escaped with a backslash 950.Pq Ql \e . 951.It Cm \&:N Ns Ar pattern 952This is identical to 953.Ql Cm \&:M , 954but selects all words which do not match 955.Ar pattern . 956.It Cm \&:O 957Order every word in variable alphabetically. 958To sort words in 959reverse order use the 960.Ql Cm \&:O:[-1..1] 961combination of modifiers. 962.It Cm \&:Ox 963Randomize words in variable. 964The results will be different each time you are referring to the 965modified variable; use the assignment with expansion 966.Pq Ql Cm \&:= 967to prevent such behaviour. 968For example, 969.Bd -literal -offset indent 970LIST= uno due tre quattro 971RANDOM_LIST= ${LIST:Ox} 972STATIC_RANDOM_LIST:= ${LIST:Ox} 973 974all: 975 @echo "${RANDOM_LIST}" 976 @echo "${RANDOM_LIST}" 977 @echo "${STATIC_RANDOM_LIST}" 978 @echo "${STATIC_RANDOM_LIST}" 979.Ed 980may produce output similar to: 981.Bd -literal -offset indent 982quattro due tre uno 983tre due quattro uno 984due uno quattro tre 985due uno quattro tre 986.Ed 987.It Cm \&:Q 988Quotes every shell meta-character in the variable, so that it can be passed 989safely through recursive invocations of 990.Nm . 991.It Cm \&:R 992Replaces each word in the variable with everything but its suffix. 993.It Cm \&:tA 994Attempt to convert variable to an absolute path using 995.Xr realpath 3 , 996if that fails, the value is unchanged. 997.It Cm \&:tl 998Converts variable to lower-case letters. 999.It Cm \&:ts Ns Ar c 1000Words in the variable are normally separated by a space on expansion. 1001This modifier sets the separator to the character 1002.Ar c . 1003If 1004.Ar c 1005is omitted, then no separator is used. 1006The common escapes (including octal numeric codes), work as expected. 1007.It Cm \&:tu 1008Converts variable to upper-case letters. 1009.It Cm \&:tW 1010Causes the value to be treated as a single word 1011(possibly containing embedded white space). 1012See also 1013.Ql Cm \&:[*] . 1014.It Cm \&:tw 1015Causes the value to be treated as a sequence of 1016words delimited by white space. 1017See also 1018.Ql Cm \&:[@] . 1019.Sm off 1020.It Cm \&:S No \&/ Ar old_string No \&/ Ar new_string No \&/ Op Cm 1gW 1021.Sm on 1022Modify the first occurrence of 1023.Ar old_string 1024in the variable's value, replacing it with 1025.Ar new_string . 1026If a 1027.Ql g 1028is appended to the last slash of the pattern, all occurrences 1029in each word are replaced. 1030If a 1031.Ql 1 1032is appended to the last slash of the pattern, only the first word 1033is affected. 1034If a 1035.Ql W 1036is appended to the last slash of the pattern, 1037then the value is treated as a single word 1038(possibly containing embedded white space). 1039If 1040.Ar old_string 1041begins with a caret 1042.Pq Ql ^ , 1043.Ar old_string 1044is anchored at the beginning of each word. 1045If 1046.Ar old_string 1047ends with a dollar sign 1048.Pq Ql \&$ , 1049it is anchored at the end of each word. 1050Inside 1051.Ar new_string , 1052an ampersand 1053.Pq Ql \*[Am] 1054is replaced by 1055.Ar old_string 1056(without any 1057.Ql ^ 1058or 1059.Ql \&$ ) . 1060Any character may be used as a delimiter for the parts of the modifier 1061string. 1062The anchoring, ampersand and delimiter characters may be escaped with a 1063backslash 1064.Pq Ql \e . 1065.Pp 1066Variable expansion occurs in the normal fashion inside both 1067.Ar old_string 1068and 1069.Ar new_string 1070with the single exception that a backslash is used to prevent the expansion 1071of a dollar sign 1072.Pq Ql \&$ , 1073not a preceding dollar sign as is usual. 1074.Sm off 1075.It Cm \&:C No \&/ Ar pattern No \&/ Ar replacement No \&/ Op Cm 1gW 1076.Sm on 1077The 1078.Cm \&:C 1079modifier is just like the 1080.Cm \&:S 1081modifier except that the old and new strings, instead of being 1082simple strings, are a regular expression (see 1083.Xr regex 3 ) 1084string 1085.Ar pattern 1086and an 1087.Xr ed 1 Ns \-style 1088string 1089.Ar replacement . 1090Normally, the first occurrence of the pattern 1091.Ar pattern 1092in each word of the value is substituted with 1093.Ar replacement . 1094The 1095.Ql 1 1096modifier causes the substitution to apply to at most one word; the 1097.Ql g 1098modifier causes the substitution to apply to as many instances of the 1099search pattern 1100.Ar pattern 1101as occur in the word or words it is found in; the 1102.Ql W 1103modifier causes the value to be treated as a single word 1104(possibly containing embedded white space). 1105Note that 1106.Ql 1 1107and 1108.Ql g 1109are orthogonal; the former specifies whether multiple words are 1110potentially affected, the latter whether multiple substitutions can 1111potentially occur within each affected word. 1112.It Cm \&:T 1113Replaces each word in the variable with its last component. 1114.It Cm \&:u 1115Remove adjacent duplicate words (like 1116.Xr uniq 1 ) . 1117.Sm off 1118.It Cm \&:\&? Ar true_string Cm \&: Ar false_string 1119.Sm on 1120If the variable name (not its value), when parsed as a .if conditional 1121expression, evaluates to true, return as its value the 1122.Ar true_string , 1123otherwise return the 1124.Ar false_string . 1125Since the variable name is used as the expression, \&:\&? must be the 1126first modifier after the variable name itself - which will, of course, 1127usually contain variable expansions. 1128A common error is trying to use expressions like 1129.Dl ${NUMBERS:M42:?match:no} 1130which actually tests defined(NUMBERS), 1131to determine is any words match "42" you need to use something like: 1132.Dl ${${NUMBERS:M42} != "":?match:no} . 1133.It Ar :old_string=new_string 1134This is the 1135.At V 1136style variable substitution. 1137It must be the last modifier specified. 1138If 1139.Ar old_string 1140or 1141.Ar new_string 1142do not contain the pattern matching character 1143.Ar % 1144then it is assumed that they are 1145anchored at the end of each word, so only suffixes or entire 1146words may be replaced. 1147Otherwise 1148.Ar % 1149is the substring of 1150.Ar old_string 1151to be replaced in 1152.Ar new_string . 1153.Pp 1154Variable expansion occurs in the normal fashion inside both 1155.Ar old_string 1156and 1157.Ar new_string 1158with the single exception that a backslash is used to prevent the 1159expansion of a dollar sign 1160.Pq Ql \&$ , 1161not a preceding dollar sign as is usual. 1162.Sm off 1163.It Cm \&:@ Ar temp Cm @ Ar string Cm @ 1164.Sm on 1165This is the loop expansion mechanism from the OSF Development 1166Environment (ODE) make. 1167Unlike 1168.Cm \&.for 1169loops expansion occurs at the time of 1170reference. 1171Assign 1172.Ar temp 1173to each word in the variable and evaluate 1174.Ar string . 1175The ODE convention is that 1176.Ar temp 1177should start and end with a period. 1178For example. 1179.Dl ${LINKS:@.LINK.@${LN} ${TARGET} ${.LINK.}@} 1180.It Cm \&:U Ns Ar newval 1181If the variable is undefined 1182.Ar newval 1183is the value. 1184If the variable is defined, the existing value is returned. 1185This is another ODE make feature. 1186It is handy for setting per-target CFLAGS for instance: 1187.Dl ${_${.TARGET:T}_CFLAGS:U${DEF_CFLAGS}} 1188If a value is only required if the variable is undefined, use: 1189.Dl ${VAR:D:Unewval} 1190.It Cm \&:D Ns Ar newval 1191If the variable is defined 1192.Ar newval 1193is the value. 1194.It Cm \&:L 1195The name of the variable is the value. 1196.It Cm \&:P 1197The path of the node which has the same name as the variable 1198is the value. 1199If no such node exists or its path is null, then the 1200name of the variable is used. 1201.Sm off 1202.It Cm \&:\&! Ar cmd Cm \&! 1203.Sm on 1204The output of running 1205.Ar cmd 1206is the value. 1207.It Cm \&:sh 1208If the variable is non-empty it is run as a command and the output 1209becomes the new value. 1210.It Cm \&::= Ns Ar str 1211The variable is assigned the value 1212.Ar str 1213after substitution. 1214This modifier and its variations are useful in 1215obscure situations such as wanting to set a variable when shell commands 1216are being parsed. 1217These assignment modifiers always expand to 1218nothing, so if appearing in a rule line by themselves should be 1219preceded with something to keep 1220.Nm 1221happy. 1222.Pp 1223The 1224.Ql Cm \&:: 1225helps avoid false matches with the 1226.At V 1227style 1228.Cm \&:= 1229modifier and since substitution always occurs the 1230.Cm \&::= 1231form is vaguely appropriate. 1232.It Cm \&::?= Ns Ar str 1233As for 1234.Cm \&::= 1235but only if the variable does not already have a value. 1236.It Cm \&::+= Ns Ar str 1237Append 1238.Ar str 1239to the variable. 1240.It Cm \&::!= Ns Ar cmd 1241Assign the output of 1242.Ar cmd 1243to the variable. 1244.It Cm \&:\&[ Ns Ar range Ns Cm \&] 1245Selects one or more words from the value, 1246or performs other operations related to the way in which the 1247value is divided into words. 1248.Pp 1249Ordinarily, a value is treated as a sequence of words 1250delimited by white space. 1251Some modifiers suppress this behaviour, 1252causing a value to be treated as a single word 1253(possibly containing embedded white space). 1254An empty value, or a value that consists entirely of white-space, 1255is treated as a single word. 1256For the purposes of the 1257.Ql Cm \&:[] 1258modifier, the words are indexed both forwards using positive integers 1259(where index 1 represents the first word), 1260and backwards using negative integers 1261(where index -1 represents the last word). 1262.Pp 1263The 1264.Ar range 1265is subjected to variable expansion, and the expanded result is 1266then interpreted as follows: 1267.Bl -tag -width index 1268.\" :[n] 1269.It Ar index 1270Selects a single word from the value. 1271.\" :[start..end] 1272.It Ar start Ns Cm \&.. Ns Ar end 1273Selects all words from 1274.Ar start 1275to 1276.Ar end , 1277inclusive. 1278For example, 1279.Ql Cm \&:[2..-1] 1280selects all words from the second word to the last word. 1281If 1282.Ar start 1283is greater than 1284.Ar end , 1285then the words are output in reverse order. 1286For example, 1287.Ql Cm \&:[-1..1] 1288selects all the words from last to first. 1289.\" :[*] 1290.It Cm \&* 1291Causes subsequent modifiers to treat the value as a single word 1292(possibly containing embedded white space). 1293Analogous to the effect of 1294\&"$*\&" 1295in Bourne shell. 1296.\" :[0] 1297.It 0 1298Means the same as 1299.Ql Cm \&:[*] . 1300.\" :[*] 1301.It Cm \&@ 1302Causes subsequent modifiers to treat the value as a sequence of words 1303delimited by white space. 1304Analogous to the effect of 1305\&"$@\&" 1306in Bourne shell. 1307.\" :[#] 1308.It Cm \&# 1309Returns the number of words in the value. 1310.El \" :[range] 1311.El 1312.Sh INCLUDE STATEMENTS, CONDITIONALS AND FOR LOOPS 1313Makefile inclusion, conditional structures and for loops reminiscent 1314of the C programming language are provided in 1315.Nm . 1316All such structures are identified by a line beginning with a single 1317dot 1318.Pq Ql \&. 1319character. 1320Files are included with either 1321.Cm \&.include Aq Ar file 1322or 1323.Cm \&.include Pf \*q Ar file Ns \*q . 1324Variables between the angle brackets or double quotes are expanded 1325to form the file name. 1326If angle brackets are used, the included makefile is expected to be in 1327the system makefile directory. 1328If double quotes are used, the including makefile's directory and any 1329directories specified using the 1330.Fl I 1331option are searched before the system 1332makefile directory. 1333For compatibility with other versions of 1334.Nm 1335.Ql include file ... 1336is also accepted. 1337If the include statement is written as 1338.Cm .-include 1339or as 1340.Cm .sinclude 1341then errors locating and/or opening include files are ignored. 1342.Pp 1343Conditional expressions are also preceded by a single dot as the first 1344character of a line. 1345The possible conditionals are as follows: 1346.Bl -tag -width Ds 1347.It Ic .error Ar message 1348The message is printed along with the name of the makefile and line number, 1349then 1350.Nm 1351will exit. 1352.It Ic .export Ar variable ... 1353Export the specified global variable. 1354If no variable list is provided, all globals are exported 1355except for internal variables (those that start with 1356.Ql \&. ) . 1357This is not affected by the 1358.Fl X 1359flag, so should be used with caution. 1360.Pp 1361Appending a variable name to 1362.Va .MAKE.EXPORTED 1363is equivalent to exporting a variable. 1364.It Ic .export-env Ar variable ... 1365The same as 1366.Ql .export , 1367except that the variable is not appended to 1368.Va .MAKE.EXPORTED . 1369This allows exporting a value to the environment which is different from that 1370used by 1371.Nm 1372internally. 1373.It Ic .info Ar message 1374The message is printed along with the name of the makefile and line number. 1375.It Ic .undef Ar variable 1376Un-define the specified global variable. 1377Only global variables may be un-defined. 1378.It Ic .unexport Ar variable ... 1379The opposite of 1380.Ql .export . 1381The specified global 1382.Va variable 1383will be removed from 1384.Va .MAKE.EXPORTED . 1385If no variable list is provided, all globals are unexported, 1386and 1387.Va .MAKE.EXPORTED 1388deleted. 1389.It Ic .unexport-env 1390Unexport all globals previously exported and 1391clear the environment inherited from the parent. 1392This operation will cause a memory leak of the original environment, 1393so should be used sparingly. 1394Testing for 1395.Va .MAKE.LEVEL 1396being 0, would make sense. 1397Also note that any variables which originated in the parent environment 1398should be explicitly preserved if desired. 1399For example: 1400.Bd -literal -offset indent 1401.Li .if ${.MAKE.LEVEL} == 0 1402PATH := ${PATH} 1403.Li .unexport-env 1404.Li .export PATH 1405.Li .endif 1406.Pp 1407.Ed 1408Would result in an environment containing only 1409.Ql Ev PATH , 1410which is the minimal useful environment. 1411Actually 1412.Ql Ev .MAKE.LEVEL 1413will also be pushed into the new environment. 1414.It Ic .warning Ar message 1415The message prefixed by 1416.Ql Pa warning: 1417is printed along with the name of the makefile and line number. 1418.It Ic \&.if Oo \&! Oc Ns Ar expression Op Ar operator expression ... 1419Test the value of an expression. 1420.It Ic .ifdef Oo \&! Oc Ns Ar variable Op Ar operator variable ... 1421Test the value of a variable. 1422.It Ic .ifndef Oo \&! Oc Ns Ar variable Op Ar operator variable ... 1423Test the value of a variable. 1424.It Ic .ifmake Oo \&! Oc Ns Ar target Op Ar operator target ... 1425Test the target being built. 1426.It Ic .ifnmake Oo \&! Ns Oc Ar target Op Ar operator target ... 1427Test the target being built. 1428.It Ic .else 1429Reverse the sense of the last conditional. 1430.It Ic .elif Oo \&! Ns Oc Ar expression Op Ar operator expression ... 1431A combination of 1432.Ql Ic .else 1433followed by 1434.Ql Ic .if . 1435.It Ic .elifdef Oo \&! Oc Ns Ar variable Op Ar operator variable ... 1436A combination of 1437.Ql Ic .else 1438followed by 1439.Ql Ic .ifdef . 1440.It Ic .elifndef Oo \&! Oc Ns Ar variable Op Ar operator variable ... 1441A combination of 1442.Ql Ic .else 1443followed by 1444.Ql Ic .ifndef . 1445.It Ic .elifmake Oo \&! Oc Ns Ar target Op Ar operator target ... 1446A combination of 1447.Ql Ic .else 1448followed by 1449.Ql Ic .ifmake . 1450.It Ic .elifnmake Oo \&! Oc Ns Ar target Op Ar operator target ... 1451A combination of 1452.Ql Ic .else 1453followed by 1454.Ql Ic .ifnmake . 1455.It Ic .endif 1456End the body of the conditional. 1457.El 1458.Pp 1459The 1460.Ar operator 1461may be any one of the following: 1462.Bl -tag -width "Cm XX" 1463.It Cm \&|\&| 1464Logical OR. 1465.It Cm \&\*[Am]\*[Am] 1466Logical 1467.Tn AND ; 1468of higher precedence than 1469.Dq \&|\&| . 1470.El 1471.Pp 1472As in C, 1473.Nm 1474will only evaluate a conditional as far as is necessary to determine 1475its value. 1476Parentheses may be used to change the order of evaluation. 1477The boolean operator 1478.Ql Ic \&! 1479may be used to logically negate an entire 1480conditional. 1481It is of higher precedence than 1482.Ql Ic \&\*[Am]\*[Am] . 1483.Pp 1484The value of 1485.Ar expression 1486may be any of the following: 1487.Bl -tag -width defined 1488.It Ic defined 1489Takes a variable name as an argument and evaluates to true if the variable 1490has been defined. 1491.It Ic make 1492Takes a target name as an argument and evaluates to true if the target 1493was specified as part of 1494.Nm Ns 's 1495command line or was declared the default target (either implicitly or 1496explicitly, see 1497.Va .MAIN ) 1498before the line containing the conditional. 1499.It Ic empty 1500Takes a variable, with possible modifiers, and evaluates to true if 1501the expansion of the variable would result in an empty string. 1502.It Ic exists 1503Takes a file name as an argument and evaluates to true if the file exists. 1504The file is searched for on the system search path (see 1505.Va .PATH ) . 1506.It Ic target 1507Takes a target name as an argument and evaluates to true if the target 1508has been defined. 1509.It Ic commands 1510Takes a target name as an argument and evaluates to true if the target 1511has been defined and has commands associated with it. 1512.El 1513.Pp 1514.Ar Expression 1515may also be an arithmetic or string comparison. 1516Variable expansion is 1517performed on both sides of the comparison, after which the integral 1518values are compared. 1519A value is interpreted as hexadecimal if it is 1520preceded by 0x, otherwise it is decimal; octal numbers are not supported. 1521The standard C relational operators are all supported. 1522If after 1523variable expansion, either the left or right hand side of a 1524.Ql Ic == 1525or 1526.Ql Ic "!=" 1527operator is not an integral value, then 1528string comparison is performed between the expanded 1529variables. 1530If no relational operator is given, it is assumed that the expanded 1531variable is being compared against 0 or an empty string in the case 1532of a string comparison. 1533.Pp 1534When 1535.Nm 1536is evaluating one of these conditional expressions, and it encounters 1537a (white-space separated) word it doesn't recognize, either the 1538.Dq make 1539or 1540.Dq defined 1541expression is applied to it, depending on the form of the conditional. 1542If the form is 1543.Ql Ic .ifdef , 1544.Ql Ic .ifndef , 1545or 1546.Ql Ic .if 1547the 1548.Dq defined 1549expression is applied. 1550Similarly, if the form is 1551.Ql Ic .ifmake 1552or 1553.Ql Ic .ifnmake , the 1554.Dq make 1555expression is applied. 1556.Pp 1557If the conditional evaluates to true the parsing of the makefile continues 1558as before. 1559If it evaluates to false, the following lines are skipped. 1560In both cases this continues until a 1561.Ql Ic .else 1562or 1563.Ql Ic .endif 1564is found. 1565.Pp 1566For loops are typically used to apply a set of rules to a list of files. 1567The syntax of a for loop is: 1568.Pp 1569.Bl -tag -compact -width Ds 1570.It Ic \&.for Ar variable Oo Ar variable ... Oc Ic in Ar expression 1571.It Aq make-rules 1572.It Ic \&.endfor 1573.El 1574.Pp 1575After the for 1576.Ic expression 1577is evaluated, it is split into words. 1578On each iteration of the loop, one word is taken and assigned to each 1579.Ic variable , 1580in order, and these 1581.Ic variables 1582are substituted into the 1583.Ic make-rules 1584inside the body of the for loop. 1585The number of words must come out even; that is, if there are three 1586iteration variables, the number of words provided must be a multiple 1587of three. 1588.Sh COMMENTS 1589Comments begin with a hash 1590.Pq Ql \&# 1591character, anywhere but in a shell 1592command line, and continue to the end of an unescaped new line. 1593.Sh SPECIAL SOURCES (ATTRIBUTES) 1594.Bl -tag -width .IGNOREx 1595.It Ic .EXEC 1596Target is never out of date, but always execute commands anyway. 1597.It Ic .IGNORE 1598Ignore any errors from the commands associated with this target, exactly 1599as if they all were preceded by a dash 1600.Pq Ql \- . 1601.\" .It Ic .INVISIBLE 1602.\" XXX 1603.\" .It Ic .JOIN 1604.\" XXX 1605.It Ic .MADE 1606Mark all sources of this target as being up-to-date. 1607.It Ic .MAKE 1608Execute the commands associated with this target even if the 1609.Fl n 1610or 1611.Fl t 1612options were specified. 1613Normally used to mark recursive 1614.Nm Ns 's . 1615.It Ic .NOPATH 1616Do not search for the target in the directories specified by 1617.Ic .PATH . 1618.It Ic .NOTMAIN 1619Normally 1620.Nm 1621selects the first target it encounters as the default target to be built 1622if no target was specified. 1623This source prevents this target from being selected. 1624.It Ic .OPTIONAL 1625If a target is marked with this attribute and 1626.Nm 1627can't figure out how to create it, it will ignore this fact and assume 1628the file isn't needed or already exists. 1629.It Ic .PHONY 1630The target does not 1631correspond to an actual file; it is always considered to be out of date, 1632and will not be created with the 1633.Fl t 1634option. 1635Suffix-transformation rules are not applied to 1636.Ic .PHONY 1637targets. 1638.It Ic .PRECIOUS 1639When 1640.Nm 1641is interrupted, it normally removes any partially made targets. 1642This source prevents the target from being removed. 1643.It Ic .RECURSIVE 1644Synonym for 1645.Ic .MAKE . 1646.It Ic .SILENT 1647Do not echo any of the commands associated with this target, exactly 1648as if they all were preceded by an at sign 1649.Pq Ql @ . 1650.It Ic .USE 1651Turn the target into 1652.Nm Ns 's 1653version of a macro. 1654When the target is used as a source for another target, the other target 1655acquires the commands, sources, and attributes (except for 1656.Ic .USE ) 1657of the 1658source. 1659If the target already has commands, the 1660.Ic .USE 1661target's commands are appended 1662to them. 1663.It Ic .USEBEFORE 1664Exactly like 1665.Ic .USE , 1666but prepend the 1667.Ic .USEBEFORE 1668target commands to the target. 1669.It Ic .WAIT 1670If 1671.Ic .WAIT 1672appears in a dependency line, the sources that precede it are 1673made before the sources that succeed it in the line. 1674Since the dependents of files are not made until the file itself 1675could be made, this also stops the dependents being built unless they 1676are needed for another branch of the dependency tree. 1677So given: 1678.Bd -literal 1679x: a .WAIT b 1680 echo x 1681a: 1682 echo a 1683b: b1 1684 echo b 1685b1: 1686 echo b1 1687 1688.Ed 1689the output is always 1690.Ql a , 1691.Ql b1 , 1692.Ql b , 1693.Ql x . 1694.br 1695The ordering imposed by 1696.Ic .WAIT 1697is only relevant for parallel makes. 1698.El 1699.Sh SPECIAL TARGETS 1700Special targets may not be included with other targets, i.e. they must be 1701the only target specified. 1702.Bl -tag -width .BEGINx 1703.It Ic .BEGIN 1704Any command lines attached to this target are executed before anything 1705else is done. 1706.It Ic .DEFAULT 1707This is sort of a 1708.Ic .USE 1709rule for any target (that was used only as a 1710source) that 1711.Nm 1712can't figure out any other way to create. 1713Only the shell script is used. 1714The 1715.Ic .IMPSRC 1716variable of a target that inherits 1717.Ic .DEFAULT Ns 's 1718commands is set 1719to the target's own name. 1720.It Ic .END 1721Any command lines attached to this target are executed after everything 1722else is done. 1723.It Ic .ERROR 1724Any command lines attached to this target are executed when another target fails. 1725The 1726.Ic .ERROR_TARGET 1727variable is set to the target that failed. 1728See also 1729.Ic MAKE_PRINT_VAR_ON_ERROR . 1730.It Ic .IGNORE 1731Mark each of the sources with the 1732.Ic .IGNORE 1733attribute. 1734If no sources are specified, this is the equivalent of specifying the 1735.Fl i 1736option. 1737.It Ic .INTERRUPT 1738If 1739.Nm 1740is interrupted, the commands for this target will be executed. 1741.It Ic .MAIN 1742If no target is specified when 1743.Nm 1744is invoked, this target will be built. 1745.It Ic .MAKEFLAGS 1746This target provides a way to specify flags for 1747.Nm 1748when the makefile is used. 1749The flags are as if typed to the shell, though the 1750.Fl f 1751option will have 1752no effect. 1753.\" XXX: NOT YET!!!! 1754.\" .It Ic .NOTPARALLEL 1755.\" The named targets are executed in non parallel mode. 1756.\" If no targets are 1757.\" specified, then all targets are executed in non parallel mode. 1758.It Ic .NOPATH 1759Apply the 1760.Ic .NOPATH 1761attribute to any specified sources. 1762.It Ic .NOTPARALLEL 1763Disable parallel mode. 1764.It Ic .NO_PARALLEL 1765Synonym for 1766.Ic .NOTPARALLEL , 1767for compatibility with other pmake variants. 1768.It Ic .ORDER 1769The named targets are made in sequence. 1770This ordering does not add targets to the list of targets to be made. 1771Since the dependents of a target do not get built until the target itself 1772could be built, unless 1773.Ql a 1774is built by another part of the dependency graph, 1775the following is a dependency loop: 1776.Bd -literal 1777\&.ORDER: a b 1778b: a 1779.Ed 1780.Pp 1781The ordering imposed by 1782.Ic .ORDER 1783is only relevant for parallel makes. 1784.\" XXX: NOT YET!!!! 1785.\" .It Ic .PARALLEL 1786.\" The named targets are executed in parallel mode. 1787.\" If no targets are 1788.\" specified, then all targets are executed in parallel mode. 1789.It Ic .PATH 1790The sources are directories which are to be searched for files not 1791found in the current directory. 1792If no sources are specified, any previously specified directories are 1793deleted. 1794If the source is the special 1795.Ic .DOTLAST 1796target, then the current working 1797directory is searched last. 1798.It Ic .PHONY 1799Apply the 1800.Ic .PHONY 1801attribute to any specified sources. 1802.It Ic .PRECIOUS 1803Apply the 1804.Ic .PRECIOUS 1805attribute to any specified sources. 1806If no sources are specified, the 1807.Ic .PRECIOUS 1808attribute is applied to every 1809target in the file. 1810.It Ic .SHELL 1811Sets the shell that 1812.Nm 1813will use to execute commands. 1814The sources are a set of 1815.Ar field=value 1816pairs. 1817.Bl -tag -width hasErrCtls 1818.It Ar name 1819This is the minimal specification, used to select one of the builtin 1820shell specs; 1821.Ar sh , 1822.Ar ksh , 1823and 1824.Ar csh . 1825.It Ar path 1826Specifies the path to the shell. 1827.It Ar hasErrCtl 1828Indicates whether the shell supports exit on error. 1829.It Ar check 1830The command to turn on error checking. 1831.It Ar ignore 1832The command to disable error checking. 1833.It Ar echo 1834The command to turn on echoing of commands executed. 1835.It Ar quiet 1836The command to turn off echoing of commands executed. 1837.It Ar filter 1838The output to filter after issuing the 1839.Ar quiet 1840command. 1841It is typically identical to 1842.Ar quiet . 1843.It Ar errFlag 1844The flag to pass the shell to enable error checking. 1845.It Ar echoFlag 1846The flag to pass the shell to enable command echoing. 1847.It Ar newline 1848The string literal to pass the shell that results in a single newline 1849character when used outside of any quoting characters. 1850.El 1851Example: 1852.Bd -literal 1853\&.SHELL: name=ksh path=/bin/ksh hasErrCtl=true \e 1854 check="set -e" ignore="set +e" \e 1855 echo="set -v" quiet="set +v" filter="set +v" \e 1856 echoFlag=v errFlag=e newline="'\en'" 1857.Ed 1858.It Ic .SILENT 1859Apply the 1860.Ic .SILENT 1861attribute to any specified sources. 1862If no sources are specified, the 1863.Ic .SILENT 1864attribute is applied to every 1865command in the file. 1866.It Ic .SUFFIXES 1867Each source specifies a suffix to 1868.Nm . 1869If no sources are specified, any previously specified suffixes are deleted. 1870It allows the creation of suffix-transformation rules. 1871.Pp 1872Example: 1873.Bd -literal 1874\&.SUFFIXES: .o 1875\&.c.o: 1876 cc -o ${.TARGET} -c ${.IMPSRC} 1877.Ed 1878.El 1879.Sh ENVIRONMENT 1880.Nm 1881uses the following environment variables, if they exist: 1882.Ev MACHINE , 1883.Ev MACHINE_ARCH , 1884.Ev MAKE , 1885.Ev MAKEFLAGS , 1886.Ev MAKEOBJDIR , 1887.Ev MAKEOBJDIRPREFIX , 1888.Ev MAKESYSPATH , 1889.Ev PWD , 1890and 1891.Ev TMPDIR . 1892.Pp 1893.Ev MAKEOBJDIRPREFIX 1894and 1895.Ev MAKEOBJDIR 1896may only be set in the environment or on the command line to 1897.Nm 1898and not as makefile variables; 1899see the description of 1900.Ql Va .OBJDIR 1901for more details. 1902.Sh FILES 1903.Bl -tag -width /usr/share/mk -compact 1904.It .depend 1905list of dependencies 1906.It Makefile 1907list of dependencies 1908.It makefile 1909list of dependencies 1910.It sys.mk 1911system makefile 1912.It /usr/share/mk 1913system makefile directory 1914.El 1915.Sh COMPATIBILITY 1916The basic make syntax is compatible between different versions of make, 1917however the special variables, variable modifiers and conditionals are not. 1918.Pp 1919The way that parallel makes are scheduled changed in 1920.Nx 4.0 1921so that .ORDER and .WAIT apply recursively to the dependant nodes. 1922The algorithms used may change again in the future. 1923.Pp 1924The way that .for loop variables are substituted changed after 1925.Nx 5.0 1926so that they still appear to be variable expansions. 1927In particular this stops them being treated as syntax, and removes some 1928obscure problems using them in .if statements. 1929.Sh SEE ALSO 1930.Xr mkdep 1 1931.Sh HISTORY 1932A 1933.Nm 1934command appeared in 1935.At v7 . 1936.Sh BUGS 1937The 1938.Nm 1939syntax is difficult to parse without actually acting of the data. 1940For instance finding the end of a variable use should involve scanning each 1941the modifiers using the correct terminator for each field. 1942In many places 1943.Nm 1944just counts {} and () in order to find the end of a variable expansion. 1945.Pp 1946There is no way of escaping a space character in a filename. 1947