Changes between Initial Version and Version 1 of kmk Quick Reference

Timestamp:

Dec 27, 2008, 9:32:24 PM (16 years ago)

Author:

bird

Comment:

--

kmk Quick Reference

@@ +1 @@
+{{{
+#!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 ``$@``.                                   |
++-----------+-----------------------------------------------------------------+
+| ``$(<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``,      | The kBuild version string and the break down     |
+| ``KBUILD_VERSION_MAJOR``,| into individual components.                      |
+| ``KBUILD_VERSION_MINOR``,|                                                  |
+| ``KBUILD_VERSION_PATCH``,|                                                  |
+| ``KBUILD_KMK_REVISION``  |                                                  |
++--------------------------+--------------------------------------------------+
+| ``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``,                 | The name with which ``kmk`` was invoked. Using   |
+| ``MAKE``                 | 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 ``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::
+
+        $(toupper text)
+
+    Fold ``text`` to lower case::
+
+        $(tolower text)
+
+    String formatting a la the unix ``printf`` command::
+
+        $(printf fmt, arg...)
+
+
+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)
+
+
+(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
+
+}}}