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