config.target added to documentation. Reworked configuration section.

Please note, that current implementation doesn't conform to what is
written in documentation. We need to investigate how to rewrite
Makefile.rules to behave as described.

darcs-hash:20071216233644-f2ef6-6e29c165e8cffa84a56a9d784df65418c6c81e2b.gz

diff --git a/doc/omk-manual.texinfo b/doc/omk-manual.texinfo
index bd536e9389ed020e3809ebfaa8834953f59aa443..82f8440a3f7f62b8467f52dad83accbf8eadd9b0 100644 (file)
--- a/doc/omk-manual.texinfo
+++ b/doc/omk-manual.texinfo
@@ -541,7 +541,7 @@ causes recompilation of all programs using that library.
 @node Configuration and Conditional Compilation, Advanced OMK Features, Dependency Tracking, OMK User's Manual
 @section Configuration and Conditional Compilation
 
-In many projects, it is necessary to configure a compilation process. By
+In many projects, it is necessary to configure the compilation process. By
 this configuring we mean, setting some parameters that influence the
 output of compilation process. In GNU projects, @command{configure}
 script is usually responsible for configuration. User provides some
@@ -554,23 +554,43 @@ section. For future releases, we plan that this mechanism can make use
 of GNU Autoconf, but currently there is no directly integrated support
 for it.
 
-In every directory you can specify some configuration parameters, which
-can be modified by a user. Then, when @command{make default-config} is
-run, all these parameters are found and together with their default
-values are stored as makefile variables in
+There exist three different configuration files
+@file{config.omk-default}, @file{config.target} and
+@file{config.omk}. All of these have to be stored in the same directory
+as @file{Makefile.rules}. During compilation, these files are included
+in @file{Makefile.rules} in this order which means that variables
+assigned in the former files are overridden by those from later
+ones. All settings specified here apply to the whole compilation
+tree. Each file is intended for a different kind of configuration
+values:
+@table @file
+@item config.omk-default
+  Stores default configuration of compiled components. This file is
+  automatically generated (see below) and should not be edited by users.
+@item config.target
+  Stores default configuration for a project or target hardware. This
+  file is intended to be stored in a version control system and should
+  be modified only by the maintainer of the project. 
+
+  For cross compiled projects, this file typically contains settings of
+  variables like @var{CC} and @var{CFLAGS}.
+@item config.omk
+  This is a file for end users, where any default settings set in the
+  above files can be overridden. This file should not be stored in
+  version control system. The project should compile without having this
+  file.
+@end table
+
+Besides variables defined in @file{config.target}, @file{Makefile.omk}
+in any subdirectory can specify some configuration parameters. When
+@command{make default-config} is run, all these parameters are found and
+together with their default values are stored as makefile variables in
 @file{config.omk-default}. This file is included during compilation, so
 if you don't specify other values, these defaults are used. If you are
 not satisfied with these defaults, you can override the values of
-parameters in @file{config.omk}. This file is also included during
-compilation and variables mentioned there takes precedence over those
-specified in @file{config.omk-default}. Both @file{config.omk} and
-@file{config.omk-default} have to be stored in the same directory as
-@file{Makefile.rules}.
-
-Besides overriding the default values of configuration parameters,
-@file{config.omk} can also be used as a common place to store some
-global settings that applies to the whole project, e.g. the compiler to
-use or common compiler flags.
+parameters either locally for your build in @file{config.omk} or
+globally for all people working with the project in
+@file{config.target}.
 
 @subsection Specifying Configuration Parameters