Changeset 61 in kBuild for trunk/doc

Timestamp:

Dec 13, 2003 11:18:38 PM (21 years ago)

Author:

bird

Message:

More..

Location:

trunk/doc

Files:

• kBuilddocs.c (modified) (4 diffs)
• kmkdocs.c (modified) (1 diff)

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.
+ *
+ *
+ *
  */
 

trunk/doc/kmkdocs.c

@@ -48 +48 @@
  *
  *
- * @subsection          The Micro Shell
- *
- * The micro shell provides the basic shell functionality kBuild need - no more,
- * no less. It is intended to be as simple as possible.
- *
- * The shell commands are case sensitive - all lowercase.
- *
- * The shell environment variables are case sensitive or insensitive according to
- * host os.
- *
- *
- *
- * @subsubsection       Command Separators
- *
- * There is one command separator '&&'. This works like splitting the command line
- * into several makefile lines. This splitting isn't done by the micro shell but
- * the makefile interpreter.
- *
- * You might thing this is limiting, but no, you can use all the makefile command
- * prefixes.
- *
- *
- *
- * @subsubsection       Path Component Separator (/)
- *
- * The shell uses '/' as path component separator.
- * For host OSes  with the notion of drive letters or similar, ':' is
- * used to separate the drive letter and the path.
- *
- *
- *
- * @subsubsection       UNC paths
- *
- * For host OSes which supports UNC paths these are supported but for the chdir
- * command.
- *
- * The Path Component Separator is still '/' for UNC paths.
- *
- *
- *
- * @subsubsection       Wildchars
- *
- * '*' and '?' are accepted as wildchars.
- *
- * '*' means 0 or more characters. <br>
- * '?' means 1 character.
- *
- * When the term 'pattern' is use in command description this means that
- * wildchars are accepted.
- *
- *
- *
- * @subsubsection       Quoting
- *
- * Use double quotes (") to quote filenames or executables containing spaces.
- *
- *
- *
- * @subsubsection       Execute Program
- *
- * If the first, possibly quoted, word of a commandline if not found as an
- * internal command will be tried executed. If no path it will be searched
- * for in the PATH environment variable.
- *
- *
- *
- * @subsubsection       Commands
- *
- * This section will describe the commands implemented by the shell.
- *
- *
- *
- * @subsubsubsection    copy
- * Copies one or more files to a target file or directory.
- *
- * <b>Syntax: copy <source file pattern> [more sources] <target> </b>
- *
- * Specify one or more source file patterns.
- *
- * Specify exactly one target. The target may be a directory or a file.
- * If it's a file and multiple source files specified either thru pattern or
- * multiple source file specifications, the target file will be a copy of the
- * last one.
- *
- * The command fails if a source file isn't found. It also fails on read or
- * write errors.
- *
- *
- *
- * @subsubsubsection    copytree
- * Copies one or more files to a target file or directory.
- *
- * <b>Syntax: copytree <source directory> <target directory> </b>
- *
- * Specify exactly one source directory.
- *
- * Specify exactly one target directory. The target directory path will be
- * created if doesn't exist.
- *
- * The command fails if source directory isn't found. It also fails on read or
- * write errors.
- *
- *
- *
- * @subsubsubsection    rm
- * Deletes one or more files.
- *
- * <b>Syntax: rm [file pattern] [more files] </b>
- *
- * Specify 0 or more file patterns for deletion.
- *
- * This command fails if it cannot delete a file. It will not fail if a file
- * doesn't exist. It will neither fail if no files are specified.
- *
- *
- *
- * @subsubsubsection    rmtree
- * Deletes one or more directory trees.
- *
- * <b>Syntax: rmtree [directory pattern] [directories] </b>
- *
- * Specify 0 or more directory patterns for deletion.
- *
- * This command fails if it cannot delete a file or directory. It will not fail
- * if a directory doesn't exist. It will neither fail if no files are specified.
- *
- *
- *
- * @subsubsubsection    chdir
- * Changes the current directory.
- *
- * This updates the .CWD macro to the new current directory path.
- *
- * <b>Syntax: chdir <directory> </b>
- *
- *
- *
- * @subsubsubsection    mkdir
- * Create directory.
- *
- * <b>Syntax:  mkdir <directory> </b>
- *
- * Specify one directory to create.
- *
- *
- *
- * @subsubsubsection    rmdir
- * Remove directory.
- *
- * <b>Syntax: rmdir <directory> </b>
- *
- * Specify one directory to remove. The directory must be empty.
- *
- * This command failes if directory isn't empty. It will not fail if
- * the directory doesn't exist.
- *
- *
- *
- * @subsubsubsection    set
- * Set environment variable.
- *
- * <b>Syntax: set <envvar>=<value> </b>
- *
- *
- *
- * @subsubsubsection    unset
- * Unset enviornment variable(s).
- *
- * <b>Syntax: unset <envvar pattern> [more envvars] </b>
- *
- * Specify on or more environment variable patterns.
- *
- *
- *
- * @subsubsubsection    pushenv
- * Pushes a set of environment variables onto the environment stack. The
- * variables can later be popped back using the popenv command.
- *
- * If '*' is specified as pattern the complete enviornment is pushed and
- * when popped it will <b>replace</b> the enviornment.
- *
- * <b>Syntax: pushenv <envvar pattern> [more envvars] </b>
- * <b>Syntax: pushenv * </b>
- *
- *
- *
- * @subsubsubsection    popenv
- * Pop a set of environment variables from the environment stack. If a '*'
- * push was done, we'll replace the enviornment with the variables poped off
- * the stack.
- *
- * <b>Syntax: popenv </b>
- *
- *
- *
- * @subsubsubsection    echo
- * Prints a message to stdout.
- *
- * <b>Syntax: echo <level> <message>
- *
- * Level is verbosity level of the message. This is compared with the
- * KBUILD_MSG_LEVEL environment variable. The message is suppressed if the
- * level is lower that KBUILD_MSG_LEVEL.
- *
- * The message can be empty. Then a blank line will be printed.
- *
- *
  *
  */