kmk Quick Reference =================== This is an attempt at summarizing all directives, functions, special variables, special targets, built-in commands, external commands, and ``kmk``-expressions. Since *all* the features are included, the quickness of this reference can be disputed. ;-) 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) [1] ifn1of (set-a,set-b) [1] if expression [1] else endif Include another makefile:: include file -include file sinclude file Include another dependency file [1]_:: 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 [1] 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 [1] export variable ?= value unexport variable Define a variable in the local context instead of the global one [1]_:: 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 ``$@``. | +-----------+-----------------------------------------------------------------+ | ``$(>`` | | Bitwise right shift. | +---------------+--------+-----------------------------------------------------+ | ``<=`` | Binary | Less or equal than. | +---------------+ +-----------------------------------------------------+ | ``<`` | | Less than. | +---------------+ +-----------------------------------------------------+ | ``>=`` | | Greater or equal than. | +---------------+ +-----------------------------------------------------+ | ``>`` | | Greater than. | +---------------+--------+-----------------------------------------------------+ | ``==`` | Binary | Equal to. | +---------------+ +-----------------------------------------------------+ | ``!=`` | | Not equal to. | +---------------+--------+-----------------------------------------------------+ | ``&`` | Binary | Bitwise AND. | +---------------+--------+-----------------------------------------------------+ | ``^`` | Binary | Bitwise XOR. | +---------------+--------+-----------------------------------------------------+ | ``|`` | Binary | Bitwise OR. | +---------------+--------+-----------------------------------------------------+ | ``&&`` | Binary | Logical AND. | +---------------+--------+-----------------------------------------------------+ | ``||`` | Binary | Logical OR. | +---------------+--------+-----------------------------------------------------+ 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 [1]_:: $(rsort list) Count the number of words in ``text``:: $(words text) Extract the ``n``\th 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 [1]_:: $(toupper text) Fold ``text`` to lower case [1]_:: $(tolower text) String formatting a la the unix ``printf`` command [1]_:: $(printf fmt, arg...) Return the length of a string or a (unexpanded) variable [1]_:: $(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 [1]_:: $(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 [1]_:: $(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 [1]_:: $(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 [1]_:: $(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...) Extract the root specification of each file name (a bit complicated on Windows & OS/2) [1]_:: $(root 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`` [1]_:: $(abspathex names...[, curdir]) Arithmetic Functions: Returns the sum of the arguments [1]_:: $(int-add addend1, addend2[, addendN]) Returns the difference between the first argument and the sum of the rest [1]_:: $(int-sub minuend, subtrahend[, subtrahendN]) Returns the product of the arguments [1]_:: $(int-mul factor1, factor2[, factorN]) Returns the quotient of first argument and the rest [1]_:: $(int-div dividend, divisor[, divisorN]) Returns the modulus of the two arguments [1]_:: $(int-mod dividend, divisor) Returns the bitwise two-complement of argument [1]_:: $(int-not val) Returns the result of a bitwise AND of the arguments [1]_:: $(int-and val1, val2[, valN]) Returns the result of a bitwise OR of the arguments [1]_:: $(int-or val1, val2[, valN]) Returns the result of a bitwise XOR of the arguments [1]_:: $(int-xor val1, val2[, valN]) Returns the ``kmk`` boolean (true = non-empty, false = empty) result of ``val1 == val2`` [1]_:: $(int-eq val1, val2) Returns the ``kmk`` boolean result of ``val1 != val2`` [1]_:: $(int-ne val1, val2) Returns the ``kmk`` boolean result of ``val1 > val2`` [1]_:: $(int-gt val1, val2) Returns the ``kmk`` boolean result of ``val1 >= val2`` [1]_:: $(int-ge val1, val2) Returns the ``kmk`` boolean result of ``val1 < val2`` [1]_:: $(int-lt val1, val2) Returns the ``kmk`` boolean result of ``val1 <= val2`` [1]_:: $(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) [2]_:: $(eq str1, str2) Invert a ``kmk`` boolean value [2]_:: $(not val) Test if ``variable`` is defined, returning a ``kmk`` boolean value [1]_:: $(defined variable) Test if ``set-a`` and ``set-b`` intersects, returning a ``kmk`` boolean value [1]_:: $(intersects set-a, set-b) Same as ``$(if )`` execpt that the condition is a ``kmk``-expression [1]_:: $(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`` [1]_:: $(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 [1]_:: $(expr kmk-expression) Stack Fuctions: Push ``item`` onto the ``stack-var``, returning the empty string [1]_:: $(stack-push stack-var, item) Pop the top item off the ``stack-var`` [1]_:: $(stack-pop stack-var) Pop the top item off the ``stack-var``, returning the empty string [1]_:: $(stack-popv stack-var) Get the top item of the ``stack-var``, returning the empty string [1]_:: $(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`` [1]_:: $(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 [1]_:: $(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 [1]_:: $(evalctx text) Same as ``$(eval $(value var))`` [1]_:: $(evalval var) Same as ``$(evalctx $(value var))`` [1]_:: $(evalvalctx var) A combination of ``$(eval )``, ``$(call )`` and ``$(value )`` [1]_:: $(evalcall var) A combination of ``$(eval )`` and ``$(call )`` [1]_:: $(evalcall var) Remove comments and blank lines from the variable ``var``. Expands to the empty string [1]_:: $(eval-opt-var var) Returns accessing ``$<`` of ``target``, either retriving the whole thing or the file at ``pos`` (one-origin) [1]_:: $(deps target[, pos]) Returns accessing ``$+`` (order + duplicates) of ``target``, either retriving the whole thing or the file at ``pos`` (one-origin) [1]_:: $(deps-all target[, pos]) Returns accessing ``$?`` of ``target``, either retriving the whole thing or the file at ``pos`` (one-origin) [1]_:: $(deps-newer target[, pos]) Returns accessing ``$|`` (order only) of ``target``, either retriving the whole thing or the file at ``pos`` (one-origin) [1]_:: $(deps-oo target[, pos]) Command Functions: Create one or more command lines avoiding the max argument length restriction of the host OS [1]_:: $(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 [1]_:: $(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 [1]_:: $(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 [1]_:: $(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 [1]_:: $(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 [1]_:: $(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 [1]_:: $(date-utc fmt,time,in-fmt) Returns the current nanosecond timestamp (monotonic when possible) [1]_:: $(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 [1]_:: $(file-size file) Searches the ``PATH`` ``kmk`` variable for the specified ``files`` [1]_:: $(which files...) OS/2: Returns the specified LIBPATH variable value [1]_:: $(libpath var) OS/2: Sets the specified LIBPATH variable value, returning the empty string [1]_:: $(libpath var,value) Debugging Functions: Returns various make statistics, if no item is specified a default selection is returned [1]_:: $(make-stats item[,itemN]) Raise a debug breakpoint. Used for debugging ``kmk`` makefile parsing [1]_:: $(breakpoint ) ----- .. [1] ``kmk`` only feature. .. [2] Experimental GNU ``make`` feature that is not enabled by default. ----- :Status: $Id: QuickReference-kmk.txt 2243 2009-01-10 02:24:02Z bird $ :Copyright: Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. Copyright (c) 2008-2009 knut st. osmundsen