= The Big Picture =

The make tool is called [wiki:kmk kmk] and is a modified [wiki:'GNU make']. 

When invoked (without the {{{-f}}} option) this will happen:
 1. [wiki:kmk kmk] will look for {{{Makefile.kmk}}}, {{{makefile.kmk}}}, {{{GNUmakefile}}}, {{{makefile}}} or {{{Makefile}}} in that order and read the first it finds. 
 1. In the makefile there are {{{include}}} statements which in turn will cause {{{header.kmk}}} and {{{footer.kmk}}} to be loaded. 
 1. {{{header.kmk}}} will setup a bunch of useful variables and load the first {{{Config.kmk}}} or {{{config.kmk}}} file in the directory tree starting from the makefile directory and up to {{{DEPTH}}}.
 1. {{{footer.kmk}}} will generate [wiki:goals make goals] from the target lists and target properties defined in the makefile.
 1. [wiki:kmk kmk] will start at the default goal ({{{all_recursive}}}) and resolve all its prerequisites.
 1. This will cause the list of passes in {{{DEFAULT_PASSES}}} to be iterated, recusing into subdirectories if configured to do so for each pass.


= The Target Lists =

[wiki:kBuild kBuild] will by default pick up and process the following target lists:
 1. {{{BLDPROGS}}} - build programs, e.g. programs that will be used later in the build process and will run on the build platform. Will by default be compiled with the {{{BUILD_PLATFORM}}} as target.
 1. {{{LIBRARIES}}} and {{{IMPORT_LIBS}}} - object libraries.
 1. {{{DLLS}}} - dynamic link libraries and shared objects.
 1. {{{PROGRAMS}}} - program binaries.
 1. {{{SYSMODS}}} - system modules, kernel extentions, device drivers, etc.
 1. {{{OTHERS}}} - user defined targets.
 1. {{{INSTALLS}}} - installation targets. This can be excluded from the default pass by adding {{{DEFAULT_PASSES := $(filter-out INSTALLS,$(DEFAULT_PASSES))}}} to the relevant {{{Config.kmk}}}.
 1. {{{PACKING}}} - the packing goals. These are the prerequisties for the {{{packing}}} pass.

TODO: More details.

= The Target Properties = 

Each target has a number of properties which [wiki:kBuild kBuild] will look for. Some of these properties will come from the '''template''' if used, others will be picked up from the relevant '''tool''' and '''sdks'''. Which properties [wiki:kBuild kBuild] looks for depends on which target list the target was picked up in.

{{{
#!html
<table class="wiki">
 <thead>
  <tr>
   <td>Property</td><td>Target Lists</td><td>Template Inheritance</td>
   <td>
    Description
   </td>
  </tr>
 </head>
 <tbody>
  <tr>
   <td>TEMPLATE</td><td>BLDPROGS, LIBRARIES, DLLS, PROGRAMS, SYSMODS, INSTALLS</td><td>No</td>
   <td>
    The property template to apply. Make sure you strip trailing tabs/spaces!
   </td>
  </tr>
  <tr>
   <td>TOOL</td><td>BLDPROGS, LIBRARIES, DLLS, PROGRAMS, SYSMODS, INSTALLS</td><td>Yes</td>
   <td>
    The tool to use to build this target.
   </td>
  </tr>
  <tr>
   <td>ATOOL</td><td>BLDPROGS, LIBRARIES, DLLS, PROGRAMS, SYSMODS</td><td>Yes</td>
   <td>
    The assembler tool to use to build this target or the assembly sources for this target.
   </td>
  </tr>
 </tbody>
</table>
}}}

...


= Using kBuild in Your Project =

First question, where should [wiki:kBuild] be installed?
There are three answers to that question:
 1. In the source tree, either imported or linked to as an svn:external. You'll need to find an easy way of invoking [wiki:kmk] with {{{PATH_KBUILD}}} set, either on the commandline or in the environment. This can typically be achieved with a script which modified the environment or installs a shell alias.
 2. Require [wiki:kBuild] to checked out somewhere outside the tree. You'll still have to find an easy way of invoking [wiki:kmk] with {{{PATH_KBUILD}}} set.
 3. Require [wiki:kBuild] to be installed on the system. This is an option which is currently being realized, see ticket #6.

Second question, which [wiki:kBuild] version to install?
It's recommended that you select the current release branch and use that. See [wiki:Versioning kBuild Versioning] for details about how a release branch is managed.
If you're really adventurous and doesn't mind some periods where things get busted, you can also use the trunk.