@contents
@ifnottex
-@node Top
+@node Top, Overview of OMK, (dir), (dir)
@top Ocera Make System
@insertcopying
@end ifnottex
-@node Overview of OMK
+@menu
+* Overview of OMK::
+* OMK Development::
+* Variable Index::
+* Concept Index::
+@end menu
+
+@node Overview of OMK, OMK Development, Top, Top
@chapter OMK Overview
@cindex overview
Your project is now ready to compile.
-@node History
+@menu
+* History::
+* Compiling Programs::
+* Configuration and Conditional Compilation::
+@end menu
+
+@node History, Compiling Programs, Overview of OMK, Overview of OMK
@section History
OMK was originally written by Pavel Pisa as a solution to have one
only once and thus decrease compilation time.} and does some
task. 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 (usually under
- @file{_compiled} directory). Also, during this pass, generated
- headers are generated according to the current configuration. See
- @ref{Configuration and Conditional Compilation} for details.
+ @file{_compiled} directory). @xref{Header Files}.
+
+ Also, during this pass, generated headers 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.
@end table
The results of compilation are stored under the @file{_compiled}
-directory. This directory is structured as a classical Unix filesystem
+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
(e.g. @file{/usr/local}).
map files, so a change to some library causes recompilation of all
programs using this library.
-@section Compiling Simple Programs
+@node Compiling Programs, Configuration and Conditional Compilation, History, Overview of OMK
+@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
@noindent The variables are:
@defvar bin_PROGRAMS
-Contains a list of names (whitespace separated) of programs to be
-compiled in this directory.
+ Contains a list of names (whitespace separated) of programs to be
+ compiled in this directory.
@end defvar
@defvar @var{program name}_SOURCES
-For every program name in @code{bin_PROGRAMS}, this variable contains a
-list of sources that are needed to compile the executable. OMK uses an
-extension of the filename to determine the compiler to compile this
-source.
+ For every program name in @code{bin_PROGRAMS}, this variable contains
+ a list of sources that are needed to compile the executable. OMK uses
+ an extension of the filename to determine the compiler to compile this
+ source.
@end defvar
@defvar @var{program name}_LIBS
-This variable contains a list of libraries the program @var{program
-name} needs to be linked to.
+ This variable contains a list of libraries the program @var{program
+ name} needs to be linked with.
+
+ @example
+ test_LIBS = m curses
+ @end example
@end defvar
@defvar LOADLIBES
-This variable contains a list of libraries all programs in this
-directory needs to be linked to.
+ This variable contains a list of libraries all programs in this
+ directory needs to be linked to.
@end defvar
@defvar INCLUDES
-Directives passed to the C or C++ compiler with additional directories
-to be searched for header files. This variable applies to all
-compilations invoked in the current directory.
-@example
-INCLUDES = -Imy_include_dir
-@end example
+ 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. If you need to specify a directory relative to 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.
+ 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.
+
+
+@section Libraries
+
+
+With OMK, you can easily create statically or dynamically linked
+libraries. The way of creating libraries is very similar to the way of
+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} is created from two sources @file{funca.c} and
+@file{funcb.c}. Interface of this library is defined in
+@file{myfunc.h}. Therfore, we export this header for use by other
+programs.
+
@example
-DEFS = -DDEBUG=1
+@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.
@end defvar
+@defvar shared_LIBRARIES
+ Specifies a list of dynamically linked libraries to be compiled.
+@end defvar
+@defvar @var{library name}_SOURCES
+ For every library name in @code{lib_LIBRARIES} or
+ @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
-@c FIXME: INCLUDES variable should not be set by rtlinux rules.
+@menu
+* Header Files::
+@end menu
+@node Header Files, , Compiling Programs, Compiling Programs
+@subsection Header Files
-@section Libraries
+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. If the header file specified here contains a
+ directory prefix (see @file{periph/} in the example below), the header
+ is copied with the same prefix under @file{includes} directory in
+ @file{_compiled} tree.
+
+ @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
+ stripped before coping the header file.
+@end defvar
-LN_INCLUDES
+@defvar renamed_include_HEADERS
+ Exports the header files under different name. The form if items in
+ this whitespace separated list is: @var{real name}@samp{->}@var{new
+ name}.
+
+ @example renamed_include_HEADERS =
+ orte_config_omk_win32.h->orte_config.h
+ @end example
+@end defvar
+
+@defvar LN_INCLUDES
+ This variable is very useful during library development. In most
+ @acronym{IDE}s, you can jump 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.
+
+ If the value of this variable equals to @samp{y}, symbolic links are
+ used instead of copies.
+@end defvar
@section Multiple Directories
-ALL_OMK_SUBDIRS
-SUBDIRS
+OMK is probably most useful in projects consisting of multiple
+directories. For such projects, it is not easy to write Makefiles from
+scratch, 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}.
-@node Configuration and Conditional Compilation
+@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.
+@end defvar
+@c TODO: Write tests for this.
+
+@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 contains @file{Makefile.omk} file. 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 the linked
+ directories automatically appears as the value of this variable.
+
+ @example
+ SUBDIRS = $(ALL_OMK_SUBDIRS)
+ @end example
+@end defvar
+
+@node Configuration and Conditional Compilation, , Compiling Programs, Overview of OMK
@section Configuration and Conditional Compilation
-@section Running OMK under Windows OS
+In many projects, it is possible to configure a 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 support for it.
+
+In every directory you can specify some configuration parameters, which
+can be modified by a user. Then, when @command{make default-config} is
+run, all these parameters are found and together with their default
+values are stored as makefile variables in
+@file{config.omk-default}. This file is included during compilation, so
+if the user doesn't specify other parameters, these default are used. If
+the user is not satisfied with these defaults, he/she can override the
+value of parameter in @file{config.omk}. This file is also included
+during compilation and variables mentioned there takes precedence over
+those specified in @file{config.omk-default}. Both @file{config.omk} and
+@file{config.omk-default} must be stored in the same directory as
+@file{Makefile.rules}.
+
+The file @file{config.omk} is common place to store some global settings
+such as the compiler to use, common compiler flags etc.
+
+@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 constrains a list of configuration parameters and their
+ default values. The format 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 defines 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} or @samp{n}
+ 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.
+@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
+
+Example of using @code{default_CONFIG}. @file{Makefile.omk} reads like:
+@example
+@verbatiminclude ../tests/config/default/Makefile.omk
+@end example
+and @file{subdir/Makefile.omk} like:
+@example
+@verbatiminclude ../tests/config/default/subdir/Makefile.omk
+@end example
+
+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
+
+@subsection Using Configuration Parameters
+
+Configuration parameters can be used by two ways:
+@enumerate
+@item
+ as variables in @file{Makefile.omk} and
+@item
+ as C preprocessor macros in OMK generated header files.
+@end enumerate
+
+@noindent For the first use, you can have in @file{Makefile.omk} something like:
+@example
+SUBDIRS = arch/$(CONFIG_ARCH)
+
+ifeq ($(CONFIG_DEBUG),y)
+DEFS += -DUSE_SIMULATOR
+endif
+@end example
+
+For the second use, there are several variables that are described here:
+
+@defvar LOCAL_CONFIG_H
+
+@end defvar
+
+@defvar config_include_HEADERS
+
+@end defvar
+
+@defvar @var{xxx}_DEFINES
+
+@end defvar
+
+
+@subsection Common Variables
+
+
+
+@section Running OMK under Windows @acronym{OS}
+
+@section Interfacing OMK to popular @acronym{IDE}s
+
+@subsection Eclipse
+
+@subsection KDevelop
+
+@subsection Emacs
+
+@subsection VIM
@section Troubleshooting
@chapter OMK Reference
+@node OMK Development, Variable Index, Overview of OMK, Top
@chapter OMK Development
-@node Variable Index
+@node Variable Index, Concept Index, OMK Development, Top
@unnumbered Variable Index
@printindex vr
-@node Concept Index
+@node Concept Index, , Variable Index, Top
@unnumbered Concept Index
@printindex cp
projects / omk.git / commitdiff