\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 $Id$
-Copyright @copyright{} 2007 Michal Sojka, Pavel Pisa
+Copyright @copyright{} 2007, 2008 Michal Sojka, Pavel Pisa
@end copying
@titlepage
@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.
@end itemize
+
+
@node Quick Start, History, Why to Use OMK?, Overview of OMK
@section Quick Start
@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
@node History, , Quick Start, Overview of OMK
@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
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
+@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 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
@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
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
+@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
@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
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
@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.
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
@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
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).
@end itemize
@node Original README, OMK Development, OMK User's Manual, Top
@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
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.
@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
projects / omk.git / blobdiff