Documentation update.

darcs-hash:20071019133904-f2ef6-c4b01a90f0a9462505bc40f8ac799733a4fe7982.gz

diff --git a/doc/manual.texinfo b/doc/manual.texinfo
index f8ececd684efab1c22e3591beed7c8c156125806..eaa287ed1a84f20fd1b8b1876a60233741516112 100644 (file)
--- a/doc/manual.texinfo
+++ b/doc/manual.texinfo
@@ -417,16 +417,81 @@ list for all options if Kconfig is used.
 
 @section Basic Concepts
 
+The main concept of OMK is very simple. In the root directory of the
+projects resides a file called @file{Makefile.rules}. This file contains
+all compilation rules needed for compilation. There are different
+@file{Makefile.rules} for different platforms (Unix, RTEMS, system-less,
+...). In every subdirectory a @file{Makefile.omk} is stored. This file
+specifies what should be done in this directory (e.g. compile a program
+from several source files). Its syntax is very simple -- see the
+following sections.
+
+In theory, this could everything, what is needed to compile a project. In
+reality, you want to be able to start compilation simply by typing
+@command{make} in some directory. Since make searches by default for a
+file @file{Makefile}, in every directory, there is small
+@file{Makefile}, whose only task is to find @file{Makefile.rules} and
+include it.
+
+The compilation process itself is comprised of several passes. The pass
+traverse the whole directory structure@footnote{In future, we are
+planning some optimization that allows OMK to traverse the directories
+only once and thus decrease compilation time.} and does some
+task. Typically, these passes are:
+@table @dfn
+@item include-pass
+    This pass takes all include files marked for ``export'' and copies
+    (or links) them to the @file{include} directory (usually under
+    @file{_compiled} directory). Also, during this pass, generated
+    headers are generated according to the current configuration. See
+    @ref{Configuration and Conditional Compilation} for details.
+@item library-pass
+    During this pass, all include files are in place, so all libraries
+    can be compiled.
+@item binary-pass
+    Finally, programs can be compiled and linked against libraries
+    created in the previous pass.
+@end table
+
+The results of compilation are stored under the @file{_compiled}
+directory. This directory is structured as a classical Unix filesystem
+(it contains directories like @file{bin}, @file{lib} and @file{include})
+and can be directly copied to the target device or to some directory
+(e.g. @file{/usr/local}).
+
+Besides @file{_compiled} directory, there in a @file{_build}
+directory. Under this directory are stored some temporary files and
+intermediate compilation products (object files, dependency files etc.).
+
 @section Dependency Tracking
 
+OMK automatically handles tracking of dependencies of compiled
+projects. It uses gcc's @option{-Mx} options to do this for object
+files. This way, whenever you change some header file, OMK recompiles
+only those files, where the changed header was really included.
+
+Dependencies are also kept for libraries and binaries. OMK parses linker
+map files, so a change to some library causes all programs using this
+library to be recompiled.
+
 @section Compiling Simple Programs
 
+
 @section Libraries
 
+LN_INCLUDES
+
+@node Configuration and Conditional Compilation
 @section Configuration and Conditional Compilation
 
 @section Running OMK under Windows OS
 
+@section Troubleshooting
+
+Renaming of some file => dependency problems.
+
+
+
 @chapter OMK Reference
 
 @chapter OMK Development