Changeset 61 for trunk/doc/kBuilddocs.c

Timestamp:

Dec 14, 2003, 12:18:38 AM (22 years ago)

Author:

bird

Message:

More..

File:

• trunk/doc/kBuilddocs.c (modified) (4 diffs)

trunk/doc/kBuilddocs.c

@@ -1 +1 @@
 /* $Id$ */
 /** @file
- * kBuild Documentation file with the sole purpose of giving doxygen
+ * A kBuild Documentation file with the sole purpose of giving doxygen
  * something to chew on.
  */
 
 
-/** @page       kBuild          kBuild
- *
- * @section     kBuild_intro    Introduction
+/** @mainpage                   kBuild
+ *
+ * @section     kBuild_intro            Introduction
  *
  * kBuild is a build system which intention is to simplify your makefiles
- * and to hide cross platform projects issues.
+ * and to hide cross platform detail for projects.
  *
  * kBuild is layered in three tiers, first comes the instructions given in the
@@ -32 +32 @@
  * 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'.
+ * files are named on the form 'tool.[toolname].kMk'.
  *
  * The tool configuration contains callable macros and definitions for
@@ -41 +41 @@
  *
  *
- * @section     kBuild_makeref  Makefile Reference
+ * @section     kBuild_makeref          Makefile Reference
  *
  * The make file must start with including a configuration file which sets up
@@ -67 +67 @@
  *
  *
+ *
+ * @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.
+ *
+ *
+ *
  */