@copying
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
@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::
+* 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
source @file{test.c}.
@example
-@verbatiminclude ../tests/programs/Makefile.omk
+@verbatiminclude tests/programs/Makefile.omk
@end example
@noindent The variables are:
by other programs.
@example
-@verbatiminclude ../tests/libraries/Makefile.omk
+@verbatiminclude tests/libraries/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
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
@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
@node Integration of Wvtest Framework, , Adding Hooks to Passes, Advanced OMK Features
@subsection Integration of Wvtest Framework
-OMK has integrated support for Wvtest unit testing framework (see
-@uref{https://github.com/apenwarr/wvtest}).
+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 is the same as @ref{test_PROGRAMS} with the exception that
-the program is automatically executed by @command{make wvtest} (see
-below).
+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_SCRIPT
-TODO
+@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
-@command{make wvtest} TODO
-
+@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 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