Released v0.2

[omk.git] / doc / omk-manual.texinfo

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename omk-manual
@documentencoding UTF-8
@settitle OMK: Ocera Make System
@c %**end of header

@copying
Manual for Ocera Make System (OMK) version $Id$

Copyright @copyright{} 2007, 2008, 2009 Michal Sojka, Pavel Pisa
@end copying

@titlepage
@title Ocera Make System Manual
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top, Overview of OMK, (dir), (dir)
@top Ocera Make System

@insertcopying
@end ifnottex


@menu
* Overview of OMK::             
* OMK User's Manual::           
* Original README::             
* OMK Development::             
* Variable Index::              
@end menu

@node Overview of OMK, OMK User's Manual, Top, Top
@chapter OMK Overview
@cindex overview

OMK is an advanced make system written entirely in GNU make. Compiling
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.

@c @section Features

@c @itemize
@c @item
@c Easy to use for beginners.
@c @item
@c Automatic handling of dependencies.
@c @item
@c Supported host platforms: all Un*x operating system including Linux,
@c Cygwin, MS DOS and maybe others.
@c @end itemize

@menu
* Why to Use OMK?::             
* Quick Start::                 
* History::                     
@end menu

@node Why to Use OMK?, Quick Start, Overview of OMK, Overview of OMK
@section Why to Use OMK?

Here we list some of OMK features, which we think are important for
choosing of a make system.


@itemize
@item
  Makefile in source directories are usually very @b{simple}.
@item
  There is only @b{one} @file{Makefile.rules} for most of components of
  a bigger project.
@item
  OMK greatly simplifies compilation of projects, where source files are
  spread between @b{multiple directories}.
@item
  OMK handles properly @b{dependencies} of source files and libraries,
  so it is not necessary to recompile the whole project if only several
  files changed.
@item
  OMK allows to freely @b{move} cross-dependant components @b{in
  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, 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
  simply creating symbolic links to external components.
@item
  Compilation of an OMK based projects don't require to install any
  files before successful finish of build.
@item
  OMK allows to call @command{make} for a particular subdirectory in the
  source tree.
@item
  Under OMK all products of compilation are stored @b{out of source
  directories}. This simplifies work with version control systems and
  helps when simultaneous compilation for multiple targets/platforms is
  needed.
@end itemize




@node Quick Start, History, Why to Use OMK?, Overview of OMK
@section Quick Start

If you get some sources, which are distributed with OMK, usually the
following commands are sufficient to compile the whole project.

@example
@verbatim
make default-config
make
@end verbatim
@end example

@noindent To use OMK in your own project, follow these steps:

@enumerate
@item
  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
  what to write in @file{Makefile.omk} files.
@item
  Run @command{make omkize} in the root directory.
@end enumerate

@noindent Your project is now ready to compile.


@node History,  , Quick Start, Overview of OMK
@section History

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
project. Several individual developers (mostly from Czech Technical
University) liked it and started to use it.

As a number of projects using OMK grew it was necessary to modularize
the make system to support more ``targets''. Michal Sojka took care
about the process of modularization.

@node OMK User's Manual, Original README, Overview of OMK, Top
@chapter OMK User's Manual

@menu
* Basic Concepts::              
* 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, 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
projects resides a file called @file{Makefile.rules}. This file contains
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 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@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.

@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
task in every directory of the project. Typically, these passes are:
@table @dfn
@anchor{include-pass}
@item include-pass
    This pass takes all include files marked for ``export'' and copies
    (or links) them to the @file{include} directory under
    @file{_compiled} directory. @xref{Header Files}.

    Also, during this pass, automatically generated header file are
    generated according to the current
    configuration. @xref{Configuration and Conditional Compilation}.
@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 file-system
(it contains directories like @file{bin}, @file{lib} and @file{include})
and can be directly copied to the target device or to some directory on
a host computer (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.).

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.

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}}.

@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.



@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
@file{Makefile.omk} (usually) in the directory where program sources are
located.

In the example bellow a program @command{test} will be compiled from
source @file{test.c}.

@example
@verbatiminclude ../tests/programs/Makefile.omk
@end example

@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 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 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 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
  Directives passed to the C or C++ compiler with additional directories
  to be searched for header files. In most cases you need to specify an
  absolute path. To specify a directory relative to the source
  directory, you can use the @code{$(SOURCES_DIR)} variable, which
  refers to the directory, where @file{Makefile.omk} is located. This
  variable applies to all compilations invoked in the current directory.

  @example
  INCLUDES = -I$(SOURCES_DIR)/my_include_dir
  @end example
@end defvar

@defvar DEFS
  Directives passed to the C or C++ compiler with preprocessor macro
  definitions. This variable applies to all compilations invoked in the
  current directory.

  @example
  DEFS = -DDEBUG=1
  @end example
@end defvar


@c FIXME: INCLUDES variable should not be set by rtlinux rules.

@node Libraries, Multiple Directories, Compiling Programs, OMK User's Manual
@section Libraries


With OMK, you can easily create statically or dynamically linked
libraries. The way of creating libraries is very similar to how programs
are created. @xref{Compiling Programs}.

In @file{Makefile.omk}, you specify several variables, which defines how
the libraries should be compiled. In the example below the library
@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
@end example

@noindent Variables for use with libraries are:

@defvar lib_LIBRARIES
  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 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.
@end defvar

@menu
* Header Files::                
@end menu

@node Header Files,  , Libraries, Libraries
@subsection Header Files

C and C++ libraries are not very useful without header files. OMK
provides several variables that specify activities on header files.

During compilation, header files are copied (or linked) from source
directories to the @file{_compiled} tree
(see @ref{include-pass}). Libraries and programs are then compiled against
these copies.

@anchor{include_HEADERS}
@defvar include_HEADERS
  Specifies the list of header files to be exported for use by other
  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
  @end example
@end defvar

@defvar nobase_include_HEADERS
  Similar to @ref{include_HEADERS}, but the directory prefix is always
  kept. To include the file exported by this variable, use
  @code{#include <@var{prefix}/@var{header.h}>}.
@end defvar

@defvar renamed_include_HEADERS
  Exports the header files under different name. The form of the items
  in this whitespace separated list is: @var{real name}@code{->}@var{new
  name}.

@example 
  renamed_include_HEADERS = orte_config_omk_win32.h->orte_config.h
@end example
@end defvar

@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, 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 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
  you can use any path specification here.

  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
  subdirectories, which contain @file{Makefile.omk}. This is especially
  useful if you are combining several projects or components
  together. In the root directory of your project, you just create
  symbolic links the components from other projects and all the linked
  directories automatically appears as the value of this variable.

  @example
  SUBDIRS = $(ALL_OMK_SUBDIRS)
  @end example
@end defvar

@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 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
parameters to @command{configure}, which is run before compilation, and
this script does all steps needed to configure the sources and
make-system in the desired way.

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 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

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 either locally for your build in @file{config.omk} or
globally for all people working with the project in
@file{config.target}.

@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
@code{default_CONFIG} variable in @file{Makefile.omk}.

@defvar default_CONFIG
  This variable contains a list of configuration parameters and their
  default values. The format of every item in this list is
  @var{CONFIG_xxxx}=@var{value}. You can name the parameter as you want,
  but it is good practice to start the name with @samp{CONFIG_} prefix.
   
  OMK can automatically generate header files, with C preprocessor macro
  definitions according to the OMK's configuration parameters. The
  actual content of generated header files depends on the form of the
  @var{value}. The possible forms are:
  
@table @code 
@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{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}
  Text without quotes. The define looks like @samp{#define CONFIG_@var{xxx} @var{text}}
@item @samp{"text"}
  Text with quotes. The define looks like @samp{#define CONFIG_@var{xxx} "@var{text}"}
@end table
@end defvar

@noindent Example of using @code{default_CONFIG}. @file{Makefile.omk} reads like:
@example
@verbatiminclude ../tests/config/default/Makefile.omk
@end example
@noindent and @file{subdir/Makefile.omk} like:
@example
@verbatiminclude ../tests/config/default/subdir/Makefile.omk
@end example

@noindent After running @command{make default-config}, the content of
@file{config.omk-default} will be:
@example
@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:
@enumerate
@item
  as variables in @file{Makefile.omk} and
@item
  as C/C++ preprocessor macros in OMK generated header files.
@end enumerate

@noindent For the first use, your @file{Makefile.omk} may contain something like:
@example
SUBDIRS = arch/$(CONFIG_ARCH)

ifeq ($(CONFIG_DEBUG),y)
DEFS += -DUSE_SIMULATOR
endif
@end example

@noindent For the second use, there are several variables that control
the generation of header files with configuration values. These
variables are described here:

@anchor{LOCAL_CONFIG_H}
@defvar LOCAL_CONFIG_H
  The value of this variable is the name of a header file, which will
  contain all configuration parameters declared in the current directory
  by @code{default_CONFIG}. This header file is accessible only by files
  in the current directory and it should be included like @code{#include
  "@var{myconfig.h}"}.

  In @file{Makefile.omk}, the use of this variable can look like this:

@example
LOCAL_CONFIG_H = myconfig.h
@end example
@end defvar

@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 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 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
  variable needs to be the same as the base name (without extension) of
  the header file.
@end defvar

@noindent Example of using @code{config_include_HEADERS}:
@example
default_CONFIG = CONFIG_LINCAN=y CONFIG_LINCANRTL=n CONFIG_LINCANVME=n
config_include_HEADERS = global.h
global_DEFINES = CONFIG_OC_LINCAN CONFIG_OC_LINCANRTL 
@end example

@noindent Here, we include only two out of the three configuration 
parameters defined in the current @file{Makefile.omk}. It is also
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.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
stored in different files and let @file{config.omk} be a symbolic link
to the desired configuration.

@vtable @code
@item CC
  The name of C compiler.
@item CFLAGS
  Command line options for C compiler.
@item CXX
  The name of C++ compiler.
@item CPPFLAGS
  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, 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
develop projects using OMK follow these steps. These steps are valid for
version 3.5.0 of KDevelop, but for previous versions it doesn't differ
much.

@enumerate
@item
  Import project to KDevelop (from menu choose @emph{Project---Import
  existing project}). Select the type of project to @emph{Generic C
  Application (Custom Buildsystem)}.
@example
  @image{kdevelop1}
@end example

@item
  Then answer to following dialogs as you want.
@example
  @image{kdevelop2}
@end example
@example
  @image{kdevelop3} @image{kdevelop4}
@end example

@item
  If you are working only on some small part of the bigger project, you
  usually don't want to recompile the whole project every time. In
  @emph{Project---Project Options}, you can specify the subdirectory where to
  run @command{make}.
@example
  @image{kdevelop5}
@end example

@item
  If you want to switch between several configurations easily (see also
  @ref{Configuration and Conditional Compilation}), in the same dialog
  you can add @option{-e} to make options. This makes environment variables
  have higher precedence than those in @file{config.omk-default}. Then,
  you can define several environments with different
  @code{CONFIG_@var{xxx}} variables and their values.
@example
  @image{kdevelop6}
@end example

@item
  You can easily switch the configurations from @emph{Build---Make
  Environment}.
@example
  @image{kdevelop7}
@end example
@end enumerate

@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,
many common editors can work easily with OMK.

Under Emacs, you can use @command{compile} or @command{recompile}
commands as you are used to do.

@node Troubleshooting,  , Interfacing OMK to popular IDEs, OMK User's Manual
@section Troubleshooting

@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.

@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

Since this manual still doesn't cover all aspects of OMK, we include
here a @file{README.rules} file, which was written for the first version
of OMK.

@b{Important notice:} This make system uses features found in recent
versions of GNU Make program. If you encounter problems with package
building, check, that you use correct version of Make program.  The
Make older than version 3.80, could not be used.  Even Make version
3.80 has annoying bug which causes building fail with misleading
message "virtual memory exhausted".  Please, upgrade at least to
version 3.81 of GNU Make.

There is list of features which we want to solve with our make system:
@itemize
@item
Central @file{Makefile.rules} for most of components of a bigger project.

FIXME (our CAN framework includes more libraries common with our other
projects, we need to separate some utility libraries etc.)
@item
The rules in more spread Makefiles are way to the hell (update for
different kernel, RT-Linux etc would be nightmare in other case).
@item
Make system should allow to freely move cross-dependant components in
directory structure without need to update users of moved component (I
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
Make system should be able to compile mutually cross-dependant
libraries and should ensure, that change in one component sources or
headers would result in relink or rebuild in components linked against
that library or including modified header file.
@item
Make system has to enable compilation out of OCERA full source tree
(we would lost many users of particular components in other case).
@item
Compile should be able to do all above work without need to install
any files before successful finish of build.
@item
Because we use some libraries for RT-Linux build and user-space build,
we need to solve how to compile from same sources to both targets.
@item
The build system should allow to call make for particular source
subdirectory. Time of recursive make through all subdirectories is
unacceptable.
@item
Make system should enable to build out of sources tree (else clean or
working with CVS sandbox gets fussy and simultaneous multiple targets
gets problematic).
@item
It would be good, if there is a possibility to call make from
read-only media sources.
@item
Make system should store results of build in some separate directory
structure to simple install and testing.
@item
Makefiles in sources directories should be simple.
@end itemize

There is probably only one alternative fully supporting above requirements
and it is GNU Autoheader...Automake...Autoconf... system.
But it is complicated and requires big amount of support files.
It would be acceptable if it could be easily used for OCERA framework.
But there are important show stoppers for that system:
@itemize
@item
It would require deep revision of all OCERA CVS contents and agreement
on this would be problematic
@item
This system is not well prepared for dual compilation for Linux and
RT-Linux sub-targets. It would mean many changes in default autoconf
setup to support this. Probably simplest way would be to rebuild GCC
tool chain for something like i586-elf-rtlinux.  This would require
even more space for OCERA development.
@end itemize

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.

There is result of our trial. It is OMK make system.
The @file{Makefile} and @file{Makefile.omk} files should be in all source
directories. Common @file{Makefile.rules} file is required in the toplevel
sources directory. Alternatively this file could be moved
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

Makefile.omk user defined variables
@vtable @code
@item SUBDIRS
list of subdirectories intended for make from actual directory
@item lib_LIBRARIES
list of the user-space libraries
@item shared_LIBRARIES
list of the user-space shared libraries
@item kernel_LIBRARIES
list of the kernel-space libraries
@item rtlinux_LIBRARIES
list of the RT-Linux kernel-space libraries
@item include_HEADERS  
list of the user-space header files
@item nobase_include_HEADERS 
headers copied even with directory part
@item kernel_HEADERS   
list of the kernel-space  header files
@item rtlinux_HEADERS  
list of the RT-Linux kernel-space  header files
@item bin_PROGRAMS     
list of the require binary programs
@item utils_PROGRAMS   
list of the development utility programs
@item kernel_MODULES   
list of the kernel side modules/applications
@item rtlinux_MODULES  
list of RT-Linux the kernel side modules/applications
@item xxx_SOURCES      
list of specific target sources
@item INCLUDES         
additional include directories and defines for user-space
@item kernel_INCLUDES  
additional include directories and defines for kernel-space
@item rtlinux_INCLUDES 
additional include directories and defines for RT-Linux
@item default_CONFIG   
list of default config assignments CONFIG_XXX=y/n ...
@end vtable

The Makefile is same for all sources directories and is only 14 lines
long.  It is there only for convenience reasons to enable call "make"
from local directory. It contains code which locates
@file{Makefile.rules} in actual or any parent directory. With standard
BASH environment it works such way, that if you get into sources
directory over symbolic links, it is able to unwind yours steps back
=> you can make links to readonly media component directories, copy
@file{Makefile.rules}, Makefile and toplevel Makefile.omk, adjust
Makefile.omk to contain only required components and then call make in
top or even directories after crossing from your tree to readonly
media.

The system compiles all files out of source directories.  The actual
version of system is adapted even for OCERA tree mode if
@code{OCERA_DIR} variable is defined in @file{Makefile.rules}

There are next predefined directory name components, which can be
adapted if required

@table @code
@item BUILD_DIR_NAME = _build
        prefix of directory, where temporary build files are stored
@item COMPILED_DIR_NAME = _compiled
        prefix of directory, where final compilation results are stored
@item GROUP_DIR_NAME = yyy
        this is used for separation of build sub-trees in OCERA environment
        where more @file{Makefile.rules} is spread in the tree
@end table

Next directories are used:

@table @code
@item KERN_BUILD_DIR   := $(MAKERULES_DIR)/$(BUILD_DIR_NAME)/kern
        directory to store intermediate files for kernel-space targets
@item USER_BUILD_DIR   := $(MAKERULES_DIR)/$(BUILD_DIR_NAME)/user
        directory to store intermediate files for user-space targets

@item USER_INCLUDE_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/include
        directory to store exported include files which should be installed later
        on user-space include path
@item USER_LIB_DIR     := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/lib
        same for user-pace libraries
@item USER_UTILS_DIR   := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/bin-utils
        utilities for testing, which would not probably be installed
@item USER_BIN_DIR     := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/bin
        binaries, which should go into directory on standard system PATH
        (/usr/local/bin, /usr/bin or $(prefix)/bin)

@item KERN_INCLUDE_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/include-kern
        directory to store exported include files which should be installed later
        on kernel-space include path
@item KERN_LIB_DIR     := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/lib-kern
        same for kernel-pace libraries
@item KERN_MODULES_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/modules
        builded modules for Linux kernel or RT-Linux system
@end table

There is more recursive passes through directories to enable
mutual dependant libraries and binaries to compile.
Next passes are defined

@table @samp
@item default-config
generates @file{config.omk-default} or xxx-default (FIXME) configuration file
@item check-dir 
checks and creates required build directories
@item include-pass   
copies header files to @code{USER_INCLUDE_DIR} and @code{KERN_INCLUDE_DIR}
@item library-pass
builds objects in USER_BUILD_DIR/@var{relative path} and creates libraries
in USER_LIB_DIR
@item binary-pass and utils-pass
links respective binaries in USER_@{BIN,UTILS@}_DIR directory. If some
object file is missing it compiles it in USER_BUILD_DIR/@var{relative path}
@item kernel-lib-pass
builds libraries for kernel space targets
@item kernel-pass 
builds kernel modules
@end table

The amount of passes is relatively high and consumes some time.  But
only other way to support all required features is to assemble one big
toplevel Makefile, which would contain all components and targets
cross-dependencies.

Drawbacks of designed make system
@itemize
@item
the system is not as fast as we would like
@item
it lacks Autoconf and configure extensive support for many systems
from UNIX to DOS and WINDOWS
@item
it does not contain support for checking existence of target
libraries and functionalities as GNU Autoconf
@item
it is heavily dependant on GNU MAKE program. But it would not be big
problem, because even many commercial applications distribute GNU MAKE
with them to be able to work in non-friendly systems
@item
the key drawback is dependence on recent MAKE version 3.80 and better
and even version 3.80 of MAKE has important bug, which has been
corrected in newer sources (FIXME)
@end itemize

The last point is critical. I have not noticed it first, because
I use Slackware-9.2 and it contains latest released version 
of MAKE (version 3.80).
The problem appears when I have tried to build bigger libraries.
There is bug in version 3.80, which results in misleading
error "Virtual memory exhausted". It is known bug with ID 1517

@smallexample
* long prerequisite inside eval(call()) => vm exhausted, Paul D. Smith
@end smallexample


I have optimized some rules to not push memory to the edge,
but there could be still issues with 3.80 version.

I have downloaded latest MAKE CVS sources. The compilation required
separate lookup and download for .po files and full Autoheader... cycle.
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
  @uref{http://paulandlesley.org/make/make-3.81beta1.tar.bz2}
Or you can get our local copy from
  @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
released about year 2000) found on Mandrake and RedHat are not
sufficient and do not support eval feature.  I do not expect, that
Debian would be more up-to-date or contain fixes to MAKE vm exhausted
bug.

The local CTU archive with our CAN components prepared for inclusion
into OCERA SF CVS could be found in my "can" directory

  @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.

If you want to test compile for RT-Linux targets, line

@example
#RTL_DIR := /home/cvs/ocera/ocera-build/kernel/rtlinux
@end example

in @file{Makefile.rules} has to be activated and updated
to point RT-Linux directory containing "rtl.mk".
There is only one library ("ulutrtl") and test utility compiled for RT-Linux
(@file{can/utils/ulut/ul_rtlchk.c}).

The next line, if enabled, controls compilation in OCERA project tree

@example
#OCERA_DIR := $(shell ( cd -L $(MAKERULES_DIR)/../../.. ; pwd -L ) )
@end example

The LinCAN driver has been updated to compile out of source directories.

Please, check, if you could compile CAN package and help us with integration
into OCERA SF CVS. Send your comments and objections. 

The OMK system has been adapted to support actual OCERA configuration process.
I am not happy with ocera.mk mix of defines and poor two or three rules,
but OMK is able to overcome that.

The OMK system has integrated rules (default-config) to build default
configuration file. The file is named @file{config.omk-default} for
the stand-alone compilation.  The name corresponds to OCERA config +
"-default" if OCERA_DIR is defined.  This file contains statements
from all @code{default_CONFIG} lines in all @file{Makefile.omk}.  The
file should be used for building of own @file{config.omk} file, or as
list for all options if Kconfig is used.

@c @chapter OMK Reference

@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

@printindex vr

@c @node Concept Index,  , Variable Index, Top
@c @unnumbered Concept Index
@c @printindex cp

@bye