\input texinfo @c -*-texinfo-*-
@c %**start of header
-@setfilename omk
-@settitle Ocera Make System
+@setfilename omk-manual
+@documentencoding UTF-8
+@settitle OMK: Ocera Make System
@c %**end of header
@copying
-Manual for Ocera Make System (OMK)
+Manual for Ocera Make System (OMK) version $Id$
-Copyright @copyright{} 2007 Michal Sojka, Pavel Pisa
+Copyright @copyright{} 2007, 2008, 2009 Michal Sojka, Pavel Pisa
@end copying
@titlepage
@cindex overview
OMK is an advanced make system written entirely in GNU make. Compiling
-software using OMK requires only GNU make binary and standard UNIX
-utilities (@command{sh}, @command{sed}, @command{cmp} and
-@command{tr}@footnote{@command{tr} is needed only for OMK to be
-compatible with MinGW.}) installed. OMK aims to be developer friendly;
-to use OMK, you do not need to understand (sometimes) cryptic syntax of
-Makefiles.
+software using OMK requires only GNU Make and standard UNIX
+utilities (@command{sh}, @command{sed}, @command{cmp}, ...)
+installed. OMK aims to be developer friendly; to use OMK, you do not
+need to understand (sometimes) cryptic syntax of Makefiles.
You can use OMK on all platforms where you can run GNU Make including
Cygwin and MinGW. MS DOS was not tested.
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
@end itemize
+
+
@node Quick Start, History, Why to Use OMK?, Overview of OMK
@section Quick Start
@enumerate
@item
- Take appropriate @file{Makefile.rules}, put it together with leaf
- @file{Makefile} to the root directory of your project.
+ The newest version of OMK can be found at @uref{http://rtime.felk.cvut.cz/omk/}.
+@item
+ Take appropriate @file{Makefile.rules} (see @ref{Properties of
+ Specific Makefile.rules}), put it together with leaf @file{Makefile}
+ to the root directory of your project.
@item
Create @file{Makefile.omk} files in all directories you want to
compile something. Please refer to @ref{OMK User's Manual} to learn
@node History, , Quick Start, Overview of OMK
@section History
-OMK was originally written by Pavel Pisa as a solution to have one
+OMK was originally written by Pavel Píša as a solution to have one
common make system for OCERA project, where we needed to compile
user-space programs, Linux kernel modules and RT Linux modules in one
package. Although this system was not accepted for the whole OCERA
@menu
* Basic Concepts::
-* Dependency Tracking::
+* Invoking OMK::
* Compiling Programs::
* Libraries::
* Multiple Directories::
+* Dependency Tracking::
* Configuration and Conditional Compilation::
+* Advanced OMK Features::
+* Properties of Specific Makefile.rules::
* 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.
+@file{Makefile.rules} or @file{Makefile.omk}, there must@footnote{When
+USE_LEAF_MAKEFILES is set to @samp{n}, this @file{Makefile} can be
+omitted in subdirectories. @xref{USE_LEAF_MAKEFILES}.} be a small
+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.
-The compilation process itself is comprised of several passes. Every
+@c TODO: Pavel's note about qmake.
+
+@anchor{passes}
+The compilation process itself is comprised of several @emph{passes}. Every
pass traverses 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 a particular
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
+
+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
+
+If your project uses an alternative make-system (e.g. Automake or custom
+makefiles), it might be useful for you to use the command:
+@example
+@command{make omkize}
+@end example
+@noindent This will find all @file{Makefile.omk} files in all subdirectories
+and copies generic @file{Makefile} from the root directory to that
+subdirectories. This way you can easily switch your project to use OMK.
-@menu
-* Compiling Programs::
-* Configuration and Conditional Compilation::
-@end menu
-@node Compiling Programs, Libraries, Dependency Tracking, OMK User's Manual
+
+@anchor{V}
+@defvar V
+If this variable equals to @samp{1}, the whole command lines for all
+executed commands are displayed. When not set or zero, only short
+messages are printed. Value of @samp{2} displays the whole command lines
+as with @samp{1} and in addition directory navigation messages are
+printed.
+@end defvar
+
+@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
@noindent The variables are:
+@anchor{bin_PROGRAMS}
@defvar bin_PROGRAMS
Contains a list of names (whitespace separated) of programs to be
compiled in this directory.
@end defvar
-@defvar @var{program name}_SOURCES
- For every program name in @code{bin_PROGRAMS}, this variable contains
- a list of sources that are needed to compile the executable. OMK uses
- an extension of the filename to determine the compiler to compile this
+@defvar test_PROGRAMS
+ Almost the same as @ref{bin_PROGRAMS}, but resulting binaries are
+ stored in @file{bin-tests} directory instead of @file{bin}. This
+ variable is intended for various test programs not to be mixed with
+ the final product.
+@end defvar
+
+@defvar utils_PROGRAMS
+ Almost the same as @ref{bin_PROGRAMS}, but resulting binaries are
+ stored in @file{bin-utils} directory instead of @file{bin}. This
+ variable is intended for various development utilities not to be mixed
+ with the final product.
+@end defvar
+
+@defvar xxx_SOURCES
+ For every program name @var{xxx} in @code{bin_PROGRAMS},
+ @code{test_PROGRAMS} or @code{utils_PROGRAMS}, this variable contains
+ a list of sources that are needed to compile the program. OMK uses an
+ extension of the filename to determine the compiler to compile this
source.
@end defvar
-@defvar @var{program name}_LIBS
- This variable contains a list of libraries the program @var{program
- name} will be linked with.
+@defvar xxx_LIBS
+ This variable contains a list of libraries the program @var{xxx} will
+ be linked with.
@example
test_LIBS = m curses
@end example
@end defvar
+@defvar lib_LOADLIBES
+ This variable contains a list of libraries which needs to be linked to
+ to all programs or shared libraries in this directory.
+@end defvar
+
@defvar LOADLIBES
- This variable contains a list of libraries all programs in this
- directory needs to be linked to.
+ This variable contains a list linker switches to load additional
+ libraries. You usually specify here -L and -l switches.
+
+ Note: The value of this variable is not used used by OMK for any purpose
+ other than linker invocation. Therefore dependency handling of shared
+ libraries does not work if the library is specified in LOADLIBES
+ instead of lib_LOADLIBES.
@end defvar
@defvar INCLUDES
In @file{Makefile.omk}, you specify several variables, which defines how
the libraries should be compiled. In the example below the library
-@samp{mylib} is created from two sources @file{funca.c} and
-@file{funcb.c}. Interface of this library is defined in
-@file{myfunc.h}. Therfore, we export this header for use by other
-programs.
+@samp{mylib} (full filename will be @file{libmylib.a}) is created from
+two sources @file{funca.c} and @file{funcb.c}. Interface of this library
+is defined in @file{myfunc.h}. Therefore, we export this header for use
+by other programs.
@example
@verbatiminclude ../tests/libraries/Makefile.omk
@noindent Variables for use with libraries are:
@defvar lib_LIBRARIES
- Specifies a list of statically linked libraries to be compiled.
+ Specifies a list of statically linked libraries to be compiled. OMK
+ automatically prepends @code{lib} prefix library names.
@end defvar
@defvar shared_LIBRARIES
Specifies a list of dynamically linked libraries to be compiled.
@end defvar
-@defvar @var{library name}_SOURCES
- For every library name in @code{lib_LIBRARIES} or
+@defvar xxx_SOURCES
+ For every library name @var{xxx} in @code{lib_LIBRARIES} or
@code{shared_LIBRARIES}, this variable contains a list of sources that
are needed to compile the library. OMK uses an extension of the
filename to determine the compiler to compile this source.
@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 example
@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.
-
+@defvar LN_HEADERS
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}.
+@anchor{SUBDIRS}
@defvar SUBDIRS
This variable contains a list of directories, in which compilation
must be also invoked. Usually, names of subdirectories are used, but
Compilation is invoked in these directories before it is invoked in
the current directory.
+
+ See also @ref{AUTOMATIC_SUBDIRS}.
@end defvar
@c TODO: Write tests for this.
+@anchor{ALL_OMK_SUBDIRS}
@defvar ALL_OMK_SUBDIRS
This variable is set by OMK and can be used as the value of
@code{SUBDIRS} variable. It contains a list of all direct
@end example
@end defvar
-@node Configuration and Conditional Compilation, Running OMK under Windows OS, Multiple Directories, OMK User's Manual
+@anchor{AUTOMATIC_SUBDIRS}
+@defvar AUTOMATIC_SUBDIRS
+ If this variable is set to @samp{y} and @code{SUBDIRS} is not assigned
+ in @file{Makefile.omk}, then @code{SUBDIRS} is assigned a default
+ value @code{$(ALL_OMK_SUBDIRS)}.
+@end defvar
+
+@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
+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
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.
+
+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
-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
+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}.
+parameters either locally for your build in @file{config.omk} or
+globally for all people working with the project in
+@file{config.target}.
-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.
+@menu
+* Specifying Configuration Parameters::
+* Using Configuration Parameters::
+* Common Variables::
+@end menu
+@node Specifying Configuration Parameters, Using Configuration Parameters, Configuration and Conditional Compilation, Configuration and Conditional Compilation
@subsection Specifying Configuration Parameters
To specify names and default values of configuration parameters use the
@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}
@verbatiminclude ../tests/config/default/config.omk-correct
@end example
+@node Using Configuration Parameters, Common Variables, Specifying Configuration Parameters, Configuration and Conditional Compilation
@subsection Using Configuration Parameters
Configuration parameters can be used in two ways:
@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
+@defvar xxx_DEFINES
This variable determines the configuration parameters that should be
stored in a header file specified by
@code{config_include_HEADERS}. The @var{xxx} in the name of this
possible to include configuration parameters defined in a different
directory.
+@node Common Variables, , Using Configuration Parameters, Configuration and Conditional Compilation
@subsection Common Variables
-It is common practice to use @file{config.omk} to store project-wide
-settings. Here is the list of variables, which are commonly set here
-(but they can also be set elsewhere, e.g. in @file{Makefile.omk}).
+It is common practice to use @file{config.target} or @file{config.omk}
+to store project-wide settings. Here is the list of variables, which are
+commonly set here (but they can also be set elsewhere, e.g. in
+@file{Makefile.omk}).
You can easily ``reconfigure'' your project by changing the
@file{config.omk} file. It is useful to have several configurations
Additional parameters (besides @code{CFLAGS}) to by passed to C++
compiler.
@end vtable
+
+@node Advanced OMK Features, Properties of Specific Makefile.rules, 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.
+
+@menu
+* Organization of the Source Tree::
+* Additional Variables::
+* Adding Hooks to Passes::
+@end menu
+
+@node Organization of the Source Tree, Additional Variables, Advanced OMK Features, Advanced OMK Features
+@subsection Organization of the Source Tree
+
+@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 the 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 Additional Variables, Adding Hooks to Passes, Organization of the Source Tree, Advanced OMK Features
+@subsection Additional Variables
+
+@anchor{USE_LEAF_MAKEFILES}
+@defvar USE_LEAF_MAKEFILES
+If this variable equals to @samp{n} (default is unset), then OMK uses
+the leaf @file{Makefile} only when it is invoked by simple
+@command{make} command. Later, during recursive directory descent leaf
+@file{Makefile} is not used and @file{Makefile.rules} is included
+directly.
+
+This feature is useful if you are integrating some non-OMK project into
+your project. You only add @file{Makefile.omk} files to the non-OMK
+project and don't need to modify project's original Makefiles.
+
+This variable can be set either globally in a @file{config.*} file or
+locally in some @file{Makefile.omk}. In the latter case, it influences
+only subdirectories of the directory containing @file{Makefile.omk}.
+@end defvar
+
+@anchor{SOURCES_DIR}
+@defvar{SOURCES_DIR}
+This variable is set internally by OMK and its value is the absolute
+path to the directory with compiled sources. It can be used if you need
+to refer to sources files in some custom constructs in
+@file{Makefile.omk}.
+@example
+@verbatim
+include_HEADERS = $(notdir $(wildcard $(SOURCES_DIR)/*.h))
+@end verbatim
+@end example
+@end defvar
+
+@defvar{srcdir}
+The same as @ref{SOURCES_DIR}. Provided for Automake compatibility.
+@end defvar
+
+@defvar{MAKERULES_DIR}
+This variable is set internally by OMK and its value is the absolute
+path to the directory containing @file{Makefile.rules} currently used
+during compilation.
+@end defvar
+
+@defvar{OMK_RULES_TYPE}
+Identification the type of @file{Makefile.rules} used for
+compilation. Values are like @samp{linux}, @samp{rtems}, @samp{sysless},
+... This variable is automatically generated during creation of
+@file{Makefile.rules} and can be used in configuration files (see
+@ref{Configuration and Conditional Compilation}) or in
+@file{Makefile.omk} to tweak compilation for specific targets.
+@end defvar
+
+@node Adding Hooks to Passes, , Additional Variables, Advanced OMK Features
+@subsection Adding Hooks to Passes
+
+Sometimes it is necessary to run some special commands as a part of
+compilation. Typical example might be a tool which generates source
+files on the fly. OMK supports calling additional commands during
+compilation by so called @emph{pass hooks}. A pass hook is an ordinary
+make target which is invoked as part of compilation during a particular
+pass (see @ref{passes}). Pass hooks can be defined by assigning their
+names to @code{xxx_HOOKS} variable.
+
+@defvar{xxx_HOOKS}
+Specifies one or more hooks (make targets) which are invoked during pass
+@var{xxx}. The working directory of commands or this target is under the
+@file{_build} tree.
+
+In the example bellow header file @file{generated_header.h} is created
+during @samp{include-pass} by @file{convert_data} program. The program
+takes @file{data_file.txt} in the source directory as the input and
+creates the header file in the in the correct directory under the
+@file{_build} tree.
+
+@example
+include-pass_HOOKS = generated_header.h
+
+generated_header.h: $(SOURCES_DIR)/data_file.txt
+ convert_data < $^ > $@@
+@end example
+@end defvar
+
+@node Properties of Specific Makefile.rules, Running OMK under Windows OS, Advanced OMK Features, OMK User's Manual
+@section Properties of Specific Makefile.rules
+
+In previous sections, general properties of @file{Makefile.rules} were
+documented. This section contains documentation to features found only
+in some particular @file{Makefile.rules}.
+
+@menu
+* Linux::
+* System-Less::
+* RTEMS::
+@end menu
+
+@node Linux, System-Less, Properties of Specific Makefile.rules, Properties of Specific Makefile.rules
+@subsection Linux
+
+This @file{Makefile.rules} is used not only for Linux as the name
+suggests, but also for other Unices and even for Windows.
+
+@defvar BUILD_OS
+ The name of the operating system (OS) where make was invoked.
+@end defvar
+
+@defvar TARGET_OS
+ Should specify the name of OS where the resulting binary should be
+ used. If not specified manually, it equals to BUILD_OS.
+@end defvar
+
+@defvar QT_SUBDIRS
+ Lists subdirectories with QT project (.pro) file. OMK will generate
+ there @file{Makefile} by calling @command{qmake} with correct
+ parameters to interface QT application to the rest of the compilation
+ tree. Then @command{make} is called there to compile QT
+ application. Variable @samp{QTDIR} must be set to the directory with
+ QT installation (e.g. /usr/share/qt4 on Debian).
+@end defvar
+
+
+@node System-Less, RTEMS, Linux, Properties of Specific Makefile.rules
+@subsection System-Less
+
+This @file{Makefile.rules} is designed for compilation of code for
+(small) micro-controllers without operating systems. See
+@uref{http://rtime.felk.cvut.cz/hw/index.php/System-Less_Framework} for
+more information about our framework, which uses this rules.
+
+@node RTEMS, , System-Less, Properties of Specific Makefile.rules
+@subsection RTEMS
+
+TODO
-@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, Properties of Specific Makefile.rules, OMK User's Manual
@section Running OMK under Windows OS
+It is possible to use OMK under Windows OS with MinGW (see
+@uref{http://www.mingw.org/}). Unfortunately, the compilation speed is
+much lower than on UNIX systems.
+
+TODO: Is it necessary to install anything special?
+
@node Interfacing OMK to popular IDEs, Troubleshooting, Running OMK under Windows OS, OMK User's Manual
@section Interfacing OMK to popular IDEs
+@menu
+* KDevelop::
+* Eclipse/CDT::
+* Emacs/Vim/etc.::
+@end menu
+
+@node KDevelop, Eclipse/CDT, Interfacing OMK to popular IDEs, Interfacing OMK to popular IDEs
@subsection KDevelop
KDevelop has support for custom build systems. To use KDevelop to
@end example
@end enumerate
-
-@subsection Eclipse
-
+@node Eclipse/CDT, Emacs/Vim/etc., KDevelop, Interfacing OMK to popular IDEs
+@subsection Eclipse/CDT
+TODO
+@node Emacs/Vim/etc., , Eclipse/CDT, Interfacing OMK to popular IDEs
@subsection Emacs, VIM, etc.
Since OMK compilation is started by executing @command{make} command,
@node Troubleshooting, , Interfacing OMK to popular IDEs, OMK User's Manual
@section Troubleshooting
-Renaming of some file => dependency problems.
+@itemize
+@item
+ If you rename some file or directory and then you can't compile your
+ project, call @command{make clean} in the directory with errors. The
+ reason for this behavior is that OMK remembers dependencies of every
+ file. After renaming something, the original name is still stored in
+ dependencies, but make doesn't know how to create this non-existent
+ source.
-Manual compilation ... V=1
+@item
+ Sometimes, you may want to compile one file the same way as OMK does
+ it, but run the compilation manually from command line. For example,
+ you want to debug some preprocessor macros and you only want to
+ produce preprocessed source instead of an object file.
+
+ To compile something manually, you can run OMK by @command{make
+ V=2}. This will print all commands executed together with directory
+ navigation messages. Find the command you want to execute manually in
+ the output. To run it, you need to change the working directory to the
+ correct one in the @file{_build} tree. The correct directory can be
+ found in make output on the line @samp{Entering directory} preceding
+ the desired command.
+
+@item
+ Currently, C++ sources are supposed to have @file{.cc} or @file{.cxx}
+ extensions. The @file{.cpp} extension is not supported (yet).
+@end itemize
@node Original README, OMK Development, OMK User's Manual, Top
@chapter Original README
@item
Make system should allow to freely move cross-dependant components in
directory structure without need to update users of moved component (I
-hate somethink like @option{-I../../sched/rtlshwq/include} in CAN makefiles for
+hate something like @option{-I../../sched/rtlshwq/include} in CAN makefiles for
example. If a component is renamed or version is added to then name,
all Makefiles in CAN will require update).
@item
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 zkontrolovat, 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
I have put together package similar to release. Only ./configure --prefix=...
and make is required. CVS sources contains version 3.81beta1.
You can download prepared sources archive from
- @indicateurl{http://paulandlesley.org/make/make-3.81beta1.tar.bz2}
+ @uref{http://paulandlesley.org/make/make-3.81beta1.tar.bz2}
Or you can get our local copy from
- @indicateurl{http://cmp.felk.cvut.cz/~pisa/can/make-3.81beta1.tar.gz}
+ @uref{http://cmp.felk.cvut.cz/~pisa/can/make-3.81beta1.tar.gz}
The archive contains even "make" binary build by me, which should work
on other Linux distributions as well. Older version of MAKE (3.79.x
The local CTU archive with our CAN components prepared for inclusion
into OCERA SF CVS could be found in my "can" directory
- @indicateurl{http://cmp.felk.cvut.cz/~pisa/can/ocera-can-031212.tar.gz}
+ @uref{http://cmp.felk.cvut.cz/~pisa/can/ocera-can-031212.tar.gz}
The code should build for user-space with new make on most of Linux distros
when make is updated.
@node OMK Development, Variable Index, Original README, Top
@chapter OMK Development
+This section is far from complete. Its purpose is to document internals
+of @file{Makefile.rules} as well as other things needed only by people
+who hack OMK itself.
+@section Passes
+
+A pass is created by instantiation of @code{omk_pass_template} with
+@var{pass-name} as one of arguments. This defines several targets which
+are described here:
+
+@table @code
+@item @var{pass-name}
+Target used to invoke the individual pass either from command line or
+from inside of @file{Makefile.rules}.
+
+@item @var{pass-name}-submakes
+Invoked recursively from @var{pass-name}. The reason for this is the
+fact that
+
+@item @var{pass-name}-this-dir
+This target calls make recursively once again with @var{pass-name}-local
+target, which does the real-work. Make's working directory is set to the
+corresponding directory in @file{_build} tree and the -local
+
+@item @var{pass-name}-@var{dirname}-subdir
+This target is responsible for recursive invocation of @command{make} in
+subdirectories specified in @code{@ref{SUBDIRS}} variable.
+@end table
@node Variable Index, , OMK Development, Top
@unnumbered Variable Index
projects / omk.git / blobdiff