Changes between Version 1 and Version 2 of BuildSystemDev


Ignore:
Timestamp:
Mar 21, 2010, 1:48:54 AM (14 years ago)
Author:
becoulet
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • BuildSystemDev

    v1 v2  
    1616
    1717= The `.config` files syntax =
     18
     19Configuration description and constraints files contains blocks.
     20Each block begins with `%config` or `%init` and declares a new token. See examples below for syntax details.
     21
     22== Configuration tokens declaration ==
    1823
    1924Their are several types of configuration tokens:
    … …  
    2126 * meta tokens which can only get defined through definition of other tokens.
    2227 * value tokens which can have any value.
    23 
    24 == Configuration token declaration ==
    2528
    2629=== Token flags ===
    … …  
    5558 `flags FLAGS […]`::
    5659   Set some flags with special meaning for the token (see above).
    57  `parent TOKEN`::
     60 `parent CONFIG_TOKEN`::
    5861   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.
    5962 `default value`::
    … …  
    6366
    6467The following tags may be used to specify features constraints:
    65  `depend TOKEN […]`::
     68 `depend CONFIG_TOKEN […]`::
    6669   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.
    67  `single TOKEN […]`::
     70 `single CONFIG_TOKEN […]`::
    6871   Same as depend with the additional constraint that only one of the given tokens may be defined.
    69  `exclude TOKEN`::
     72 `exclude CONFIG_TOKEN`::
    7073   Specify excluded tokens, the current token must not be defined at the same time as any given token.
    71  `when TOKEN_CONDITION […]`::
     74 `when CONFIG_TOKEN_CONDITION […]`::
    7275   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.
    73  `provide TOKEN`::
     76 `provide CONFIG_TOKEN`::
    7477   Define a meta token if the current token is defined.
    7578
    7679Some tags may be used to deals with values tokens. Value tokens must have the `value` flag set:
    7780
    78  `require TOKEN_CONDITION […]`::
     81 `require CONFIG_TOKEN_CONDITION […]`::
    7982   Requirements on value tokens, having at least one condition evaluates to true on the line is mandatory if the current token is defined.
    80  `provide TOKEN=value`::
     83 `provide CONFIG_TOKEN=value`::
    8184   Set a value token to the specified value if the current token is defined.
    8285
    8386Some tags can be used to give some configurations advice to the user when building MutekH:
    8487
    85  `suggest TOKEN_CONDITION`::
     88 `suggest CONFIG_TOKEN_CONDITION`::
    8689   Defining the current feature token suggest the given condition to the user.
    87  `suggest_when TOKEN_CONDITION […]`::
     90 `suggest_when CONFIG_TOKEN_CONDITION […]`::
    8891   The current token will be suggested to the user if dependencies are actually satisfied and all given conditions are met.
    8992
    90 The `TOKEN_CONDITION` might check different conditions:
    91 
    92  * Token definition check: `TOKEN` or `TOKEN!`
    93  * Token value equality check: `TOKEN=value`
    94  * Token numerical value magnitude check: `TOKEN<value` or `TOKEN>value`
     93The `CONFIG_TOKEN_CONDITION` might check different conditions:
     94
     95 * Token definition check: `CONFIG_TOKEN` or `CONFIG_TOKEN!`
     96 * Token value equality check: `CONFIG_TOKEN=value`
     97 * Token numerical value magnitude check: `CONFIG_TOKEN<value` or `CONFIG_TOKEN>value`
    9598
    9699The configuration tool will check both constraint rules consistency and build configuration file respect of the rules when building MutekH.
     100
     101=== Example ===
    97102
    98103Configuration constraints example:
    … …  
    121126}}}
    122127
     128== Initialization tokens declaration ==
     129
     130Initialization order of different software components at system start needs close attention.
     131Having all modules and features initialized in proper order is challenging in modular and configurable projects like MutekH.
     132
     133The configuration tools offers a way to specify initialization code ordering constraints and to optionally associate them to configuration tokens.
     134This has several advantages:
     135 * It allows inserting external modules initialization code in the right place without patching the main tree.
     136 * It avoids the burdensome work of maintaining initialization function calls and associated `#ifdef` directives.
     137 * It ensures initialization function invocations do not get badly reordered to satisfy a new constraint, while ignoring an older one.
     138
     139A C source file will be generated with given initialization code respecting ordering constraints and current configuration.
     140An error will be emitted if constraints can not be satisfied.
     141
     142=== Constraint tags ===
     143
     144For each configuration token, one may use the following tags:
     145 `parent CONFIG_TOKEN`::
     146   When this tag is present, the initialization rules described in the block are ignored if the associated configuration token is undefined.
     147 `after INIT_TOKEN`::
     148   This tag imposes the requirement that the code from current token be executed '''after''' the code associated with INIT_TOKEN.
     149 `before INIT_TOKEN`::
     150   This tag imposes the requirement that the code from current token be executed '''before''' the code associated with INIT_TOKEN.
     151 `during INIT_TOKEN`::
     152   This tag make token inherits from constraints expressed for the given INIT_TOKEN. The given token must be a place holder token and can not have associated code.
     153 `code C code here`::
     154   This tag associates some initialization C code to the token. This tag may be used multiple times to add more code lines.
     155
     156=== Example ===
     157
     158Initialization constraints example:
     159{{{
     160%init INIT_FEATURE
     161  parent CONFIG_FEATURE
     162  during INIT_LIBRARIES
     163  after INIT_LIBC_STDIO      # an explanation why this is needed
     164  code great_feature_init();
     165%init end
     166}}}
     167
    123168= Source tree `Makefile` syntax and rules =
    124169
    125170Makefiles in source directories may use the following variables:
    126171 `objs`::
    127    A list of .o files compiled from `.c`, `.s` or `.S` files
     172   A list of `.o` files compiled from `.c`, `.s` or `.S` files
    128173 `meta`::
    129174   A list of files that may be translated from `.m4`, `.cpp` or `.def` files