source: trunk/doc/kBuilddocs.c@ 61

/* $Id: kBuilddocs.c 61 2003-12-13 23:18:38Z 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:
 * <dl>
 *  <dt>.FLAGS
 *      <dd>Flags to pass to all tools. The flags are passed unchanged.
 *
 *  <dt>.CFLAGS
 *      <dd>Flags to pass to the compiler of C source files.
 *
 *  <dt>.CXXFLAGS
 *      <dd>Flags to pass to the compiler of C++ source files.
 *
 *  <dt>.AFLAGS
 *      <dd>Flags to pass to the compiler of assembly source files.
 *
 *  <dt>.JFLAGS
 *      <dd>Flags to pass to the compiler of java source files.
 *
 *  <dt>.RCFLAGS
 *      <dd>Flags to pass to the compiler of resource source files.
 *
 *  <dt>.HLPFLAGS
 *      <dd>Flags to pass to the compiler of help source files.
 *
 *  <dt>.IPFFLAGS
 *      <dd>Flags to pass to the compiler of book (OS/2 IPF) source files.
 *
 *  <dt>.LFLAGS
 *      <dd>Flags to pass to the linker.
 *
 *  <dt>.ARFLAGS
 *      <dd>Flags to pass to the librarian.
 *
 *
 *  <dt>.OPTS
 *      <dd>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.
 *
 *  <dt>.COPTS
 *      <dd>Symbolic options passed to the compiler of C source files.
 *
 *  <dt>.CXXOPTS
 *      <dd>Symbolic options passed to the compiler of C++ source files.
 *
 *  <dt>.AOPTS
 *      <dd>Symbolic options passed to the compiler of assmebly source files.
 *
 *  <dt>.JOPTS
 *      <dd>Symbolic options passed to the compiler of java source files.
 *
 *  <dt>.RCOPTS
 *      <dd>Symbolic options passed to the compiler of resource source files.
 *
 *  <dt>.HLPOPTS
 *      <dd>Symbolic options passed to the compiler of help source files.
 *
 *  <dt>.IPFOPTS
 *      <dd>Symbolic options passed to the compiler of book (OS/2 IPF) source files.
 *
 *  <dt>.LOPTS
 *      <dd>Symbolic options passed to the linker.
 *
 *  <dt>.AROPTS
 *      <dd>Symbolic options passed to the librarian.
 *
 *
 *  <dt>.DEFS
 *      <dd>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.
 *
 *  <dt>.CDEFS
 *      <dd>Definitions to pass to the compiler of C source files.
 *
 *  <dt>.CXXDEFS
 *      <dd>Definitions to pass to the compiler of C++ source files.
 *
 *  <dt>.ADEFS
 *      <dd>Definitions to pass to the compiler of assmbly source files.
 *
 *  <dt>.RCDEFS
 *      <dd>Definitions to pass to the compiler of resource source files.
 *
 *
 *  <dt>.INCS
 *      <dd>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.
 *
 *  <dt>.CINCS
 *      <dd>Include path directives to pass to the compiler of C source files.
 *
 *  <dt>.CXXINCS
 *      <dd>Include path directives to pass to the compiler of C++ source files.
 *
 *  <dt>.AINCS
 *      <dd>Include path directives to pass to the compiler of assmbly source files.
 *
 *  <dt>.RCINCS
 *      <dd>Include path directives to pass to the compiler of resource source files.
 *
 *
 *  <dt>.INS
 *      <dd>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.
 *
 *  <dt>.INSDIR
 *      <dd>Which subdirectory under the installation root to put the target.
 *
 *  <dt>.PUB
 *      <dd>For targets which are by default private defining this attribute
 *          cause that target to be published.
 *          Note! Same as .INS note.
 *
 *  <dt>.PUBDIR
 *      <dd>Which subdirectory under the publish root to put the target.
 *
 *
 *  <dt>.NAME
 *      <dd>Alternative name under which to publish and install the target.
 *          Note! Same as .INS note.
 *
 *  <dt>.SUFF
 *      <dd>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.
 *
 *  <dt>.PREF
 *      <dd>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.
 * </dl>
 *
 *
 *
 * @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.
 *
 *
 *
 */