Changes between Version 11 and Version 12 of BuildSystem

Timestamp:

Nov 28, 2009, 4:08:11 PM (15 years ago)

Author:

becoulet

Comment:

--

BuildSystem

@@ -4 +4 @@
 = Overview of the build process =
 
-The build system take a configuration file, processes the dependancies, and compiles the desired kernel.
-
-Depending on the targeted architecture, the output file may be an ELF (.out), a plain binary file (.bin), an intel-hex file (.hex) or an object file (.o).
-
-The build system takes care of dependancies, file modifications, ...
+The build system takes a build configuration file and compiles the desired kernel together with the application.
+
+The build system takes care of dependencies, file modifications, ... And is still simple to use for the beginner.
+
+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).
 
 = User point of view =
 
-== Makefile options (command line) ==
-
-When building with MutekH, several options may be used to change the behavior of the build system.
+== Invocation ==
+
+When building MutekH, several options may be used to change the behavior of the build system.
 These options are given through variables when calling `make`, in the form:
+
 {{{
 $ make VAR1=value1 VAR2=value2
 }}}
 
-The following options are mandatory:
+Real build process invocation just need to specify build configuration to use:
+
+{{{
+# using flat and simple build configuration file
+$ make CONF=examples/hello/config_soclib_mipsel
+}}}
+{{{
+# using sectioned build configuration file
+$ make CONF=examples/hello/config BUILD=soclib-mipsel
+}}}
+
+== Main variables ==
+
+The following option is mandatory:
  `CONF=`::
-   An absolute path to the root configuration file for the desired kernel instance.
+   An absolute path to the build configuration file.
+
+The following option may be required depending on build configuration file:
+ `BUILD=`::
+   A colon separated list of build section names to consider in the build configuration file.
 
 The following options may be useful:
@@ -54 +72 @@
    This prints the flags used for compilation
 
-The following targets are available to get help about configuration
+The following targets are available to get help about configuration.
 
  `listconfig`::
@@ -62 +80 @@
  `showconfig`::
    This prints detailed information about a given configuration token. Token must be specified with `TOKEN=` variable argument.
-   {{{
-$ make showconfig TOKEN=CONFIG_PTHREAD
-}}}
+
+See usage below.
 
 == Build configuration files ==
+
+=== Content ===
 
 MutekH build configuration files contain tokens defining the kernel we are currently building. They must contain:
@@ -77 +96 @@
  * ...
 
+=== Basic syntax ===
+
 Syntax is `token` '''space''' `value`. Tokens begin with `CONFIG_`. Value may be unspecified thus defaults to `defined`. e.g.
 {{{
@@ -102 +123 @@
 
 Most common values are `defined` and `undefined` to enable and disables features, but some tokens may need numerical or string values.
+
+Have a look to [source:trunk/mutekh/examples/hello] for examples of complete build configuration files.
+
+== Help display ==
+
+To display the list of all available tokens:
+{{{
+$ make CONF=path/to/config_file listconfig
+$ make CONF=path/to/config_file listallconfig
+}}}
+
+To display help about a specific token:
+{{{
+$ make CONF=path/to/config_file showconfig TOKEN=CONFIG_PTHREAD
+}}}
+
+The [http://www.mutekh.org/www/mutekh_api/ MutekH API reference manual] describes all available configuration tokens too.
+
+=== Module declaration ===
 
 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:
@@ -110 +150 @@
 }}}
 
-To display the list of all available tokens, do
-{{{
-$ make listallconfig
-}}}
-
-For a list of current available tokens depending on your configuration file, do
-{{{
-$ make CONF=path/to/config_file listconfig
-}}}
+=== Advanced syntax ===
+
+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.
+
+Build configuration files may contains some directives:
+
+ `%section pattern [pattern ...]`::
+   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-*`). Wildcar match non-empty and non-hypens text.
+ `%common`::
+   Revert to unconditional common file part, default at beginning of a file.
+ `%else`::
+   Change current conditional state.
+ `%include filename`::
+   Include a configuration file, the new file always begin in `%common` state.
+ `%types type [type ...]::
+   Specify that the current section exhibits the given types. No more than one section can be in use with the same type.
+ `%requiretypes type [type ...]`::
+   All specified types must have been defined. May be used in sections or common part.
+ `%set variable content`::
+   Set a variable which can be expanded using {{{$(variable)}}} syntax. Environment is initially imported as variables. Moreover {{{$(CONFIGPATH)}}} and {{{$(CONFIGSECTION)}}} are predefined special variables.
+ `%warning text`::
+   Produce a warning message
+ `%error text`::
+   Produce an error message
+
+The `default` section name is in use when no section name is passed through the `BUILD` variable.
+
+Have a look to [source:trunk/mutekh/examples/hello/config] for an example of advanced build configuration file.
 
 = Developer point of view =