wiki:kmk Quick Reference

Context Navigation

Version 2 (modified by bird, 16 years ago) ( diff )
--

kmk Quick Reference

This appendix summarizes the directives, text manipulation functions, and special variables which kmk understands.

Directives

Here is a summary of the directives kmk recognizes:

Define a multi-line, recursively-expanded variable:
define variable
endef
Conditionally evaluate part of the makefile:
ifdef variable
ifndef variable
ifeq (a,b)
ifeq "a" "b"
ifeq 'a' 'b'
ifneq (a,b)
ifneq "a" "b"
ifneq 'a' 'b'
if1of (set-a,set-b)
ifn1of (set-a,set-b)
if expression
else
endif
Include another makefile:
include file
-include file
sinclude file
Include another dependency file:
includedep file
Define a variable, overriding any previous definition, even one from the command line:
override variable = value
override variable := value
override variable += value
override variable <= value
override variable ?= value
override define variable
endef
Tell kmk to export all variables to child processes by default:
export
Tell kmk whether or not to export a particular variable to child processes:
export variable
export variable = value
export variable := value
export variable += value
export variable <= value
export variable ?= value
unexport variable
Define a variable in the local context instead of the global one:
local variable = value
local variable := value
local variable += value
local variable <= value
local variable ?= value
local define variable
endef
Specify a search path for files matching a % pattern:
vpath pattern path
Remove all search paths previously specified for pattern:
vpath pattern
Remove all search paths previously specified in any vpath directive:
vpath

Automatic variables

Here is a summary of the automatic variables.

Variable	Description
`$@`	The file name of the target.
`$<`	The name of the first prerequisite.
`$?`	The names of all the prerequisites that are newer than the target, with spaces between them.
`$^`	The names of all the prerequisites, duplicates omitted.
`$+`	The names of all the prerequisites, duplicates and order preserved
`$*`	The stem with which an implicit rule matches.
`$\|`	The name of all the order only prerequisites.
`$(@D)`	The directory part of `$@`.
`$(<D)`	The directory part of `$<`.
`$(?D)`	The directory part of `$?`.
`$(^D)`	The directory part of `%^`.
`$(+D)`	The directory part of `$+`.
`$(*D)`	The directory part of `$*`.
`$(\|D)`	The directory part of `$\|`.
`$(@F)`	The file-within-directory part of `$@`.
`$(<F)`	The file-within-directory part of `$<`.
`$(?F)`	The file-within-directory part of `$?`.
`$(^F)`	The file-within-directory part of `$^`.
`$(+F)`	The file-within-directory part of `$+`.
`$(*F)`	The file-within-directory part of `$*`.
`$(\|F)`	The file-within-directory part of `$\|`.

Special variables

All variables starting with a . is reserved by kmk. The following variables are specially used or/and defined by kmk:

Variable	Description
`.DEFAULT_GOAL`	The makefile default goal. You can set this in the makefile, if you don't it will default to the first target that is encountered.
`.FEATURES`	List of GNU `make` features. Do not set this.
`.INCLUDE_DIRS`	List of include directories, `-I` arguments and defaults. Do not set this.
`.RECIPEPREFIX`	Recipe prefix, defaults to tab.
`.VARIABLES`	Special variable which exands to the list of variable. Do not set this.
`CURDIR`	Set to the pathname of the current working directory (after all `-C` options are processed, if any). Do not set this.
`KBUILD_VERSION`, `KBUILD_VERSION_MAJOR`, `KBUILD_VERSION_MINOR`, `KBUILD_VERSION_PATCH`, `KBUILD_KMK_REVISION`	The kBuild version string and the break down into individual components.
`KBUILD_HOST`	The host operating system.
`KBUILD_HOST_ARCH`	The host architecture.
`KBUILD_HOST_CPU`	The host CPU `kmk` is built for, set to `blend` if not any particular CPU.
`KBUILD_PATH`	Where the kBuild scripts are.
`KBUILD_BIN_PATH`	Where the host specific kBuild binaries are.
`KMK`, `MAKE`	The name with which `kmk` was invoked. Using this variable in recipes has special meaning.
`KMK_BUILTIN`	List of built-in commands.
`KMK_FEATURES`	List of `kmk` specific features.
`KMK_FLAGS`	The flags given to `kmk`. You can set this in the environment or a makefile to set flags. It is never appropriate to use `KMK_FLAGS` directly in a recipe line: its contents may not be quoted correctly for use in the shell. Always allow recursive `kmk`'s to obtain these values through the environment from its parent.
`KMK_LEVEL`	The number of levels of recursion (sub-makes).
`KMK_VERSION`	The GNU `make` version number.
`MAKECMDGOALS`	The targets given to `kmk` on the command line. Do not set this.
`MAKEFILES`	Makefiles to be read on every invocation of `kmk`.
`MAKEFILE_LIST`	List of the makefiles that `kmk` has opened.
`MAKESHELL`	OS/2 and MS-DOS only, the name of the command interpreter that is to be used by `kmk`. This value takes precedence over the value of SHELL.
`SHELL`	The name of the default command interpreter, kmk_ash. You can set SHELL in the makefile to change the shell used to run recipes. The SHELL variable is handled specially when importing from and exporting to the environment.
`SUFFIXES`	The default list of suffixes before `kmk` reads any makefiles (always empty).
`VPATH`	Directory search path for files not found in the current directory.

The following variables reflects kmk options. Do not set these.

Variable	Description
`KMK_OPTS_JOBS`	-j slots, `0` if not given.
`KMK_OPTS_KEEP_GOING`	-k indictor (`0`/`1`).
`KMK_OPTS_JUST_PRINT`	-n indicator (`0`/`1`).
`KMK_OPTS_PRORITY`	--priority level, `0` if not given.
`KMK_OPTS_AFFINITY`	--affinity mask, `0` if not given.
`KMK_OPTS_STATISTICS`	--statistics indicator (`0`/`1`).
`KMK_OPTS_PRINT_TIME`	The --print-time value.
`KMK_OPTS_PRETTY_COMMAND_PRINTING`	--pretty-command-printing indicator.

Built-in functions

String Manipulation Functions:

Replace from with to in text:
$(subst from,to,text)
Replace words matching pattern with replacement in text:
$(patsubst pattern,replacement,text)
Remove excess whitespace characters from string:
$(strip string)
Locate find in text, returning find if found:
$(findstring find,text)
Select words in text that match one of the pattern words:
$(filter pattern...,text)
Select words in text that do not match any of the pattern words:
$(filter-out pattern...,text)
Sort the words in list lexicographically, removing duplicates:
$(sort list)
Sort the words in list lexicographically in reserve order, removing duplicates:
$(rsort list)
Count the number of words in text:
$(words text)
Extract the nth word (one-origin) of text:
$(word n,text)
Returns the list of words in text from s to e (one-origin):
$(wordlist s,e,text)
Extract the first word of names:
$(firstword names...)
Extract the last word of names:
$(lastword names...)
Join two parallel lists of words:
$(join list1,list2)
Fold text to upper case:
$(toupper text)
Fold text to lower case:
$(tolower text)
String formatting a la the unix printf command:
$(printf fmt, arg...)
Return the length of a string or a (unexpanded) variable:
$(length string)
$(length-var var)
Find the position of needle in haystack, returns 0 if not found. Negative start indices are relative to the end of haystack, while positive ones are one based:
$(pos needle, haystack[, start])
$(lastpos needle, haystack[, start])
Returns the specified substring. The start works like with $(pos ). If the substring is partially outside the string the result will be padded with pad if present:
$(substr string, start[, length[, pad]])
Insert in into str at the specified position. n works like with $(pos ), except that 0 is the end of the string:
$(insert in, str[, n[, length[, pad]]])
Translate string exchanging characters in from-set with to-set, optionally completing to-set with pad-char if specified. If no pad-char characters absent in to-set will be deleted:
$(translate string, from-set[, to-set[, pad-char]])

Functions for file names:

Extract the directory part of each file name:
$(dir names...)
Extract the non-directory part of each file name:
$(notdir names...)
Extract the suffix (the last . and following characters) of each file name:
$(suffix names...)
Extract the base name (name without suffix) of each file name:
$(basename names...)
Append suffix to each word in names:
$(addsuffix suffix,names...)
Prepend prefix to each word in names:
$(addprefix prefix,names...)
Find file names matching a shell file name pattern (not a % pattern):
$(wildcard pattern...)
For each file name in names, expand to an absolute name that does not contain any ., .., nor symlinks:
$(realpath names...)
For each file name in names, expand to an absolute name that does not contain any . or .. components, but preserves symlinks:
$(abspath names...)
Same as $(abspath ) except that the current directory can be specified as curdir:
$(abspathex names...[, curdir])

Arithmetic Functions:

Returns the sum of the arguments:
$(int-add addend1, addend2[, addendN])
Returns the difference between the first argument and the sum of the rest:
$(int-sub minuend, subtrahend[, subtrahendN])
Returns the product of the arguments:
$(int-mul factor1, factor2[, factorN])
Returns the quotient of first argument and the rest:
$(int-div dividend, divisor[, divisorN])
Returns the modulus of the two arguments:
$(int-mod dividend, divisor)
Returns the bitwise two-complement of argument:
$(int-not val)
Returns the result of a bitwise AND of the arguments:
$(int-and val1, val2[, valN])
Returns the result of a bitwise OR of the arguments:
$(int-or val1, val2[, valN])
Returns the result of a bitwise XOR of the arguments:
$(int-xor val1, val2[, valN])
Returns the kmk boolean (true = non-empty, false = empty) result of val1 == val2:
$(int-eq val1, val2)
Returns the kmk boolean result of val1 != val2:
$(int-ne val1, val2)
Returns the kmk boolean result of val1 > val2:
$(int-gt val1, val2)
Returns the kmk boolean result of val1 >= val2:
$(int-ge val1, val2)
Returns the kmk boolean result of val1 < val2:
$(int-lt val1, val2)
Returns the kmk boolean result of val1 <= val2:
$(int-le val1, val2)

Boolean and Conditional Functions:

Condition is false if the condition evaluates to an empty string (stripped). Evaluate the true-part if the condition is true, otherwise the false-part:
$(if condition,true-part[,false-part])
Test if any of the conditions evalues to non-empty string, returning the first one:
$(or condition1[,condition2[,condition3[...]]])
Test if all of the conditions evaluates to non-empty strings, returning the last one:
$(and condition1[,condition2[,condition3[...]]])
Test if the two strings are identical, returning kmk boolean (true = non-empty, false = empty):
$(eq str1, str2)
Invert a kmk boolean value:
$(not val)
Test if variable is defined, returning a kmk boolean value:
$(defined variable)
Test if set-a and set-b intersects, returning a kmk boolean value:
$(intersects set-a, set-b)
Same as $(if ) execpt that the condition is a kmk expression:
$(if-expr kmk-expression,true-part[,false-part])
Select the first true condition (kmk expression) and expand the following body. Special condition strings default and otherwise:
$(select when1-cond, when1-body[, whenN-cond, whenN-body])
Evalutate the kmk expression returning what it evalues as. This is the preferred way of doing arithmentic now:
$(expr kmk-expression)

Stack Fuctions:

Push item onto the stack-var, returning the empty string:
$(stack-push stack-var, item)
Pop the top item off the stack-var:
$(stack-pop stack-var)
Pop the top item off the stack-var, returning the empty string:
$(stack-popv stack-var)
Get the top item of the stack-var, returning the empty string:
$(stack-top stack-var)

Advanced Functions:

Evaluates to the contents of the variable var, with no expansion performed on it:
$(value var)
Evaluate body with var bound to each word in words, and concatenate the results (spaced):
$(foreach var,words,body)
C-style for-loop. Start by evaluating init. Each iteration will first check whether the condition (kmk-expression) is true, then expand body concatenating the result to the previous iterations (spaced), and finally evaluate next:
$(for init,conditions,next,body)
C-style while-loop. Each iteration will check whether the condition (kmk-expression) is true, then expand body concatenating the result to the previous iterations:
$(while conditions,body)
Evaluate the variable var replacing any references to $(1), $(2) with the first, second, etc. param values:
$(call var,param,...)
Evaluate text then read the results as makefile commands. Expands to the empty string:
$(eval text)
Same as $(eval text) except that the text is expanded in its own variable context:
$(evalctx text)
Same as $(eval $(value var)):
$(evalval var)
Same as $(evalctx $(value var)):
$(evalvalctx var)
A combination of $(eval ), $(call ) and $(value ):
$(evalcall var)
A combination of $(eval ) and $(call ):
$(evalcall var)
Remove comments and blank lines from the variable var. Expands to the empty string:
$(eval-opt-var var)
Returns accessing $< of target, either retriving the whole thing or the file at pos (one-origin):
$(deps target[, pos])
Returns accessing $+ (order + duplicates) of target, either retriving the whole thing or the file at pos (one-origin):
$(deps-all target[, pos])
Returns accessing $? of target, either retriving the whole thing or the file at pos (one-origin):
$(deps-newer target[, pos])
Returns accessing $| (order only) of target, either retriving the whole thing or the file at pos (one-origin):
$(deps-oo target[, pos])

Command Functions:

Create one or more command lines avoiding the max argument length restriction of the host OS:
$(xargs ar cas mylib.a,$(objects))
$(xargs ar cas mylib.a,ar as mylib.a,$(objects))
Returns the commands for the specified target separated by new-line, space, or a user defined string. Note that this might not produce the 100% correct result if any of the prerequisite automatic variables are used:
$(commands target)
$(commands-sc target)
$(commands-usr target,sep)
Compares two commands returning the empty string if equal and the 3rd argument if not. This differs from $(comp-vars v1,v2,ne) in that line by line is stripped of leading spaces, command prefixes and trailing spaces before comparing:
$(comp-cmds cmds-var1, cmds-var2, ne)
$(comp-cmds-ex cmds1, cmd2, ne)
Compares the values of the two variables returning the empty string if equal and the 3rd argument if not. Leading and trailing spaces is ignored:
$(comp-var var1, var2, ne)

Utility functions:

When this function is evaluated, kmk generates a fatal error with the message text:
$(error text...)
When this function is evaluated, kmk generates a warning with the message text:
$(warning text...)
When this function is evaluated, kmk generates a info with the message text:
$(info text...)
Execute a shell command and return its output:
$(shell command)
Return a string describing how the kmk variable variable was defined:
$(origin variable)
Return a string describing the flavor of the kmk variable variable:
$(flavor variable)
Returns the current local time and date formatted in the strftime style specifier fmt. fmt defaults to %Y-%m-%dT%H:%M:%S when not specified:
$(date fmt)
Returns the current UTC time and date formatted in the strftime style specifier fmt. fmt defaults to %Y-%m-%dT%H:%M:%SZ when not specified:
$(date-utc fmt)
Reformats the in time and date using fmt. The in-fmt defaults to fmt if not specified. While fmt defaults to %Y-%m-%dT%H:%M:%SZ if not specified:
$(date-utc fmt,time,in-fmt)
Returns the current nanosecond timestamp (monotonic when possible):
$(nanots )
Returns the size of the specified file, or -1 if the size could not be obtained. This can be used to check if a file exist or not:
$(file-size file)
Searches the PATH kmk variable for the specified files:
$(which files...)
OS/2: Returns the specified LIBPATH variable value:
$(libpath var)
OS/2: Sets the specified LIBPATH variable value, returning the empty string:
$(libpath var,value)

Debugging Functions:

Returns various make statistics, if no item is specified a default selection is returned:
$(make-stats item[,itemN])
Raise a debug breakpoint. Used for debugging kmk makefile parsing:
$(breakpoint )

Special Targets

todo

Built-in Commands

todo

kmk-expression

todo

Status:

$Id: QuickReference-kmk.txt 2163 2008-12-30 00:57:13Z bird $

Note: See TracWiki for help on using the wiki.

Download in other formats:

Plain Text