The Big Picture

The make tool is called kmk and is a modified GNU make.

When invoked (without the -f option) this will happen:

1. kmk will look for Makefile.kmk, makefile.kmk, GNUmakefile, makefile or Makefile in that order and read the first it finds.
2. In the makefile there are include statements which in turn will cause header.kmk and footer.kmk to be loaded.
3. 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.
4. footer.kmk will generate make goals from the target lists and target properties defined in the makefile.
5. kmk will start at the default goal (all_recursive) and resolve all its prerequisites.
6. 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

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.
2. LIBRARIES and IMPORT_LIBS - object libraries.
3. DLLS - dynamic link libraries and shared objects.
4. PROGRAMS - program binaries.
5. SYSMODS - system modules, kernel extentions, device drivers, etc.
6. OTHERS - user defined targets.
7. 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.
8. 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 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 kBuild looks for depends on which target list the target was picked up in.

Property	Target Lists	Template Inheritance	Description
TEMPLATE	BLDPROGS, LIBRARIES, DLLS, PROGRAMS, SYSMODS, INSTALLS	No	The property template to apply. Make sure you strip trailing tabs/spaces!
TOOL	BLDPROGS, LIBRARIES, DLLS, PROGRAMS, SYSMODS, INSTALLS	Yes	The tool to use to build this target.
ATOOL	BLDPROGS, LIBRARIES, DLLS, PROGRAMS, SYSMODS	Yes	The assembler tool to use to build this target or the assembly sources for this target.

...

Using kBuild in Your Project

First question, where should 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 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 kBuild to checked out somewhere outside the tree. You'll still have to find an easy way of invoking kmk with PATH_KBUILD set.
3. Require kBuild to be installed on the system. This is an option which is currently being realized, see ticket #6.

Second question, which kBuild version to install? It's recommended that you select the current release branch and use that. See 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.