Changes between Version 26 and Version 27 of BuildSystem


Ignore:
Timestamp:
Dec 18, 2012, 12:54:57 PM (12 years ago)
Author:
becoulet
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • BuildSystem

    v26 v27  
    22= Introduction =
    33
    4 This document describes the MutekH build system invocation and base features and is intended for beginners and application developers.
    5 
    6 The build system takes care of features dependencies, file modifications, ... but is still simple to use for the beginner.
     4This page describes the MutekH build system invocation and base features and is intended for MutekH user and application developers.
     5
     6The build system is responsible for building MutekH with requested features configuration.
    77MutekH source code is highly configurable, this implies the application developer
    88has to provide a '''build configuration file''' along with the application source code.
    99
    10 Available features, tweakable values and associated constraints are represented by '''configuration tokens'''
    11 and described by kernel developers through '''configuration description files''' (.config) in the source tree.
    12 The configuration description syntax is detailed on the BuildSystemDev page which cover more advanced topics.
    13 
     10Available features, options and associated constraints are represented by '''configuration tokens'''
     11which are declared by kernel developers in '''configuration description files''' (.config) in the kernel source tree.
     12These files define set the set of configuration tokens which can be assigned in a '''build configuration file'''.
     13The configuration description syntax is detailed on the BuildSystemDev page which cover more advanced topics related to kernel developpment.
     14
     15This page focus on the build system invocation and the format of the build configuration file.
    1416Reading the BuildingExamples page may be of some interest too.
    1517
    … …  
    1719
    1820== Building ==
     21
     22Invocation of the build system is performed by running GNU make at the root of the MutekH source tree.
    1923
    2024When building MutekH, several options may be used to change the behavior of the build system.
    … …  
    2529}}}
    2630
    27 Real build process invocation just need to specify build configuration to use:
    28 
    29 When using a flat build configuration file:
    30 {{{
    31 $ make CONF=examples/hello/config_soclib_mipsel
    32 }}}
    33 
    34 When using a sectioned build configuration files, you need to specify which sections must be considered for the build:
    35 {{{
    36 $ make CONF=examples/hello/config BUILD=soclib-mips32el
    37 $ make CONF=examples/hello/config BUILD=soclib-arm:debug
    38 }}}
    39 
    40 Depending 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).
     31Build process invocation actually require the user to specify a build configuration file to use.
     32
     33Using a flat build configuration file which contains the whole kernel configuration,
     34including supported hardware and device drivers definitions, is the most simple way to invoke the build system:
     35{{{
     36$ make CONF=path/to/config.build
     37}}}
     38
     39This however requires the user to write a long build configuration file which is target specific.
     40Relying on a sectioned build configuration files (see below) make this file short and easier to write.
     41We then need to specify which sections of the file must be considered for the build:
     42{{{
     43$ make CONF=path/to/config.build BUILD=ibmpc-x86
     44$ make CONF=path/to/config.build BUILD=gaisler-leon3
     45$ make CONF=path/to/config.build BUILD=soclib-mips32el:pf-tutorial
     46}}}
    4147
    4248== Configuration display ==
    4349
    44 This section explains how to display information about MutekH configuration being used.
     50This section explains how to display information about the MutekH configuration being used.
    4551
    4652You can display a list of relevant tokens with their value for a given configuration:
    4753{{{
    48 $ make CONF=path/to/config_file listconfig
    49 }}}
    50 
    51 You can display a list of '''all''' tokens with their value for a given configuration:
    52 {{{
    53 $ make CONF=path/to/config_file listallconfig
    54 }}}
    55 
    56 To display help about a specific token:
    57 {{{
    58 $ make CONF=path/to/config_file showconfig TOKEN=CONFIG_PTHREAD
    59 }}}
     54$ make CONF=path/to/config.build BUILD=... listconfig
     55}}}
     56
     57You can display a detailed description of initializations which take place during KernelStartUp; this also depend on the build configuration in use:
     58{{{
     59$ make CONF=path/to/config.build BUILD=... listinit
     60}}}
     61
     62More targets are available, see below.
     63
     64== Build log ==
     65
     66When the compilation process ran successfully, a build log is written to a `.log` file named after the generated kernel file.
     67This file contains various information about the configuration used for the build which can be useful to developpers.
    6068
    6169= Main variables =
    … …  
    7280 `VERBOSE=1`::
    7381   Prints all the commands executed
     82 `TARGET_EXT=`::
     83   Generate a kernel image in various formats: `out` (elf), `o` (object), `bin` (flat binary), `hex` or `srec`.
    7484
    7585The following options are useful when building out of the source tree:
    … …  
    95105
    96106 `showpaths`::
    97    This prints the modules that will be built, their paths, …
     107   This prints the modules that will be built along with associated paths.
    98108 `cflags`::
    99    This prints the flags used for compilation
     109   This prints the flags used for compilation.
    100110
    101111The following targets are available to get help about configuration.
    102112
    103113 `listconfig`::
    104    Prints the current configuration as expanded by MutekH build system. It also prints available --- but currently undefined --- configuration tokens.
     114   Prints values of configuration tokens which would be used to build MutekH according to current build configuration.
    105115 `listallconfig`::
    106    Prints all the configuration tokens, even the ones incompatible with the current configuration.
    107  `showconfig`::
    108    This prints detailed information about a given configuration token. Token must be specified with `TOKEN=` variable argument.
     116   Prints all the configuration tokens, including internal tokens and tokens with undefined parents.
     117 `listflatconfig`::
     118   Prints the content of a minimal flat configuration file which could be used to define current configuration.
     119 `listinit`::
     120   Prints initialization tokens and initilization function calls which will take place during KernelStartUp according to current build configuration.
    109121
    110122See usage below.
    … …  
    114126== Content ==
    115127
    116 MutekH build configuration files contain token values pairs defining the kernel we are currently building. They must contain:
     128The MutekH build configuration file defines token values describing feature included in the kernel which is being built. It must contain:
    117129
    118130 * the license for the application, enforcing license compatibility between some kernel parts and your code,
    119131 * the target architecture
    120  * the libraries used, and their configurations
    121  * the used drivers
     132 * libraries to build, and related options
     133 * device drivers
    122134 * some global compilation switches (optimization, debugging, …)
    123135 * ...
    … …  
    127139Syntax is `token` '''space''' `value`. Tokens begin with `CONFIG_`. Value may be omitted thus defaults to `defined`. e.g.
    128140{{{
     141...
     142
    129143CONFIG_LICENSE_APP_LGPL
    130144
    … …  
    147161}}}
    148162
    149 Most common values are `defined` and `undefined` to enable and disables features, but some tokens may need numerical or string values.
    150 
    151 The easiest way to write a configuration file is to rely on and include common sectioned configuration files and
    152 just write the minimal application related configuration yourself. See below.
    153 
    154 Have a look to [source:hg/examples/hello] for examples of working build configuration files.
     163Most common values are `defined` and `undefined` to enable and disables features, but some tokens may take numerical or string values.
     164
     165The easiest way to describe your configuration is to rely on sectioned '''build configuration files''' which are provided in the kernel source tree.
     166These files are split in multiple sections which are conditionnaly parsed depending on the value of the `BUILD` variable passed to the build system.
     167
     168They provide default configurations for supported processors and platforms so that you just have to write a minimal file which take care of enabling
     169modules and features which are needed by your application. This way, all configuration token related to target hardware will get their value from those files.
     170This do not prevent the user to override a token value after inclusion of one of those files.
     171The user can also define its own sections on its build configuration, see syntax at the end of this page.
     172
     173{{{
     174...
     175
     176CONFIG_LICENSE_APP_LGPL
     177
     178CONFIG_PTHREAD
     179
     180%include platforms.build
     181
     182CONFIG_CPU_MAXCOUNT 4
     183}}}
     184
     185Have a look to [source:hg/examples/hello] for examples of real build configuration files.
    155186
    156187The [http://www.mutekh.org/www/mutekh_api/ MutekH API reference manual] describes all available configuration tokens.
    … …  
    160191MutekH has a modular and component-based architecture.
    161192
    162 A build configuration file may declare a new module for the application.
     193A build configuration file must declare a new module for the application.
    163194Modules can be located anywhere outside of the main source tree.
    164 We must tell the build system the directory where the configuration lies.
     195We must tell the build system the directory where the configuration file is located.
    165196The path to the module directory is usually the same as its configuration file and the `CONFIGPATH` special variable is well suited:
    166197{{{
    … …  
    180211== Advanced syntax ==
    181212
    182 Basic configuration is really simple. Complex applications or multiple target architectures require
     213As explained previoudly, basic build configuration format is simple.
     214Complex applications or support for multiple target architectures require
    183215maintaining multiple configuration files which can be difficult and annoying.
    184 The directives presented here are used to make things easier. They are mainly used in common build configuration files found in [source:hg/examples/build].
     216The directives presented here can be used to define conditional sections in build configuration files.
    185217
    186218Sectioning directives are useful to consider a set of configuration definitions depending on the `BUILD` variable of `make` invocation:
    … …  
    229261The `default` section name is in use when no section name is passed through the `BUILD` variable.
    230262
    231 Some build configuration files are available in [source:examples/common] and can be included to
    232 target common platforms without having to deals with all configuration token. This helps keeping application
    233 configuration file short. Configuration tokens can be redefined multiple times,
    234 allowing to override values set in included files.
    235 
     263Some build configuration files are provided in the kernel source tree and can be included to
     264target hardware platforms without having to deals with all related configuration token.
     265Configuration tokens can be assigned multiple times, this allows overriding values previously assigned in included files.
     266