| 1 | /* $Id: kBuilddocs.c 59 2003-12-13 19:14:23Z bird $ */
|
|---|
| 2 | /** @file
|
|---|
| 3 | * kBuild Documentation file with the sole purpose of giving doxygen
|
|---|
| 4 | * something to chew on.
|
|---|
| 5 | */
|
|---|
| 6 |
|
|---|
| 7 |
|
|---|
| 8 | /** @page kBuild kBuild
|
|---|
| 9 | *
|
|---|
| 10 | * @section kBuild_intro Introduction
|
|---|
| 11 | *
|
|---|
| 12 | * kBuild is a build system which intention is to simplify your makefiles
|
|---|
| 13 | * and to hide cross platform projects issues.
|
|---|
| 14 | *
|
|---|
| 15 | * kBuild is layered in three tiers, first comes the instructions given in the
|
|---|
| 16 | * makefile, seconds comes the instructions given in a configuration (CFG),
|
|---|
| 17 | * third comes the tool configuration. Now, let me explain by giving an
|
|---|
| 18 | * example - the typical hello world program.
|
|---|
| 19 | *
|
|---|
| 20 | * In the makefile you tell kBuild that there is one program called 'hello'
|
|---|
| 21 | * which shall be built by defining PROGRAMS=hello. This 'hello' target
|
|---|
| 22 | * have one source file 'hello.c', thus hello.SRCS=hello.c. For enabling the
|
|---|
| 23 | * compile time fireworks option WITH_FIREWORKS needs to be #defined, this is
|
|---|
| 24 | * acomplished setting hello_DEFS=WITH_FIREWORKS. The fireworks requires the
|
|---|
| 25 | * libfirecracker.a library, hello_LIBS=firecracker. hello_CFG=gcc.default
|
|---|
| 26 | * tells kBuild that the 'hello' program target is to build using the
|
|---|
| 27 | * configuration called 'gcc.default'.
|
|---|
| 28 | *
|
|---|
| 29 | * The configuration 'gcc.default' can be defined anywhere, but if it's not
|
|---|
| 30 | * defined yet kBuild will load it from the file 'cfg.gcc.default.kMk'.
|
|---|
| 31 | * The configuration contains definitions of how to build all kind of files
|
|---|
| 32 | * and references to the tools to be used and such. The configuration will
|
|---|
| 33 | * ask kBuild to load any tool configurations it needs. These configuration
|
|---|
| 34 | * files are named on the form 'tool.<toolname>.kMk'.
|
|---|
| 35 | *
|
|---|
| 36 | * The tool configuration contains callable macros and definitions for
|
|---|
| 37 | * invoking the tool. This process involes setting up required environment
|
|---|
| 38 | * variables, interpreting symblic flags, wrap setting up define and include
|
|---|
| 39 | * arguments (_DEFS, _INCL), executing the tool, and cleaning up.
|
|---|
| 40 | *
|
|---|
| 41 | *
|
|---|
| 42 | *
|
|---|
| 43 | * @section kBuild_makeref Makefile Reference
|
|---|
| 44 | *
|
|---|
| 45 | * The make file must start with including a configuration file which sets up
|
|---|
| 46 | * the inital kBuild environment with all it's standard variables. It's
|
|---|
| 47 | * prefered that you keep one or more include files for a project which figures
|
|---|
| 48 | * out stuff like the root location and includes the kBuild header.kmk file.
|
|---|
| 49 | * For the main config file of a source tree the prefered name is kBuild.kMk.
|
|---|
| 50 | *
|
|---|
| 51 | * After having included the kBuild environment and any additions to it
|
|---|
| 52 | * specific to the source tree (like predefined configurations) setup the main
|
|---|
| 53 | * target clues. The main target clues are what kBuild uses to determin what to
|
|---|
| 54 | * build and how those things are to be built. The clues are put into the
|
|---|
| 55 | * variables PROGRAMS, DLLS, DRIVERS, LIBRARIES, OBJECTS, JARS, CLASSES and
|
|---|
| 56 | * OTHERS. The variables and the attributes of their targets will be explained
|
|---|
| 57 | * in detail later.
|
|---|
| 58 | *
|
|---|
| 59 | * Giving kBuild it's main clues, set the attributes of each of the targets.
|
|---|
| 60 | *
|
|---|
| 61 | * When all target attributes have been set include the kBuild main rules. Do
|
|---|
| 62 | * this by specificly address the include: include $(PATH_KBUILD)/rules.kMk
|
|---|
| 63 | *
|
|---|
| 64 | * If there is need for any rules or your own, put them at the end of the
|
|---|
| 65 | * makefile. Target rules may be used to generate files, or to do special task
|
|---|
| 66 | * during custom passes, or make special targets specified in the OTHERS clue.
|
|---|
| 67 | *
|
|---|
| 68 | *
|
|---|
| 69 | */
|
|---|
| 70 |
|
|---|
