| 227 | | = Developer point of view = |
| 228 | | |
| 229 | | MutekH has a component-based architecture where each module declares its configuration tokens. |
| 230 | | |
| 231 | | Tokens are declared in configuration description files which are located at various places in the MutekH source tree. |
| 232 | | These constraints configuration files have a different syntax from the build configuration files. |
| 233 | | They are designed to declare configuration tokens and express relationships between available tokens. |
| 234 | | |
| 235 | | Declared tokens can have their value changed in build configuration files and can be tested from C source code and Makefile. |
| 236 | | |
| 237 | | == The .config constraints files == |
| 238 | | |
| 239 | | Their are several types of configuration tokens: |
| 240 | | * normal features enabling tokens which can be either defined or undefined in build configuration files. |
| 241 | | * meta tokens which can only get defined through definition of other tokens. |
| 242 | | * value tokens which can have any value. |
| 243 | | |
| 244 | | === Token flags === |
| 245 | | |
| 246 | | Several flags can be attached to tokens, most important ones are: |
| 247 | | `value`:: |
| 248 | | Indicate the token is a value token. Value tokens can not have dependencies but can take values other than `defined` and `undefined` |
| 249 | | `meta`:: |
| 250 | | Indicate the token is a meta token which may only be defined by an other token using the `provide` tag. |
| 251 | | `auto`:: |
| 252 | | Indicate the token may be automatically defined to satisfy dependencies. |
| 253 | | |
| 254 | | Other flags can be attached to tokens: |
| 255 | | `harddep`:: |
| 256 | | Indicate the token can not be safely undefined due to a unsatisfied dependency. |
| 257 | | `mandatory`:: |
| 258 | | Indicate the token can not be undefined at all. Useful to enforce requirements on other tokens, mainly for mandatory modules. |
| 259 | | `root`:: |
| 260 | | Indicate the token has no parent. |
| 261 | | `internal`:: |
| 262 | | Indicate the token is for internal use and can not be defined in build configuration file directly. |
| 263 | | `noexport`:: |
| 264 | | Indicate the token should not be written out in generated files. |
| 265 | | `private`:: |
| 266 | | Indicate the token can not be used with `parent`, `depend` or `provide` tag from an other `.config` file. |
| 267 | | |
| 268 | | === Constraint tags === |
| 269 | | |
| 270 | | For each configuration token, one may use the following tags: |
| 271 | | `desc Description string without quotes`:: |
| 272 | | Short description about the token, multiple `desc` tags will be concatenated. |
| 273 | | `flags FLAGS […]`:: |
| 274 | | Set some flags with special meaning for the token (see above). |
| 275 | | `parent TOKEN`:: |
| 276 | | Hierarchical dependency, it ensures all token with a parent gets silently undefined if the parent is undefined. This prevents options enabled by default to stay enabled if the parent is disabled; this way it avoids errors due to unneeded requirements. This is also used to hide irrelevant tokens from the help screen if the parent token is undefined. |
| 277 | | `default value`:: |
| 278 | | Set the token default value. `defined` and `undefined` values act as booleans. default value is `undefined` if this line is omitted. |
| 279 | | `module name [long name]`:: |
| 280 | | The feature token is associated with a module name. A module with the given name and the actual config file directory will be considered for building when the token gets defined. |
| 281 | | |
| 282 | | The following tags may be used to specify features constraints: |
| 283 | | `depend TOKEN […]`:: |
| 284 | | The tag must be used to express feature dependencies, at least one of the given feature tokens is required. Unsatisfied dependency undefine the current token and emit a notice, unless flags modify this behavior. |
| 285 | | `single TOKEN […]`:: |
| 286 | | Same as depend with the additional constraint that only one of the given tokens may be defined. |
| 287 | | `exclude TOKEN`:: |
| 288 | | Specify excluded tokens, the current token must not be defined at the same time as any given token. |
| 289 | | `when TOKEN_CONDITION […]`:: |
| 290 | | The current feature token will be automatically defined if all specified conditions are met. Missing dependencies will emit a notice as if it was defined in the build configuration file. |
| 291 | | `provide TOKEN`:: |
| 292 | | Define a meta token if the current token is defined. |
| 293 | | |
| 294 | | Some tags may be used to deals with values tokens. Value tokens must have the `value` flag set: |
| 295 | | |
| 296 | | `require TOKEN_CONDITION […]`:: |
| 297 | | Requirements on value tokens, having at least one condition evaluates to true on the line is mandatory if the current token is defined. |
| 298 | | `provide TOKEN=value`:: |
| 299 | | Set a value token to the specified value if the current token is defined. |
| 300 | | |
| 301 | | Some tags can be used to give some configurations advice to the user when building MutekH: |
| 302 | | |
| 303 | | `suggest TOKEN_CONDITION`:: |
| 304 | | Defining the current feature token suggest the given condition to the user. |
| 305 | | `suggest_when TOKEN_CONDITION […]`:: |
| 306 | | The current token will be suggested to the user if dependencies are actually satisfied and all given conditions are met. |
| 307 | | |
| 308 | | The `TOKEN_CONDITION` might check different conditions: |
| 309 | | |
| 310 | | * Token definition check: `TOKEN` or `TOKEN!` |
| 311 | | * Token value equality check: `TOKEN=value` |
| 312 | | * Token numerical value magnitude check: `TOKEN<value` or `TOKEN>value` |
| 313 | | |
| 314 | | The configuration tool will check both constraint rules consistency and build configuration file respect of the rules when building MutekH. |
| 315 | | |
| 316 | | Configuration constraints example: |
| 317 | | {{{ |
| 318 | | %config CONFIG_FEATURE |
| 319 | | desc This is a great module for MutekH |
| 320 | | depend CONFIG_MUTEK_SCHEDULER |
| 321 | | module great The great library |
| 322 | | require CONFIG_CPU_MAXCOUNT>1 |
| 323 | | %config end |
| 324 | | |
| 325 | | %config CONFIG_FEATURE_DEBUG |
| 326 | | desc Enable debug mode for the great feature |
| 327 | | parent CONFIG_FEATURE |
| 328 | | provide CONFIG_FEATURE_STACK_SIZE=4096 |
| 329 | | when CONFIG_DEBUG |
| 330 | | %config end |
| 331 | | |
| 332 | | %config CONFIG_FEATURE_STACK_SIZE |
| 333 | | desc This is the thread stack size for the great feature |
| 334 | | parent CONFIG_FEATURE |
| 335 | | flags value |
| 336 | | default 512 |
| 337 | | %config end |
| 338 | | |
| 339 | | }}} |
| 340 | | |
| 341 | | == Source tree Makefile syntax & rules == |
| 342 | | |
| 343 | | Makefiles in source directories may use the following variables: |
| 344 | | `objs`:: |
| 345 | | A list of .o files compiled from `.c`, `.s` or `.S` files |
| 346 | | `meta`:: |
| 347 | | A list of files that may be translated from `.m4`, `.cpp` or `.def` files |
| 348 | | `copy`:: |
| 349 | | A list of files that must be copied verbatim from source directory to object directory |
| 350 | | `subdirs`:: |
| 351 | | A list of subdirectories where more files are to be processed. These directories must exist and contain a `Makefile`. |
| 352 | | `doc_headers`:: |
| 353 | | A list of header files which must be parsed to generate the [http://www.mutekh.org/www/mutekh_api/ MutekH API reference manual], see [wiki:HeaderDoc header documentation] for details. |
| 354 | | |
| 355 | | Makefiles may contain optional flags that may be used for compilation: |
| 356 | | `file.o_CFLAGS=…`:: |
| 357 | | CFLAGS to use for a given object |
| 358 | | `DIR_CFLAGS=…`:: |
| 359 | | CFLAGS to use for all the objects compiled by the current Makefile. Flags added by this setting add-up with the object-specific ones above. |
| 360 | | |
| 361 | | Moreover, one may use `ifeq (…,…)` make constructs to conditionally compile different things. Configuration tokens are usable. |
| 362 | | |
| 363 | | Example: |
| 364 | | {{{ |
| 365 | | objs = main.o |
| 366 | | |
| 367 | | ifeq ($(CONFIG_SRL_SOCLIB),defined) |
| 368 | | objs += barrier.o sched_wait.o srl_log.o hw_init.o |
| 369 | | else |
| 370 | | objs += posix_wait_cycles.o |
| 371 | | endif |
| 372 | | |
| 373 | | main.o_CFLAGS = -O0 -ggdb |
| 374 | | }}} |
| 375 | | |
| 376 | | == The arch & cpu specific parts == |
| 377 | | |
| 378 | | Architecture and CPU directories have some special files which are injected in the building process: |
| 379 | | * config.mk, included by make. It can define some compilation flags |
| 380 | | * ldscript, invoked at link-time. |
| 381 | | * Architecture ldscript must create a loadable binary |
| 382 | | * CPU ldscript usually only specifies the entry point name |
| 383 | | |
| 384 | | === config.mk === |
| 385 | | |
| 386 | | The arch `config.mk` may override the following variables: |
| 387 | | `ARCHCFLAGS`:: |
| 388 | | C-compiler flags |
| 389 | | `ARCHLDFLAGS`:: |
| 390 | | Linker flags |
| 391 | | `LD_NO_Q`:: |
| 392 | | Linker for the current architecture does not support -q switch, this slightly changes the linking process. |
| 393 | | `HOSTCPPFLAGS`:: |
| 394 | | Flags to give to host's cpp (HOSTCPP) program. This is only used for expansion of `.def` files. |
| 395 | | |
| 396 | | The cpu `config.mk` may override the following variables: |
| 397 | | |
| 398 | | `CPUCFLAGS`:: |
| 399 | | C-compiler flags |
| 400 | | `CPULDFLAGS`:: |
| 401 | | Linker flags |
| 402 | | |
| 403 | | === ldscript === |
| 404 | | |
| 405 | | Try `info ld` for a guide through ldscripts… |
| 406 | | |
| 407 | | This ldscript is taken from architecture's object directory, thus it may be obtained from either: |
| 408 | | * copy |
| 409 | | * m4 processing |
| 410 | | * cpp processing |
| 411 | | |
| 412 | | See |
| 413 | | [source:trunk/mutekh/arch/emu/ldscript arch/emu/ldscript], |
| 414 | | [source:trunk/mutekh/arch/soclib/ldscript.m4 arch/soclib/ldscript.m4], and |
| 415 | | [source:trunk/mutekh/arch/simple/ldscript.cpp arch/simple/ldscript.cpp] for the three flavors ! |
| 416 | | |
| 417 | | = Notes = |
| 418 | | == Prerequisites == |
| 419 | | |
| 420 | | The MutekH build-system is based on GNU Make features. It makes intensive use of: |
| 421 | | * includes |
| 422 | | * $(foreach) $(subst) $(eval) $(call) macros |
| 423 | | * macro definitions |
| 424 | | Therefore, a Make-3.81 at least is mandatory. |
