1 \input texinfo @c -*-texinfo-*-
3 @setfilename omk-manual
4 @settitle OMK: Ocera Make System
8 Manual for Ocera Make System (OMK)
10 Copyright @copyright{} 2007 Michal Sojka, Pavel Pisa
14 @title Ocera Make System Manual
16 @vskip 0pt plus 1filll
23 @node Top, Overview of OMK, (dir), (dir)
24 @top Ocera Make System
38 @node Overview of OMK, OMK User's Manual, Top, Top
42 OMK is an advanced make system written entirely in GNU make. Compiling
43 software using OMK requires only GNU make binary and standard UNIX
44 utilities (@command{sh}, @command{sed}, @command{cmp} and
45 @command{tr}@footnote{@command{tr} is needed only for OMK to be
46 compatible with MinGW.}) installed. OMK aims to be developer friendly;
47 to use OMK, you do not need to understand (sometimes) cryptic syntax of
50 You can use OMK on all platforms where you can run GNU Make including
51 Cygwin and MinGW. MS DOS was not tested.
57 @c Easy to use for beginners.
59 @c Automatic handling of dependencies.
61 @c Supported host platforms: all Un*x operating system including Linux,
62 @c Cygwin, MS DOS and maybe others.
71 @node Why to Use OMK?, Quick Start, Overview of OMK, Overview of OMK
72 @section Why to Use OMK?
74 Here we list some of OMK features, which we think are important for
75 choosing of a make system.
80 Makefile in source directories are usually very @b{simple}.
82 There is only @b{one} @file{Makefile.rules} for most of components of
85 OMK greatly simplifies compilation of projects, where source files are
86 spread between @b{multiple directories}.
88 OMK handles properly @b{dependencies} of source files and libraries,
89 so it is not necessary to recompile the whole project if only several
92 OMK allows to freely @b{move} cross-dependant components @b{in
93 directory structure} without the need to update users of moved
94 component. I hate something like
95 @option{-I../../sched/rtlshwq/include} in makefiles for example. If a
96 component is renamed or version is added to the name, many Makefiles
97 in the project would require an update.
99 The above feature is very helpful in @b{combining components}
100 (libraries) from different projects/developers to a single project by
101 simply creating symbolic links to external components.
103 Compilation of an OMK based projects don't require to install any
104 files before successful finish of build.
106 OMK allows to call @command{make} for a particular subdirectory in the
109 Under OMK all products of compilation are stored @b{out of source
110 directories}. This simplifies work with version control systems and
111 helps when simultaneous compilation for multiple targets/platforms is
116 @node Quick Start, History, Why to Use OMK?, Overview of OMK
119 If you get some sources, which are distributed with OMK, usually the
120 following commands are sufficient to compile the whole project.
129 @noindent To use OMK in your own project, follow these steps:
133 Take appropriate @file{Makefile.rules}, put it together with leaf
134 @file{Makefile} to the root directory of your project.
136 Create @file{Makefile.omk} files in all directories you want to
137 compile something. Please refer to @ref{OMK User's Manual} to learn
138 what to write in @file{Makefile.omk} files.
140 Run @command{make omkize} in the root directory.
143 @noindent Your project is now ready to compile.
146 @node History, , Quick Start, Overview of OMK
149 OMK was originally written by Pavel Pisa as a solution to have one
150 common make system for OCERA project, where we needed to compile
151 user-space programs, Linux kernel modules and RT Linux modules in one
152 package. Although this system was not accepted for the whole OCERA
153 project. Several individual developers (mostly from Czech Technical
154 University) liked it and started to use it.
156 As a number of projects using OMK grew it was necessary to modularize
157 the make system to support more ``targets''. Michal Sojka took care
158 about the process of modularization.
160 @node OMK User's Manual, Original README, Overview of OMK, Top
161 @chapter OMK User's Manual
166 * Compiling Programs::
168 * Multiple Directories::
169 * Dependency Tracking::
170 * Configuration and Conditional Compilation::
171 * Advanced OMK Features::
172 * Properties of Specific Makefile.rules::
173 * Running OMK under Windows OS::
174 * Interfacing OMK to popular IDEs::
178 @node Basic Concepts, Invoking OMK, OMK User's Manual, OMK User's Manual
179 @section Basic Concepts
181 The main concept of OMK is very simple. In the root directory of the
182 projects resides a file called @file{Makefile.rules}. This file contains
183 all compilation rules needed for compilation of a particular
184 project. There are different @file{Makefile.rules} for different
185 platforms (Unix, RTEMS, system-less, ...). In every subdirectory a
186 @file{Makefile.omk} is stored. This file determines what should be done
187 in the respective directory (e.g. compile a program from several source
188 files). Its syntax is very simple -- see the following sections.
190 Since make searches by default for a @file{Makefile} and not for
191 @file{Makefile.rules} or @file{Makefile.omk}, there must be a small
192 generic @file{Makefile} in every directory, whose task is only to find
193 @file{Makefile.rules} in the actual or any parent directory and include
194 it. This search is performed only once at the beginning of compilation.
196 @c TODO: Pavel's note about qmake.
199 The compilation process itself is comprised of several @emph{passes}. Every
200 pass traverses the whole directory structure@footnote{In future, we are
201 planning some optimization that allows OMK to traverse the directories
202 only once and thus decrease compilation time.} and does a particular
203 task in every directory of the project. Typically, these passes are:
205 @anchor{include-pass}
207 This pass takes all include files marked for ``export'' and copies
208 (or links) them to the @file{include} directory under
209 @file{_compiled} directory. @xref{Header Files}.
211 Also, during this pass, automatically generated header file are
212 generated according to the current
213 configuration. @xref{Configuration and Conditional Compilation}.
215 During this pass, all include files are in place, so all libraries
218 Finally, programs can be compiled and linked against libraries
219 created in the previous pass.
222 The results of compilation are stored under the @file{_compiled}
223 directory. This directory is structured as a classical Unix file-system
224 (it contains directories like @file{bin}, @file{lib} and @file{include})
225 and can be directly copied to the target device or to some directory on
226 a host computer (e.g. @file{/usr/local}).
228 Besides @file{_compiled} directory, there in a @file{_build}
229 directory. Under this directory are stored some temporary files and
230 intermediate compilation products (object files, dependency files etc.).
232 In the next section, we provide an overview of methods, how to invoke
233 OMK from command line. Section @ref{Interfacing OMK to popular IDEs}
234 covers running of OMK from popular IDEs.
236 Sections @ref{Compiling Programs} through @ref{Configuration and
237 Conditional Compilation} deals with the content of
238 @file{Makefile.omk}. Its syntax in usual cases compatible to GNU
239 Automake's @file{Makefile.am} syntax. Also, the scheme for naming
240 variables was inspired by Automake so most OMK variables have the name
241 like @samp{@var{target}_@var{TYPE}}.
243 @node Invoking OMK, Compiling Programs, Basic Concepts, OMK User's Manual
244 @section Invoking OMK
246 Before using OMK for the first time, you have to call:
248 @command{make default-config}
250 @noindent See @ref{Configuration and Conditional Compilation} for
251 details. If you forget to do this, OMK will notice you.
253 To compile the whole project or only some subtree of the project, call
257 @noindent in the appropriate directory.
259 To clean files in @file{_build} directory but not in @file{_compiled}
265 To clean the compilation completely, you can either remove
266 @file{_compiled} and @file{_build} directories manually, or call
268 @command{make distclean}
270 @noindent which does the same. This command removes these directories
271 even if you call it from a subdirectory.
273 To debug compilation problems, you can use @code{V} variable (see
279 You can also set values of some other variables on command line for
280 temporary change something. The example below compiles the code
281 temporarily with debugging information:
283 @command{make CFLAGS="-g -O0 -Wall"}
286 If your project uses an alternative make-system (e.g. Automake or custom
287 makefiles), it might be useful for you to use the command:
289 @command{make omkize}
291 @noindent This will find all @file{Makefile.omk} files in all subdirectories
292 and copies generic @file{Makefile} from the root directory to that
293 subdirectories. This way you can easily switch your project to use OMK.
299 If this variable equals to @samp{1}, the whole command lines for all
300 executed commands are displayed. When not set or zero, only short
301 messages are printed. Value of @samp{2} displays the whole command lines
302 as with @samp{1} and in addition directory navigation messages are
306 @node Compiling Programs, Libraries, Invoking OMK, OMK User's Manual
307 @section Compiling Programs
309 To tell OMK to compile a program, you need to set some variables in
310 @file{Makefile.omk} (usually) in the directory where program sources are
313 In the example bellow a program @command{test} will be compiled from
314 source @file{test.c}.
317 @verbatiminclude ../tests/programs/Makefile.omk
320 @noindent The variables are:
322 @anchor{bin_PROGRAMS}
324 Contains a list of names (whitespace separated) of programs to be
325 compiled in this directory.
328 @defvar test_PROGRAMS
329 Almost the same as @ref{bin_PROGRAMS}, but resulting binaries are
330 stored in @file{bin-tests} directory instead of @file{bin}. This
331 variable is intended for various test programs not to be mixed with
335 @defvar utils_PROGRAMS
336 Almost the same as @ref{bin_PROGRAMS}, but resulting binaries are
337 stored in @file{bin-utils} directory instead of @file{bin}. This
338 variable is intended for various development utilities not to be mixed
339 with the final product.
343 For every program name @var{xxx} in @code{bin_PROGRAMS},
344 @code{test_PROGRAMS} or @code{utils_PROGRAMS}, this variable contains
345 a list of sources that are needed to compile the program. OMK uses an
346 extension of the filename to determine the compiler to compile this
351 This variable contains a list of libraries the program @var{xxx} will
360 This variable contains a list of libraries all programs in this
361 directory needs to be linked to.
365 Directives passed to the C or C++ compiler with additional directories
366 to be searched for header files. In most cases you need to specify an
367 absolute path. To specify a directory relative to the source
368 directory, you can use the @code{$(SOURCES_DIR)} variable, which
369 refers to the directory, where @file{Makefile.omk} is located. This
370 variable applies to all compilations invoked in the current directory.
373 INCLUDES = -I$(SOURCES_DIR)/my_include_dir
378 Directives passed to the C or C++ compiler with preprocessor macro
379 definitions. This variable applies to all compilations invoked in the
388 @c FIXME: INCLUDES variable should not be set by rtlinux rules.
390 @node Libraries, Multiple Directories, Compiling Programs, OMK User's Manual
394 With OMK, you can easily create statically or dynamically linked
395 libraries. The way of creating libraries is very similar to how programs
396 are created. @xref{Compiling Programs}.
398 In @file{Makefile.omk}, you specify several variables, which defines how
399 the libraries should be compiled. In the example below the library
400 @samp{mylib} (full filename will be @file{libmylib.a}) is created from
401 two sources @file{funca.c} and @file{funcb.c}. Interface of this library
402 is defined in @file{myfunc.h}. Therfore, we export this header for use
406 @verbatiminclude ../tests/libraries/Makefile.omk
409 @noindent Variables for use with libraries are:
411 @defvar lib_LIBRARIES
412 Specifies a list of statically linked libraries to be compiled. OMK
413 automaticvally prepends @code{lib} prefix library names.
416 @defvar shared_LIBRARIES
417 Specifies a list of dynamically linked libraries to be compiled.
421 For every library name @var{xxx} in @code{lib_LIBRARIES} or
422 @code{shared_LIBRARIES}, this variable contains a list of sources that
423 are needed to compile the library. OMK uses an extension of the
424 filename to determine the compiler to compile this source.
431 @node Header Files, , Libraries, Libraries
432 @subsection Header Files
434 C and C++ libraries are not very useful without header files. OMK
435 provides several variables that specify activities on header files.
437 During compilation, header files are copied (or linked) from source
438 directories to the @file{_compiled} tree
439 (see @ref{include-pass}). Libraries and programs are then compiled against
442 @anchor{include_HEADERS}
443 @defvar include_HEADERS
444 Specifies the list of header files to be exported for use by other
445 libraries/programs. The files are exported directly to the
446 @file{include} directory even if the file is located in a subdirectory
447 (like @file{sci_regs.h} in the example below)
450 include_HEADERS = regs.h periph/sci_regs.h
454 @defvar nobase_include_HEADERS
455 Similar to @ref{include_HEADERS}, but the directory prefix is always
456 kept. To include the file exported by this variable, use
457 @code{#include <@var{prefix}/@var{header.h}>}.
460 @defvar renamed_include_HEADERS
461 Exports the header files under different name. The form of the items
462 in this whitespace separated list is: @var{real name}@code{->}@var{new
466 renamed_include_HEADERS = orte_config_omk_win32.h->orte_config.h
471 If this variable equals to @samp{y}, symbolic links to headers in
472 source directories are used in @file{_compiled} tree instead of
475 Normally, the header files are copied into @file{_compiled} directory
476 to be prepared for transfer into target location afterwards. Copying
477 ensures that resulting libraries are in correspondence with the header
478 files even if the header is changed by a developer but the library is
481 @c Another reason for having single include directory for the whole
482 @c project is tat every component knows where to find header files of
485 On the other side, the copying could make problems during
486 development. Most @acronym{IDE}s, allows you to jump directly to the
487 place, where an error is reported by the compiler. If the error is in
488 a header file, IDE opens you the copy of the header file. If you
489 correct the error there, after the next compilation, your header file
490 will be overwritten by the old version from your source tree.
492 This option is not typically used in @file{Makefile.omk}, but in the
493 top level configuration file @file{config.omk} or on command line.
496 @node Multiple Directories, Dependency Tracking, Libraries, OMK User's Manual
497 @section Multiple Directories
499 OMK is probably most useful in projects consisting of multiple
500 directories. For such projects, it is not easy to write from scratch
501 classic Makefiles that provides all the needed features.
503 You can instruct OMK to descend to a (sub)directory by setting the
504 @code{SUBDIRS} variable in @file{Makefile.omk}.
507 This variable contains a list of directories, in which compilation
508 must be also invoked. Usually, names of subdirectories are used, but
509 you can use any path specification here.
511 Compilation is invoked in these directories before it is invoked in
512 the current directory.
514 @c TODO: Write tests for this.
516 @defvar ALL_OMK_SUBDIRS
517 This variable is set by OMK and can be used as the value of
518 @code{SUBDIRS} variable. It contains a list of all direct
519 subdirectories, which contain @file{Makefile.omk}. This is especially
520 useful if you are combining several projects or components
521 together. In the root directory of your project, you just create
522 symbolic links the components from other projects and all the linked
523 directories automatically appears as the value of this variable.
526 SUBDIRS = $(ALL_OMK_SUBDIRS)
530 @node Dependency Tracking, Configuration and Conditional Compilation, Multiple Directories, OMK User's Manual
531 @section Dependency Tracking
533 OMK automatically handles tracking of dependencies of files in compiled
534 projects. It uses gcc's @option{-M@var{x}} options to do this for object
535 files. This way, whenever you change some header file, OMK recompiles
536 only those files, where the changed header was really included.
538 Dependencies are also maintained for libraries and binaries. To find the
539 dependencies, OMK parses linker map files, so a change to some library
540 causes recompilation of all programs using that library.
542 @node Configuration and Conditional Compilation, Advanced OMK Features, Dependency Tracking, OMK User's Manual
543 @section Configuration and Conditional Compilation
545 In many projects, it is necessary to configure the compilation process. By
546 this configuring we mean, setting some parameters that influence the
547 output of compilation process. In GNU projects, @command{configure}
548 script is usually responsible for configuration. User provides some
549 parameters to @command{configure}, which is run before compilation, and
550 this script does all steps needed to configure the sources and
551 make-system in the desired way.
553 OMK has its own configuration mechanism, which is described in this
554 section. For future releases, we plan that this mechanism can make use
555 of GNU Autoconf, but currently there is no directly integrated support
558 There exist three different configuration files
559 @file{config.omk-default}, @file{config.target} and
560 @file{config.omk}. All of these have to be stored in the same directory
561 as @file{Makefile.rules}. During compilation, these files are included
562 in @file{Makefile.rules} in this order which means that variables
563 assigned in the former files are overridden by those from later
564 ones. All settings specified here apply to the whole compilation
565 tree. Each file is intended for a different kind of configuration
568 @item config.omk-default
569 Stores default configuration of compiled components. This file is
570 automatically generated (see below) and should not be edited by users.
572 Stores default configuration for a project or target hardware. This
573 file is intended to be stored in a version control system and should
574 be modified only by the maintainer of the project.
576 For cross compiled projects, this file typically contains settings of
577 variables like @var{CC} and @var{CFLAGS}.
579 This is a file for end users, where any default settings set in the
580 above files can be overridden. This file should not be stored in
581 version control system. The project should compile without having this
585 Besides variables defined in @file{config.target}, @file{Makefile.omk}
586 in any subdirectory can specify some configuration parameters. When
587 @command{make default-config} is run, all these parameters are found and
588 together with their default values are stored as makefile variables in
589 @file{config.omk-default}. This file is included during compilation, so
590 if you don't specify other values, these defaults are used. If you are
591 not satisfied with these defaults, you can override the values of
592 parameters either locally for your build in @file{config.omk} or
593 globally for all people working with the project in
594 @file{config.target}.
597 * Specifying Configuration Parameters::
598 * Using Configuration Parameters::
602 @node Specifying Configuration Parameters, Using Configuration Parameters, Configuration and Conditional Compilation, Configuration and Conditional Compilation
603 @subsection Specifying Configuration Parameters
605 To specify names and default values of configuration parameters use the
606 @code{default_CONFIG} variable in @file{Makefile.omk}.
608 @defvar default_CONFIG
609 This variable contains a list of configuration parameters and their
610 default values. The format of every item in this list is
611 @var{CONFIG_xxxx}=@var{value}. You can name the parameter as you want,
612 but it is good practice to start the name with @samp{CONFIG_} prefix.
614 OMK can automatically generate header files, with C preprocessor macro
615 definitions according to the OMK's configuration parameters. The
616 actual content of generated header files depends on the form of the
617 @var{value}. The possible forms are:
620 @item @samp{y}, @samp{n} or @samp{x}
621 This defines boolean parameters. If the value of the parameter is
622 @samp{y}, the @samp{#define CONFIG_@var{xxx} 1} is generated, if it is
623 @samp{n}, no @code{#define} is generated.
625 @samp{x} is a special value called @emph{recessive 'n'}. The meaning
626 is that this parameter influences the component in the current
627 directory (i.e. the corresponding @code{#define} will be included in
628 @code{LOCAL_CONFIG_H}; see @ref{LOCAL_CONFIG_H}) but the default value
629 is not specified here. If the default value is not specified anywhere,
630 the behavior is the same as if @samp{n} is specified.
632 Numeric parameters. The define looks like @samp{#define CONFIG_@var{xxx} @var{number}}
634 Text without quotes. The define looks like @samp{#define CONFIG_@var{xxx} @var{text}}
636 Text with quotes. The define looks like @samp{#define CONFIG_@var{xxx} "@var{text}"}
640 @noindent Example of using @code{default_CONFIG}. @file{Makefile.omk} reads like:
642 @verbatiminclude ../tests/config/default/Makefile.omk
644 @noindent and @file{subdir/Makefile.omk} like:
646 @verbatiminclude ../tests/config/default/subdir/Makefile.omk
649 @noindent After running @command{make default-config}, the content of
650 @file{config.omk-default} will be:
652 @verbatiminclude ../tests/config/default/config.omk-correct
655 @node Using Configuration Parameters, Common Variables, Specifying Configuration Parameters, Configuration and Conditional Compilation
656 @subsection Using Configuration Parameters
658 Configuration parameters can be used in two ways:
661 as variables in @file{Makefile.omk} and
663 as C/C++ preprocessor macros in OMK generated header files.
666 @noindent For the first use, your @file{Makefile.omk} may contain something like:
668 SUBDIRS = arch/$(CONFIG_ARCH)
670 ifeq ($(CONFIG_DEBUG),y)
671 DEFS += -DUSE_SIMULATOR
675 @noindent For the second use, there are several variables that control
676 the generation of header files with configuration values. These
677 variables are described here:
679 @anchor{LOCAL_CONFIG_H}
680 @defvar LOCAL_CONFIG_H
681 The value of this variable is the name of a header file, which will
682 contain all configuration parameters declared in the current directory
683 by @code{default_CONFIG}. This header file is accessible only by files
684 in the current directory and it should be included like @code{#include
687 In @file{Makefile.omk}, the use of this variable can look like this:
690 LOCAL_CONFIG_H = myconfig.h
694 @defvar config_include_HEADERS
695 This variable is similar to @code{LOCAL_CONFIG_H}. One difference is
696 that the generated header file is accessible to all sub-projects in
697 all directories, not only to the files in the same directory (the
698 header is stored in @file{_compiled} tree). The second difference is
699 that you have to specify, which configuration parameters you want to
700 appear in the header file.
704 This variable determines the configuration parameters that should be
705 stored in a header file specified by
706 @code{config_include_HEADERS}. The @var{xxx} in the name of this
707 variable needs to be the same as the base name (without extension) of
711 @noindent Example of using @code{config_include_HEADERS}:
713 default_CONFIG = CONFIG_LINCAN=y CONFIG_LINCANRTL=n CONFIG_LINCANVME=n
714 config_include_HEADERS = global.h
715 global_DEFINES = CONFIG_OC_LINCAN CONFIG_OC_LINCANRTL
718 @noindent Here, we include only two out of the three configuration
719 parameters defined in the current @file{Makefile.omk}. It is also
720 possible to include configuration parameters defined in a different
723 @node Common Variables, , Using Configuration Parameters, Configuration and Conditional Compilation
724 @subsection Common Variables
726 It is common practice to use @file{config.omk} to store project-wide
727 settings. Here is the list of variables, which are commonly set here
728 (but they can also be set elsewhere, e.g. in @file{Makefile.omk}).
730 You can easily ``reconfigure'' your project by changing the
731 @file{config.omk} file. It is useful to have several configurations
732 stored in different files and let @file{config.omk} be a symbolic link
733 to the desired configuration.
737 The name of C compiler.
739 Command line options for C compiler.
741 The name of C++ compiler.
743 Additional parameters (besides @code{CFLAGS}) to by passed to C++
747 @node Advanced OMK Features, Properties of Specific Makefile.rules, Configuration and Conditional Compilation, OMK User's Manual
748 @section Advanced OMK Features
750 In this section we list several OMK features, which are more complicated
751 or rarely used so they were omitted in previous sections.
754 * Organization of the Source Tree::
755 * Additional Variables::
756 * Adding Hooks to Passes::
759 @node Organization of the Source Tree, Additional Variables, Advanced OMK Features, Advanced OMK Features
760 @subsection Organization of the Source Tree
764 The @file{_compiled} directory can be shared between multiple projects
765 (by using symbolic links).
768 If you work on a bigger project, you usually don't need to rebuild the
769 whole project and call @command{make} only in a
770 subdirectory. Sometimes, it might be useful to rebuild the whole
771 project. You can either change working directory to the root of your
772 project and call @command{make} there or, as a shortcut, you can use
773 @code{W} variable (see @ref{W}) to compile everything directly from a
780 Searching for @file{Makefile.rules} works such way, that if you get
781 into sources directory over symbolic links, OMK is able to unwind your
782 steps back. This implies you can make links to component directories
783 on read-only media, copy @file{Makefile.rules}, @file{Makefile} and
784 top-level @file{Makefile.omk}, adjust @file{Makefile.omk} to contain
785 only required components and then call @command{make} in the top
786 directory or even in read-only directories after changing working
787 directory from your tree to the readonly media.
793 If this variable equals to @samp{1}, the @b{whole} project is
794 (re)compiled, even if @command{make} is called from a subdirectory.
797 @node Additional Variables, Adding Hooks to Passes, Organization of the Source Tree, Advanced OMK Features
798 @subsection Additional Variables
800 @anchor{USE_LEAF_MAKEFILES}
801 @defvar USE_LEAF_MAKEFILES
802 If this variable equals to @samp{n} (default is unset), then OMK uses
803 the leaf @file{Makefile} only when it is invoked by simple
804 @command{make} command. Later, during recursive directory descent leaf
805 @file{Makefile} is not used and @file{Makefile.rules} is included
808 This feature is useful if you are integrating some non-OMK project into
809 your project. You only add @file{Makefile.omk} files to the other
810 project and don't need to modify project's original Makefiles.
812 This variable can be set either globally in a @file{config.*} file or
813 locally in some @file{Makefile.omk}. In the latter case, it influences
814 only subdirectories of the directory containing @file{Makefile.omk}.
819 This variable is set internally by OMK and its value is the absolute
820 path to the directory with compiled sources. It can be used if you need
821 to refer to sources files in some custom constructs in
825 include_HEADERS = $(notdir $(wildcard $(SOURCES_DIR)/*.h))
831 The same as @ref{SOURCES_DIR}. Provided for Automake compatibility.
834 @defvar{MAKERULES_DIR}
835 This variable is set internally by OMK and its value is the absolute
836 path to the directory containing @file{Makefile.rules} currently used
840 @defvar{OMK_RULES_TYPE}
841 Identification the type of @file{Makefile.rules} used for
842 compilation. Values are like @samp{linux}, @samp{rtems}, @samp{sysless},
843 ... This variable is automatically generated during creation of
844 @file{Makefile.rules} and can be used in configuration files (see
845 @ref{Configuration and Conditional Compilation}) or in
846 @file{Makefile.omk} to tweak compilation for specific targets.
849 @node Adding Hooks to Passes, , Additional Variables, Advanced OMK Features
850 @subsection Adding Hooks to Passes
852 Sometimes it is necessary to run some special commands as a part of
853 compilation. Typical example might be a tool which generates source
854 files on the fly. OMK supports calling additional commands during
855 compilation by so called @emph{pass hooks}. A pass hook is an ordinary
856 make target which is invoked as part of compilation during a particular
857 pass (see @ref{passes}). Pass hooks can be defined by assigning their
858 names to @code{xxx_HOOKS} variable.
861 Specifies one or more hooks (make targets) which are invoked during pass
862 @var{xxx}. The working directory of commands or this target is under the
865 In the example bellow header file @file{generated_header.h} is created
866 during @samp{include-pass} by @file{convert_data} program. The program
867 takes @file{data_file.txt} in the source directory as the input and
868 creates the header file in the in the correct directory under the
872 include-pass_HOOKS = generated_header.h
874 generated_header.h: $(SOURCES_DIR)/data_file.txt
875 convert_data < $^ > $@@
879 @node Properties of Specific Makefile.rules, Running OMK under Windows OS, Advanced OMK Features, OMK User's Manual
880 @section Properties of Specific Makefile.rules
882 In previous sections, general properties of @file{Makefile.rules} were
883 documented. This section contains documentation to features found only
884 in some particular @file{Makefile.rules}.
892 @node Linux, System-Less, Properties of Specific Makefile.rules, Properties of Specific Makefile.rules
895 This @file{Makefile.rules} is used not only for Linux as the name
896 sugest, but also for other Unices and even for Windows.
899 The name of the operating system (OS) where make was invoked.
903 Should specify the name of OS where the resulting binary should be
904 used. If not specified manually, it equals to BUILD_OS.
908 Lists subdirectories with QT project (.pro) file. OMK will generate
909 there @file{Makefile} by calling @command{qmake} with correct
910 parameters to interface QT application to the rest of the compilation
911 tree. Then @command{make} is called there to compile QT
912 application. Variable @samp{QTDIR} must be set to the directory with
913 QT instalation (e.g. /usr/share/qt4 on Debian).
917 @node System-Less, RTEMS, Linux, Properties of Specific Makefile.rules
918 @subsection System-Less
920 @node RTEMS, , System-Less, Properties of Specific Makefile.rules
924 @node Running OMK under Windows OS, Interfacing OMK to popular IDEs, Properties of Specific Makefile.rules, OMK User's Manual
925 @section Running OMK under Windows OS
927 @node Interfacing OMK to popular IDEs, Troubleshooting, Running OMK under Windows OS, OMK User's Manual
928 @section Interfacing OMK to popular IDEs
936 @node KDevelop, Eclipse/CDT, Interfacing OMK to popular IDEs, Interfacing OMK to popular IDEs
939 KDevelop has support for custom build systems. To use KDevelop to
940 develop projects using OMK follow these steps. These steps are valid for
941 version 3.5.0 of KDevelop, but for previous versions it doesn't differ
946 Import project to KDevelop (from menu choose @emph{Project---Import
947 existing project}). Select the type of project to @emph{Generic C
948 Application (Custom Buildsystem)}.
954 Then answer to following dialogs as you want.
959 @image{kdevelop3} @image{kdevelop4}
963 If you are working only on some small part of the bigger project, you
964 usually don't want to recompile the whole project every time. In
965 @emph{Project---Project Options}, you can specify the subdirectory where to
972 If you want to switch between several configurations easily (see also
973 @ref{Configuration and Conditional Compilation}), in the same dialog
974 you can add @option{-e} to make options. This makes environment variables
975 have higher precedence than those in @file{config.omk-default}. Then,
976 you can define several environments with different
977 @code{CONFIG_@var{xxx}} variables and their values.
983 You can easily switch the configurations from @emph{Build---Make
990 @node Eclipse/CDT, Emacs/Vim/etc., KDevelop, Interfacing OMK to popular IDEs
991 @subsection Eclipse/CDT
993 @node Emacs/Vim/etc., , Eclipse/CDT, Interfacing OMK to popular IDEs
994 @subsection Emacs, VIM, etc.
996 Since OMK compilation is started by executing @command{make} command,
997 many common editors can work easily with OMK.
999 Under Emacs, you can use @command{compile} or @command{recompile}
1000 commands as you are used to do.
1002 @node Troubleshooting, , Interfacing OMK to popular IDEs, OMK User's Manual
1003 @section Troubleshooting
1007 If you rename some file or directory and then you can't compile your
1008 project, call @command{make clean} in the directory with errors. The
1009 reason for this behavior is that OMK remembers dependencies of every
1010 file. After renaming something, the original name is still stored in
1011 dependencies, but make doesn't know how to create this non-existent
1015 Sometimes, you may want to compile one file the same way as OMK does
1016 it, but run the compilation manually from command line. For example,
1017 you want to debug some preprocessor macros and you only want to
1018 produce preprocessed source instead of object file.
1020 To compile something manually, you can run OMK with @command{make
1021 V=2}. This will print all commands executed together with directory
1022 navigation messages. Find the command you want to execute manually in
1023 the output. To run it, you need to change the working directory to the
1024 correct one in the @file{_build} tree. The correct directory can be
1025 found in make output on the line @samp{Entering directory} preceding
1026 the desired command.
1029 @node Original README, OMK Development, OMK User's Manual, Top
1030 @chapter Original README
1032 Since this manual still doesn't cover all aspects of OMK, we include
1033 here a @file{README.rules} file, which was written for the first version
1036 @b{Important notice:} This make system uses features found in recent
1037 versions of GNU Make program. If you encounter problems with package
1038 building, check, that you use correct version of Make program. The
1039 Make older than version 3.80, could not be used. Even Make version
1040 3.80 has annoying bug which causes building fail with misleading
1041 message "virtual memory exhausted". Please, upgrade at least to
1042 version 3.81 of GNU Make.
1044 There is list of features which we want to solve with our make system:
1047 Central @file{Makefile.rules} for most of components of a bigger project.
1049 FIXME (our CAN framework includes more libraries common with our other
1050 projects, we need to separate some utility libraries etc.)
1052 The rules in more spread Makefiles are way to the hell (update for
1053 different kernel, RT-Linux etc would be nightmare in other case).
1055 Make system should allow to freely move cross-dependant components in
1056 directory structure without need to update users of moved component (I
1057 hate somethink like @option{-I../../sched/rtlshwq/include} in CAN makefiles for
1058 example. If a component is renamed or version is added to then name,
1059 all Makefiles in CAN will require update).
1061 Make system should be able to compile mutually cross-dependant
1062 libraries and should ensure, that change in one component sources or
1063 headers would result in relink or rebuild in components linked against
1064 that library or including modified header file.
1066 Make system has to enable compilation out of OCERA full source tree
1067 (we would lost many users of particular components in other case).
1069 Compile should be able to do all above work without need to install
1070 any files before successful finish of build.
1072 Because we use some libraries for RT-Linux build and user-space build,
1073 we need to solve how to compile from same sources to both targets.
1075 The build system should allow to call make for particular source
1076 subdirectory. Time of recursive make through all subdirectories is
1079 Make system should enable to build out of sources tree (else clean or
1080 working with CVS sandbox gets fussy and simultaneous multiple targets
1083 It would be good, if there is a possibility to call make from
1084 read-only media sources.
1086 Make system should store results of build in some separate directory
1087 structure to simple install and testing.
1089 Makefiles in sources directories should be simple.
1092 There is probably only one alternative fully supporting above requirements
1093 and it is GNU Autoheader...Automake...Autoconf... system.
1094 But it is complicated and requires big amount of support files.
1095 It would be acceptable if it could be easily used for OCERA framework.
1096 But there are important show stoppers for that system:
1099 It would require deep revision of all OCERA CVS contents and agreement
1100 on this would be problematic
1102 This system is not well prepared for dual compilation for Linux and
1103 RT-Linux sub-targets. It would mean many changes in default autoconf
1104 setup to support this. Probably simplest way would be to rebuild GCC
1105 tool chain for something like i586-elf-rtlinux. This would require
1106 even more space for OCERA development.
1109 The problem calls for some solution, which would have minimal impact
1110 on other components and would be elegant and would be maintainable
1111 and small, because our main goal is components development and not
1112 make systems development.
1114 There is result of our trial. It is OMK make system.
1115 The @file{Makefile} and @file{Makefile.omk} files should be in all source
1116 directories. Common @file{Makefile.rules} file is required in the toplevel
1117 sources directory. Alternatively this file could be moved
1118 to link tree pointing into readonly media or can be anywhere
1119 else if @code{MAKERULES_DIR} and @code{SOURCES_DIR} are specified.
1121 @c !!! tohle tam nejak zmizelo, mozna by to chtelo skontrolovat, ze to
1122 @c sedi s aktualnim stavem
1125 Syntax of Makefile.omk files is for usual cases compatible
1126 to Automake's Makefile.am descriptions. There are specific targets
1127 for RT-Linux and Linux kernel related stuff
1129 Makefile.omk user defined variables
1132 list of subdirectories intended for make from actual directory
1134 list of the user-space libraries
1135 @item shared_LIBRARIES
1136 list of the user-space shared libraries
1137 @item kernel_LIBRARIES
1138 list of the kernel-space libraries
1139 @item rtlinux_LIBRARIES
1140 list of the RT-Linux kernel-space libraries
1141 @item include_HEADERS
1142 list of the user-space header files
1143 @item nobase_include_HEADERS
1144 headers copied even with directory part
1145 @item kernel_HEADERS
1146 list of the kernel-space header files
1147 @item rtlinux_HEADERS
1148 list of the RT-Linux kernel-space header files
1150 list of the require binary programs
1151 @item utils_PROGRAMS
1152 list of the development utility programs
1153 @item kernel_MODULES
1154 list of the kernel side modules/applications
1155 @item rtlinux_MODULES
1156 list of RT-Linux the kernel side modules/applications
1158 list of specific target sources
1160 additional include directories and defines for user-space
1161 @item kernel_INCLUDES
1162 additional include directories and defines for kernel-space
1163 @item rtlinux_INCLUDES
1164 additional include directories and defines for RT-Linux
1165 @item default_CONFIG
1166 list of default config assignments CONFIG_XXX=y/n ...
1169 The Makefile is same for all sources directories and is only 14 lines
1170 long. It is there only for convenience reasons to enable call "make"
1171 from local directory. It contains code which locates
1172 @file{Makefile.rules} in actual or any parent directory. With standard
1173 BASH environment it works such way, that if you get into sources
1174 directory over symbolic links, it is able to unwind yours steps back
1175 => you can make links to readonly media component directories, copy
1176 @file{Makefile.rules}, Makefile and toplevel Makefile.omk, adjust
1177 Makefile.omk to contain only required components and then call make in
1178 top or even directories after crossing from your tree to readonly
1181 The system compiles all files out of source directories. The actual
1182 version of system is adapted even for OCERA tree mode if
1183 @code{OCERA_DIR} variable is defined in @file{Makefile.rules}
1185 There are next predefined directory name components, which can be
1189 @item BUILD_DIR_NAME = _build
1190 prefix of directory, where temporary build files are stored
1191 @item COMPILED_DIR_NAME = _compiled
1192 prefix of directory, where final compilation results are stored
1193 @item GROUP_DIR_NAME = yyy
1194 this is used for separation of build sub-trees in OCERA environment
1195 where more @file{Makefile.rules} is spread in the tree
1198 Next directories are used:
1201 @item KERN_BUILD_DIR := $(MAKERULES_DIR)/$(BUILD_DIR_NAME)/kern
1202 directory to store intermediate files for kernel-space targets
1203 @item USER_BUILD_DIR := $(MAKERULES_DIR)/$(BUILD_DIR_NAME)/user
1204 directory to store intermediate files for user-space targets
1206 @item USER_INCLUDE_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/include
1207 directory to store exported include files which should be installed later
1208 on user-space include path
1209 @item USER_LIB_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/lib
1210 same for user-pace libraries
1211 @item USER_UTILS_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/bin-utils
1212 utilities for testing, which would not probably be installed
1213 @item USER_BIN_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/bin
1214 binaries, which should go into directory on standard system PATH
1215 (/usr/local/bin, /usr/bin or $(prefix)/bin)
1217 @item KERN_INCLUDE_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/include-kern
1218 directory to store exported include files which should be installed later
1219 on kernel-space include path
1220 @item KERN_LIB_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/lib-kern
1221 same for kernel-pace libraries
1222 @item KERN_MODULES_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/modules
1223 builded modules for Linux kernel or RT-Linux system
1226 There is more recursive passes through directories to enable
1227 mutual dependant libraries and binaries to compile.
1228 Next passes are defined
1231 @item default-config
1232 generates @file{config.omk-default} or xxx-default (FIXME) configuration file
1234 checks and creates required build directories
1236 copies header files to @code{USER_INCLUDE_DIR} and @code{KERN_INCLUDE_DIR}
1238 builds objects in USER_BUILD_DIR/@var{relative path} and creates libraries
1240 @item binary-pass and utils-pass
1241 links respective binaries in USER_@{BIN,UTILS@}_DIR directory. If some
1242 object file is missing it compiles it in USER_BUILD_DIR/@var{relative path}
1243 @item kernel-lib-pass
1244 builds libraries for kernel space targets
1246 builds kernel modules
1249 The amount of passes is relatively high and consumes some time. But
1250 only other way to support all required features is to assemble one big
1251 toplevel Makefile, which would contain all components and targets
1254 Drawbacks of designed make system
1257 the system is not as fast as we would like
1259 it lacks Autoconf and configure extensive support for many systems
1260 from UNIX to DOS and WINDOWS
1262 it does not contain support for checking existence of target
1263 libraries and functionalities as GNU Autoconf
1265 it is heavily dependant on GNU MAKE program. But it would not be big
1266 problem, because even many commercial applications distribute GNU MAKE
1267 with them to be able to work in non-friendly systems
1269 the key drawback is dependence on recent MAKE version 3.80 and better
1270 and even version 3.80 of MAKE has important bug, which has been
1271 corrected in newer sources (FIXME)
1274 The last point is critical. I have not noticed it first, because
1275 I use Slackware-9.2 and it contains latest released version
1276 of MAKE (version 3.80).
1277 The problem appears when I have tried to build bigger libraries.
1278 There is bug in version 3.80, which results in misleading
1279 error "Virtual memory exhausted". It is known bug with ID 1517
1282 * long prerequisite inside eval(call()) => vm exhausted, Paul D. Smith
1286 I have optimized some rules to not push memory to the edge,
1287 but there could be still issues with 3.80 version.
1289 I have downloaded latest MAKE CVS sources. The compilation required
1290 separate lookup and download for .po files and full Autoheader... cycle.
1291 I have put together package similar to release. Only ./configure --prefix=...
1292 and make is required. CVS sources contains version 3.81beta1.
1293 You can download prepared sources archive from
1294 @indicateurl{http://paulandlesley.org/make/make-3.81beta1.tar.bz2}
1295 Or you can get our local copy from
1296 @indicateurl{http://cmp.felk.cvut.cz/~pisa/can/make-3.81beta1.tar.gz}
1298 The archive contains even "make" binary build by me, which should work
1299 on other Linux distributions as well. Older version of MAKE (3.79.x
1300 released about year 2000) found on Mandrake and RedHat are not
1301 sufficient and do not support eval feature. I do not expect, that
1302 Debian would be more up-to-date or contain fixes to MAKE vm exhausted
1305 The local CTU archive with our CAN components prepared for inclusion
1306 into OCERA SF CVS could be found in my "can" directory
1308 @indicateurl{http://cmp.felk.cvut.cz/~pisa/can/ocera-can-031212.tar.gz}
1310 The code should build for user-space with new make on most of Linux distros
1311 when make is updated.
1313 If you want to test compile for RT-Linux targets, line
1316 #RTL_DIR := /home/cvs/ocera/ocera-build/kernel/rtlinux
1319 in @file{Makefile.rules} has to be activated and updated
1320 to point RT-Linux directory containing "rtl.mk".
1321 There is only one library ("ulutrtl") and test utility compiled for RT-Linux
1322 (@file{can/utils/ulut/ul_rtlchk.c}).
1324 The next line, if enabled, controls compilation in OCERA project tree
1327 #OCERA_DIR := $(shell ( cd -L $(MAKERULES_DIR)/../../.. ; pwd -L ) )
1330 The LinCAN driver has been updated to compile out of source directories.
1332 Please, check, if you could compile CAN package and help us with integration
1333 into OCERA SF CVS. Send your comments and objections.
1335 The OMK system has been adapted to support actual OCERA configuration process.
1336 I am not happy with ocera.mk mix of defines and poor two or three rules,
1337 but OMK is able to overcome that.
1339 The OMK system has integrated rules (default-config) to build default
1340 configuration file. The file is named @file{config.omk-default} for
1341 the stand-alone compilation. The name corresponds to OCERA config +
1342 "-default" if OCERA_DIR is defined. This file contains statements
1343 from all @code{default_CONFIG} lines in all @file{Makefile.omk}. The
1344 file should be used for building of own @file{config.omk} file, or as
1345 list for all options if Kconfig is used.
1347 @c @chapter OMK Reference
1349 @node OMK Development, Variable Index, Original README, Top
1350 @chapter OMK Development
1354 @node Variable Index, , OMK Development, Top
1355 @unnumbered Variable Index
1359 @c @node Concept Index, , Variable Index, Top
1360 @c @unnumbered Concept Index