/* $Id: kBuilddocs.c 62 2003-12-13 23:27:56Z bird $ */
/** @file
* A kBuild Documentation file with the sole purpose of giving doxygen
* something to chew on.
*/
/** @mainpage kBuild
*
* @section kBuild_intro Introduction
*
* kBuild is a build system which intention is to simplify your makefiles
* and to hide cross platform detail for projects.
*
* kBuild is layered in three tiers, first comes the instructions given in the
* makefile, seconds comes the instructions given in a configuration (CFG),
* third comes the tool configuration. Now, let me explain by giving an
* example - the typical hello world program.
*
* In the makefile you tell kBuild that there is one program called 'hello'
* which shall be built by defining PROGRAMS=hello. This 'hello' target
* have one source file 'hello.c', thus hello.SRCS=hello.c. For enabling the
* compile time fireworks option WITH_FIREWORKS needs to be #defined, this is
* acomplished setting hello_DEFS=WITH_FIREWORKS. The fireworks requires the
* libfirecracker.a library, hello_LIBS=firecracker. hello_CFG=gcc.default
* tells kBuild that the 'hello' program target is to build using the
* configuration called 'gcc.default'.
*
* The configuration 'gcc.default' can be defined anywhere, but if it's not
* defined yet kBuild will load it from the file 'cfg.gcc.default.kMk'.
* The configuration contains definitions of how to build all kind of files
* and references to the tools to be used and such. The configuration will
* ask kBuild to load any tool configurations it needs. These configuration
* files are named on the form 'tool.[toolname].kMk'.
*
* The tool configuration contains callable macros and definitions for
* invoking the tool. This process involes setting up required environment
* variables, interpreting symblic flags, wrap setting up define and include
* arguments (_DEFS, _INCL), executing the tool, and cleaning up.
*
*
*
* @section kBuild_makeref Makefile Reference
*
* The make file must start with including a configuration file which sets up
* the inital kBuild environment with all it's standard variables. It's
* prefered that you keep one or more include files for a project which figures
* out stuff like the root location and includes the kBuild header.kmk file.
* For the main config file of a source tree the prefered name is kBuild.kMk.
*
* After having included the kBuild environment and any additions to it
* specific to the source tree (like predefined configurations) setup the main
* target clues. The main target clues are what kBuild uses to determin what to
* build and how those things are to be built. The clues are put into the
* variables PROGRAMS, DLLS, DRIVERS, LIBRARIES, OBJECTS, JARS, CLASSES and
* OTHERS. The variables and the attributes of their targets will be explained
* in detail later.
*
* Giving kBuild it's main clues, set the attributes of each of the targets.
*
* When all target attributes have been set include the kBuild main rules. Do
* this by specificly address the include: include $(PATH_KBUILD)/rules.kMk
*
* If there is need for any rules or your own, put them at the end of the
* makefile. Target rules may be used to generate files, or to do special task
* during custom passes, or make special targets specified in the OTHERS clue.
*
*
*
* @subsection kBuild_attributes Target Attributes
*
* Target attributes are use to define how to build a target. Some attributes
* have several specializations, like the .INCS attribute, a rule of thum is
* that the more specialized attributes is given higher precedence when
* ordering the result on a commandline or when used internally by kBuild.
* For instance, concidering the gcc C compiler, kBuild will pass .CINCS
* before .INCS.
*
* kBuild defines a wide range of target attributes. They might apply
* differently to different main targets. See in the section for the main in
* question for details on which attributes applicable to targets of that type.
*
* The attributes can be used on levels with different scope:
*
* - The broadest scope is gained when using the attribute unqualified,
* applying it to all targets in that makefile.
*
* - Qualifying the attribute with a target name, for instance like
* hello.CDEFS, applies that attribute to a target and all it's
* dependencies. The target name does not have to be a main target,
* allthough for only the main targets may be used without care to
* tool or platform specific suffixes or prefixes.
*
* - Qualifying the attribute with a target name and a immediate
* dependant make that attribute apply to that dependant when
* made for that specific main target.
*
*
* Possible target attributes:
*
* - .FLAGS
*
- Flags to pass to all tools. The flags are passed unchanged.
*
*
- .CFLAGS
*
- Flags to pass to the compiler of C source files.
*
*
- .CXXFLAGS
*
- Flags to pass to the compiler of C++ source files.
*
*
- .AFLAGS
*
- Flags to pass to the compiler of assembly source files.
*
*
- .JFLAGS
*
- Flags to pass to the compiler of java source files.
*
*
- .RCFLAGS
*
- Flags to pass to the compiler of resource source files.
*
*
- .HLPFLAGS
*
- Flags to pass to the compiler of help source files.
*
*
- .IPFFLAGS
*
- Flags to pass to the compiler of book (OS/2 IPF) source files.
*
*
- .LFLAGS
*
- Flags to pass to the linker.
*
*
- .ARFLAGS
*
- Flags to pass to the librarian.
*
*
*
- .OPTS
*
- Symbolic options passed to compilers and linkers. kBuild defines
* (or will soon) a set of generic options used among all the tools
* which can be used for better cross tool interoperability.
*
* Note that allthough generic symbolic options are a nice idea, tools
* have different capabilities, so only a very small subset might be
* valid for all tools or all tools in a tools group. kBuild will
* detect illegal options and complain about it.
*
*
- .COPTS
*
- Symbolic options passed to the compiler of C source files.
*
*
- .CXXOPTS
*
- Symbolic options passed to the compiler of C++ source files.
*
*
- .AOPTS
*
- Symbolic options passed to the compiler of assmebly source files.
*
*
- .JOPTS
*
- Symbolic options passed to the compiler of java source files.
*
*
- .RCOPTS
*
- Symbolic options passed to the compiler of resource source files.
*
*
- .HLPOPTS
*
- Symbolic options passed to the compiler of help source files.
*
*
- .IPFOPTS
*
- Symbolic options passed to the compiler of book (OS/2 IPF) source files.
*
*
- .LOPTS
*
- Symbolic options passed to the linker.
*
*
- .AROPTS
*
- Symbolic options passed to the librarian.
*
*
*
- .DEFS
*
- Definitions to pass to compilers. The attribute contains a list
* of definitions with no -D or any other compiler option in front.
* If the definition have an value assigned use follow it by and
* equal sign and the value, no spaces before or after the equal sign.
*
*
- .CDEFS
*
- Definitions to pass to the compiler of C source files.
*
*
- .CXXDEFS
*
- Definitions to pass to the compiler of C++ source files.
*
*
- .ADEFS
*
- Definitions to pass to the compiler of assmbly source files.
*
*
- .RCDEFS
*
- Definitions to pass to the compiler of resource source files.
*
*
*
- .INCS
*
- Include path directives passed to compilers. The attribute contains
* a list of paths to directory which are to be searched for included
* files. The paths shall not be prefixed with any compiler options
* like -I, neither shall they be separated with ':' or ';'. Use space
* as separator between paths.
*
*
- .CINCS
*
- Include path directives to pass to the compiler of C source files.
*
*
- .CXXINCS
*
- Include path directives to pass to the compiler of C++ source files.
*
*
- .AINCS
*
- Include path directives to pass to the compiler of assmbly source files.
*
*
- .RCINCS
*
- Include path directives to pass to the compiler of resource source files.
*
*
*
- .INS
*
- For targets which are by default private defining this attribute
* cause that target to be installed.
*
* Note! This attribute is not automatically inherited by subtargets,
* i.e. use on makefile scope means it applies to main targets, while
* using it on a target scope means that specific target and nothing
* else.
*
*
- .PUB
*
- For targets which are by default private defining this attribute
* cause that target to be published.
* Note! Same as .INS note.
*
*
- .PRIVATE
*
- For targets which are by default published and/or installed
* defining this attribute will prevent the target from being
* installed and publish. This attribute overrides .INS and .PUB.
* Note! Same as .INS note.
*
*
*
- .INSDIR
*
- Which subdirectory under the installation root to put the target.
*
*
- .PUBDIR
*
- Which subdirectory under the publish root to put the target.
*
*
*
- .NAME
*
- Alternative name under which to publish and install the target.
* Note! Same as .INS note.
*
*
- .SUFF
*
- Suffix to append to the target name. Most subtargets have a default
* suffix and also some main targets do. This attribute set or
* overrides suffix of a target.
* Note! Same as .INS note.
* Note! Suffix differs from extension in that it includes any leading
* dot.
*
*
- .PREF
*
- Prefix to append to the target name. Some targets (libraries for
* instance) have a default prefix. This attribute sets or overrides
* the prefix.
* Note! Same as .INS note.
*
*
*
- .CFG
*
- The configuration to use when building the target. It is
* mandatory that this attribute is present.
*
*
*
*
*
* @subsection kBuild_makerefclues Main Target Clues
*
* The main target clues are what tells kBuild what to do. This section will
* detail with each of them in some detail.
*
*
* @subsubsection kBuild_PROGRAMS The PROGRAMS Clue
*
* The PROGRAMS clue gives kBuild a list of executable image targets to be made.
*
*
* @subsubsection kBuild_DLLS The DLLS Clue
*
* The DLLS clue gives kBuild a list of dynamic link library and shared object
* library targets to be made
*
*
* @subsubsection kBuild_DRIVERS The DRIVERS Clue
*
* The DRIVERS clue gives kBuild a list of driver module targets (OS kernel
* modules) to be made.
*
*
* @subsubsection kBuild_LIBRARIES The LIBRARIES Clue
*
* The LIBRARIES clue gives kBuild a list of object library targets to be made.
*
*
* @subsubsection kBuild_OBJECTS The OBJECTS Clue
*
* The OBJECTS clue gives kBuild a list of object module targets to be made.
*
*
* @subsubsection kBuild_JARS The JARS Clue
*
* The JARS clue gives kBuild a list of java archive targets to be made.
*
*
* @subsubsection kBuild_CLASSES The CLASSES Clue
*
* The CLASSES clue gives kBuild a list of java class targets to be made.
*
*
* @subsubsection kBuild_OTHERS The OTHERS Clue
*
* The OTHERS clue gives kBuild a list of other targets to be made.
*
*
*
*/