source: trunk/kBuild/doc/QuickReference-kmk.html@ 2148

Last change on this file since 2148 was 2147, checked in by bird, 17 years ago

sketches
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 42.7 KB
Line 
1<?xml version="1.0" encoding="utf-8" ?>
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
6<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
7<title>kmk Quick Reference</title>
8<style type="text/css">
9
10/*
11:Author: David Goodger
12:Contact: goodger@users.sourceforge.net
13:Date: $Date: 2008-12-27 20:36:13 +0000 (Sat, 27 Dec 2008) $
14:Revision: $Revision: 2147 $
15:Copyright: This stylesheet has been placed in the public domain.
16
17Default cascading style sheet for the HTML output of Docutils.
18
19See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
20customize this style sheet.
21*/
22
23/* used to remove borders from tables and images */
24.borderless, table.borderless td, table.borderless th {
25 border: 0 }
26
27table.borderless td, table.borderless th {
28 /* Override padding for "table.docutils td" with "! important".
29 The right padding separates the table cells. */
30 padding: 0 0.5em 0 0 ! important }
31
32.first {
33 /* Override more specific margin styles with "! important". */
34 margin-top: 0 ! important }
35
36.last, .with-subtitle {
37 margin-bottom: 0 ! important }
38
39.hidden {
40 display: none }
41
42a.toc-backref {
43 text-decoration: none ;
44 color: black }
45
46blockquote.epigraph {
47 margin: 2em 5em ; }
48
49dl.docutils dd {
50 margin-bottom: 0.5em }
51
52/* Uncomment (and remove this text!) to get bold-faced definition list terms
53dl.docutils dt {
54 font-weight: bold }
55*/
56
57div.abstract {
58 margin: 2em 5em }
59
60div.abstract p.topic-title {
61 font-weight: bold ;
62 text-align: center }
63
64div.admonition, div.attention, div.caution, div.danger, div.error,
65div.hint, div.important, div.note, div.tip, div.warning {
66 margin: 2em ;
67 border: medium outset ;
68 padding: 1em }
69
70div.admonition p.admonition-title, div.hint p.admonition-title,
71div.important p.admonition-title, div.note p.admonition-title,
72div.tip p.admonition-title {
73 font-weight: bold ;
74 font-family: sans-serif }
75
76div.attention p.admonition-title, div.caution p.admonition-title,
77div.danger p.admonition-title, div.error p.admonition-title,
78div.warning p.admonition-title {
79 color: red ;
80 font-weight: bold ;
81 font-family: sans-serif }
82
83/* Uncomment (and remove this text!) to get reduced vertical space in
84 compound paragraphs.
85div.compound .compound-first, div.compound .compound-middle {
86 margin-bottom: 0.5em }
87
88div.compound .compound-last, div.compound .compound-middle {
89 margin-top: 0.5em }
90*/
91
92div.dedication {
93 margin: 2em 5em ;
94 text-align: center ;
95 font-style: italic }
96
97div.dedication p.topic-title {
98 font-weight: bold ;
99 font-style: normal }
100
101div.figure {
102 margin-left: 2em ;
103 margin-right: 2em }
104
105div.footer, div.header {
106 clear: both;
107 font-size: smaller }
108
109div.line-block {
110 display: block ;
111 margin-top: 1em ;
112 margin-bottom: 1em }
113
114div.line-block div.line-block {
115 margin-top: 0 ;
116 margin-bottom: 0 ;
117 margin-left: 1.5em }
118
119div.sidebar {
120 margin-left: 1em ;
121 border: medium outset ;
122 padding: 1em ;
123 background-color: #ffffee ;
124 width: 40% ;
125 float: right ;
126 clear: right }
127
128div.sidebar p.rubric {
129 font-family: sans-serif ;
130 font-size: medium }
131
132div.system-messages {
133 margin: 5em }
134
135div.system-messages h1 {
136 color: red }
137
138div.system-message {
139 border: medium outset ;
140 padding: 1em }
141
142div.system-message p.system-message-title {
143 color: red ;
144 font-weight: bold }
145
146div.topic {
147 margin: 2em }
148
149h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
150h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
151 margin-top: 0.4em }
152
153h1.title {
154 text-align: center }
155
156h2.subtitle {
157 text-align: center }
158
159hr.docutils {
160 width: 75% }
161
162img.align-left {
163 clear: left }
164
165img.align-right {
166 clear: right }
167
168ol.simple, ul.simple {
169 margin-bottom: 1em }
170
171ol.arabic {
172 list-style: decimal }
173
174ol.loweralpha {
175 list-style: lower-alpha }
176
177ol.upperalpha {
178 list-style: upper-alpha }
179
180ol.lowerroman {
181 list-style: lower-roman }
182
183ol.upperroman {
184 list-style: upper-roman }
185
186p.attribution {
187 text-align: right ;
188 margin-left: 50% }
189
190p.caption {
191 font-style: italic }
192
193p.credits {
194 font-style: italic ;
195 font-size: smaller }
196
197p.label {
198 white-space: nowrap }
199
200p.rubric {
201 font-weight: bold ;
202 font-size: larger ;
203 color: maroon ;
204 text-align: center }
205
206p.sidebar-title {
207 font-family: sans-serif ;
208 font-weight: bold ;
209 font-size: larger }
210
211p.sidebar-subtitle {
212 font-family: sans-serif ;
213 font-weight: bold }
214
215p.topic-title {
216 font-weight: bold }
217
218pre.address {
219 margin-bottom: 0 ;
220 margin-top: 0 ;
221 font-family: serif ;
222 font-size: 100% }
223
224pre.literal-block, pre.doctest-block {
225 margin-left: 2em ;
226 margin-right: 2em ;
227 background-color: #eeeeee }
228
229span.classifier {
230 font-family: sans-serif ;
231 font-style: oblique }
232
233span.classifier-delimiter {
234 font-family: sans-serif ;
235 font-weight: bold }
236
237span.interpreted {
238 font-family: sans-serif }
239
240span.option {
241 white-space: nowrap }
242
243span.pre {
244 white-space: pre }
245
246span.problematic {
247 color: red }
248
249span.section-subtitle {
250 /* font-size relative to parent (h1..h6 element) */
251 font-size: 80% }
252
253table.citation {
254 border-left: solid 1px gray;
255 margin-left: 1px }
256
257table.docinfo {
258 margin: 2em 4em }
259
260table.docutils {
261 margin-top: 0.5em ;
262 margin-bottom: 0.5em }
263
264table.footnote {
265 border-left: solid 1px black;
266 margin-left: 1px }
267
268table.docutils td, table.docutils th,
269table.docinfo td, table.docinfo th {
270 padding-left: 0.5em ;
271 padding-right: 0.5em ;
272 vertical-align: top }
273
274table.docutils th.field-name, table.docinfo th.docinfo-name {
275 font-weight: bold ;
276 text-align: left ;
277 white-space: nowrap ;
278 padding-left: 0 }
279
280h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
281h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
282 font-size: 100% }
283
284tt.docutils {
285 background-color: #eeeeee }
286
287ul.auto-toc {
288 list-style-type: none }
289
290</style>
291</head>
292<body>
293<div class="document" id="kmk-quick-reference">
294<h1 class="title">kmk Quick Reference</h1>
295<p>This appendix summarizes the directives, text manipulation functions, and
296special variables which <tt class="docutils literal"><span class="pre">kmk</span></tt> understands.</p>
297<!-- See section Special Built-in Target Names and Summary of Options, for other
298summaries. -->
299<div class="section">
300<h1><a id="directives" name="directives">Directives</a></h1>
301<p>Here is a summary of the directives <tt class="docutils literal"><span class="pre">kmk</span></tt> recognizes:</p>
302<blockquote>
303<p>Define a multi-line, recursively-expanded variable:</p>
304<pre class="literal-block">
305define variable
306endef
307</pre>
308<p>Conditionally evaluate part of the makefile:</p>
309<pre class="literal-block">
310ifdef variable
311ifndef variable
312ifeq (a,b)
313ifeq &quot;a&quot; &quot;b&quot;
314ifeq 'a' 'b'
315ifneq (a,b)
316ifneq &quot;a&quot; &quot;b&quot;
317ifneq 'a' 'b'
318if1of (set-a,set-b)
319ifn1of (set-a,set-b)
320if expression
321else
322endif
323</pre>
324<p>Include another makefile:</p>
325<pre class="literal-block">
326include file
327-include file
328sinclude file
329</pre>
330<p>Include another dependency file:</p>
331<pre class="literal-block">
332includedep file
333</pre>
334<p>Define a variable, overriding any previous definition, even one from the
335command line:</p>
336<pre class="literal-block">
337override variable = value
338override variable := value
339override variable += value
340override variable &lt;= value
341override variable ?= value
342override define variable
343endef
344</pre>
345<p>Tell <tt class="docutils literal"><span class="pre">kmk</span></tt> to export all variables to child processes by default:</p>
346<pre class="literal-block">
347export
348</pre>
349<p>Tell <tt class="docutils literal"><span class="pre">kmk</span></tt> whether or not to export a particular variable to child
350processes:</p>
351<pre class="literal-block">
352export variable
353export variable = value
354export variable := value
355export variable += value
356export variable &lt;= value
357export variable ?= value
358unexport variable
359</pre>
360<p>Define a variable in the local context instead of the global one:</p>
361<pre class="literal-block">
362local variable = value
363local variable := value
364local variable += value
365local variable &lt;= value
366local variable ?= value
367local define variable
368endef
369</pre>
370<p>Specify a search path for files matching a <tt class="docutils literal"><span class="pre">%</span></tt> pattern:</p>
371<pre class="literal-block">
372vpath pattern path
373</pre>
374<p>Remove all search paths previously specified for pattern:</p>
375<pre class="literal-block">
376vpath pattern
377</pre>
378<p>Remove all search paths previously specified in any vpath directive:</p>
379<pre class="literal-block">
380vpath
381</pre>
382</blockquote>
383</div>
384<div class="section">
385<h1><a id="automatic-variables" name="automatic-variables">Automatic variables</a></h1>
386<p>Here is a summary of the automatic variables.</p>
387<table border="1" class="docutils">
388<colgroup>
389<col width="14%" />
390<col width="86%" />
391</colgroup>
392<thead valign="bottom">
393<tr><th class="head">Variable</th>
394<th class="head">Description</th>
395</tr>
396</thead>
397<tbody valign="top">
398<tr><td><tt class="docutils literal"><span class="pre">$&#64;</span></tt></td>
399<td>The file name of the target.</td>
400</tr>
401<tr><td><tt class="docutils literal"><span class="pre">$&lt;</span></tt></td>
402<td>The name of the first prerequisite.</td>
403</tr>
404<tr><td><tt class="docutils literal"><span class="pre">$?</span></tt></td>
405<td>The names of all the prerequisites that are newer than the
406target, with spaces between them.</td>
407</tr>
408<tr><td><tt class="docutils literal"><span class="pre">$^</span></tt></td>
409<td>The names of all the prerequisites, duplicates omitted.</td>
410</tr>
411<tr><td><tt class="docutils literal"><span class="pre">$+</span></tt></td>
412<td>The names of all the prerequisites, duplicates and order
413preserved</td>
414</tr>
415<tr><td><tt class="docutils literal"><span class="pre">$*</span></tt></td>
416<td>The stem with which an implicit rule matches.</td>
417</tr>
418<tr><td><tt class="docutils literal"><span class="pre">$|</span></tt></td>
419<td>The name of all the order only prerequisites.</td>
420</tr>
421<tr><td><tt class="docutils literal"><span class="pre">$(&#64;D)</span></tt></td>
422<td>The directory part of <tt class="docutils literal"><span class="pre">$&#64;</span></tt>.</td>
423</tr>
424<tr><td><tt class="docutils literal"><span class="pre">$(&lt;D)</span></tt></td>
425<td>The directory part of <tt class="docutils literal"><span class="pre">$&lt;</span></tt>.</td>
426</tr>
427<tr><td><tt class="docutils literal"><span class="pre">$(?D)</span></tt></td>
428<td>The directory part of <tt class="docutils literal"><span class="pre">$?</span></tt>.</td>
429</tr>
430<tr><td><tt class="docutils literal"><span class="pre">$(^D)</span></tt></td>
431<td>The directory part of <tt class="docutils literal"><span class="pre">%^</span></tt>.</td>
432</tr>
433<tr><td><tt class="docutils literal"><span class="pre">$(+D)</span></tt></td>
434<td>The directory part of <tt class="docutils literal"><span class="pre">$+</span></tt>.</td>
435</tr>
436<tr><td><tt class="docutils literal"><span class="pre">$(*D)</span></tt></td>
437<td>The directory part of <tt class="docutils literal"><span class="pre">$*</span></tt>.</td>
438</tr>
439<tr><td><tt class="docutils literal"><span class="pre">$(|D)</span></tt></td>
440<td>The directory part of <tt class="docutils literal"><span class="pre">$|</span></tt>.</td>
441</tr>
442<tr><td><tt class="docutils literal"><span class="pre">$(&#64;F)</span></tt></td>
443<td>The file-within-directory part of <tt class="docutils literal"><span class="pre">$&#64;</span></tt>.</td>
444</tr>
445<tr><td><tt class="docutils literal"><span class="pre">$(&lt;F)</span></tt></td>
446<td>The file-within-directory part of <tt class="docutils literal"><span class="pre">$&lt;</span></tt>.</td>
447</tr>
448<tr><td><tt class="docutils literal"><span class="pre">$(?F)</span></tt></td>
449<td>The file-within-directory part of <tt class="docutils literal"><span class="pre">$?</span></tt>.</td>
450</tr>
451<tr><td><tt class="docutils literal"><span class="pre">$(^F)</span></tt></td>
452<td>The file-within-directory part of <tt class="docutils literal"><span class="pre">$^</span></tt>.</td>
453</tr>
454<tr><td><tt class="docutils literal"><span class="pre">$(+F)</span></tt></td>
455<td>The file-within-directory part of <tt class="docutils literal"><span class="pre">$+</span></tt>.</td>
456</tr>
457<tr><td><tt class="docutils literal"><span class="pre">$(*F)</span></tt></td>
458<td>The file-within-directory part of <tt class="docutils literal"><span class="pre">$*</span></tt>.</td>
459</tr>
460<tr><td><tt class="docutils literal"><span class="pre">$(|F)</span></tt></td>
461<td>The file-within-directory part of <tt class="docutils literal"><span class="pre">$|</span></tt>.</td>
462</tr>
463</tbody>
464</table>
465</div>
466<div class="section">
467<h1><a id="special-variables" name="special-variables">Special variables</a></h1>
468<p>All variables starting with a <tt class="docutils literal"><span class="pre">.</span></tt> is reserved by <tt class="docutils literal"><span class="pre">kmk</span></tt>. The following
469variables are specially used or/and defined by <tt class="docutils literal"><span class="pre">kmk</span></tt>:</p>
470<table border="1" class="docutils">
471<colgroup>
472<col width="34%" />
473<col width="66%" />
474</colgroup>
475<thead valign="bottom">
476<tr><th class="head">Variable</th>
477<th class="head">Description</th>
478</tr>
479</thead>
480<tbody valign="top">
481<tr><td><tt class="docutils literal"><span class="pre">.DEFAULT_GOAL</span></tt></td>
482<td>The makefile default goal. You can set this in
483the makefile, if you don't it will default to
484the first target that is encountered.</td>
485</tr>
486<tr><td><tt class="docutils literal"><span class="pre">.FEATURES</span></tt></td>
487<td>List of GNU <tt class="docutils literal"><span class="pre">make</span></tt> features. Do not set this.</td>
488</tr>
489<tr><td><tt class="docutils literal"><span class="pre">.INCLUDE_DIRS</span></tt></td>
490<td>List of include directories, <tt class="docutils literal"><span class="pre">-I</span></tt> arguments
491and defaults. Do not set this.</td>
492</tr>
493<tr><td><tt class="docutils literal"><span class="pre">.RECIPEPREFIX</span></tt></td>
494<td>Recipe prefix, defaults to tab.</td>
495</tr>
496<tr><td><tt class="docutils literal"><span class="pre">.VARIABLES</span></tt></td>
497<td>Special variable which exands to the list of
498variable. Do not set this.</td>
499</tr>
500<tr><td><tt class="docutils literal"><span class="pre">CURDIR</span></tt></td>
501<td>Set to the pathname of the current working
502directory (after all <tt class="docutils literal"><span class="pre">-C</span></tt> options are
503processed, if any). Do not set this.</td>
504</tr>
505<tr><td><tt class="docutils literal"><span class="pre">KBUILD_VERSION</span></tt>,
506<tt class="docutils literal"><span class="pre">KBUILD_VERSION_MAJOR</span></tt>,
507<tt class="docutils literal"><span class="pre">KBUILD_VERSION_MINOR</span></tt>,
508<tt class="docutils literal"><span class="pre">KBUILD_VERSION_PATCH</span></tt>,
509<tt class="docutils literal"><span class="pre">KBUILD_KMK_REVISION</span></tt></td>
510<td>The kBuild version string and the break down
511into individual components.</td>
512</tr>
513<tr><td><tt class="docutils literal"><span class="pre">KBUILD_HOST</span></tt></td>
514<td>The host operating system.</td>
515</tr>
516<tr><td><tt class="docutils literal"><span class="pre">KBUILD_HOST_ARCH</span></tt></td>
517<td>The host architecture.</td>
518</tr>
519<tr><td><tt class="docutils literal"><span class="pre">KBUILD_HOST_CPU</span></tt></td>
520<td>The host CPU <tt class="docutils literal"><span class="pre">kmk</span></tt> is built for, set to
521<tt class="docutils literal"><span class="pre">blend</span></tt> if not any particular CPU.</td>
522</tr>
523<tr><td><tt class="docutils literal"><span class="pre">KBUILD_PATH</span></tt></td>
524<td>Where the kBuild scripts are.</td>
525</tr>
526<tr><td><tt class="docutils literal"><span class="pre">KBUILD_BIN_PATH</span></tt></td>
527<td>Where the host specific kBuild binaries are.</td>
528</tr>
529<tr><td><tt class="docutils literal"><span class="pre">KMK</span></tt>,
530<tt class="docutils literal"><span class="pre">MAKE</span></tt></td>
531<td>The name with which <tt class="docutils literal"><span class="pre">kmk</span></tt> was invoked. Using
532this variable in recipes has special meaning.</td>
533</tr>
534<tr><td><tt class="docutils literal"><span class="pre">KMK_BUILTIN</span></tt></td>
535<td>List of built-in commands.</td>
536</tr>
537<tr><td><tt class="docutils literal"><span class="pre">KMK_FEATURES</span></tt></td>
538<td>List of <tt class="docutils literal"><span class="pre">kmk</span></tt> specific features.</td>
539</tr>
540<tr><td><tt class="docutils literal"><span class="pre">KMK_FLAGS</span></tt></td>
541<td><p class="first">The flags given to <tt class="docutils literal"><span class="pre">kmk</span></tt>. You can set this in
542the environment or a makefile to set flags.</p>
543<p class="last">It is never appropriate to use <tt class="docutils literal"><span class="pre">KMK_FLAGS</span></tt>
544directly in a recipe line: its contents may not
545be quoted correctly for use in the shell. Always
546allow recursive <tt class="docutils literal"><span class="pre">kmk</span></tt>'s to obtain these values
547through the environment from its parent.</p>
548</td>
549</tr>
550<tr><td><tt class="docutils literal"><span class="pre">KMK_LEVEL</span></tt></td>
551<td>The number of levels of recursion (sub-makes).</td>
552</tr>
553<tr><td><tt class="docutils literal"><span class="pre">KMK_VERSION</span></tt></td>
554<td>The GNU <tt class="docutils literal"><span class="pre">make</span></tt> version number.</td>
555</tr>
556<tr><td><tt class="docutils literal"><span class="pre">MAKECMDGOALS</span></tt></td>
557<td>The targets given to <tt class="docutils literal"><span class="pre">kmk</span></tt> on the command line.
558Do not set this.</td>
559</tr>
560<tr><td><tt class="docutils literal"><span class="pre">MAKEFILES</span></tt></td>
561<td>Makefiles to be read on every invocation of
562<tt class="docutils literal"><span class="pre">kmk</span></tt>.</td>
563</tr>
564<tr><td><tt class="docutils literal"><span class="pre">MAKEFILE_LIST</span></tt></td>
565<td>List of the makefiles that <tt class="docutils literal"><span class="pre">kmk</span></tt> has opened.</td>
566</tr>
567<tr><td><tt class="docutils literal"><span class="pre">MAKESHELL</span></tt></td>
568<td>OS/2 and MS-DOS only, the name of the command
569interpreter that is to be used by <tt class="docutils literal"><span class="pre">kmk</span></tt>. This
570value takes precedence over the value of SHELL.</td>
571</tr>
572<tr><td><tt class="docutils literal"><span class="pre">SHELL</span></tt></td>
573<td>The name of the default command interpreter,
574kmk_ash. You can set SHELL in the makefile to
575change the shell used to run recipes. The SHELL
576variable is handled specially when importing
577from and exporting to the environment.</td>
578</tr>
579<tr><td><tt class="docutils literal"><span class="pre">SUFFIXES</span></tt></td>
580<td>The default list of suffixes before <tt class="docutils literal"><span class="pre">kmk</span></tt>
581reads any makefiles (always empty).</td>
582</tr>
583<tr><td><tt class="docutils literal"><span class="pre">VPATH</span></tt></td>
584<td>Directory search path for files not found in the
585current directory.</td>
586</tr>
587</tbody>
588</table>
589<p>The following variables reflects <tt class="docutils literal"><span class="pre">kmk</span></tt> options. Do not set these.</p>
590<table border="1" class="docutils">
591<colgroup>
592<col width="49%" />
593<col width="51%" />
594</colgroup>
595<thead valign="bottom">
596<tr><th class="head">Variable</th>
597<th class="head">Description</th>
598</tr>
599</thead>
600<tbody valign="top">
601<tr><td><tt class="docutils literal"><span class="pre">KMK_OPTS_JOBS</span></tt></td>
602<td>-j slots, <tt class="docutils literal"><span class="pre">0</span></tt> if not given.</td>
603</tr>
604<tr><td><tt class="docutils literal"><span class="pre">KMK_OPTS_KEEP_GOING</span></tt></td>
605<td>-k indictor (<tt class="docutils literal"><span class="pre">0</span></tt>/<tt class="docutils literal"><span class="pre">1</span></tt>).</td>
606</tr>
607<tr><td><tt class="docutils literal"><span class="pre">KMK_OPTS_JUST_PRINT</span></tt></td>
608<td>-n indicator (<tt class="docutils literal"><span class="pre">0</span></tt>/<tt class="docutils literal"><span class="pre">1</span></tt>).</td>
609</tr>
610<tr><td><tt class="docutils literal"><span class="pre">KMK_OPTS_PRORITY</span></tt></td>
611<td>--priority level, <tt class="docutils literal"><span class="pre">0</span></tt> if not given.</td>
612</tr>
613<tr><td><tt class="docutils literal"><span class="pre">KMK_OPTS_AFFINITY</span></tt></td>
614<td>--affinity mask, <tt class="docutils literal"><span class="pre">0</span></tt> if not given.</td>
615</tr>
616<tr><td><tt class="docutils literal"><span class="pre">KMK_OPTS_STATISTICS</span></tt></td>
617<td>--statistics indicator (<tt class="docutils literal"><span class="pre">0</span></tt>/<tt class="docutils literal"><span class="pre">1</span></tt>).</td>
618</tr>
619<tr><td><tt class="docutils literal"><span class="pre">KMK_OPTS_PRINT_TIME</span></tt></td>
620<td>The --print-time value.</td>
621</tr>
622<tr><td><tt class="docutils literal"><span class="pre">KMK_OPTS_PRETTY_COMMAND_PRINTING</span></tt></td>
623<td>--pretty-command-printing indicator.</td>
624</tr>
625</tbody>
626</table>
627</div>
628<div class="section">
629<h1><a id="built-in-functions" name="built-in-functions">Built-in functions</a></h1>
630<p>String Manipulation Functions:</p>
631<blockquote>
632<p>Replace <tt class="docutils literal"><span class="pre">from</span></tt> with <tt class="docutils literal"><span class="pre">to</span></tt> in <tt class="docutils literal"><span class="pre">text</span></tt>:</p>
633<pre class="literal-block">
634$(subst from,to,text)
635</pre>
636<p>Replace words matching <tt class="docutils literal"><span class="pre">pattern</span></tt> with <tt class="docutils literal"><span class="pre">replacement</span></tt> in <tt class="docutils literal"><span class="pre">text</span></tt>:</p>
637<pre class="literal-block">
638$(patsubst pattern,replacement,text)
639</pre>
640<p>Remove excess whitespace characters from <tt class="docutils literal"><span class="pre">string</span></tt>:</p>
641<pre class="literal-block">
642$(strip string)
643</pre>
644<p>Locate <tt class="docutils literal"><span class="pre">find</span></tt> in <tt class="docutils literal"><span class="pre">text</span></tt>, returning <tt class="docutils literal"><span class="pre">find</span></tt> if found:</p>
645<pre class="literal-block">
646$(findstring find,text)
647</pre>
648<p>Select words in <tt class="docutils literal"><span class="pre">text</span></tt> that match one of the <tt class="docutils literal"><span class="pre">pattern</span></tt> words:</p>
649<pre class="literal-block">
650$(filter pattern...,text)
651</pre>
652<p>Select words in <tt class="docutils literal"><span class="pre">text</span></tt> that do not match any of the <tt class="docutils literal"><span class="pre">pattern</span></tt> words:</p>
653<pre class="literal-block">
654$(filter-out pattern...,text)
655</pre>
656<p>Sort the words in <tt class="docutils literal"><span class="pre">list</span></tt> lexicographically, removing duplicates:</p>
657<pre class="literal-block">
658$(sort list)
659</pre>
660<p>Sort the words in <tt class="docutils literal"><span class="pre">list</span></tt> lexicographically in reserve order, removing
661duplicates:</p>
662<pre class="literal-block">
663$(rsort list)
664</pre>
665<p>Count the number of words in <tt class="docutils literal"><span class="pre">text</span></tt>:</p>
666<pre class="literal-block">
667$(words text)
668</pre>
669<p>Extract the <tt class="docutils literal"><span class="pre">n</span></tt>th word (one-origin) of <tt class="docutils literal"><span class="pre">text</span></tt>:</p>
670<pre class="literal-block">
671$(word n,text)
672</pre>
673<p>Returns the list of words in <tt class="docutils literal"><span class="pre">text</span></tt> from <tt class="docutils literal"><span class="pre">s</span></tt> to <tt class="docutils literal"><span class="pre">e</span></tt> (one-origin):</p>
674<pre class="literal-block">
675$(wordlist s,e,text)
676</pre>
677<p>Extract the first word of <tt class="docutils literal"><span class="pre">names</span></tt>:</p>
678<pre class="literal-block">
679$(firstword names...)
680</pre>
681<p>Extract the last word of <tt class="docutils literal"><span class="pre">names</span></tt>:</p>
682<pre class="literal-block">
683$(lastword names...)
684</pre>
685<p>Join two parallel lists of words:</p>
686<pre class="literal-block">
687$(join list1,list2)
688</pre>
689<p>Fold <tt class="docutils literal"><span class="pre">text</span></tt> to upper case:</p>
690<pre class="literal-block">
691$(toupper text)
692</pre>
693<p>Fold <tt class="docutils literal"><span class="pre">text</span></tt> to lower case:</p>
694<pre class="literal-block">
695$(tolower text)
696</pre>
697<p>String formatting a la the unix <tt class="docutils literal"><span class="pre">printf</span></tt> command:</p>
698<pre class="literal-block">
699$(printf fmt, arg...)
700</pre>
701</blockquote>
702<p>Functions for file names:</p>
703<blockquote>
704<p>Extract the directory part of each file <tt class="docutils literal"><span class="pre">name</span></tt>:</p>
705<pre class="literal-block">
706$(dir names...)
707</pre>
708<p>Extract the non-directory part of each file <tt class="docutils literal"><span class="pre">name</span></tt>:</p>
709<pre class="literal-block">
710$(notdir names...)
711</pre>
712<p>Extract the suffix (the last <tt class="docutils literal"><span class="pre">.</span></tt> and following characters) of each file
713<tt class="docutils literal"><span class="pre">name</span></tt>:</p>
714<pre class="literal-block">
715$(suffix names...)
716</pre>
717<p>Extract the base name (name without suffix) of each file name:</p>
718<pre class="literal-block">
719$(basename names...)
720</pre>
721<p>Append <tt class="docutils literal"><span class="pre">suffix</span></tt> to each word in <tt class="docutils literal"><span class="pre">names</span></tt>:</p>
722<pre class="literal-block">
723$(addsuffix suffix,names...)
724</pre>
725<p>Prepend <tt class="docutils literal"><span class="pre">prefix</span></tt> to each word in <tt class="docutils literal"><span class="pre">names</span></tt>:</p>
726<pre class="literal-block">
727$(addprefix prefix,names...)
728</pre>
729<p>Find file names matching a shell file name <tt class="docutils literal"><span class="pre">pattern</span></tt> (not a <tt class="docutils literal"><span class="pre">%</span></tt>
730pattern):</p>
731<pre class="literal-block">
732$(wildcard pattern...)
733</pre>
734<p>For each file name in <tt class="docutils literal"><span class="pre">names</span></tt>, expand to an absolute name that does not
735contain any <tt class="docutils literal"><span class="pre">.</span></tt>, <tt class="docutils literal"><span class="pre">..</span></tt>, nor symlinks:</p>
736<pre class="literal-block">
737$(realpath names...)
738</pre>
739<p>For each file name in <tt class="docutils literal"><span class="pre">names</span></tt>, expand to an absolute name that does not
740contain any <tt class="docutils literal"><span class="pre">.</span></tt> or <tt class="docutils literal"><span class="pre">..</span></tt> components, but preserves symlinks:</p>
741<pre class="literal-block">
742$(abspath names...)
743</pre>
744<p>Same as <tt class="docutils literal"><span class="pre">$(abspath</span> <span class="pre">)</span></tt> except that the current directory can be
745specified as <tt class="docutils literal"><span class="pre">curdir</span></tt>:</p>
746<pre class="literal-block">
747$(abspathex names...[, curdir])
748</pre>
749</blockquote>
750<p>Arithmetic Functions:</p>
751<blockquote>
752<p>Returns the sum of the arguments:</p>
753<pre class="literal-block">
754$(int-add addend1, addend2[, addendN])
755</pre>
756<p>Returns the difference between the first argument and the sum of the rest:</p>
757<pre class="literal-block">
758$(int-sub minuend, subtrahend[, subtrahendN])
759</pre>
760<p>Returns the product of the arguments:</p>
761<pre class="literal-block">
762$(int-mul factor1, factor2[, factorN])
763</pre>
764<p>Returns the quotient of first argument and the rest:</p>
765<pre class="literal-block">
766$(int-div dividend, divisor[, divisorN])
767</pre>
768<p>Returns the modulus of the two arguments:</p>
769<pre class="literal-block">
770$(int-mod dividend, divisor)
771</pre>
772<p>Returns the bitwise two-complement of argument:</p>
773<pre class="literal-block">
774$(int-not val)
775</pre>
776<p>Returns the result of a bitwise AND of the arguments:</p>
777<pre class="literal-block">
778$(int-and val1, val2[, valN])
779</pre>
780<p>Returns the result of a bitwise OR of the arguments:</p>
781<pre class="literal-block">
782$(int-or val1, val2[, valN])
783</pre>
784<p>Returns the result of a bitwise XOR of the arguments:</p>
785<pre class="literal-block">
786$(int-xor val1, val2[, valN])
787</pre>
788<p>Returns the <tt class="docutils literal"><span class="pre">kmk</span></tt> boolean (true = non-empty, false = empty) result
789of <tt class="docutils literal"><span class="pre">val1</span> <span class="pre">==</span> <span class="pre">val2</span></tt>:</p>
790<pre class="literal-block">
791$(int-eq val1, val2)
792</pre>
793<p>Returns the <tt class="docutils literal"><span class="pre">kmk</span></tt> boolean result of <tt class="docutils literal"><span class="pre">val1</span> <span class="pre">!=</span> <span class="pre">val2</span></tt>:</p>
794<pre class="literal-block">
795$(int-ne val1, val2)
796</pre>
797<p>Returns the <tt class="docutils literal"><span class="pre">kmk</span></tt> boolean result of <tt class="docutils literal"><span class="pre">val1</span> <span class="pre">&gt;</span> <span class="pre">val2</span></tt>:</p>
798<pre class="literal-block">
799$(int-gt val1, val2)
800</pre>
801<p>Returns the <tt class="docutils literal"><span class="pre">kmk</span></tt> boolean result of <tt class="docutils literal"><span class="pre">val1</span> <span class="pre">&gt;=</span> <span class="pre">val2</span></tt>:</p>
802<pre class="literal-block">
803$(int-ge val1, val2)
804</pre>
805<p>Returns the <tt class="docutils literal"><span class="pre">kmk</span></tt> boolean result of <tt class="docutils literal"><span class="pre">val1</span> <span class="pre">&lt;</span> <span class="pre">val2</span></tt>:</p>
806<pre class="literal-block">
807$(int-lt val1, val2)
808</pre>
809<p>Returns the <tt class="docutils literal"><span class="pre">kmk</span></tt> boolean result of <tt class="docutils literal"><span class="pre">val1</span> <span class="pre">&lt;=</span> <span class="pre">val2</span></tt>:</p>
810<pre class="literal-block">
811$(int-le val1, val2)
812</pre>
813</blockquote>
814<p>(Mostly) Boolean Functions:</p>
815<blockquote>
816<p>Condition is false if the <tt class="docutils literal"><span class="pre">condition</span></tt> evaluates to an empty string
817(stripped). Evaluate the <tt class="docutils literal"><span class="pre">true-part</span></tt> if the condition is true, otherwise
818the <tt class="docutils literal"><span class="pre">false-part</span></tt>:</p>
819<pre class="literal-block">
820$(if condition,true-part[,false-part])
821</pre>
822<p>Test if any of the conditions evalues to non-empty string, returning the
823first one:</p>
824<pre class="literal-block">
825$(or condition1[,condition2[,condition3[...]]])
826</pre>
827<p>Test if all of the conditions evaluates to non-empty strings, returning the
828last one:</p>
829<pre class="literal-block">
830$(and condition1[,condition2[,condition3[...]]])
831</pre>
832<p>Test if the two strings are identical, returning <tt class="docutils literal"><span class="pre">kmk</span></tt> boolean (true =
833non-empty, false = empty):</p>
834<pre class="literal-block">
835$(eq str1, str2)
836</pre>
837<p>Invert a <tt class="docutils literal"><span class="pre">kmk</span></tt> boolean value:</p>
838<pre class="literal-block">
839$(not val)
840</pre>
841<p>Test if <tt class="docutils literal"><span class="pre">variable</span></tt> is defined, returning a <tt class="docutils literal"><span class="pre">kmk</span></tt> boolean value:</p>
842<pre class="literal-block">
843$(defined variable)
844</pre>
845<p>Test if <tt class="docutils literal"><span class="pre">set-a</span></tt> and <tt class="docutils literal"><span class="pre">set-b</span></tt> intersects, returning a <tt class="docutils literal"><span class="pre">kmk</span></tt> boolean
846value:</p>
847<pre class="literal-block">
848$(intersects set-a, set-b)
849</pre>
850<p>Same as <tt class="docutils literal"><span class="pre">$(if</span> <span class="pre">)</span></tt> execpt that the condition is a <tt class="docutils literal"><span class="pre">kmk</span></tt> expression:</p>
851<pre class="literal-block">
852$(if kmk-expression,true-part[,false-part])
853</pre>
854<p>Evalutate the <tt class="docutils literal"><span class="pre">kmk</span></tt> expression returning what it evalues as. This is
855the preferred way of doing arithmentic now:</p>
856<pre class="literal-block">
857$(expr kmk-expression)
858</pre>
859</blockquote>
860<p>Stack Fuctions:</p>
861<blockquote>
862<p>Push <tt class="docutils literal"><span class="pre">item</span></tt> onto the <tt class="docutils literal"><span class="pre">stack-var</span></tt>, returning the empty string:</p>
863<pre class="literal-block">
864$(stack-push stack-var, item)
865</pre>
866<p>Pop the top item off the <tt class="docutils literal"><span class="pre">stack-var</span></tt>:</p>
867<pre class="literal-block">
868$(stack-pop stack-var)
869</pre>
870<p>Pop the top item off the <tt class="docutils literal"><span class="pre">stack-var</span></tt>, returning the empty string:</p>
871<pre class="literal-block">
872$(stack-popv stack-var)
873</pre>
874<p>Get the top item of the <tt class="docutils literal"><span class="pre">stack-var</span></tt>, returning the empty string:</p>
875<pre class="literal-block">
876$(stack-top stack-var)
877</pre>
878</blockquote>
879<p>Advanced Functions:</p>
880<blockquote>
881<p>Evaluates to the contents of the variable <tt class="docutils literal"><span class="pre">var</span></tt>, with no expansion
882performed on it:</p>
883<pre class="literal-block">
884$(value var)
885</pre>
886<p>Evaluate <tt class="docutils literal"><span class="pre">text</span></tt> with <tt class="docutils literal"><span class="pre">var</span></tt> bound to each word in <tt class="docutils literal"><span class="pre">words</span></tt>, and
887concatenate the results (spaced):</p>
888<pre class="literal-block">
889$(foreach var,words,text)
890</pre>
891<p>Evaluate the variable <tt class="docutils literal"><span class="pre">var</span></tt> replacing any references to <tt class="docutils literal"><span class="pre">$(1)</span></tt>,
892<tt class="docutils literal"><span class="pre">$(2)</span></tt> with the first, second, etc. <tt class="docutils literal"><span class="pre">param</span></tt> values:</p>
893<pre class="literal-block">
894$(call var,param,...)
895</pre>
896<p>Evaluate <tt class="docutils literal"><span class="pre">text</span></tt> then read the results as makefile commands. Expands
897to the empty string:</p>
898<pre class="literal-block">
899$(eval text)
900</pre>
901<p>Same as <tt class="docutils literal"><span class="pre">$(eval</span> <span class="pre">text)</span></tt> except that the <tt class="docutils literal"><span class="pre">text</span></tt> is expanded in its
902own variable context:</p>
903<pre class="literal-block">
904$(evalctx text)
905</pre>
906<p>Same as <tt class="docutils literal"><span class="pre">$(eval</span> <span class="pre">$(value</span> <span class="pre">var))</span></tt>:</p>
907<pre class="literal-block">
908$(evalval var)
909</pre>
910<p>Same as <tt class="docutils literal"><span class="pre">$(evalctx</span> <span class="pre">$(value</span> <span class="pre">var))</span></tt>:</p>
911<pre class="literal-block">
912$(evalvalctx var)
913</pre>
914<p>A combination of <tt class="docutils literal"><span class="pre">$(eval</span> <span class="pre">)</span></tt>, <tt class="docutils literal"><span class="pre">$(call</span> <span class="pre">)</span></tt> and <tt class="docutils literal"><span class="pre">$(value</span> <span class="pre">)</span></tt>:</p>
915<pre class="literal-block">
916$(evalcall var)
917</pre>
918<p>A combination of <tt class="docutils literal"><span class="pre">$(eval</span> <span class="pre">)</span></tt> and <tt class="docutils literal"><span class="pre">$(call</span> <span class="pre">)</span></tt>:</p>
919<pre class="literal-block">
920$(evalcall var)
921</pre>
922<p>Remove comments and blank lines from the variable <tt class="docutils literal"><span class="pre">var</span></tt>. Expands to
923the empty string:</p>
924<pre class="literal-block">
925$(eval-opt-var var)
926</pre>
927<p>Returns accessing <tt class="docutils literal"><span class="pre">$&lt;</span></tt> of <tt class="docutils literal"><span class="pre">target</span></tt>, either retriving the whole thing
928or the file at <tt class="docutils literal"><span class="pre">pos</span></tt> (one-origin):</p>
929<pre class="literal-block">
930$(deps target[, pos])
931</pre>
932<p>Returns accessing <tt class="docutils literal"><span class="pre">$+</span></tt> (order + duplicates) of <tt class="docutils literal"><span class="pre">target</span></tt>, either
933retriving the whole thing or the file at <tt class="docutils literal"><span class="pre">pos</span></tt> (one-origin):</p>
934<pre class="literal-block">
935$(deps-all target[, pos])
936</pre>
937<p>Returns accessing <tt class="docutils literal"><span class="pre">$?</span></tt> of <tt class="docutils literal"><span class="pre">target</span></tt>, either retriving the whole
938thing or the file at <tt class="docutils literal"><span class="pre">pos</span></tt> (one-origin):</p>
939<pre class="literal-block">
940$(deps-newer target[, pos])
941</pre>
942<p>Returns accessing <tt class="docutils literal"><span class="pre">$|</span></tt> (order only) of <tt class="docutils literal"><span class="pre">target</span></tt>, either retriving the
943whole thing or the file at <tt class="docutils literal"><span class="pre">pos</span></tt> (one-origin):</p>
944<pre class="literal-block">
945$(deps-oo target[, pos])
946</pre>
947</blockquote>
948<p>Command Functions:</p>
949<blockquote>
950<p>Create one or more command lines avoiding the max argument
951length restriction of the host OS:</p>
952<pre class="literal-block">
953$(xargs ar cas mylib.a,$(objects))
954$(xargs ar cas mylib.a,ar as mylib.a,$(objects))
955</pre>
956<p>Returns the commands for the specified target separated by new-line, space,
957or a user defined string. Note that this might not produce the 100% correct
958result if any of the prerequisite automatic variables are used:</p>
959<pre class="literal-block">
960$(commands target)
961$(commands-sc target)
962$(commands-usr target,sep)
963</pre>
964<p>Compares two commands returning the empty string if equal and the 3rd
965argument if not. This differs from <tt class="docutils literal"><span class="pre">$(comp-vars</span> <span class="pre">v1,v2,ne)</span></tt> in that
966line by line is stripped of leading spaces, command prefixes and
967trailing spaces before comparing:</p>
968<pre class="literal-block">
969$(comp-cmds cmds-var1, cmds-var2, ne)
970$(comp-cmds-ex cmds1, cmd2, ne)
971</pre>
972<p>Compares the values of the two variables returning the empty string if
973equal and the 3rd argument if not. Leading and trailing spaces is ignored:</p>
974<pre class="literal-block">
975$(comp-var var1, var2, ne)
976</pre>
977</blockquote>
978<p>Utility functions:</p>
979<blockquote>
980<p>When this function is evaluated, <tt class="docutils literal"><span class="pre">kmk</span></tt> generates a fatal error with the
981message <tt class="docutils literal"><span class="pre">text</span></tt>:</p>
982<pre class="literal-block">
983$(error text...)
984</pre>
985<p>When this function is evaluated, <tt class="docutils literal"><span class="pre">kmk</span></tt> generates a warning with the
986message <tt class="docutils literal"><span class="pre">text</span></tt>:</p>
987<pre class="literal-block">
988$(warning text...)
989</pre>
990<p>When this function is evaluated, <tt class="docutils literal"><span class="pre">kmk</span></tt> generates a info with the
991message <tt class="docutils literal"><span class="pre">text</span></tt>:</p>
992<pre class="literal-block">
993$(info text...)
994</pre>
995<p>Execute a shell <tt class="docutils literal"><span class="pre">command</span></tt> and return its output:</p>
996<pre class="literal-block">
997$(shell command)
998</pre>
999<p>Return a string describing how the <tt class="docutils literal"><span class="pre">kmk</span></tt> variable <tt class="docutils literal"><span class="pre">variable</span></tt> was defined:</p>
1000<pre class="literal-block">
1001$(origin variable)
1002</pre>
1003<p>Return a string describing the flavor of the <tt class="docutils literal"><span class="pre">kmk</span></tt> variable <tt class="docutils literal"><span class="pre">variable</span></tt>:</p>
1004<pre class="literal-block">
1005$(flavor variable)
1006</pre>
1007<p>Returns the current local time and date formatted in the <tt class="docutils literal"><span class="pre">strftime</span></tt>
1008style specifier <tt class="docutils literal"><span class="pre">fmt</span></tt>. <tt class="docutils literal"><span class="pre">fmt</span></tt> defaults to <tt class="docutils literal"><span class="pre">%Y-%m-%dT%H:%M:%S</span></tt> when
1009not specified:</p>
1010<pre class="literal-block">
1011$(date fmt)
1012</pre>
1013<p>Returns the current UTC time and date formatted in the <tt class="docutils literal"><span class="pre">strftime</span></tt>
1014style specifier <tt class="docutils literal"><span class="pre">fmt</span></tt>. <tt class="docutils literal"><span class="pre">fmt</span></tt> defaults to <tt class="docutils literal"><span class="pre">%Y-%m-%dT%H:%M:%SZ</span></tt> when
1015not specified:</p>
1016<pre class="literal-block">
1017$(date-utc fmt)
1018</pre>
1019<p>Reformats the <tt class="docutils literal"><span class="pre">in</span></tt> time and date using <tt class="docutils literal"><span class="pre">fmt</span></tt>. The <tt class="docutils literal"><span class="pre">in-fmt</span></tt> defaults
1020to <tt class="docutils literal"><span class="pre">fmt</span></tt> if not specified. While <tt class="docutils literal"><span class="pre">fmt</span></tt> defaults to
1021<tt class="docutils literal"><span class="pre">%Y-%m-%dT%H:%M:%SZ</span></tt> if not specified:</p>
1022<pre class="literal-block">
1023$(date-utc fmt,time,in-fmt)
1024</pre>
1025<p>Returns the current nanosecond timestamp (monotonic when possible):</p>
1026<pre class="literal-block">
1027$(nanots )
1028</pre>
1029<p>Returns the size of the specified file, or -1 if the size could not
1030be obtained. This can be used to check if a file exist or not:</p>
1031<pre class="literal-block">
1032$(file-size file)
1033</pre>
1034<p>Searches the <tt class="docutils literal"><span class="pre">PATH</span></tt> <tt class="docutils literal"><span class="pre">kmk</span></tt> variable for the specified <tt class="docutils literal"><span class="pre">files</span></tt>:</p>
1035<pre class="literal-block">
1036$(which files...)
1037</pre>
1038<p>OS/2: Returns the specified LIBPATH variable value:</p>
1039<pre class="literal-block">
1040$(libpath var)
1041</pre>
1042<p>OS/2: Sets the specified LIBPATH variable value, returning the empty string:</p>
1043<pre class="literal-block">
1044$(libpath var,value)
1045</pre>
1046</blockquote>
1047<p>Debugging Functions:</p>
1048<blockquote>
1049<p>Returns various make statistics, if no item is specified a default
1050selection is returned:</p>
1051<pre class="literal-block">
1052$(make-stats item[,itemN])
1053</pre>
1054<p>Raise a debug breakpoint. Used for debugging <tt class="docutils literal"><span class="pre">kmk</span></tt> makefile parsing:</p>
1055<pre class="literal-block">
1056$(breakpoint )
1057</pre>
1058</blockquote>
1059</div>
1060<div class="section">
1061<h1><a id="special-targets" name="special-targets">Special Targets</a></h1>
1062<p>todo</p>
1063</div>
1064<div class="section">
1065<h1><a id="built-in-commands" name="built-in-commands">Built-in Commands</a></h1>
1066<p>todo</p>
1067</div>
1068<div class="section">
1069<h1><a id="kmk-expression" name="kmk-expression">kmk-expression</a></h1>
1070<p>todo</p>
1071<hr class="docutils" />
1072<table class="docutils field-list" frame="void" rules="none">
1073<col class="field-name" />
1074<col class="field-body" />
1075<tbody valign="top">
1076<tr class="field"><th class="field-name">Status:</th><td class="field-body"><p class="first">$Id: QuickReference-kmk.html 2147 2008-12-27 20:36:13Z bird $</p>
1077</td>
1078</tr>
1079<tr class="field"><th class="field-name">Copyright:</th><td class="field-body"><p class="first">Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995,
10801996, 1997, 1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006,
10812007 Free Software Foundation, Inc.</p>
1082<p class="last">Copyright (C) 2008 Knut St. Osmundsen</p>
1083</td>
1084</tr>
1085</tbody>
1086</table>
1087</div>
1088</div>
1089</body>
1090</html>
Note: See TracBrowser for help on using the repository browser.