directory structure} without the need to update users of moved
component. I hate something like
@option{-I../../sched/rtlshwq/include} in makefiles for example. If a
- component is renamed or version is added to the name, all Makefiles
- in will require an update.
+ component is renamed or version is added to the name, many Makefiles
+ in the project would require an update.
@item
The above feature is very helpful in @b{combining components}
(libraries) from different projects/developers to a single project by
@menu
* Basic Concepts::
-* Dependency Tracking::
+* Invoking OMK::
* Compiling Programs::
* Libraries::
* Multiple Directories::
+* Dependency Tracking::
* Configuration and Conditional Compilation::
+* Advanced OMK Features::
* Running OMK under Windows OS::
* Interfacing OMK to popular IDEs::
* Troubleshooting::
@end menu
-@node Basic Concepts, Dependency Tracking, OMK User's Manual, OMK User's Manual
+@node Basic Concepts, Invoking OMK, OMK User's Manual, OMK User's Manual
@section Basic Concepts
The main concept of OMK is very simple. In the root directory of the
all compilation rules needed for compilation of a particular
project. 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
+@file{Makefile.omk} is stored. This file determines what should be done
+in the respective directory (e.g. compile a program from several source
files). Its syntax is very simple -- see the following sections.
Since make searches by default for a @file{Makefile} and not for
@file{Makefile.rules} or @file{Makefile.omk}, there must be a small
-@file{Makefile} in every directory, whose task is only to find
-@file{Makefile.rules} and include it. The @file{Makefile.rules} is
-searched starting from the current directory and continuing to upper
-directories.
+generic @file{Makefile} in every directory, whose task is only to find
+@file{Makefile.rules} in the actual or any parent directory and include
+it. This search is performed only once at the beginning of compilation.
+
+@c TODO: Pavel's note about qmake.
The compilation process itself is comprised of several passes. Every
pass traverses the whole directory structure@footnote{In future, we are
directory. Under this directory are stored some temporary files and
intermediate compilation products (object files, dependency files etc.).
-@node Dependency Tracking, Compiling Programs, Basic Concepts, OMK User's Manual
-@section Dependency Tracking
+In the next section, we provide an overview of methods, how to invoke
+OMK from command line. Section @ref{Interfacing OMK to popular IDEs}
+covers running of OMK from popular IDEs.
-OMK automatically handles tracking of dependencies of files in compiled
-projects. It uses gcc's @option{-M@var{x}} 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.
+Sections @ref{Compiling Programs} through @ref{Configuration and
+Conditional Compilation} deals with the content of
+@file{Makefile.omk}. Its syntax in usual cases compatible to GNU
+Automake's @file{Makefile.am} syntax. Also, the scheme for naming
+variables was inspired by Automake so most OMK variables have the name
+like @samp{@var{target}_@var{TYPE}}.
-Dependencies are also maintained for libraries and binaries. To find the
-dependencies, OMK parses linker map files, so a change to some library
-causes recompilation of all programs using that library.
+@node Invoking OMK, Compiling Programs, Basic Concepts, OMK User's Manual
+@section Invoking OMK
-@menu
-* Compiling Programs::
-* Configuration and Conditional Compilation::
-@end menu
+Before using OMK for the first time, you have to call:
+@example
+@command{make default-config}
+@end example
+@noindent See @ref{Configuration and Conditional Compilation} for
+details. If you forget to do this, OMK will notice you.
+
+To compile the whole project or only some subtree of the project, call
+@example
+@command{make}
+@end example
+@noindent in the appropriate directory.
+
+To clean files in @file{_build} directory but not in @file{_compiled}
+one, use:
+@example
+@command{make clean}
+@end example
+
+To clean the compilation completely, you can either remove
+@file{_compiled} and @file{_build} directories manually, or call
+@example
+@command{make distclean}
+@end example
+@noindent which does the same. This command removes these directories
+even if you call it from a subdirectory.
+
+To debug compilation problems, you can use @code{V} variable (see
+@ref{V}):
+@example
+@command{make V=1}
+@end example
+
+You can also set values of some other variables on command line for
+temporary change something. The example below compiles the code
+temporarily with debugging information:
+@example
+@command{make CFLAGS="-g -O0 -Wall"}
+@end example
+
+
+@anchor{V}
+@defvar V
+If this variable equals to @samp{1}, the whole command lines for all
+executed commands are displayed. Otherwise, only a short messages are
+printed.
+@end defvar
-@node Compiling Programs, Libraries, Dependency Tracking, OMK User's Manual
+@node Compiling Programs, Libraries, Invoking OMK, OMK User's Manual
@section Compiling Programs
To tell OMK to compile a program, you need to set some variables in
@anchor{include_HEADERS}
@defvar include_HEADERS
Specifies the list of header files to be exported for use by other
- libraries/programs. If the header file specified here contains a
- directory prefix (see @file{periph/} in the example below), the header
- is copied with the same prefix under @file{includes} directory in
- @file{_compiled} tree.
+ libraries/programs. The files are exported directly to the
+ @file{include} directory even if the file is located in a subdirectory
+ (like @file{sci_regs.h} in the example below)
@example
include_HEADERS = regs.h periph/sci_regs.h
@defvar nobase_include_HEADERS
Similar to @ref{include_HEADERS}, but the directory prefix is always
- stripped before coping the header file.
+ kept. To include the file exported by this variable, use
+ @code{#include <@var{prefix}/@var{header.h}>}.
@end defvar
@defvar renamed_include_HEADERS
@end defvar
@defvar LN_INCLUDES
- This variable is very useful during library development. Most
- @acronym{IDE}s, allows you to jump directly to the place, where an
- error is reported by the compiler. If the error is in a header file,
- IDE opens you the copy of the header file. If you correct the error
- there, after the next compilation, your header file will be
- overwritten by the old version from your source tree.
-
If this variable equals to @samp{y}, symbolic links to headers in
source directories are used in @file{_compiled} tree instead of
copies.
+
+ Normally, the header files are copied into @file{_compiled} directory
+ to be prepared for transfer into target location afterwards. Copying
+ ensures that resulting libraries are in correspondence with the header
+ files even if the header is changed by a developer but the library is
+ not recompiled.
+
+@c Another reason for having single include directory for the whole
+@c project is tat every component knows where to find header files of
+@c other components.
+
+ On the other side, the copying could make problems during
+ development. Most @acronym{IDE}s, allows you to jump directly to the
+ place, where an error is reported by the compiler. If the error is in
+ a header file, IDE opens you the copy of the header file. If you
+ correct the error there, after the next compilation, your header file
+ will be overwritten by the old version from your source tree.
+
+ This option is not typically used in @file{Makefile.omk}, but in the
+ top level configuration file @file{config.omk} or on command line.
@end defvar
-@node Multiple Directories, Configuration and Conditional Compilation, Libraries, OMK User's Manual
+@node Multiple Directories, Dependency Tracking, Libraries, OMK User's Manual
@section Multiple Directories
OMK is probably most useful in projects consisting of multiple
-directories. For such projects, it is not easy to write Makefiles that
-provides all the needed features, from scratch.
+directories. For such projects, it is not easy to write from scratch
+classic Makefiles that provides all the needed features.
You can instruct OMK to descend to a (sub)directory by setting the
@code{SUBDIRS} variable in @file{Makefile.omk}.
@end example
@end defvar
-@node Configuration and Conditional Compilation, Running OMK under Windows OS, Multiple Directories, OMK User's Manual
+@node Dependency Tracking, Configuration and Conditional Compilation, Multiple Directories, OMK User's Manual
+@section Dependency Tracking
+
+OMK automatically handles tracking of dependencies of files in compiled
+projects. It uses gcc's @option{-M@var{x}} 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 maintained for libraries and binaries. To find the
+dependencies, OMK parses linker map files, so a change to some library
+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
OMK has its own configuration mechanism, which is described in this
section. For future releases, we plan that this mechanism can make use
-of GNU autoconf, but currently there is no support for it.
+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
@var{value}. The possible forms are:
@table @code
-@item @samp{y} or @samp{n}
+@item @samp{y}, @samp{n} or @samp{x}
This defines boolean parameters. If the value of the parameter is
@samp{y}, the @samp{#define CONFIG_@var{xxx} 1} is generated, if it is
- @samp{n}, no @code{#define} is generated.
+ @samp{n}, no @code{#define} is generated.
+
+ @samp{x} is a special value called @emph{recessive 'n'}. The meaning
+ is that this parameter influences the component in the current
+ directory (i.e. the corresponding @code{#define} will be included in
+ @code{LOCAL_CONFIG_H}; see @ref{LOCAL_CONFIG_H}) but the default value
+ is not specified here. If the default value is not specified anywhere,
+ the behavior is the same as if @samp{n} is specified.
@item @samp{number}
Numeric parameters. The define looks like @samp{#define CONFIG_@var{xxx} @var{number}}
@item @samp{text}
@defvar config_include_HEADERS
This variable is similar to @code{LOCAL_CONFIG_H}. One difference is
- that the generated header file is accessible to all files, not only to
- files in the same directory (it is stored in @file{_compiled}
- tree). The second difference is that you have to specify, which
- configuration parameters you want to appear in the header file.
+ that the generated header file is accessible to all sub-projects in
+ all directories, not only to the files in the same directory (the
+ header is stored in @file{_compiled} tree). The second difference is
+ that you have to specify, which configuration parameters you want to
+ appear in the header file.
@end defvar
@defvar @var{xxx}_DEFINES
Additional parameters (besides @code{CFLAGS}) to by passed to C++
compiler.
@end vtable
+
+@node Advanced OMK Features, Running OMK under Windows OS, Configuration and Conditional Compilation, OMK User's Manual
+@section Advanced OMK Features
+
+In this section we list several OMK features, which are more complicated
+or rarely used so they were omitted in previous sections.
+
+@itemize
+@item
+ The @file{_compiled} directory can be shared between multiple projects
+ (by using symbolic links).
+
+@item
+ If you work on a bigger project, you usually don't need to rebuild the
+ whole project and call @command{make} only in a
+ subdirectory. Sometimes, it might be useful to rebuild the whole
+ project. You can either change working directory to the root of your
+ project and call @command{make} there or, as a shortcut, you can use
+ @code{W} variable (see @ref{W}) to compile everything directly from a
+ subdirectory.
+@example
+@code{make W=1}
+@end example
+
+@item
+ Searching for @file{Makefile.rules} works such way, that if you get
+ into sources directory over symbolic links, OMK is able to unwind your
+ steps back. This implies you can make links to component directories
+ on read-only media, copy @file{Makefile.rules}, @file{Makefile} and
+ top-level @file{Makefile.omk}, adjust @file{Makefile.omk} to contain
+ only required components and then call @command{make} in the top
+ directory or even in read-only directories after changing working
+ directory from your tree to readonly media.
+@end itemize
+
+
+@anchor{W}
+@defvar W
+If this variable equals to @samp{1}, the @b{whole} project is
+(re)compiled, even if @command{make} is called from a subdirectory.
+@end defvar
+
+
+
-@node Running OMK under Windows OS, Interfacing OMK to popular IDEs, Configuration and Conditional Compilation, OMK User's Manual
+@node Running OMK under Windows OS, Interfacing OMK to popular IDEs, Advanced OMK Features, OMK User's Manual
@section Running OMK under Windows OS
@node Interfacing OMK to popular IDEs, Troubleshooting, Running OMK under Windows OS, OMK User's Manual
even more space for OCERA development.
@end itemize
-The problem calls for same solution, which would have minimal impact
+The problem calls for some solution, which would have minimal impact
on other components and would be elegant and would be maintainable
and small, because our main goal is components development and not
make systems development.
to link tree pointing into readonly media or can be anywhere
else if @code{MAKERULES_DIR} and @code{SOURCES_DIR} are specified.
+@c !!! tohle tam nejak zmizelo, mozna by to chtelo skontrolovat, ze to
+@c sedi s aktualnim stavem
+
+
Syntax of Makefile.omk files is for usual cases compatible
to Automake's Makefile.am descriptions. There are specific targets
for RT-Linux and Linux kernel related stuff
projects / omk.git / commitdiff