| 1 | /* $Id: kBuilddocs.c 62 2003-12-13 23:27:56Z bird $ */
|
|---|
| 2 | /** @file
|
|---|
| 3 | * A kBuild Documentation file with the sole purpose of giving doxygen
|
|---|
| 4 | * something to chew on.
|
|---|
| 5 | */
|
|---|
| 6 |
|
|---|
| 7 |
|
|---|
| 8 | /** @mainpage 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 detail for projects.
|
|---|
| 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 | * @subsection kBuild_attributes Target Attributes
|
|---|
| 71 | *
|
|---|
| 72 | * Target attributes are use to define how to build a target. Some attributes
|
|---|
| 73 | * have several specializations, like the .INCS attribute, a rule of thum is
|
|---|
| 74 | * that the more specialized attributes is given higher precedence when
|
|---|
| 75 | * ordering the result on a commandline or when used internally by kBuild.
|
|---|
| 76 | * For instance, concidering the gcc C compiler, kBuild will pass .CINCS
|
|---|
| 77 | * before .INCS.
|
|---|
| 78 | *
|
|---|
| 79 | * kBuild defines a wide range of target attributes. They might apply
|
|---|
| 80 | * differently to different main targets. See in the section for the main in
|
|---|
| 81 | * question for details on which attributes applicable to targets of that type.
|
|---|
| 82 | *
|
|---|
| 83 | * The attributes can be used on levels with different scope:
|
|---|
| 84 | *
|
|---|
| 85 | * - The broadest scope is gained when using the attribute unqualified,
|
|---|
| 86 | * applying it to all targets in that makefile.
|
|---|
| 87 | *
|
|---|
| 88 | * - Qualifying the attribute with a target name, for instance like
|
|---|
| 89 | * hello.CDEFS, applies that attribute to a target and all it's
|
|---|
| 90 | * dependencies. The target name does not have to be a main target,
|
|---|
| 91 | * allthough for only the main targets may be used without care to
|
|---|
| 92 | * tool or platform specific suffixes or prefixes.
|
|---|
| 93 | *
|
|---|
| 94 | * - Qualifying the attribute with a target name and a immediate
|
|---|
| 95 | * dependant make that attribute apply to that dependant when
|
|---|
| 96 | * made for that specific main target.
|
|---|
| 97 | *
|
|---|
| 98 | *
|
|---|
| 99 | * Possible target attributes:
|
|---|
| 100 | * <dl>
|
|---|
| 101 | * <dt>.FLAGS
|
|---|
| 102 | * <dd>Flags to pass to all tools. The flags are passed unchanged.
|
|---|
| 103 | *
|
|---|
| 104 | * <dt>.CFLAGS
|
|---|
| 105 | * <dd>Flags to pass to the compiler of C source files.
|
|---|
| 106 | *
|
|---|
| 107 | * <dt>.CXXFLAGS
|
|---|
| 108 | * <dd>Flags to pass to the compiler of C++ source files.
|
|---|
| 109 | *
|
|---|
| 110 | * <dt>.AFLAGS
|
|---|
| 111 | * <dd>Flags to pass to the compiler of assembly source files.
|
|---|
| 112 | *
|
|---|
| 113 | * <dt>.JFLAGS
|
|---|
| 114 | * <dd>Flags to pass to the compiler of java source files.
|
|---|
| 115 | *
|
|---|
| 116 | * <dt>.RCFLAGS
|
|---|
| 117 | * <dd>Flags to pass to the compiler of resource source files.
|
|---|
| 118 | *
|
|---|
| 119 | * <dt>.HLPFLAGS
|
|---|
| 120 | * <dd>Flags to pass to the compiler of help source files.
|
|---|
| 121 | *
|
|---|
| 122 | * <dt>.IPFFLAGS
|
|---|
| 123 | * <dd>Flags to pass to the compiler of book (OS/2 IPF) source files.
|
|---|
| 124 | *
|
|---|
| 125 | * <dt>.LFLAGS
|
|---|
| 126 | * <dd>Flags to pass to the linker.
|
|---|
| 127 | *
|
|---|
| 128 | * <dt>.ARFLAGS
|
|---|
| 129 | * <dd>Flags to pass to the librarian.
|
|---|
| 130 | *
|
|---|
| 131 | *
|
|---|
| 132 | * <dt>.OPTS
|
|---|
| 133 | * <dd>Symbolic options passed to compilers and linkers. kBuild defines
|
|---|
| 134 | * (or will soon) a set of generic options used among all the tools
|
|---|
| 135 | * which can be used for better cross tool interoperability.
|
|---|
| 136 | *
|
|---|
| 137 | * Note that allthough generic symbolic options are a nice idea, tools
|
|---|
| 138 | * have different capabilities, so only a very small subset might be
|
|---|
| 139 | * valid for all tools or all tools in a tools group. kBuild will
|
|---|
| 140 | * detect illegal options and complain about it.
|
|---|
| 141 | *
|
|---|
| 142 | * <dt>.COPTS
|
|---|
| 143 | * <dd>Symbolic options passed to the compiler of C source files.
|
|---|
| 144 | *
|
|---|
| 145 | * <dt>.CXXOPTS
|
|---|
| 146 | * <dd>Symbolic options passed to the compiler of C++ source files.
|
|---|
| 147 | *
|
|---|
| 148 | * <dt>.AOPTS
|
|---|
| 149 | * <dd>Symbolic options passed to the compiler of assmebly source files.
|
|---|
| 150 | *
|
|---|
| 151 | * <dt>.JOPTS
|
|---|
| 152 | * <dd>Symbolic options passed to the compiler of java source files.
|
|---|
| 153 | *
|
|---|
| 154 | * <dt>.RCOPTS
|
|---|
| 155 | * <dd>Symbolic options passed to the compiler of resource source files.
|
|---|
| 156 | *
|
|---|
| 157 | * <dt>.HLPOPTS
|
|---|
| 158 | * <dd>Symbolic options passed to the compiler of help source files.
|
|---|
| 159 | *
|
|---|
| 160 | * <dt>.IPFOPTS
|
|---|
| 161 | * <dd>Symbolic options passed to the compiler of book (OS/2 IPF) source files.
|
|---|
| 162 | *
|
|---|
| 163 | * <dt>.LOPTS
|
|---|
| 164 | * <dd>Symbolic options passed to the linker.
|
|---|
| 165 | *
|
|---|
| 166 | * <dt>.AROPTS
|
|---|
| 167 | * <dd>Symbolic options passed to the librarian.
|
|---|
| 168 | *
|
|---|
| 169 | *
|
|---|
| 170 | * <dt>.DEFS
|
|---|
| 171 | * <dd>Definitions to pass to compilers. The attribute contains a list
|
|---|
| 172 | * of definitions with no -D or any other compiler option in front.
|
|---|
| 173 | * If the definition have an value assigned use follow it by and
|
|---|
| 174 | * equal sign and the value, no spaces before or after the equal sign.
|
|---|
| 175 | *
|
|---|
| 176 | * <dt>.CDEFS
|
|---|
| 177 | * <dd>Definitions to pass to the compiler of C source files.
|
|---|
| 178 | *
|
|---|
| 179 | * <dt>.CXXDEFS
|
|---|
| 180 | * <dd>Definitions to pass to the compiler of C++ source files.
|
|---|
| 181 | *
|
|---|
| 182 | * <dt>.ADEFS
|
|---|
| 183 | * <dd>Definitions to pass to the compiler of assmbly source files.
|
|---|
| 184 | *
|
|---|
| 185 | * <dt>.RCDEFS
|
|---|
| 186 | * <dd>Definitions to pass to the compiler of resource source files.
|
|---|
| 187 | *
|
|---|
| 188 | *
|
|---|
| 189 | * <dt>.INCS
|
|---|
| 190 | * <dd>Include path directives passed to compilers. The attribute contains
|
|---|
| 191 | * a list of paths to directory which are to be searched for included
|
|---|
| 192 | * files. The paths shall not be prefixed with any compiler options
|
|---|
| 193 | * like -I, neither shall they be separated with ':' or ';'. Use space
|
|---|
| 194 | * as separator between paths.
|
|---|
| 195 | *
|
|---|
| 196 | * <dt>.CINCS
|
|---|
| 197 | * <dd>Include path directives to pass to the compiler of C source files.
|
|---|
| 198 | *
|
|---|
| 199 | * <dt>.CXXINCS
|
|---|
| 200 | * <dd>Include path directives to pass to the compiler of C++ source files.
|
|---|
| 201 | *
|
|---|
| 202 | * <dt>.AINCS
|
|---|
| 203 | * <dd>Include path directives to pass to the compiler of assmbly source files.
|
|---|
| 204 | *
|
|---|
| 205 | * <dt>.RCINCS
|
|---|
| 206 | * <dd>Include path directives to pass to the compiler of resource source files.
|
|---|
| 207 | *
|
|---|
| 208 | *
|
|---|
| 209 | * <dt>.INS
|
|---|
| 210 | * <dd>For targets which are by default private defining this attribute
|
|---|
| 211 | * cause that target to be installed.
|
|---|
| 212 | *
|
|---|
| 213 | * Note! This attribute is not automatically inherited by subtargets,
|
|---|
| 214 | * i.e. use on makefile scope means it applies to main targets, while
|
|---|
| 215 | * using it on a target scope means that specific target and nothing
|
|---|
| 216 | * else.
|
|---|
| 217 | *
|
|---|
| 218 | * <dt>.PUB
|
|---|
| 219 | * <dd>For targets which are by default private defining this attribute
|
|---|
| 220 | * cause that target to be published.
|
|---|
| 221 | * Note! Same as .INS note.
|
|---|
| 222 | *
|
|---|
| 223 | * <dt>.PRIVATE
|
|---|
| 224 | * <dd>For targets which are by default published and/or installed
|
|---|
| 225 | * defining this attribute will prevent the target from being
|
|---|
| 226 | * installed and publish. This attribute overrides .INS and .PUB.
|
|---|
| 227 | * Note! Same as .INS note.
|
|---|
| 228 | *
|
|---|
| 229 | *
|
|---|
| 230 | * <dt>.INSDIR
|
|---|
| 231 | * <dd>Which subdirectory under the installation root to put the target.
|
|---|
| 232 | *
|
|---|
| 233 | * <dt>.PUBDIR
|
|---|
| 234 | * <dd>Which subdirectory under the publish root to put the target.
|
|---|
| 235 | *
|
|---|
| 236 | *
|
|---|
| 237 | * <dt>.NAME
|
|---|
| 238 | * <dd>Alternative name under which to publish and install the target.
|
|---|
| 239 | * Note! Same as .INS note.
|
|---|
| 240 | *
|
|---|
| 241 | * <dt>.SUFF
|
|---|
| 242 | * <dd>Suffix to append to the target name. Most subtargets have a default
|
|---|
| 243 | * suffix and also some main targets do. This attribute set or
|
|---|
| 244 | * overrides suffix of a target.
|
|---|
| 245 | * Note! Same as .INS note.
|
|---|
| 246 | * Note! Suffix differs from extension in that it includes any leading
|
|---|
| 247 | * dot.
|
|---|
| 248 | *
|
|---|
| 249 | * <dt>.PREF
|
|---|
| 250 | * <dd>Prefix to append to the target name. Some targets (libraries for
|
|---|
| 251 | * instance) have a default prefix. This attribute sets or overrides
|
|---|
| 252 | * the prefix.
|
|---|
| 253 | * Note! Same as .INS note.
|
|---|
| 254 | *
|
|---|
| 255 | *
|
|---|
| 256 | * <dt>.CFG
|
|---|
| 257 | * <dd>The configuration to use when building the target. It is
|
|---|
| 258 | * mandatory that this attribute is present.
|
|---|
| 259 | *
|
|---|
| 260 | * </dl>
|
|---|
| 261 | *
|
|---|
| 262 | *
|
|---|
| 263 | *
|
|---|
| 264 | * @subsection kBuild_makerefclues Main Target Clues
|
|---|
| 265 | *
|
|---|
| 266 | * The main target clues are what tells kBuild what to do. This section will
|
|---|
| 267 | * detail with each of them in some detail.
|
|---|
| 268 | *
|
|---|
| 269 | *
|
|---|
| 270 | * @subsubsection kBuild_PROGRAMS The PROGRAMS Clue
|
|---|
| 271 | *
|
|---|
| 272 | * The PROGRAMS clue gives kBuild a list of executable image targets to be made.
|
|---|
| 273 | *
|
|---|
| 274 | *
|
|---|
| 275 | * @subsubsection kBuild_DLLS The DLLS Clue
|
|---|
| 276 | *
|
|---|
| 277 | * The DLLS clue gives kBuild a list of dynamic link library and shared object
|
|---|
| 278 | * library targets to be made
|
|---|
| 279 | *
|
|---|
| 280 | *
|
|---|
| 281 | * @subsubsection kBuild_DRIVERS The DRIVERS Clue
|
|---|
| 282 | *
|
|---|
| 283 | * The DRIVERS clue gives kBuild a list of driver module targets (OS kernel
|
|---|
| 284 | * modules) to be made.
|
|---|
| 285 | *
|
|---|
| 286 | *
|
|---|
| 287 | * @subsubsection kBuild_LIBRARIES The LIBRARIES Clue
|
|---|
| 288 | *
|
|---|
| 289 | * The LIBRARIES clue gives kBuild a list of object library targets to be made.
|
|---|
| 290 | *
|
|---|
| 291 | *
|
|---|
| 292 | * @subsubsection kBuild_OBJECTS The OBJECTS Clue
|
|---|
| 293 | *
|
|---|
| 294 | * The OBJECTS clue gives kBuild a list of object module targets to be made.
|
|---|
| 295 | *
|
|---|
| 296 | *
|
|---|
| 297 | * @subsubsection kBuild_JARS The JARS Clue
|
|---|
| 298 | *
|
|---|
| 299 | * The JARS clue gives kBuild a list of java archive targets to be made.
|
|---|
| 300 | *
|
|---|
| 301 | *
|
|---|
| 302 | * @subsubsection kBuild_CLASSES The CLASSES Clue
|
|---|
| 303 | *
|
|---|
| 304 | * The CLASSES clue gives kBuild a list of java class targets to be made.
|
|---|
| 305 | *
|
|---|
| 306 | *
|
|---|
| 307 | * @subsubsection kBuild_OTHERS The OTHERS Clue
|
|---|
| 308 | *
|
|---|
| 309 | * The OTHERS clue gives kBuild a list of other targets to be made.
|
|---|
| 310 | *
|
|---|
| 311 | *
|
|---|
| 312 | *
|
|---|
| 313 | */
|
|---|
| 314 |
|
|---|
