Changes between Version 16 and Version 17 of BuildSystem


Ignore:
Timestamp:
Mar 8, 2010, 7:24:14 PM (15 years ago)
Author:
becoulet
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • BuildSystem

    v16 v17  
    44= Overview of the build process =
    55
    6 The build system takes a build configuration file and compiles the desired kernel together with the application.
    7 
    8 The build system takes care of dependencies, file modifications, ... And is still simple to use for the beginner.
    9 
    10 Depending on the target architecture, the output file may be an ELF (.out), a plain binary file (.bin), an intel-hex file (.hex) or an object file (.o).
     6The build system use one or more used defined *build configuration files* to compiles the desired kernel together with the application.
     7
     8The build system takes care of features dependencies, file modifications, ... And is still simple to use for the beginner.
     9Available features, tweakable values and associated constraints are represented by *configuration tokens* and described by developers through *configuration description files* (.config) in the source tree.
     10
     11Depending on the target architecture, the binary output file may be an ELF (.out), a plain binary file (.bin), an intel-hex file (.hex) or an object file (.o).
    1112
    1213= User point of view =
    … …  
    2324Real build process invocation just need to specify build configuration to use:
    2425
    25 {{{
    26 # using flat and simple build configuration file
     26When using a flat build configuration file:
     27{{{
    2728$ make CONF=examples/hello/config_soclib_mipsel
    2829}}}
    29 {{{
    30 # using sectioned build configuration file
    31 $ make CONF=examples/hello/config BUILD=soclib-mipsel
    32 }}}
    33 
    34 == Main variables ==
     30
     31When using a sectioned build configuration files, you need to specify which sections must be considered for the build:
     32{{{
     33$ make CONF=examples/hello/config BUILD=soclib-mips32el
     34$ make CONF=examples/hello/config BUILD=soclib-arm:debug
     35}}}
     36
     37=== Main variables ===
    3538
    3639The following option is mandatory:
    … …  
    5457   An absolute path to the directory containing the {{{.config.*}}} files, this defaults to `$(BUILD_DIR)`
    5558
    56 == Make targets ==
     59=== Make targets ===
    5760
    5861The following targets are available
    … …  
    8790=== Content ===
    8891
    89 MutekH build configuration files contain tokens defining the kernel we are currently building. They must contain:
     92MutekH build configuration files contain token values pairs defining the kernel we are currently building. They must contain:
    9093
    9194 * the license for the application, enforcing license compatibility between some kernel parts and your code,
    … …  
    98101=== Basic syntax ===
    99102
    100 Syntax is `token` '''space''' `value`. Tokens begin with `CONFIG_`. Value may be unspecified thus defaults to `defined`. e.g.
     103Syntax is `token` '''space''' `value`. Tokens begin with `CONFIG_`. Value may be omitted thus defaults to `defined`. e.g.
    101104{{{
    102105CONFIG_LICENSE_APP_LGPL
    … …  
    111114CONFIG_PTHREAD
    112115
    113 CONFIG_MUTEK_CONSOLE
    114 
    115116# Device drivers
    116117CONFIG_DRIVER_CHAR_EMUTTY
    … …  
    124125Most common values are `defined` and `undefined` to enable and disables features, but some tokens may need numerical or string values.
    125126
    126 Have a look to [source:trunk/mutekh/examples/hello] for examples of complete build configuration files.
     127The easiest way to write a configuration file is to rely on and include common sectioned configuration files and
     128just write the minimal application related configuration yourself. See below.
     129
     130Have a look to [source:trunk/mutekh/examples/hello] for examples of working build configuration files.
     131
     132The [http://www.mutekh.org/www/mutekh_api/ MutekH API reference manual] describes all available configuration tokens.
    127133
    128134== Help display ==
    129135
    130 To display the list of all available tokens:
     136You can display a list of relevant tokens with their value for a given configuration:
    131137{{{
    132138$ make CONF=path/to/config_file listconfig
     139}}}
     140
     141You can display a list of *all* tokens with their value for a given configuration:
     142{{{
    133143$ make CONF=path/to/config_file listallconfig
    134144}}}
    … …  
    139149}}}
    140150
    141 The [http://www.mutekh.org/www/mutekh_api/ MutekH API reference manual] describes all available configuration tokens too.
    142 
    143151=== Module declaration ===
    144152
    145 A build configuration file may declare a new module. Modules can be located anywhere outside of the main source tree. We must tell the build system the directory where the configuration lies. The path to the module directory is usually the same as its configuration file:
     153A build configuration file may declare a new module. Modules can be located anywhere outside of the main source tree.
     154We must tell the build system the directory where the configuration lies.
     155The path to the module directory is usually the same as its configuration file and the `CONFIGPATH` special variable is well suited:
    146156{{{
    147157# New source code module to be compiled
    … …  
    150160}}}
    151161
     162=== Output name ===
     163
     164the MutekH build system takes care of building in directory named after application name and build target.
     165This determine the application output file name too. You may want to set your application output name in build configuration file:
     166{{{
     167  %set OUTPUT_NAME hello
     168}}}
     169
    152170=== Advanced syntax ===
    153171
    154 Basic configuration is really simple. Complex applications or multiple target architectures require maintaining multiple configuration files which can be difficult and annoying. The directives presented here can be used to make things easier.
    155 
    156 Build configuration files may contains some directives:
     172Basic configuration is really simple. Complex applications or multiple target architectures require
     173maintaining multiple configuration files which can be difficult and annoying.
     174The directives presented here are used to make things easier. They are mainly used in common build configuration files found in [source:trunk/mutekh/examples/build].
     175
     176Sectioning directives are useful to consider a set of configuration definitions depending on the `BUILD` variable of `make` invocation:
    157177
    158178 `%section pattern [pattern ...]`::
    159    Start a section which will be conditionaly considered depending on the `BUILD` variable. `pattern` is a pattern matching expression which may contain text, hypens and wildcards (e.i. `text-text-*`). Wildcards match non-empty and non-hypens text.
     179   Start a section which will be conditionaly considered depending on the `BUILD` variable. `pattern` is a pattern matching expression which may contain text, hypens and wildcards (e.i. `text-text-*`). Wildcards match non-empty and non-hypens text. A new `%section token automatically terminate previous section.`
    160180 `%common`::
    161181   Revert to unconditional common file part, default at beginning of a file.
    162182 `%else`::
    163183   Change current conditional state.
    164  `%include filename`::
    165    Include a configuration file, the new file always begin in `%common` state.
     184 `%subsection [pattern ...]`::
     185   Begin a nested section. Multiple levels of subsections can be used. Subsections thus defined must be end by `%end`.
     186 `%end`::
     187   End a subsection started with `%subsection`.
     188
     189Section types directives can be used to enforce use of sections:
     190
    166191 `%types type [type ...]`::
    167192   Specify that the current section exhibits the given types. No more than one section can be in use with the same type.
    168193 `%requiretypes type [type ...]`::
    169194   All specified types must have been defined. May be used in sections or common part.
     195
     196Build configuration files may contain variables:
     197
    170198 `%set variable content`::
    171199   Set a variable which can be expanded using {{{$(variable)}}} syntax. Environment is initially imported as variables. Moreover {{{$(CONFIGPATH)}}} and {{{$(CONFIGSECTION)}}} are predefined special variables.
    172200 `%append variable content`::
    173201   Appends content to a variable.
     202
     203Build configuration files may include other files:
     204
     205 `%include filename`::
     206   Include a configuration file, the new file always begin in `%common` state.
     207
     208Build configuration files may report things to the user:
     209
     210 `%notice text`::
     211   Produce a notice message.
    174212 `%warning text`::
    175    Produce a warning message
     213   Produce a warning message.
     214 `%die text`::
     215   Produce an error message.
    176216 `%error text`::
    177    Produce an error message
     217   Produce an error message with file location information.
    178218
    179219The `default` section name is in use when no section name is passed through the `BUILD` variable.
    180220
    181 Have a look to [source:trunk/mutekh/examples/hello/config] for an example of advanced build configuration file.
     221Some build configuration files are available in [source:examples/common] and can be included to
     222target common platforms without having to deals with all configuration token. This helps keeping application
     223configuration file short. Configuration tokens can be redefined multiple times,
     224allowing to override values set in included files.
    182225
    183226= Developer point of view =
    … …  
    185228MutekH has a component-based architecture where each module declares its configuration tokens.
    186229
    187 Tokens are declared is constraint configuration files which are located at various places in the MutekH source tree.
     230Tokens are declared in configuration description files which are located at various places in the MutekH source tree.
    188231These constraints configuration files have a different syntax from the build configuration files.
    189232They are designed to declare configuration tokens and express relationships between available tokens.
    … …  
    194237
    195238For each configuration token, one may use the following tags:
     239
    196240 `desc Description string without quotes`::
    197241   Short description about the token
     242 `flags FLAGS […]`
     243   Set some flags with special meaning for the token.
     244 `parent TOKEN`::
     245   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. Tokens with no parent must have the `root` flag set.
    198246 `default value`::
    199    Set the token default value. `defined` and `undefined` values act as booleans.
     247   Set the token default value. `defined` and `undefined` values act as booleans. default value is `undefined` if this line is omitted.
     248 `module name [long name]`
     249   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.
     250
     251The following tags may be used to specify features constraints:
     252
    200253 `depend TOKEN […]`::
    201    Dependencies, having at least one of the tokens on the line is required, if unsatisfied the current token gets undefined and a warning is emitted. May be used to disable features because of missing prerequisites.
    202  `parent TOKEN`::
    203    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 unrelevant tokens from the help screen if the parent token is undefined.
    204  `require TOKEN […]`::
    205    Mandatory requirements, having at least one of the tokens on the line is mandatory, conflict yields error. May be usd to enforce definition of some mandatory configuration values.
    206  `provide TOKEN […]`::
    207    Defining the current token enforce definition of the specified token.
    208  `provide TOKEN=value`::
    209    Defining the current token enforce definition of the specified token with the given value.
    210  `provide TOKEN=+value`::
    211    Defining the current token enforce definition of the specified token and concat the given value.
     254   Dependencies, at least one of the feature tokens on the line is required, if unsatisfied the current token gets undefined and a notice is emitted. May be used to disable features because of missing prerequisites.
    212255 `exclude TOKEN`::
    213    Mandatory excluded tokens, the specified token must not be defined
    214  `suggest TOKEN […]`::
    215    Makes a token suggest other tokens when it is defined. This is for help listing.
     256   Specify excluded token, the current and specified token must not be defined at the same time.
    216257 `single TOKEN […]`::
    217258   Only one of the following tokens may be defined at the same time
    218  `fallback TOKEN`::
    219    The fallback token will be enabled if the current one may not be enabled
    220 
    221 The configuration tool may use multiple pass to find a valid configuration when tokens are disabled or enforced by given rules.
     259 `when TOKEN_CONDITION […]`::
     260   The current feature token will be automatically defined if all specified conditions are met.
     261
     262Some tags may be used to deals with values rather than features enabling tokens. Value tokens must have the `value` flag set:
     263
     264 `require TOKEN_CONDITION […]`::
     265   Mandatory requirements, having at least one of the tokens on the line is mandatory, conflict yields error. May be used to enforce definition of some mandatory configuration values.
     266 `provide TOKEN=value`::
     267   Defining the current feature token enforce definition of the specified value token with the given value. The `nodefine` flag indicate token is for internal use and can not be defined by the user.
     268
     269Some tags can be used to give some configurations advice to the user when building MutekH:
     270
     271 `suggest TOKEN_CONDITION`::
     272   Defining the current feature token suggest the given condition to the user.
     273 `suggest_when TOKEN_CONDITION […]`::
     274   The current token will suggest being considered to the user if it still has its default value and all condition are met.
     275
     276The `TOKEN_CONDITION` might check different conditions:
     277
     278 * Token definition check: `TOKEN`
     279 * Token value equality check: `TOKEN=value`
     280 * Token numerical value magnitude check: `TOKEN<value` or `TOKEN>value`
     281
     282The configuration tool will check all rules when building MutekH with a given build configuration file.
    222283
    223284Example:
    224285{{{
    225 %module Module name for documentation
    226 
    227 %config CONFIG_SRL
    228 desc MutekS API
    229 provide CONFIG_MODULES=+libsrl:$(CONFIGPATH)
    230 depend CONFIG_MUTEK_SCHEDULER
    231 depend CONFIG_MWMR
    232 require CONFIG_SRL_SOCLIB CONFIG_SRL_STD
    233 single CONFIG_SRL_SOCLIB CONFIG_SRL_STD
    234 default undefined
     286%config CONFIG_FEATURE
     287  desc This is a great module for MutekH
     288  depend CONFIG_MUTEK_SCHEDULER
     289  module great The great library
     290  require CONFIG_CPU_MAXCOUNT>1
    235291%config end
    236 }}}
    237 
    238 Here we declare a `CONFIG_SRL` token which
    239  * depends on `CONFIG_MUTEK_SCHEDULER` and `CONFIG_MWMR`,
    240  * requires `CONFIG_SRL_SOCLIB` or `CONFIG_SRL_STD`,
    241  * adds the directory containing the `.config` as a new "libsrl" module
    242 
    243 Environment variable substitution takes place in both build and constraints configuration files.
    244 
    245 == The directories Makefile syntax & rules ==
    246 
    247 Makefiles in directories may use the following variables:
     292
     293%config CONFIG_FEATURE_DEBUG
     294  desc Enable debug mode for the great feature
     295  parent CONFIG_FEATURE
     296  provide CONFIG_FEATURE_STACK_SIZE=4096
     297  when CONFIG_DEBUG
     298%config end
     299
     300%config CONFIG_FEATURE_STACK_SIZE
     301  desc This is the thread stack size for the great feature
     302  parent CONFIG_FEATURE
     303  flags value
     304  default 512
     305%config end
     306
     307}}}
     308
     309== Source tree Makefile syntax & rules ==
     310
     311Makefiles in source directories may use the following variables:
    248312 `objs`::
    249313   A list of .o files compiled from `.c`, `.s` or `.S` files