\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)
+Manual for Ocera Make System (OMK) version
+@include .version
-Copyright @copyright{} 2007 Michal Sojka, Pavel Pisa
+Copyright @copyright{} 2007, 2008, 2009, 2010, 2011, 2013 Michal Sojka, Pavel Pisa
@end copying
@titlepage
@contents
@ifnottex
-@node Top, Overview of OMK, (dir), (dir)
+@node Top, Overview, (dir), (dir)
@top Ocera Make System
@insertcopying
@menu
-* Overview of OMK::
-* OMK User's Manual::
-* Original README::
-* OMK Development::
-* Variable Index::
+* Overview::
+* User's Manual::
+* Original README::
+* Development::
+* Variable Index::
@end menu
-@node Overview of OMK, OMK User's Manual, Top, Top
-@chapter OMK Overview
+@node Overview, User's Manual, Top, Top
+@chapter Overview
@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.
@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 of OMK, Overview of OMK
+@node Why to Use OMK?, Quick Start, Overview, Overview
@section Why to Use OMK?
Here we list some of OMK features, which we think are important for
@end itemize
-@node Quick Start, History, Why to Use OMK?, Overview of OMK
+
+
+@node Quick Start, History, Why to Use OMK?, Overview
@section Quick Start
If you get some sources, which are distributed with OMK, usually the
@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
+ compile something. Please refer to @ref{User's Manual} to learn
what to write in @file{Makefile.omk} files.
@item
Run @command{make omkize} in the root directory.
@noindent Your project is now ready to compile.
-@node History, , Quick Start, Overview of OMK
+@node History, , Quick Start, Overview
@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
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
+@node User's Manual, Original README, Overview, Top
+@chapter 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::
+* 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, OMK User's Manual, OMK User's Manual
+@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 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.
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
+@node Invoking OMK, Compiling Programs, Basic Concepts, User's Manual
@section Invoking OMK
Before using OMK for the first time, you have to call:
printed.
@end defvar
-@node Compiling Programs, Libraries, Invoking OMK, OMK User's Manual
+@node Compiling Programs, Compiling Libraries, Invoking 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
+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:
compiled in this directory.
@end defvar
+@anchor{test_PROGRAMS}
@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
@end example
@end defvar
-@defvar LOADLIBES
- This variable contains a list of libraries all programs in this
- directory needs to be linked to.
+@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 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.
+@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
- @example
- INCLUDES = -I$(SOURCES_DIR)/my_include_dir
- @end example
+@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 DEFS
- Directives passed to the C or C++ compiler with preprocessor macro
- definitions. This variable applies to all compilations invoked in the
- current directory.
+@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
- @example
- DEFS = -DDEBUG=1
- @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
-@c FIXME: INCLUDES variable should not be set by rtlinux rules.
+@defvar LOADLIBES
+ This variable contains a list linker switches to load additional
+ libraries. You usually specify here -L and -l switches.
-@node Libraries, Multiple Directories, Compiling Programs, OMK User's Manual
-@section Libraries
+ 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
+
+@node Compiling Libraries, Compiler Flags, Compiling Programs, User's Manual
+@section Compiling Libraries
With OMK, you can easily create statically or dynamically linked
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}. Therfore, we export this header for use
+is defined in @file{myfunc.h}. Therefore, we export this header for use
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:
@defvar lib_LIBRARIES
Specifies a list of statically linked libraries to be compiled. OMK
- automaticvally prepends @code{lib} prefix library names.
+ automatically prepends @code{lib} prefix library names.
@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, , Libraries, Libraries
+@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 specify activities on header files.
+provides several variables that control operations with 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.
+During compilation, header files are copied (or linked by symbolic
+links) from source directories to the @file{_compiled} tree (see
+@ref{include-pass}). Libraries and programs are then compiled against
+these copies. The following variables control which headers are copied
+and what is their destination file name.
@anchor{include_HEADERS}
@defvar include_HEADERS
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 Multiple Directories, Dependency Tracking, Libraries, OMK User's Manual
-@section Multiple Directories
+@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
directories. For such projects, it is not easy to write from scratch
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 Dependency Tracking, Configuration and Conditional Compilation, 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, Recursing into Subdirectories, 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.
+OMK automatically tracks dependencies of files in the project.
+Dependencies of object files are produced with gcc's @option{-M@var{x}}
+options. This means that whenever a header file is changed, OMK
+recompiles only those files, which included that file.
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.
+causes relinking of all programs using that library.
-@node Configuration and Conditional Compilation, Advanced OMK Features, Dependency Tracking, OMK User's Manual
+@node Configuration and Conditional Compilation, Advanced OMK Features, Dependency Tracking, User's Manual
@section Configuration and Conditional Compilation
In many projects, it is necessary to configure the compilation process. By
@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.
@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
compiler.
@end vtable
-@node Advanced OMK Features, Properties of Specific Makefile.rules, Configuration and Conditional Compilation, OMK User's Manual
+@node Advanced OMK Features, Properties of Specific Makefile.rules, Configuration and Conditional Compilation, 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
-* Unsorted Advanced Features::
-* Adding Hooks to Passes::
+* Organization of the Source Tree::
+* Additional Variables::
+* Adding Hooks to Passes::
+* Integration of Wvtest Framework::
@end menu
-@node Unsorted Advanced Features, Adding Hooks to Passes, Advanced OMK Features, Advanced OMK Features
-@subsection Unsorted Advanced Features
+@node Organization of the Source Tree, Additional Variables, Advanced OMK Features, Advanced OMK Features
+@subsection Organization of the Source Tree
@itemize
@item
top-level @file{Makefile.omk}, adjust @file{Makefile.omk} to contain
only required components and then call @command{make} in the top
directory or even in read-only directories after changing working
- directory from your tree to readonly media.
+ directory from your tree to the readonly media.
@end itemize
(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
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 other
+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
@file{Makefile.omk} to tweak compilation for specific targets.
@end defvar
-@node Adding Hooks to Passes, , Unsorted Advanced Features, Advanced OMK Features
+@node Adding Hooks to Passes, Integration of Wvtest Framework, Additional Variables, Advanced OMK Features
@subsection Adding Hooks to Passes
Sometimes it is necessary to run some special commands as a part of
@end example
@end defvar
-@node Properties of Specific Makefile.rules, Running OMK under Windows OS, Advanced OMK Features, OMK User's Manual
+@node Integration of Wvtest Framework, , Adding Hooks to Passes, Advanced OMK Features
+@subsection Integration of Wvtest Framework
+
+OMK has integrated support for
+@uref{https://github.com/apenwarr/wvtest,Wvtest unit testing framework}.
+It is a very minimalistic framework whose integration with OMK does not
+impose almost any particular policy of writing the tests. Wvtest tests
+are specified by the following two variables:
+
+@defvar wvtest_PROGRAMS
+This variable has the same meaning as @ref{test_PROGRAMS} with two
+exceptions: (1) the program is automatically linked with the library
+specified by @code{WVTEST_LIBRARY} variable and (2) the program is
+automatically executed by @command{make wvtest} (see below).
+@end defvar
+
+@defvar wvtest_SCRIPTS
+Defines the name of a script (e.g. shell script) which is executed by
+@command{make wvtest}. Write the scripts so, that they can be run from
+arbitrary directory, i.e. in the case of shell scripts ensure that the
+@file{wvtest.sh} library is sourced like this:
+@example
+@code{. $(dirname $0)/wvtest.sh}
+@end example
+@end defvar
+
+@defvar WVTEST_LIBRARY
+Specifies the name of the library that is automatically linked with
+@code{wvtest_PROGRAMS}. The default is @file{wvtest}.
+@end defvar
+
+There is also an OMK pass called @code{wvtest-pass} which consecutively
+runs all @code{wvtest_PROGRAMS} and @code{wvtest_SCRIPTS} in the
+traversed subdirectories of the current directory. Every program or
+script is executed in a temporary directory under @file{_build}
+directory with @code{PATH} variable modified to include
+@file{_compiled/bin} as the first component and @code{LD_LIBRARY_PATH}
+modified to include @file{_compiled/lib} as the first component. This
+allows the tests to run the @code{bin_PROGRAMS} without explicitly
+specifying their full path and to use shared libraries without the path
+as well.
+
+When make is invoked as @command{make wvtest} it runs @command{make
+wvtest-pass} under the control of @file{wvtestrun} script, which must be
+present in the same directory as @file{Makefile.rules}. This script
+suppresses the normal output of passed tests and prints only their
+summary. For failed tests, the full output is shown. Additionally, when
+the output is written to a terminal, the status of each test is
+displayed in color for easy inspection.
+
+@node Properties of Specific Makefile.rules, Running OMK under Windows OS, Advanced OMK Features, User's Manual
@section Properties of Specific Makefile.rules
In previous sections, general properties of @file{Makefile.rules} were
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
@subsection Linux
This @file{Makefile.rules} is used not only for Linux as the name
-sugest, but also for other Unices and even for Windows.
+suggests, but also for other Unices and even for Windows.
@defvar BUILD_OS
The name of the operating system (OS) where make was invoked.
@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
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 instalation (e.g. /usr/share/qt4 on Debian).
+ 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
+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
-
-
-@node Running OMK under Windows OS, Interfacing OMK to popular IDEs, Properties of Specific Makefile.rules, OMK User's Manual
+
+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
-@node Interfacing OMK to popular IDEs, Troubleshooting, Running OMK under Windows OS, OMK User's Manual
+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, User's Manual
@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
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
+@node Troubleshooting, , Interfacing OMK to popular IDEs, User's Manual
+@section Troubleshooting & Knows Bugs
@itemize
@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 object file.
+ produce preprocessed source instead of an object file.
- To compile something manually, you can run OMK with @command{make
+ 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).
+
+@item
+ Removing of library source file does not cause the library to be
+ rebuild. You need to manually delete the library or run @command{make
+ distclean} before you run @command{make}.
@end itemize
-@node Original README, OMK Development, OMK User's Manual, Top
+@node Original README, Development, User's Manual, Top
@chapter Original README
Since this manual still doesn't cover all aspects of OMK, we include
@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
to link tree pointing into readonly media or can be anywhere
else if @code{MAKERULES_DIR} and @code{SOURCES_DIR} are specified.
-@c !!! tohle tam nejak zmizelo, mozna by to chtelo skontrolovat, ze to
+@c !!! tohle tam nejak zmizelo, mozna by to chtelo zkontrolovat, ze to
@c sedi s aktualnim stavem
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
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.
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,
@c @chapter OMK Reference
-@node OMK Development, Variable Index, Original README, Top
-@chapter OMK Development
+@node Development, Variable Index, Original README, Top
+@chapter 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
+@node Variable Index, , Development, Top
@unnumbered Variable Index
@printindex vr
projects / omk.git / blobdiff