{{{
#!rst

kBuild Quick Reference
======================

This is an attempt at summarizing the magic of kBuild makefiles. 

Note! This is work in progress and very very incomplete at the moment.


The anatomy of a kBuild Makefile
--------------------------------

A typical makefile::

    # $Id: QuickReference-kBuild.txt 2345 2009-04-19 23:47:42Z bird $
    ## @file
    # Makefile description.
    #

    #
    # Copyright (c) year name
    # License, disclaimer and other legal text.
    #

    SUB_DEPTH = ../..
    include $(KBUILD_PATH)/subheader.kmk

    #
    # Include sub-makefiles.
    #
    include $(PATH_CURRENT)/subdir1/Makefile.kmk
    include $(PATH_CURRENT)/subdir2/Makefile.kmk

    #
    # Global variables.
    #
    MYPREFIX_SOMETHING = or another

    #
    # Target lists.
    #
    DLLS += mydll
    PROGRAMS += myprogs

    #
    # mydll - description.
    #
    mydll_TEMPLATE = MYDLL
    mydll_SOURCES = mydll.c
    mydll_SOURCES.win = $(mydll_0_OUTDIR)/mydll.def

    #
    # myprog - description.
    #
    myprog_TEMPLATE = MYPROG
    myprog_SOURCES = myprog.c

    #
    # Custom rules (optional of course).
    #
    $$(mydll_0_OUTDIR)/mydll.def:
    	$(APPEND) -t $@ LIBRARY mydll.dll
    	$(APPEND)    $@ EXPORTS
    	$(APPEND)    $@ '    myfunction'

    include $(FILE_KBUILD_SUB_FOOTER)


Target lists
------------

+-+-------------------+-------------------------------------------------------+
|#| Name              | Description                                           |
+=+===================+=======================================================+
|1| ``BLDPROGS``      | Build programs, targets the host platform.            |
+-+-------------------+-------------------------------------------------------+
|2| ``LIBRARIES``     | Libraries (not shared).                               |
+-+-------------------+-------------------------------------------------------+
|3| ``IMPORT_LIBS``   | Import libraries or stub shared libraries.            |
+-+-------------------+-------------------------------------------------------+
|4| ``DLLS``          | DLLs, Shared Libraries, DYLIBs, etc.                  |
+-+-------------------+-------------------------------------------------------+
|5| ``PROGRAMS``      | Executable programs.                                  |
+-+-------------------+-------------------------------------------------------+
|6| ``SYSMODS``       | System modules (kexts, kernel modules, drivers, etc). |
+-+-------------------+-------------------------------------------------------+
|7| ``MISCBINS``      | Miscellanceous binaries like BIOS images and such.    |
+-+-------------------+-------------------------------------------------------+
|8| ``INSTALLS``      | Things to install. [1]_                               |
+-+-------------------+-------------------------------------------------------+
|9| ``FETCHES``       | Things to fetch. [1]_                                 |
+-+-------------------+-------------------------------------------------------+
|a| ``OTHERS``        | List of targets made during the others pass.          |
+-+-------------------+-------------------------------------------------------+


Target properties
-----------------

The first column indicates the kind of property, S=Single, D=Deferred,
Ar=Accumlate-Right and Al=Accumulate-Left.

The third column should be cross referenced with the first column in the
target list table above.

+--+-------------------+-------+----------------------------------------------+
|K | Name              | Which | Description                                  |
+==+===================+=======+==============================================+
|S | ``ARLIBSUFF``     | 2     |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``ARTOOL``        | 2     |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``ASOBJSUFF``     | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``ASTOOL``        | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``BINSUFF``       | 7     |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``BLD_TRG``       | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``BLD_TRG_ARCH``  | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``BLD_TRG_CPU``   | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``BLD_TYPE``      | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``COBJSUFF``      | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``CTOOL``         | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``CXXOBJSUFF``    | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``CXXTOOL``       | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``DLLSUFF``       | 34    |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``EXESUFF``       | 15    |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``FETCHDIR``      | 9     |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``FETCHTOOL``     | 9     |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``GID``           | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``INST``          | 1-9   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``LDTOOL``        | 13-7  |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``LIBSUFF``       | 234   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``MODE``          | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``NOINST``        | 1-8   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``OBJCOBJSUFF``   | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``OBJCTOOL``      | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``OBJSUFF``       | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``PATCHTOOL``     | 9     |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``RCOBJSUFF``     | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``RCTOOL``        | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``SYSSUFF``       | 6     |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``TEMPLATE``      | 1-9   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``TOOL``          | 1-9   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``UID``           | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``UNPACKTOOL``    | 9     |                                              |
+--+-------------------+-------+----------------------------------------------+
|D | ``INSTALLER``     | 1-8   |                                              |
+--+-------------------+-------+----------------------------------------------+
|D | ``INSTFUN``       | 1-8   |                                              |
+--+-------------------+-------+----------------------------------------------+
|D | ``NAME``          | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|D | ``POST_CMDS``     | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|D | ``PRE_CMDS``      | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|D | ``SONAME``        | 13-7  |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``ARFLAGS``       | 2     |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``ASDEFS``        | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``ASFLAGS``       | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``CDEFS``         | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``CFLAGS``        | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``CXXDEFS``       | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``CXXFLAGS``      | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``DEFS``          | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``DEPS``          | 1-8   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``FETCHFLAGS``    | 9     |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``IDFLAGS``       | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``IFDLAGS``       | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``ISFLAGS``       | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``LDFLAGS``       | 13-7  |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``LNK_DEPS``      | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``LNK_ORDERDEPS`` | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``OBJCDEFS``      | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``OBJCFLAGS``     | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``ORDERDEPS``     | 1-8   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``PATCHFLAGS``    | 9     |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``RCDEFS``        | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``RCFLAGS``       | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``UNPACKFLAGS``   | 9     |                                              |
+--+-------------------+-------+----------------------------------------------+
|Al| ``ASINCS``        | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Al| ``BLDDIRS``       | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Al| ``CINCS``         | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Al| ``CLEAN``         | 1-9   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Al| ``CXXINCS``       | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Al| ``DIRS``          | 8     |                                              |
+--+-------------------+-------+----------------------------------------------+
|Al| ``INCS``          | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Al| ``INTERMEDIATES`` | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Al| ``LIBPATH``       | 13-7  |                                              |
+--+-------------------+-------+----------------------------------------------+
|Al| ``LIBS``          | 13-7  |                                              |
+--+-------------------+-------+----------------------------------------------+
|Al| ``OBJCINCS``      | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Al| ``RCINCS``        | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Al| ``SDKS``          | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Al| ``SOURCES``       | 1-9   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Al| ``SRC_HANDLERS``  | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Al| ``USES``          | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+


-----

.. [1] Normally not one of the default passes.

-----

:Status: $Id: QuickReference-kBuild.txt 2345 2009-04-19 23:47:42Z bird $
:Copyright: Copyright (c) 2009 knut st. osmundsen

}}}