@c %**end of header
@copying
-Manual for Ocera Make System (OMK) version @include .version
+Manual for Ocera Make System (OMK) version
+@include .version
-Copyright @copyright{} 2007, 2008, 2009, 2010, 2011 Michal Sojka, Pavel Pisa
+Copyright @copyright{} 2007, 2008, 2009, 2010, 2011, 2013 Michal Sojka, Pavel Pisa
@end copying
@titlepage
@menu
-* Overview::
-* User's Manual::
-* Original README::
-* Development::
-* Variable Index::
+* Overview::
+* User's Manual::
+* Original README::
+* Development::
+* Variable Index::
@end menu
@node Overview, User's Manual, Top, Top
@c @end itemize
@menu
-* Why to Use OMK?::
-* Quick Start::
-* History::
+* Why to Use OMK?::
+* Quick Start::
+* History::
@end menu
@node Why to Use OMK?, Quick Start, Overview, Overview
@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}
+ 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
@chapter User's Manual
@menu
-* Basic Concepts::
-* Invoking OMK::
-* Compiling Programs::
-* Compiling Libraries::
-* Recursing into Subdirectories::
-* 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::
+* Basic Concepts::
+* Invoking OMK::
+* Compiling Programs::
+* Compiling Libraries::
+* Compiler Flags::
+* Recursing into Subdirectories::
+* 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, User's Manual, 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.
+The main concept of OMK is very simple. In the heart of OMK are two
+files @file{Makefile.rules} and @file{Makefile.omk}. The former one
+resides in project root directory and contains all compilation rules
+needed for compilation of the particular project. There are different
+@file{Makefile.rules} for different platforms (Unix, RTEMS, system-less,
+...). @file{Makefile.omk} is stored in every (sub)directory and
+describes what should @command{make} perform in that directory (e.g.
+compile a program from several source files). It uses declarative syntax
+(assign values to variables) similar to Automake files
+@file{Makefile.am}. The content of @file{Makefile.omk} is described in
+the following sections.
+
+Since @command{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.
@file{Makefile.omk} (usually) in the directory where program sources are
located.
-In the example bellow a program @command{test} will be compiled from
+In the example bellow program @command{test} will be compiled from
source @file{test.c}.
@example
-@verbatiminclude ../tests/programs/Makefile.omk
+@verbatiminclude tests/programs/compile-a-single-source-c-program/Makefile.omk
@end example
@noindent The variables are:
@end example
@end defvar
+@defvar xxx_CFLAGS
+ CFLAGS specific for the compiler program. If this variable is set, its
+ value efectively overrides the value of AM_CFLAGS variable.
+@end defvar
+
+@defvar xxx_CXXFLAGS
+ CXXFLAGS specific for the compiler program. If this variable is set, its
+ value efectively overrides the value of AM_CXXFLAGS variable.
+@end defvar
+
+@defvar xxx_CPPFLAGS
+ CPPFLAGS specific for the compiler program. If this variable is set, its
+ value efectively overrides the value of AM_CPPFLAGS variable.
+@end defvar
+
+@defvar xxx_GEN_SOURCES
+ Program sources generated (by other rules) in the build directory. See
+ the following example.
+ @verbatiminclude tests/programs/generated-sources/Makefile.omk
+
+@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.
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 Compiling Libraries, Recursing into Subdirectories, Compiling Programs, User's Manual
+@node Compiling Libraries, Compiler Flags, Compiling Programs, User's Manual
@section Compiling Libraries
by other programs.
@example
-@verbatiminclude ../tests/libraries/Makefile.omk
+@verbatiminclude tests/libraries/static-library/Makefile.omk
@end example
@noindent Variables for use with libraries are:
@end defvar
@defvar shared_LIBRARIES
- Specifies a list of dynamically linked libraries to be compiled.
+ Specifies a list of dynamically linked libraries to be compiled.
@end defvar
@defvar xxx_SOURCES
@end defvar
@menu
-* Header Files::
+* Header Files::
@end menu
@node Header Files, , Compiling Libraries, Compiling Libraries
@subsection Header Files
C and C++ libraries are not very useful without header files. OMK
-provides several variables that controls operations with header files.
+provides several variables that control operations with header files.
During compilation, header files are copied (or linked by symbolic
links) from source directories to the @file{_compiled} tree (see
in this whitespace separated list is: @var{real name}@code{->}@var{new
name}.
-@example
+@example
renamed_include_HEADERS = orte_config_omk_win32.h->orte_config.h
@end example
@end defvar
@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.
+@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
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 Recursing into Subdirectories, Dependency Tracking, Compiling Libraries, User's Manual
+@node Compiler Flags, Recursing into Subdirectories, Compiling Libraries, User's Manual
+@section Compiler Flags
+
+OMK follows the same philosophy for flag variables as does Automake. The
+variables with AM_ prefix (e.g. AM_CPPFLAGS) are supposed to be used by
+the package developer and variable without that prefix (e.g. CPPFLAGS)
+are reserved for the user. The following
+
+@defvar AM_CPPFLAGS
+Preprocessor switches.
+@end defvar
+
+@defvar AM_CFLAGS
+C compiler switches.
+@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 Recursing into Subdirectories, Dependency Tracking, Compiler Flags, User's Manual
@section Recursing into Subdirectories
OMK is probably most useful in projects consisting of multiple
@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.
+ 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}.
@file{config.target}.
@menu
-* Specifying Configuration Parameters::
-* Using Configuration Parameters::
-* Common Variables::
+* 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
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
+
+@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{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
@noindent Example of using @code{default_CONFIG}. @file{Makefile.omk} reads like:
@example
-@verbatiminclude ../tests/config/default/Makefile.omk
+@verbatiminclude tests/default-config/Makefile.omk
@end example
@noindent and @file{subdir/Makefile.omk} like:
@example
-@verbatiminclude ../tests/config/default/subdir/Makefile.omk
+@verbatiminclude tests/default-config/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
+@verbatiminclude tests/default-config/config.omk-correct
@end example
@node Using Configuration Parameters, Common Variables, Specifying Configuration Parameters, Configuration and Conditional Compilation
@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
+global_DEFINES = CONFIG_OC_LINCAN CONFIG_OC_LINCANRTL
@end example
-@noindent Here, we include only two out of the three configuration
+@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.
or rarely used so they were omitted in previous sections.
@menu
-* Organization of the Source Tree::
-* Additional Variables::
-* Adding Hooks to Passes::
-* Integration of Wvtest Framework::
+* Organization of the Source Tree::
+* Additional Variables::
+* Adding Hooks to Passes::
+* Integration of Wvtest Framework::
@end menu
@node Organization of the Source Tree, Additional Variables, Advanced OMK Features, Advanced OMK Features
in some particular @file{Makefile.rules}.
@menu
-* Linux::
-* System-Less::
-* RTEMS::
+* Linux::
+* System-Less::
+* RTEMS::
@end menu
@node Linux, System-Less, Properties of Specific Makefile.rules, Properties of Specific Makefile.rules
@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.
+ used. If not specified manually, it equals to BUILD_OS.
@end defvar
@defvar QT_SUBDIRS
QT installation (e.g. /usr/share/qt4 on Debian).
@end defvar
+@defvar bin_SCRIPTS
+ Lists the names of the files (persumably scripts) to be copied to
+ @file{_compiled/bin}.
+@end defvar
+
+
@node System-Less, RTEMS, Linux, Properties of Specific Makefile.rules
@subsection System-Less
@subsection RTEMS
TODO
-
-
+
+
@node Running OMK under Windows OS, Interfacing OMK to popular IDEs, Properties of Specific Makefile.rules, User's Manual
@section Running OMK under Windows OS
@section Interfacing OMK to popular IDEs
@menu
-* KDevelop::
-* Eclipse/CDT::
-* Emacs/Vim/etc.::
+* KDevelop::
+* Eclipse/CDT::
+* Emacs/Vim/etc.::
@end menu
@node KDevelop, Eclipse/CDT, Interfacing OMK to popular IDEs, Interfacing OMK to popular IDEs
list of the kernel-space libraries
@item rtlinux_LIBRARIES
list of the RT-Linux kernel-space libraries
-@item include_HEADERS
+@item include_HEADERS
list of the user-space header files
-@item nobase_include_HEADERS
+@item nobase_include_HEADERS
headers copied even with directory part
-@item kernel_HEADERS
+@item kernel_HEADERS
list of the kernel-space header files
-@item rtlinux_HEADERS
+@item rtlinux_HEADERS
list of the RT-Linux kernel-space header files
-@item bin_PROGRAMS
+@item bin_PROGRAMS
list of the require binary programs
-@item utils_PROGRAMS
+@item utils_PROGRAMS
list of the development utility programs
-@item kernel_MODULES
+@item kernel_MODULES
list of the kernel side modules/applications
-@item rtlinux_MODULES
+@item rtlinux_MODULES
list of RT-Linux the kernel side modules/applications
-@item xxx_SOURCES
+@item xxx_SOURCES
list of specific target sources
-@item INCLUDES
+@item INCLUDES
additional include directories and defines for user-space
-@item kernel_INCLUDES
+@item kernel_INCLUDES
additional include directories and defines for kernel-space
-@item rtlinux_INCLUDES
+@item rtlinux_INCLUDES
additional include directories and defines for RT-Linux
-@item default_CONFIG
+@item default_CONFIG
list of default config assignments CONFIG_XXX=y/n ...
@end vtable
@table @samp
@item default-config
generates @file{config.omk-default} or xxx-default (FIXME) configuration file
-@item check-dir
+@item check-dir
checks and creates required build directories
-@item include-pass
+@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
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
+@item kernel-pass
builds kernel modules
@end table
@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
+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
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.
+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,
@item @var{pass-name}-submakes
Invoked recursively from @var{pass-name}. The reason for this is the
-fact that
+fact that
@item @var{pass-name}-this-dir
This target calls make recursively once again with @var{pass-name}-local
projects / omk.git / blobdiff