{{{ #!rst kmk Quick Reference =================== This appendix summarizes the directives, text manipulation functions, and special variables which ``kmk`` understands. .. See section Special Built-in Target Names and Summary of Options, for other summaries. 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 ``$@``. | +-----------+-----------------------------------------------------------------+ | ``$( 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) (Mostly) Boolean 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 kmk-expression,true-part[,false-part]) 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 ``text`` with ``var`` bound to each word in ``words``, and concatenate the results (spaced):: $(foreach var,words,text) 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 ----- :Status: $Id: QuickReference-kmk.txt 2146 2008-12-27 20:22:53Z 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 Knut St. Osmundsen }}}