Changes between Version 2 and Version 3 of kmk Quick Reference


Ignore:
Timestamp:
Dec 31, 2008, 1:12:04 AM (11 years ago)
Author:
bird
Comment:

updated to current text

Legend:

Unmodified
Added
Removed
Modified
  • kmk Quick Reference

    v2 v3  
    55===================
    66
    7 This appendix summarizes the directives, text manipulation functions, and
    8 special variables which ``kmk`` understands.
    9 
    10 .. See section Special Built-in Target Names and Summary of Options, for other
    11    summaries.
     7This is an attempt at summarizing all directives, functions, special variables,
     8special targets, built-in commands, external commands, and ``kmk``-expressions.
     9Since *all* the features are included, the quickness of this reference can be
     10disputed. ;-)
     11
    1212
    1313
     
    3232        ifneq "a" "b"
    3333        ifneq 'a' 'b'
    34         if1of (set-a,set-b)
    35         ifn1of (set-a,set-b)
    36         if expression
     34        if1of (set-a,set-b)             [1]
     35        ifn1of (set-a,set-b)            [1]
     36        if expression                   [1]
    3737        else
    3838        endif
     
    4444        sinclude file
    4545
    46     Include another dependency file::
     46    Include another dependency file [1]_::
    4747
    4848        includedep file
     
    5454        override variable := value
    5555        override variable += value
    56         override variable <= value
     56        override variable <= value      [1]
    5757        override variable ?= value
    5858        override define variable
     
    7070        export variable := value
    7171        export variable += value
    72         export variable <= value
     72        export variable <= value        [1]
    7373        export variable ?= value
    7474        unexport variable
    7575
    76     Define a variable in the local context instead of the global one::
     76    Define a variable in the local context instead of the global one [1]_::
    7777
    7878        local variable = value
     
    181181+--------------------------+--------------------------------------------------+
    182182| ``KBUILD_VERSION``,      | The kBuild version string and the break down     |
    183 | ``KBUILD_VERSION_MAJOR``,| into individual components.                      |
     183| ``KBUILD_VERSION_MAJOR``,| into individual components. [1]_                 |
    184184| ``KBUILD_VERSION_MINOR``,|                                                  |
    185185| ``KBUILD_VERSION_PATCH``,|                                                  |
    186186| ``KBUILD_KMK_REVISION``  |                                                  |
    187187+--------------------------+--------------------------------------------------+
    188 | ``KBUILD_HOST``          | The host operating system.                       |
    189 +--------------------------+--------------------------------------------------+
    190 | ``KBUILD_HOST_ARCH``     | The host architecture.                           |
    191 +--------------------------+--------------------------------------------------+
    192 | ``KBUILD_HOST_CPU``     | The host CPU ``kmk`` is built for, set to        |
     188| ``KBUILD_HOST`` [1]_     | The host operating system.                       |
     189+--------------------------+--------------------------------------------------+
     190| ``KBUILD_HOST_ARCH`` [1]_| The host architecture.                           |
     191+--------------------------+--------------------------------------------------+
     192| ``KBUILD_HOST_CPU`` [1]_ | The host CPU ``kmk`` is built for, set to        |
    193193|                          | ``blend`` if not any particular CPU.             |
    194194+--------------------------+--------------------------------------------------+
    195 | ``KBUILD_PATH``          | Where the kBuild scripts are.                    |
    196 +--------------------------+--------------------------------------------------+
    197 | ``KBUILD_BIN_PATH``     | Where the host specific kBuild binaries are.     |
    198 +--------------------------+--------------------------------------------------+
    199 | ``KMK``,                 | The name with which ``kmk`` was invoked. Using   |
     195| ``KBUILD_PATH`` [1]_     | Where the kBuild scripts are.                    |
     196+--------------------------+--------------------------------------------------+
     197| ``KBUILD_BIN_PATH`` [1]_ | Where the host specific kBuild binaries are.     |
     198+--------------------------+--------------------------------------------------+
     199| ``KMK`` [1]_,            | The name with which ``kmk`` was invoked. Using   |
    200200| ``MAKE``                 | this variable in recipes has special meaning.    |
    201201+--------------------------+--------------------------------------------------+
    202 | ``KMK_BUILTIN``          | List of built-in commands.                       |
    203 +--------------------------+--------------------------------------------------+
    204 | ``KMK_FEATURES``         | List of ``kmk`` specific features.               |
    205 +--------------------------+--------------------------------------------------+
    206 | ``KMK_FLAGS``            | The flags given to ``kmk``. You can set this in  |
     202| ``KMK_BUILTIN`` [1]_     | List of built-in commands.                       |
     203+--------------------------+--------------------------------------------------+
     204| ``KMK_FEATURES`` [1]_    | List of ``kmk`` specific features.               |
     205+--------------------------+--------------------------------------------------+
     206| ``KMK_FLAGS`` [1]_       | The flags given to ``kmk``. You can set this in  |
    207207|                          | the environment or a makefile to set flags.      |
    208208|                          |                                                  |
     
    213213|                          | through the environment from its parent.         |
    214214+--------------------------+--------------------------------------------------+
    215 | ``KMK_LEVEL``            | The number of levels of recursion (sub-makes).   |
    216 +--------------------------+--------------------------------------------------+
    217 | ``KMK_VERSION``          | The GNU ``make`` version number.                 |
     215| ``KMK_LEVEL`` [1]_       | The number of levels of recursion (sub-makes).   |
     216+--------------------------+--------------------------------------------------+
     217| ``KMK_VERSION`` [1]_     | The GNU ``make`` version number.                 |
    218218+--------------------------+--------------------------------------------------+
    219219| ``MAKECMDGOALS``         | The targets given to ``kmk`` on the command line.|
     
    243243
    244244
    245 The following variables reflects ``kmk`` options. Do not set these.
     245The following variables reflects ``kmk`` options. Do not set these. [1]_
    246246
    247247+-------------------------------------+---------------------------------------+
     
    267267
    268268
     269Special Targets
     270---------------
     271
     272Certain names have special meanings if they appear as targets.
     273
     274+-------------------------------+---------------------------------------------+
     275| Target                        | Description                                 |
     276+===============================+=============================================+
     277| ``.DEFAULT``                  | The recipe is used for any target for which |
     278|                               | no rules are found.                         |
     279+-------------------------------+---------------------------------------------+
     280| ``.DELETE_ON_ERROR``          | If mentioned, ``kmk`` will delete the       |
     281|                               | targets of a rule if it has changed and its |
     282|                               | recipe fails or is interrupted.             |
     283+-------------------------------+---------------------------------------------+
     284| ``.EXPORT_ALL_VARIABLES``     | If mentioned, all variables will by default |
     285|                               | be exported to child processes.             |
     286+-------------------------------+---------------------------------------------+
     287| ``.IGNORE``                   | Ignore errors in the execution of the recipe|
     288|                               | for the targets ``.IGNORE`` depends on, if  |
     289|                               | no prequisites all targets are affected.    |
     290+-------------------------------+---------------------------------------------+
     291| ``.INTERMEDIATE``             | The prerequisites are treated as            |
     292|                               | intermediate files (implicite rules).       |
     293+-------------------------------+---------------------------------------------+
     294| ``.LOW_RESOLUTION_TIME``      | ``kmk`` will assume prerequisite files are  |
     295|                               | created with low resolution time stamps.    |
     296+-------------------------------+---------------------------------------------+
     297| ``.NOTPARALLEL``              | If mentioned without any prerequisites,     |
     298|                               | ``kmk`` will run serially as if -j1 was     |
     299|                               | given. If it has prerequisites ``kmk`` [1]_ |
     300|                               | will only do this for the targets among     |
     301|                               | them.                                       |
     302+-------------------------------+---------------------------------------------+
     303| ``.PHONY``                    | The prerequisites are considered phony and  |
     304|                               | will be rebuilt unconditionally.            |
     305+-------------------------------+---------------------------------------------+
     306| ``.PRECIOUS``                 | The targets which ``.PRECIOUS`` depends     |
     307|                               | will to be deleted if ``kmk`` is killed or  |
     308|                               | interrupted while their building.           |
     309+-------------------------------+---------------------------------------------+
     310| ``.SECONDARY``                | The prerequisites are treated as            |
     311|                               | intermediate files, except that they are    |
     312|                               | never automatically deleted. If used with   |
     313|                               | no prerequisites all targets gets this      |
     314|                               | treatement.                                 |
     315+-------------------------------+---------------------------------------------+
     316| ``.SECONDEXPANSION``          | If mentioned, all prerequisite lists after  |
     317|                               | it will be expanded a second time after all |
     318|                               | makefiles have been read.                   |
     319+-------------------------------+---------------------------------------------+
     320| ``.SECONDTARGETEXPANSION``    | If mentioned, all targets after it will be  |
     321| [1]_                          | expanded a second time after all makefiles  |
     322|                               | have been read.                             |
     323+-------------------------------+---------------------------------------------+
     324| ``.SILENT``                   | ``kmk`` will not print the recipe for       |
     325|                               | targets listed as prerequisites, if none    |
     326|                               | then it applies to all targets.             |
     327+-------------------------------+---------------------------------------------+
     328| ``.SUFFIXES``                 | The prerequisites are the list of suffixes  |
     329|                               | used in checking for suffix rules. If it    |
     330|                               | appears without prerequisites it the suffix |
     331|                               | will be cleared.                            |
     332+-------------------------------+---------------------------------------------+
     333
     334
     335
     336Commands
     337--------
     338
     339Builtin commands [1]_ all start with ``kmk_builtin_``, so in order to save
     340space this prefix has been omitted in the table below. All commands comes in an
     341external edition that can be used by/in the shell, these are prefixed ``kmk_``.
     342
     343+---------------+-------------------------------------------------------------+
     344| Command       | Description                                                 |
     345+===============+=============================================================+
     346| ``append``    | Append text to a file. The builtin version can output the   |
     347|               | value of a variable or the commands of a target.            |
     348+---------------+-------------------------------------------------------------+
     349| ``cat``       | The BSD ``cat`` command.                                    |
     350+---------------+-------------------------------------------------------------+
     351| ``chmod``     | The BSD ``chmod`` command.                                  |
     352+---------------+-------------------------------------------------------------+
     353| ``cmp``       | The BSD ``cmp`` command.                                    |
     354+---------------+-------------------------------------------------------------+
     355| ``cp``        | The BSD ``cp`` command with some twaking.                   |
     356+---------------+-------------------------------------------------------------+
     357| ``echo``      | The BSD ``echo`` command.                                   |
     358+---------------+-------------------------------------------------------------+
     359| ``expr``      | The BSD ``expr`` command.                                   |
     360+---------------+-------------------------------------------------------------+
     361| ``install``   | The BSD ``install`` command with some tweaking.             |
     362+---------------+-------------------------------------------------------------+
     363| ``kDepIDB``   | Extract dependencies from a Visual C++ .IDB file.           |
     364+---------------+-------------------------------------------------------------+
     365| ``ln``        | The BSD ``ln`` command.                                     |
     366+---------------+-------------------------------------------------------------+
     367| ``md5sum``    | Typical MD5 sum program, custom kBuild version.             |
     368+---------------+-------------------------------------------------------------+
     369| ``mkdir``     | The BSD ``mkdir`` command.                                  |
     370+---------------+-------------------------------------------------------------+
     371| ``mv``        | The BSD ``mv`` command with some tweaking.                  |
     372+---------------+-------------------------------------------------------------+
     373| ``printf``    | The BSD ``printf`` command.                                 |
     374+---------------+-------------------------------------------------------------+
     375| ``rm``        | The BSD ``rm`` command with some tweaking.                  |
     376+---------------+-------------------------------------------------------------+
     377| ``rmdir``     | The BSD ``rmdir`` command with some tweaking.               |
     378+---------------+-------------------------------------------------------------+
     379| ``sleep``     | Typical ``sleep`` program, custom kBuild version.           |
     380+---------------+-------------------------------------------------------------+
     381| ``test``      | The BSD ``test`` program with some tweaking.                |
     382+---------------+-------------------------------------------------------------+
     383
     384Some additional external commands are available in the ``kmk`` / ``kBuild``
     385environment (``kSomething`` command are not prefixed with ``kmk_``):
     386
     387+---------------+-------------------------------------------------------------+
     388| Command       | Description                                                 |
     389+===============+=============================================================+
     390| ``kDepPre``   | Extract dependencies from the C/C++ preprocessor output.    |
     391+---------------+-------------------------------------------------------------+
     392| ``kObjCache`` | Simple object file cache program.                           |
     393+---------------+-------------------------------------------------------------+
     394| ``ash``       | Almquist's shell (NetBSD variant).                          |
     395+---------------+-------------------------------------------------------------+
     396| ``gmake``     | Vanilla GNU ``make`` from same sources as ``kmk``.          |
     397+---------------+-------------------------------------------------------------+
     398| ``redirect``  | Shell avoidance tool. Sets up file descriptors, environment |
     399|               | variables and current directory before kicking of program.  |
     400+---------------+-------------------------------------------------------------+
     401| ``sed``       | GNU ``sed`` with some tweaks to avoid involving the shell.  |
     402+---------------+-------------------------------------------------------------+
     403| ``time``      | Stopwatch utility for measuring program execution time(s).  |
     404+---------------+-------------------------------------------------------------+
     405
     406
     407
     408kmk-expression
     409--------------
     410
     411``kmk``-expressions [1]_ are related to the C/C++ preprocessor in some ways as
     412well as ``nmake`` and BSD ``make``. There are however some peculiarities
     413because of the way GNU ``make`` choose to represent booleans in its function
     414library, so, strings can be turned into boolean by taking any non-empty string
     415as true.
     416
     417Quoting using single quotes results in hard strings, while double quotes and
     418unquoted string results in soft strings that can be converted to number or
     419boolean to fit the situation.
     420
     421Here's the operator table in decending precedence order:
     422
     423+---------------+--------+-----------------------------------------------------+
     424| Operator      | Type   | Description                                         |
     425+===============+========+=====================================================+
     426| ``defined``   | Unary  | Checks if the following variable exists.            |
     427+---------------+        +-----------------------------------------------------+
     428| ``exists``    |        | Checks if the following file exists.                |
     429+---------------+        +-----------------------------------------------------+
     430| ``target``    |        | Checks if the following target exists.              |
     431+---------------+        +-----------------------------------------------------+
     432| ``bool``      |        | Casts the following value to boolean.               |
     433+---------------+        +-----------------------------------------------------+
     434| ``num``       |        | Casts the following value to a number.              |
     435+---------------+        +-----------------------------------------------------+
     436| ``str``       |        | Casts the following value to a string.              |
     437+---------------+--------+-----------------------------------------------------+
     438| ``!``         | Unary  | Logical NOT.                                        |
     439+---------------+        +-----------------------------------------------------+
     440| ``+``         |        | Pluss prefix.                                       |
     441+---------------+        +-----------------------------------------------------+
     442| ``-``         |        | Minus prefix.                                       |
     443+---------------+        +-----------------------------------------------------+
     444| ``~``         |        | Bitwise one's complement.                           |
     445+---------------+--------+-----------------------------------------------------+
     446| ``*``         | Binary | Multiplication (product).                           |
     447+---------------+        +-----------------------------------------------------+
     448| ``/``         |        | Division (quotient).                                |
     449+---------------+        +-----------------------------------------------------+
     450| ``%``         |        | Modulus (remainder).                                |
     451+---------------+--------+-----------------------------------------------------+
     452| ``+``         | Binary | Addition (sum).                                     |
     453+---------------+        +-----------------------------------------------------+
     454| ``-``         |        | Subtraction (difference).                           |
     455+---------------+--------+-----------------------------------------------------+
     456| ``<<``        | Binary | Bitwise left shift.                                 |
     457+---------------+        +-----------------------------------------------------+
     458| ``>>``        |        | Bitwise right shift.                                |
     459+---------------+--------+-----------------------------------------------------+
     460| ``<=``        | Binary | Less or equal than.                                 |
     461+---------------+        +-----------------------------------------------------+
     462| ``<``         |        | Less than.                                          |
     463+---------------+        +-----------------------------------------------------+
     464| ``>=``        |        | Greater or equal than.                              |
     465+---------------+        +-----------------------------------------------------+
     466| ``>``         |        | Greater than.                                       |
     467+---------------+--------+-----------------------------------------------------+
     468| ``==``        | Binary | Equal to.                                           |
     469+---------------+        +-----------------------------------------------------+
     470| ``!=``        |        | Not equal to.                                       |
     471+---------------+--------+-----------------------------------------------------+
     472| ``&``         | Binary | Bitwise AND.                                        |
     473+---------------+--------+-----------------------------------------------------+
     474| ``^``         | Binary | Bitwise XOR.                                        |
     475+---------------+--------+-----------------------------------------------------+
     476| ``|``         | Binary | Bitwise OR.                                         |
     477+---------------+--------+-----------------------------------------------------+
     478| ``&&``        | Binary | Logical AND.                                        |
     479+---------------+--------+-----------------------------------------------------+
     480| ``||``        | Binary | Logical OR.                                         |
     481+---------------+--------+-----------------------------------------------------+
     482
     483
     484
    269485Built-in functions
    270486------------------
     
    302518
    303519    Sort the words in ``list`` lexicographically in reserve order, removing
    304     duplicates::
     520    duplicates [1]_::
    305521
    306522        $(rsort list)
     
    330546        $(join list1,list2)
    331547
    332     Fold ``text`` to upper case::
     548    Fold ``text`` to upper case [1]_::
    333549
    334550        $(toupper text)
    335551
    336     Fold ``text`` to lower case::
     552    Fold ``text`` to lower case [1]_::
    337553
    338554        $(tolower text)
    339555
    340     String formatting a la the unix ``printf`` command::
     556    String formatting a la the unix ``printf`` command [1]_::
    341557
    342558        $(printf fmt, arg...)
    343559
    344     Return the length of a string or a (unexpanded) variable::
     560    Return the length of a string or a (unexpanded) variable [1]_::
    345561
    346562        $(length string)
     
    349565    Find the position of ``needle`` in ``haystack``, returns 0 if not found.
    350566    Negative ``start`` indices are relative to the end of ``haystack``, while
    351     positive ones are one based::
     567    positive ones are one based [1]_::
    352568
    353569        $(pos needle, haystack[, start])
     
    356572    Returns the specified substring. The ``start`` works like with ``$(pos )``.
    357573    If the substring is partially outside the ``string`` the result will be
    358     padded with ``pad`` if present::
     574    padded with ``pad`` if present [1]_::
    359575
    360576        $(substr string, start[, length[, pad]])
    361577
    362578    Insert ``in`` into ``str`` at the specified position. ``n`` works like with
    363     ``$(pos )``, except that ``0`` is the end of the string::
     579    ``$(pos )``, except that ``0`` is the end of the string [1]_::
    364580
    365581        $(insert in, str[, n[, length[, pad]]])
     
    367583    Translate ``string`` exchanging characters in ``from-set`` with ``to-set``,
    368584    optionally completing ``to-set`` with ``pad-char`` if specified. If no
    369     ``pad-char`` characters absent in ``to-set`` will be deleted::
     585    ``pad-char`` characters absent in ``to-set`` will be deleted [1]_::
    370586
    371587        $(translate string, from-set[, to-set[, pad-char]])
     
    391607        $(basename names...)
    392608
     609    Extract the root specification of each file name (a bit complicated on
     610    Windows & OS/2) [1]_::
     611
     612        $(root names...)
     613
    393614    Append ``suffix`` to each word in ``names``::
    394615
     
    415636
    416637    Same as ``$(abspath )`` except that the current directory can be
    417     specified as ``curdir``::
     638    specified as ``curdir`` [1]_::
    418639
    419640        $(abspathex names...[, curdir])
     
    422643Arithmetic Functions:
    423644
    424     Returns the sum of the arguments::
     645    Returns the sum of the arguments [1]_::
    425646
    426647        $(int-add addend1, addend2[, addendN])
    427648
    428     Returns the difference between the first argument and the sum of the rest::
     649    Returns the difference between the first argument and the sum of the
     650    rest [1]_::
    429651
    430652        $(int-sub minuend, subtrahend[, subtrahendN])
    431653
    432     Returns the product of the arguments::
     654    Returns the product of the arguments [1]_::
    433655
    434656        $(int-mul factor1, factor2[, factorN])
    435657
    436     Returns the quotient of first argument and the rest::
     658    Returns the quotient of first argument and the rest [1]_::
    437659
    438660        $(int-div dividend, divisor[, divisorN])
    439661
    440     Returns the modulus of the two arguments::
     662    Returns the modulus of the two arguments [1]_::
    441663
    442664        $(int-mod dividend, divisor)
    443665
    444     Returns the bitwise two-complement of argument::
     666    Returns the bitwise two-complement of argument [1]_::
    445667
    446668        $(int-not val)
    447669
    448     Returns the result of a bitwise AND of the arguments::
     670    Returns the result of a bitwise AND of the arguments [1]_::
    449671
    450672        $(int-and val1, val2[, valN])
    451673
    452     Returns the result of a bitwise OR of the arguments::
     674    Returns the result of a bitwise OR of the arguments [1]_::
    453675
    454676        $(int-or val1, val2[, valN])
    455677
    456     Returns the result of a bitwise XOR of the arguments::
     678    Returns the result of a bitwise XOR of the arguments [1]_::
    457679
    458680        $(int-xor val1, val2[, valN])
    459681
    460682    Returns the ``kmk`` boolean (true = non-empty, false = empty) result
    461     of ``val1 == val2``::
     683    of ``val1 == val2`` [1]_::
    462684
    463685        $(int-eq val1, val2)
    464686
    465     Returns the ``kmk`` boolean result of ``val1 != val2``::
     687    Returns the ``kmk`` boolean result of ``val1 != val2`` [1]_::
    466688
    467689        $(int-ne val1, val2)
    468690
    469     Returns the ``kmk`` boolean result of ``val1 > val2``::
     691    Returns the ``kmk`` boolean result of ``val1 > val2`` [1]_::
    470692
    471693        $(int-gt val1, val2)
    472694
    473     Returns the ``kmk`` boolean result of ``val1 >= val2``::
     695    Returns the ``kmk`` boolean result of ``val1 >= val2`` [1]_::
    474696
    475697        $(int-ge val1, val2)
    476698
    477     Returns the ``kmk`` boolean result of ``val1 < val2``::
     699    Returns the ``kmk`` boolean result of ``val1 < val2`` [1]_::
    478700
    479701        $(int-lt val1, val2)
    480702
    481     Returns the ``kmk`` boolean result of ``val1 <= val2``::
     703    Returns the ``kmk`` boolean result of ``val1 <= val2`` [1]_::
    482704
    483705        $(int-le val1, val2)
     
    504726
    505727    Test if the two strings are identical, returning ``kmk`` boolean (true =
    506     non-empty, false = empty)::
     728    non-empty, false = empty) [2]_::
    507729
    508730        $(eq str1, str2)
    509731
    510     Invert a ``kmk`` boolean value::
     732    Invert a ``kmk`` boolean value [2]_::
    511733
    512734        $(not val)
    513735
    514     Test if ``variable`` is defined, returning a ``kmk`` boolean value::
     736    Test if ``variable`` is defined, returning a ``kmk`` boolean value [1]_::
    515737
    516738        $(defined variable)
    517739
    518740    Test if ``set-a`` and ``set-b`` intersects, returning a ``kmk`` boolean
    519     value::
     741    value [1]_::
    520742
    521743        $(intersects set-a, set-b)
    522744
    523     Same as ``$(if )`` execpt that the condition is a ``kmk`` expression::
     745    Same as ``$(if )`` execpt that the condition is a ``kmk``-expression [1]_::
    524746
    525747        $(if-expr kmk-expression,true-part[,false-part])
    526748
    527     Select the first true condition (``kmk`` expression) and expand the
    528     following body. Special condition strings ``default`` and ``otherwise``::
     749    Select the first true condition (``kmk``-expression) and expand the
     750    following body. Special condition strings ``default`` and
     751    ``otherwise`` [1]_::
    529752
    530753        $(select when1-cond, when1-body[, whenN-cond, whenN-body])
    531754
    532     Evalutate the ``kmk`` expression returning what it evalues as. This is
    533     the preferred way of doing arithmentic now::
     755    Evalutate the ``kmk-expression`` returning what it evalues as. This is
     756    the preferred way of doing arithmentic now [1]_::
    534757
    535758        $(expr kmk-expression)
     
    538761Stack Fuctions:
    539762
    540       Push ``item`` onto the ``stack-var``, returning the empty string::
     763      Push ``item`` onto the ``stack-var``, returning the empty string [1]_::
    541764
    542765            $(stack-push stack-var, item)
    543766
    544       Pop the top item off the ``stack-var``::
     767      Pop the top item off the ``stack-var`` [1]_::
    545768
    546769            $(stack-pop stack-var)
    547770
    548       Pop the top item off the ``stack-var``, returning the empty string::
     771      Pop the top item off the ``stack-var``, returning the empty string [1]_::
    549772
    550773            $(stack-popv stack-var)
    551774
    552       Get the top item of the ``stack-var``, returning the empty string::
     775      Get the top item of the ``stack-var``, returning the empty string [1]_::
    553776
    554777            $(stack-top stack-var)
     
    570793    first check whether the ``condition`` (``kmk``-expression) is true,
    571794    then expand ``body`` concatenating the result to the previous iterations
    572     (spaced), and finally evaluate ``next``::
     795    (spaced), and finally evaluate ``next`` [1]_::
    573796
    574797        $(for init,conditions,next,body)
     
    576799    C-style while-loop. Each iteration will check whether the ``condition``
    577800    (``kmk``-expression) is true, then expand ``body`` concatenating the
    578     result to the previous iterations::
     801    result to the previous iterations [1]_::
    579802
    580803        $(while conditions,body)
     
    591814
    592815    Same as ``$(eval text)`` except that the ``text`` is expanded in its
    593     own variable context::
     816    own variable context [1]_::
    594817
    595818        $(evalctx text)
    596819
    597     Same as ``$(eval $(value var))``::
     820    Same as ``$(eval $(value var))`` [1]_::
    598821
    599822        $(evalval var)
    600823
    601     Same as ``$(evalctx $(value var))``::
     824    Same as ``$(evalctx $(value var))`` [1]_::
    602825
    603826        $(evalvalctx var)
    604827
    605     A combination of ``$(eval )``, ``$(call )`` and ``$(value )``::
     828    A combination of ``$(eval )``, ``$(call )`` and ``$(value )`` [1]_::
    606829
    607830        $(evalcall var)
    608831
    609     A combination of ``$(eval )`` and ``$(call )``::
     832    A combination of ``$(eval )`` and ``$(call )`` [1]_::
    610833
    611834        $(evalcall var)
    612835
    613836    Remove comments and blank lines from the variable ``var``. Expands to
    614     the empty string::
     837    the empty string [1]_::
    615838
    616839        $(eval-opt-var var)
    617840
    618841    Returns accessing ``$<`` of ``target``, either retriving the whole thing
    619     or the file at ``pos`` (one-origin)::
     842    or the file at ``pos`` (one-origin) [1]_::
    620843
    621844        $(deps target[, pos])
    622845
    623846    Returns accessing ``$+`` (order + duplicates) of ``target``, either
    624     retriving the whole thing or the file at ``pos`` (one-origin)::
     847    retriving the whole thing or the file at ``pos`` (one-origin) [1]_::
    625848
    626849        $(deps-all target[, pos])
    627850
    628851    Returns accessing ``$?``  of ``target``, either retriving the whole
    629     thing or the file at ``pos`` (one-origin)::
     852    thing or the file at ``pos`` (one-origin) [1]_::
    630853
    631854        $(deps-newer target[, pos])
    632855
    633856    Returns accessing ``$|`` (order only)  of ``target``, either retriving the
    634     whole thing or the file at ``pos`` (one-origin)::
     857    whole thing or the file at ``pos`` (one-origin) [1]_::
    635858
    636859        $(deps-oo target[, pos])
     
    640863
    641864    Create one or more command lines avoiding the max argument
    642     length restriction of the host OS::
     865    length restriction of the host OS [1]_::
    643866
    644867        $(xargs ar cas mylib.a,$(objects))
     
    648871    Returns the commands for the specified target separated by new-line, space,
    649872    or a user defined string. Note that this might not produce the 100% correct
    650     result if any of the prerequisite automatic variables are used::
     873    result if any of the prerequisite automatic variables are used [1]_::
    651874
    652875        $(commands target)
     
    657880    argument if not. This differs from ``$(comp-vars v1,v2,ne)`` in that
    658881    line by line is stripped of leading spaces, command prefixes and
    659     trailing spaces before comparing::
     882    trailing spaces before comparing [1]_::
    660883
    661884        $(comp-cmds cmds-var1, cmds-var2, ne)
     
    664887
    665888    Compares the values of the two variables returning the empty string if
    666     equal and the 3rd argument if not. Leading and trailing spaces is ignored::
     889    equal and the 3rd argument if not. Leading and trailing spaces is
     890    ignored [1]_::
    667891
    668892        $(comp-var var1, var2, ne)
     
    700924    Returns the current local time and date formatted in the ``strftime``
    701925    style specifier ``fmt``. ``fmt`` defaults to ``%Y-%m-%dT%H:%M:%S`` when
    702     not specified::
     926    not specified [1]_::
    703927
    704928        $(date fmt)
     
    706930    Returns the current UTC time and date formatted in the ``strftime``
    707931    style specifier ``fmt``. ``fmt`` defaults to ``%Y-%m-%dT%H:%M:%SZ`` when
    708     not specified::
     932    not specified [1]_::
    709933
    710934        $(date-utc fmt)
     
    712936    Reformats the ``in`` time and date using ``fmt``. The ``in-fmt`` defaults
    713937    to ``fmt`` if not specified. While ``fmt`` defaults to
    714     ``%Y-%m-%dT%H:%M:%SZ`` if not specified::
     938    ``%Y-%m-%dT%H:%M:%SZ`` if not specified [1]_::
    715939
    716940        $(date-utc fmt,time,in-fmt)
    717941
    718     Returns the current nanosecond timestamp (monotonic when possible)::
     942    Returns the current nanosecond timestamp (monotonic when possible) [1]_::
    719943
    720944        $(nanots )
    721945
    722946    Returns the size of the specified file, or -1 if the size could not
    723     be obtained. This can be used to check if a file exist or not::
     947    be obtained. This can be used to check if a file exist or not [1]_::
    724948
    725949        $(file-size file)
    726950
    727     Searches the ``PATH`` ``kmk`` variable for the specified ``files``::
     951    Searches the ``PATH`` ``kmk`` variable for the specified ``files`` [1]_::
    728952
    729953        $(which files...)
    730954
    731     OS/2: Returns the specified LIBPATH variable value::
     955    OS/2: Returns the specified LIBPATH variable value [1]_::
    732956
    733957        $(libpath var)
    734958
    735     OS/2: Sets the specified LIBPATH variable value, returning the empty string::
     959    OS/2: Sets the specified LIBPATH variable value, returning the empty
     960    string [1]_::
    736961
    737962        $(libpath var,value)
     
    741966
    742967    Returns various make statistics, if no item is specified a default
    743     selection is returned::
     968    selection is returned [1]_::
    744969
    745970        $(make-stats item[,itemN])
    746971
    747     Raise a debug breakpoint. Used for debugging ``kmk`` makefile parsing::
     972    Raise a debug breakpoint. Used for debugging ``kmk`` makefile
     973    parsing [1]_::
    748974
    749975        $(breakpoint )
    750976
    751977
    752 
    753 Special Targets
    754 ---------------
    755 
    756 todo
    757 
    758 
    759 
    760 Built-in Commands
    761 -----------------
    762 
    763 todo
    764 
    765 
    766 
    767 kmk-expression
    768 --------------
    769 
    770 todo
    771 
    772 
    773 
    774978-----
    775979
    776 :Status: $Id: QuickReference-kmk.txt 2163 2008-12-30 00:57:13Z bird $
     980.. [1] ``kmk`` only feature.
     981.. [2] Experimental GNU ``make`` feature that is not enabled by default.
     982
     983-----
     984
     985:Status: $Id: QuickReference-kmk.txt 2172 2008-12-31 00:03:02Z bird $
    777986:Copyright: Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995,
    778987            1996, 1997, 1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006,