1 \input texinfo @c -*-texinfo-*-
3 @setfilename omk-manual
4 @documentencoding UTF-8
5 @settitle OMK: Ocera Make System
9 Manual for Ocera Make System (OMK) version @include .version
11 Copyright @copyright{} 2007, 2008, 2009, 2010, 2011 Michal Sojka, Pavel Pisa
15 @title Ocera Make System Manual
17 @vskip 0pt plus 1filll
24 @node Top, Overview, (dir), (dir)
25 @top Ocera Make System
39 @node Overview, User's Manual, Top, Top
43 OMK is an advanced make system written entirely in GNU make. Compiling
44 software using OMK requires only GNU Make and standard UNIX
45 utilities (@command{sh}, @command{sed}, @command{cmp}, ...)
46 installed. OMK aims to be developer friendly; to use OMK, you do not
47 need to understand (sometimes) cryptic syntax of Makefiles.
49 You can use OMK on all platforms where you can run GNU Make including
50 Cygwin and MinGW. MS DOS was not tested.
56 @c Easy to use for beginners.
58 @c Automatic handling of dependencies.
60 @c Supported host platforms: all Un*x operating system including Linux,
61 @c Cygwin, MS DOS and maybe others.
70 @node Why to Use OMK?, Quick Start, Overview, Overview
71 @section Why to Use OMK?
73 Here we list some of OMK features, which we think are important for
74 choosing of a make system.
79 Makefile in source directories are usually very @b{simple}.
81 There is only @b{one} @file{Makefile.rules} for most of components of
84 OMK greatly simplifies compilation of projects, where source files are
85 spread between @b{multiple directories}.
87 OMK handles properly @b{dependencies} of source files and libraries,
88 so it is not necessary to recompile the whole project if only several
91 OMK allows to freely @b{move} cross-dependant components @b{in
92 directory structure} without the need to update users of moved
93 component. I hate something like
94 @option{-I../../sched/rtlshwq/include} in makefiles for example. If a
95 component is renamed or version is added to the name, many Makefiles
96 in the project would require an update.
98 The above feature is very helpful in @b{combining components}
99 (libraries) from different projects/developers to a single project by
100 simply creating symbolic links to external components.
102 Compilation of an OMK based projects don't require to install any
103 files before successful finish of build.
105 OMK allows to call @command{make} for a particular subdirectory in the
108 Under OMK all products of compilation are stored @b{out of source
109 directories}. This simplifies work with version control systems and
110 helps when simultaneous compilation for multiple targets/platforms is
117 @node Quick Start, History, Why to Use OMK?, Overview
120 If you get some sources, which are distributed with OMK, usually the
121 following commands are sufficient to compile the whole project.
130 @noindent To use OMK in your own project, follow these steps:
134 The newest version of OMK can be found at @uref{http://rtime.felk.cvut.cz/omk/}.
136 Take appropriate @file{Makefile.rules} (see @ref{Properties of
137 Specific Makefile.rules}), put it together with leaf @file{Makefile}
138 to the root directory of your project.
140 Create @file{Makefile.omk} files in all directories you want to
141 compile something. Please refer to @ref{User's Manual} to learn
142 what to write in @file{Makefile.omk} files.
144 Run @command{make omkize} in the root directory.
147 @noindent Your project is now ready to compile.
150 @node History, , Quick Start, Overview
153 OMK was originally written by Pavel Píša as a solution to have one
154 common make system for OCERA project, where we needed to compile
155 user-space programs, Linux kernel modules and RT Linux modules in one
156 package. Although this system was not accepted for the whole OCERA
157 project. Several individual developers (mostly from Czech Technical
158 University) liked it and started to use it.
160 As a number of projects using OMK grew it was necessary to modularize
161 the make system to support more ``targets''. Michal Sojka took care
162 about the process of modularization.
164 @node User's Manual, Original README, Overview, Top
165 @chapter User's Manual
170 * Compiling Programs::
171 * Compiling Libraries::
172 * Recursing into Subdirectories::
173 * Dependency Tracking::
174 * Configuration and Conditional Compilation::
175 * Advanced OMK Features::
176 * Properties of Specific Makefile.rules::
177 * Running OMK under Windows OS::
178 * Interfacing OMK to popular IDEs::
182 @node Basic Concepts, Invoking OMK, User's Manual, User's Manual
183 @section Basic Concepts
185 The main concept of OMK is very simple. In the root directory of the
186 projects resides a file called @file{Makefile.rules}. This file contains
187 all compilation rules needed for compilation of a particular
188 project. There are different @file{Makefile.rules} for different
189 platforms (Unix, RTEMS, system-less, ...). In every subdirectory a
190 @file{Makefile.omk} is stored. This file determines what should be done
191 in the respective directory (e.g. compile a program from several source
192 files). Its syntax is very simple -- see the following sections.
194 Since make searches by default for a @file{Makefile} and not for
195 @file{Makefile.rules} or @file{Makefile.omk}, there must@footnote{When
196 USE_LEAF_MAKEFILES is set to @samp{n}, this @file{Makefile} can be
197 omitted in subdirectories. @xref{USE_LEAF_MAKEFILES}.} be a small
198 generic @file{Makefile} in every directory, whose task is only to find
199 @file{Makefile.rules} in the actual or any parent directory and include
200 it. This search is performed only once at the beginning of compilation.
202 @c TODO: Pavel's note about qmake.
205 The compilation process itself is comprised of several @emph{passes}. Every
206 pass traverses the whole directory structure@footnote{In future, we are
207 planning some optimization that allows OMK to traverse the directories
208 only once and thus decrease compilation time.} and does a particular
209 task in every directory of the project. Typically, these passes are:
211 @anchor{include-pass}
213 This pass takes all include files marked for ``export'' and copies
214 (or links) them to the @file{include} directory under
215 @file{_compiled} directory. @xref{Header Files}.
217 Also, during this pass, automatically generated header file are
218 generated according to the current
219 configuration. @xref{Configuration and Conditional Compilation}.
221 During this pass, all include files are in place, so all libraries
224 Finally, programs can be compiled and linked against libraries
225 created in the previous pass.
228 The results of compilation are stored under the @file{_compiled}
229 directory. This directory is structured as a classical Unix file-system
230 (it contains directories like @file{bin}, @file{lib} and @file{include})
231 and can be directly copied to the target device or to some directory on
232 a host computer (e.g. @file{/usr/local}).
234 Besides @file{_compiled} directory, there in a @file{_build}
235 directory. Under this directory are stored some temporary files and
236 intermediate compilation products (object files, dependency files etc.).
238 In the next section, we provide an overview of methods, how to invoke
239 OMK from command line. Section @ref{Interfacing OMK to popular IDEs}
240 covers running of OMK from popular IDEs.
242 Sections @ref{Compiling Programs} through @ref{Configuration and
243 Conditional Compilation} deals with the content of
244 @file{Makefile.omk}. Its syntax in usual cases compatible to GNU
245 Automake's @file{Makefile.am} syntax. Also, the scheme for naming
246 variables was inspired by Automake so most OMK variables have the name
247 like @samp{@var{target}_@var{TYPE}}.
249 @node Invoking OMK, Compiling Programs, Basic Concepts, User's Manual
250 @section Invoking OMK
252 Before using OMK for the first time, you have to call:
254 @command{make default-config}
256 @noindent See @ref{Configuration and Conditional Compilation} for
257 details. If you forget to do this, OMK will notice you.
259 To compile the whole project or only some subtree of the project, call
263 @noindent in the appropriate directory.
265 To clean files in @file{_build} directory but not in @file{_compiled}
271 To clean the compilation completely, you can either remove
272 @file{_compiled} and @file{_build} directories manually, or call
274 @command{make distclean}
276 @noindent which does the same. This command removes these directories
277 even if you call it from a subdirectory.
279 To debug compilation problems, you can use @code{V} variable (see
285 You can also set values of some other variables on command line for
286 temporary change something. The example below compiles the code
287 temporarily with debugging information:
289 @command{make CFLAGS="-g -O0 -Wall"}
292 If your project uses an alternative make-system (e.g. Automake or custom
293 makefiles), it might be useful for you to use the command:
295 @command{make omkize}
297 @noindent This will find all @file{Makefile.omk} files in all subdirectories
298 and copies generic @file{Makefile} from the root directory to that
299 subdirectories. This way you can easily switch your project to use OMK.
305 If this variable equals to @samp{1}, the whole command lines for all
306 executed commands are displayed. When not set or zero, only short
307 messages are printed. Value of @samp{2} displays the whole command lines
308 as with @samp{1} and in addition directory navigation messages are
312 @node Compiling Programs, Compiling Libraries, Invoking OMK, User's Manual
313 @section Compiling Programs
315 To tell OMK to compile a program, you need to set some variables in
316 @file{Makefile.omk} (usually) in the directory where program sources are
319 In the example bellow a program @command{test} will be compiled from
320 source @file{test.c}.
323 @verbatiminclude ../tests/programs/Makefile.omk
326 @noindent The variables are:
328 @anchor{bin_PROGRAMS}
330 Contains a list of names (whitespace separated) of programs to be
331 compiled in this directory.
334 @anchor{test_PROGRAMS}
335 @defvar test_PROGRAMS
336 Almost the same as @ref{bin_PROGRAMS}, but resulting binaries are
337 stored in @file{bin-tests} directory instead of @file{bin}. This
338 variable is intended for various test programs not to be mixed with
342 @defvar utils_PROGRAMS
343 Almost the same as @ref{bin_PROGRAMS}, but resulting binaries are
344 stored in @file{bin-utils} directory instead of @file{bin}. This
345 variable is intended for various development utilities not to be mixed
346 with the final product.
350 For every program name @var{xxx} in @code{bin_PROGRAMS},
351 @code{test_PROGRAMS} or @code{utils_PROGRAMS}, this variable contains
352 a list of sources that are needed to compile the program. OMK uses an
353 extension of the filename to determine the compiler to compile this
358 This variable contains a list of libraries the program @var{xxx} will
366 @defvar lib_LOADLIBES
367 This variable contains a list of libraries which needs to be linked to
368 to all programs or shared libraries in this directory.
372 This variable contains a list linker switches to load additional
373 libraries. You usually specify here -L and -l switches.
375 Note: The value of this variable is not used used by OMK for any purpose
376 other than linker invocation. Therefore dependency handling of shared
377 libraries does not work if the library is specified in LOADLIBES
378 instead of lib_LOADLIBES.
382 Directives passed to the C or C++ compiler with additional directories
383 to be searched for header files. In most cases you need to specify an
384 absolute path. To specify a directory relative to the source
385 directory, you can use the @code{$(SOURCES_DIR)} variable, which
386 refers to the directory, where @file{Makefile.omk} is located. This
387 variable applies to all compilations invoked in the current directory.
390 INCLUDES = -I$(SOURCES_DIR)/my_include_dir
395 Directives passed to the C or C++ compiler with preprocessor macro
396 definitions. This variable applies to all compilations invoked in the
405 @c FIXME: INCLUDES variable should not be set by rtlinux rules.
407 @node Compiling Libraries, Recursing into Subdirectories, Compiling Programs, User's Manual
408 @section Compiling Libraries
411 With OMK, you can easily create statically or dynamically linked
412 libraries. The way of creating libraries is very similar to how programs
413 are created. @xref{Compiling Programs}.
415 In @file{Makefile.omk}, you specify several variables, which defines how
416 the libraries should be compiled. In the example below the library
417 @samp{mylib} (full filename will be @file{libmylib.a}) is created from
418 two sources @file{funca.c} and @file{funcb.c}. Interface of this library
419 is defined in @file{myfunc.h}. Therefore, we export this header for use
423 @verbatiminclude ../tests/libraries/Makefile.omk
426 @noindent Variables for use with libraries are:
428 @defvar lib_LIBRARIES
429 Specifies a list of statically linked libraries to be compiled. OMK
430 automatically prepends @code{lib} prefix library names.
433 @defvar shared_LIBRARIES
434 Specifies a list of dynamically linked libraries to be compiled.
438 For every library name @var{xxx} in @code{lib_LIBRARIES} or
439 @code{shared_LIBRARIES}, this variable contains a list of sources that
440 are needed to compile the library. OMK uses an extension of the
441 filename to determine the compiler to compile this source.
448 @node Header Files, , Compiling Libraries, Compiling Libraries
449 @subsection Header Files
451 C and C++ libraries are not very useful without header files. OMK
452 provides several variables that controls operations with header files.
454 During compilation, header files are copied (or linked by symbolic
455 links) from source directories to the @file{_compiled} tree (see
456 @ref{include-pass}). Libraries and programs are then compiled against
457 these copies. The following variables control which headers are copied
458 and what is their destination file name.
460 @anchor{include_HEADERS}
461 @defvar include_HEADERS
462 Specifies the list of header files to be exported for use by other
463 libraries/programs. The files are exported directly to the
464 @file{include} directory even if the file is located in a subdirectory
465 (like @file{sci_regs.h} in the example below)
468 include_HEADERS = regs.h periph/sci_regs.h
472 @defvar nobase_include_HEADERS
473 Similar to @ref{include_HEADERS}, but the directory prefix is always
474 kept. To include the file exported by this variable, use
475 @code{#include <@var{prefix}/@var{header.h}>}.
478 @defvar renamed_include_HEADERS
479 Exports the header files under different name. The form of the items
480 in this whitespace separated list is: @var{real name}@code{->}@var{new
484 renamed_include_HEADERS = orte_config_omk_win32.h->orte_config.h
489 If this variable equals to @samp{y}, symbolic links to headers in
490 source directories are used in @file{_compiled} tree instead of
493 Normally, the header files are copied into @file{_compiled} directory
494 to be prepared for transfer into target location afterwards. Copying
495 ensures that resulting libraries are in correspondence with the header
496 files even if the header is changed by a developer but the library is
499 @c Another reason for having single include directory for the whole
500 @c project is tat every component knows where to find header files of
503 On the other side, the copying could make problems during
504 development. Most @acronym{IDE}s, allows you to jump directly to the
505 place, where an error is reported by the compiler. If the error is in
506 a header file, IDE opens you the copy of the header file. If you
507 correct the error there, after the next compilation, your header file
508 will be overwritten by the old version from your source tree.
510 This option is not typically used in @file{Makefile.omk}, but in the
511 top level configuration file @file{config.omk} or on command line.
514 @node Recursing into Subdirectories, Dependency Tracking, Compiling Libraries, User's Manual
515 @section Recursing into Subdirectories
517 OMK is probably most useful in projects consisting of multiple
518 directories. For such projects, it is not easy to write from scratch
519 classic Makefiles that provides all the needed features.
521 You can instruct OMK to descend to a (sub)directory by setting the
522 @code{SUBDIRS} variable in @file{Makefile.omk}.
526 This variable contains a list of directories, in which compilation
527 must be also invoked. Usually, names of subdirectories are used, but
528 you can use any path specification here.
530 Compilation is invoked in these directories before it is invoked in
531 the current directory.
533 See also @ref{AUTOMATIC_SUBDIRS}.
535 @c TODO: Write tests for this.
537 @anchor{ALL_OMK_SUBDIRS}
538 @defvar ALL_OMK_SUBDIRS
539 This variable is set by OMK and can be used as the value of
540 @code{SUBDIRS} variable. It contains a list of all direct
541 subdirectories, which contain @file{Makefile.omk}. This is especially
542 useful if you are combining several projects or components
543 together. In the root directory of your project, you just create
544 symbolic links the components from other projects and all the linked
545 directories automatically appears as the value of this variable.
548 SUBDIRS = $(ALL_OMK_SUBDIRS)
552 @anchor{AUTOMATIC_SUBDIRS}
553 @defvar AUTOMATIC_SUBDIRS
554 If this variable is set to @samp{y} and @code{SUBDIRS} is not assigned
555 in @file{Makefile.omk}, then @code{SUBDIRS} is assigned a default
556 value @code{$(ALL_OMK_SUBDIRS)}.
559 @node Dependency Tracking, Configuration and Conditional Compilation, Recursing into Subdirectories, User's Manual
560 @section Dependency Tracking
562 OMK automatically tracks dependencies of files in the project.
563 Dependencies of object files are produced with gcc's @option{-M@var{x}}
564 options. This means that whenever a header file is changed, OMK
565 recompiles only those files, which included that file.
567 Dependencies are also maintained for libraries and binaries. To find the
568 dependencies, OMK parses linker map files, so a change to some library
569 causes relinking of all programs using that library.
571 @node Configuration and Conditional Compilation, Advanced OMK Features, Dependency Tracking, User's Manual
572 @section Configuration and Conditional Compilation
574 In many projects, it is necessary to configure the compilation process. By
575 this configuring we mean, setting some parameters that influence the
576 output of compilation process. In GNU projects, @command{configure}
577 script is usually responsible for configuration. User provides some
578 parameters to @command{configure}, which is run before compilation, and
579 this script does all steps needed to configure the sources and
580 make-system in the desired way.
582 OMK has its own configuration mechanism, which is described in this
583 section. For future releases, we plan that this mechanism can make use
584 of GNU Autoconf, but currently there is no directly integrated support
587 There exist three different configuration files
588 @file{config.omk-default}, @file{config.target} and
589 @file{config.omk}. All of these have to be stored in the same directory
590 as @file{Makefile.rules}. During compilation, these files are included
591 in @file{Makefile.rules} in this order which means that variables
592 assigned in the former files are overridden by those from later
593 ones. All settings specified here apply to the whole compilation
594 tree. Each file is intended for a different kind of configuration
597 @item config.omk-default
598 Stores default configuration of compiled components. This file is
599 automatically generated (see below) and should not be edited by users.
601 Stores default configuration for a project or target hardware. This
602 file is intended to be stored in a version control system and should
603 be modified only by the maintainer of the project.
605 For cross compiled projects, this file typically contains settings of
606 variables like @var{CC} and @var{CFLAGS}.
608 This is a file for end users, where any default settings set in the
609 above files can be overridden. This file should not be stored in
610 version control system. The project should compile without having this
614 Besides variables defined in @file{config.target}, @file{Makefile.omk}
615 in any subdirectory can specify some configuration parameters. When
616 @command{make default-config} is run, all these parameters are found and
617 together with their default values are stored as makefile variables in
618 @file{config.omk-default}. This file is included during compilation, so
619 if you don't specify other values, these defaults are used. If you are
620 not satisfied with these defaults, you can override the values of
621 parameters either locally for your build in @file{config.omk} or
622 globally for all people working with the project in
623 @file{config.target}.
626 * Specifying Configuration Parameters::
627 * Using Configuration Parameters::
631 @node Specifying Configuration Parameters, Using Configuration Parameters, Configuration and Conditional Compilation, Configuration and Conditional Compilation
632 @subsection Specifying Configuration Parameters
634 To specify names and default values of configuration parameters use the
635 @code{default_CONFIG} variable in @file{Makefile.omk}.
637 @defvar default_CONFIG
638 This variable contains a list of configuration parameters and their
639 default values. The format of every item in this list is
640 @var{CONFIG_xxxx}=@var{value}. You can name the parameter as you want,
641 but it is good practice to start the name with @samp{CONFIG_} prefix.
643 OMK can automatically generate header files, with C preprocessor macro
644 definitions according to the OMK's configuration parameters. The
645 actual content of generated header files depends on the form of the
646 @var{value}. The possible forms are:
649 @item @samp{y}, @samp{n} or @samp{x}
650 This defines boolean parameters. If the value of the parameter is
651 @samp{y}, the @samp{#define CONFIG_@var{xxx} 1} is generated, if it is
652 @samp{n}, no @code{#define} is generated.
654 @samp{x} is a special value called @emph{recessive 'n'}. The meaning
655 is that this parameter influences the component in the current
656 directory (i.e. the corresponding @code{#define} will be included in
657 @code{LOCAL_CONFIG_H}; see @ref{LOCAL_CONFIG_H}) but the default value
658 is not specified here. If the default value is not specified anywhere,
659 the behavior is the same as if @samp{n} is specified.
661 Numeric parameters. The define looks like @samp{#define CONFIG_@var{xxx} @var{number}}
663 Text without quotes. The define looks like @samp{#define CONFIG_@var{xxx} @var{text}}
665 Text with quotes. The define looks like @samp{#define CONFIG_@var{xxx} "@var{text}"}
669 @noindent Example of using @code{default_CONFIG}. @file{Makefile.omk} reads like:
671 @verbatiminclude ../tests/config/default/Makefile.omk
673 @noindent and @file{subdir/Makefile.omk} like:
675 @verbatiminclude ../tests/config/default/subdir/Makefile.omk
678 @noindent After running @command{make default-config}, the content of
679 @file{config.omk-default} will be:
681 @verbatiminclude ../tests/config/default/config.omk-correct
684 @node Using Configuration Parameters, Common Variables, Specifying Configuration Parameters, Configuration and Conditional Compilation
685 @subsection Using Configuration Parameters
687 Configuration parameters can be used in two ways:
690 as variables in @file{Makefile.omk} and
692 as C/C++ preprocessor macros in OMK generated header files.
695 @noindent For the first use, your @file{Makefile.omk} may contain something like:
697 SUBDIRS = arch/$(CONFIG_ARCH)
699 ifeq ($(CONFIG_DEBUG),y)
700 DEFS += -DUSE_SIMULATOR
704 @noindent For the second use, there are several variables that control
705 the generation of header files with configuration values. These
706 variables are described here:
708 @anchor{LOCAL_CONFIG_H}
709 @defvar LOCAL_CONFIG_H
710 The value of this variable is the name of a header file, which will
711 contain all configuration parameters declared in the current directory
712 by @code{default_CONFIG}. This header file is accessible only by files
713 in the current directory and it should be included like @code{#include
716 In @file{Makefile.omk}, the use of this variable can look like this:
719 LOCAL_CONFIG_H = myconfig.h
723 @defvar config_include_HEADERS
724 This variable is similar to @code{LOCAL_CONFIG_H}. One difference is
725 that the generated header file is accessible to all sub-projects in
726 all directories, not only to the files in the same directory (the
727 header is stored in @file{_compiled} tree). The second difference is
728 that you have to specify, which configuration parameters you want to
729 appear in the header file.
733 This variable determines the configuration parameters that should be
734 stored in a header file specified by
735 @code{config_include_HEADERS}. The @var{xxx} in the name of this
736 variable needs to be the same as the base name (without extension) of
740 @noindent Example of using @code{config_include_HEADERS}:
742 default_CONFIG = CONFIG_LINCAN=y CONFIG_LINCANRTL=n CONFIG_LINCANVME=n
743 config_include_HEADERS = global.h
744 global_DEFINES = CONFIG_OC_LINCAN CONFIG_OC_LINCANRTL
747 @noindent Here, we include only two out of the three configuration
748 parameters defined in the current @file{Makefile.omk}. It is also
749 possible to include configuration parameters defined in a different
752 @node Common Variables, , Using Configuration Parameters, Configuration and Conditional Compilation
753 @subsection Common Variables
755 It is common practice to use @file{config.target} or @file{config.omk}
756 to store project-wide settings. Here is the list of variables, which are
757 commonly set here (but they can also be set elsewhere, e.g. in
758 @file{Makefile.omk}).
760 You can easily ``reconfigure'' your project by changing the
761 @file{config.omk} file. It is useful to have several configurations
762 stored in different files and let @file{config.omk} be a symbolic link
763 to the desired configuration.
767 The name of C compiler.
769 Command line options for C compiler.
771 The name of C++ compiler.
773 Additional parameters (besides @code{CFLAGS}) to by passed to C++
777 @node Advanced OMK Features, Properties of Specific Makefile.rules, Configuration and Conditional Compilation, User's Manual
778 @section Advanced OMK Features
780 In this section we list several OMK features, which are more complicated
781 or rarely used so they were omitted in previous sections.
784 * Organization of the Source Tree::
785 * Additional Variables::
786 * Adding Hooks to Passes::
787 * Integration of Wvtest Framework::
790 @node Organization of the Source Tree, Additional Variables, Advanced OMK Features, Advanced OMK Features
791 @subsection Organization of the Source Tree
795 The @file{_compiled} directory can be shared between multiple projects
796 (by using symbolic links).
799 If you work on a bigger project, you usually don't need to rebuild the
800 whole project and call @command{make} only in a
801 subdirectory. Sometimes, it might be useful to rebuild the whole
802 project. You can either change working directory to the root of your
803 project and call @command{make} there or, as a shortcut, you can use
804 @code{W} variable (see @ref{W}) to compile everything directly from a
811 Searching for @file{Makefile.rules} works such way, that if you get
812 into sources directory over symbolic links, OMK is able to unwind your
813 steps back. This implies you can make links to component directories
814 on read-only media, copy @file{Makefile.rules}, @file{Makefile} and
815 top-level @file{Makefile.omk}, adjust @file{Makefile.omk} to contain
816 only required components and then call @command{make} in the top
817 directory or even in read-only directories after changing working
818 directory from your tree to the readonly media.
824 If this variable equals to @samp{1}, the @b{whole} project is
825 (re)compiled, even if @command{make} is called from a subdirectory.
828 @node Additional Variables, Adding Hooks to Passes, Organization of the Source Tree, Advanced OMK Features
829 @subsection Additional Variables
831 @anchor{USE_LEAF_MAKEFILES}
832 @defvar USE_LEAF_MAKEFILES
833 If this variable equals to @samp{n} (default is unset), then OMK uses
834 the leaf @file{Makefile} only when it is invoked by simple
835 @command{make} command. Later, during recursive directory descent leaf
836 @file{Makefile} is not used and @file{Makefile.rules} is included
839 This feature is useful if you are integrating some non-OMK project into
840 your project. You only add @file{Makefile.omk} files to the non-OMK
841 project and don't need to modify project's original Makefiles.
843 This variable can be set either globally in a @file{config.*} file or
844 locally in some @file{Makefile.omk}. In the latter case, it influences
845 only subdirectories of the directory containing @file{Makefile.omk}.
850 This variable is set internally by OMK and its value is the absolute
851 path to the directory with compiled sources. It can be used if you need
852 to refer to sources files in some custom constructs in
856 include_HEADERS = $(notdir $(wildcard $(SOURCES_DIR)/*.h))
862 The same as @ref{SOURCES_DIR}. Provided for Automake compatibility.
865 @defvar{MAKERULES_DIR}
866 This variable is set internally by OMK and its value is the absolute
867 path to the directory containing @file{Makefile.rules} currently used
871 @defvar{OMK_RULES_TYPE}
872 Identification the type of @file{Makefile.rules} used for
873 compilation. Values are like @samp{linux}, @samp{rtems}, @samp{sysless},
874 ... This variable is automatically generated during creation of
875 @file{Makefile.rules} and can be used in configuration files (see
876 @ref{Configuration and Conditional Compilation}) or in
877 @file{Makefile.omk} to tweak compilation for specific targets.
880 @node Adding Hooks to Passes, Integration of Wvtest Framework, Additional Variables, Advanced OMK Features
881 @subsection Adding Hooks to Passes
883 Sometimes it is necessary to run some special commands as a part of
884 compilation. Typical example might be a tool which generates source
885 files on the fly. OMK supports calling additional commands during
886 compilation by so called @emph{pass hooks}. A pass hook is an ordinary
887 make target which is invoked as part of compilation during a particular
888 pass (see @ref{passes}). Pass hooks can be defined by assigning their
889 names to @code{xxx_HOOKS} variable.
892 Specifies one or more hooks (make targets) which are invoked during pass
893 @var{xxx}. The working directory of commands or this target is under the
896 In the example bellow header file @file{generated_header.h} is created
897 during @samp{include-pass} by @file{convert_data} program. The program
898 takes @file{data_file.txt} in the source directory as the input and
899 creates the header file in the in the correct directory under the
903 include-pass_HOOKS = generated_header.h
905 generated_header.h: $(SOURCES_DIR)/data_file.txt
906 convert_data < $^ > $@@
910 @node Integration of Wvtest Framework, , Adding Hooks to Passes, Advanced OMK Features
911 @subsection Integration of Wvtest Framework
913 OMK has integrated support for Wvtest unit testing framework (see
914 @uref{https://github.com/apenwarr/wvtest}).
916 @defvar wvtest_PROGRAMS
917 This variable is the same as @ref{test_PROGRAMS} with the exception that
918 the program is automatically executed by @command{make wvtest} (see
922 @defvar wvtest_SCRIPT
926 @command{make wvtest} TODO
930 @node Properties of Specific Makefile.rules, Running OMK under Windows OS, Advanced OMK Features, User's Manual
931 @section Properties of Specific Makefile.rules
933 In previous sections, general properties of @file{Makefile.rules} were
934 documented. This section contains documentation to features found only
935 in some particular @file{Makefile.rules}.
943 @node Linux, System-Less, Properties of Specific Makefile.rules, Properties of Specific Makefile.rules
946 This @file{Makefile.rules} is used not only for Linux as the name
947 suggests, but also for other Unices and even for Windows.
950 The name of the operating system (OS) where make was invoked.
954 Should specify the name of OS where the resulting binary should be
955 used. If not specified manually, it equals to BUILD_OS.
959 Lists subdirectories with QT project (.pro) file. OMK will generate
960 there @file{Makefile} by calling @command{qmake} with correct
961 parameters to interface QT application to the rest of the compilation
962 tree. Then @command{make} is called there to compile QT
963 application. Variable @samp{QTDIR} must be set to the directory with
964 QT installation (e.g. /usr/share/qt4 on Debian).
968 @node System-Less, RTEMS, Linux, Properties of Specific Makefile.rules
969 @subsection System-Less
971 This @file{Makefile.rules} is designed for compilation of code for
972 (small) micro-controllers without operating systems. See
973 @uref{http://rtime.felk.cvut.cz/hw/index.php/System-Less_Framework} for
974 more information about our framework, which uses this rules.
976 @node RTEMS, , System-Less, Properties of Specific Makefile.rules
982 @node Running OMK under Windows OS, Interfacing OMK to popular IDEs, Properties of Specific Makefile.rules, User's Manual
983 @section Running OMK under Windows OS
985 It is possible to use OMK under Windows OS with MinGW (see
986 @uref{http://www.mingw.org/}). Unfortunately, the compilation speed is
987 much lower than on UNIX systems.
989 TODO: Is it necessary to install anything special?
991 @node Interfacing OMK to popular IDEs, Troubleshooting, Running OMK under Windows OS, User's Manual
992 @section Interfacing OMK to popular IDEs
1000 @node KDevelop, Eclipse/CDT, Interfacing OMK to popular IDEs, Interfacing OMK to popular IDEs
1001 @subsection KDevelop
1003 KDevelop has support for custom build systems. To use KDevelop to
1004 develop projects using OMK follow these steps. These steps are valid for
1005 version 3.5.0 of KDevelop, but for previous versions it doesn't differ
1010 Import project to KDevelop (from menu choose @emph{Project---Import
1011 existing project}). Select the type of project to @emph{Generic C
1012 Application (Custom Buildsystem)}.
1018 Then answer to following dialogs as you want.
1023 @image{kdevelop3} @image{kdevelop4}
1027 If you are working only on some small part of the bigger project, you
1028 usually don't want to recompile the whole project every time. In
1029 @emph{Project---Project Options}, you can specify the subdirectory where to
1036 If you want to switch between several configurations easily (see also
1037 @ref{Configuration and Conditional Compilation}), in the same dialog
1038 you can add @option{-e} to make options. This makes environment variables
1039 have higher precedence than those in @file{config.omk-default}. Then,
1040 you can define several environments with different
1041 @code{CONFIG_@var{xxx}} variables and their values.
1047 You can easily switch the configurations from @emph{Build---Make
1054 @node Eclipse/CDT, Emacs/Vim/etc., KDevelop, Interfacing OMK to popular IDEs
1055 @subsection Eclipse/CDT
1057 @node Emacs/Vim/etc., , Eclipse/CDT, Interfacing OMK to popular IDEs
1058 @subsection Emacs, VIM, etc.
1060 Since OMK compilation is started by executing @command{make} command,
1061 many common editors can work easily with OMK.
1063 Under Emacs, you can use @command{compile} or @command{recompile}
1064 commands as you are used to do.
1066 @node Troubleshooting, , Interfacing OMK to popular IDEs, User's Manual
1067 @section Troubleshooting & Knows Bugs
1071 If you rename some file or directory and then you can't compile your
1072 project, call @command{make clean} in the directory with errors. The
1073 reason for this behavior is that OMK remembers dependencies of every
1074 file. After renaming something, the original name is still stored in
1075 dependencies, but make doesn't know how to create this non-existent
1079 Sometimes, you may want to compile one file the same way as OMK does
1080 it, but run the compilation manually from command line. For example,
1081 you want to debug some preprocessor macros and you only want to
1082 produce preprocessed source instead of an object file.
1084 To compile something manually, you can run OMK by @command{make
1085 V=2}. This will print all commands executed together with directory
1086 navigation messages. Find the command you want to execute manually in
1087 the output. To run it, you need to change the working directory to the
1088 correct one in the @file{_build} tree. The correct directory can be
1089 found in make output on the line @samp{Entering directory} preceding
1090 the desired command.
1093 Currently, C++ sources are supposed to have @file{.cc} or @file{.cxx}
1094 extensions. The @file{.cpp} extension is not supported (yet).
1097 Removing of library source file does not cause the library to be
1098 rebuild. You need to manually delete the library or run @command{make
1099 distclean} before you run @command{make}.
1102 @node Original README, Development, User's Manual, Top
1103 @chapter Original README
1105 Since this manual still doesn't cover all aspects of OMK, we include
1106 here a @file{README.rules} file, which was written for the first version
1109 @b{Important notice:} This make system uses features found in recent
1110 versions of GNU Make program. If you encounter problems with package
1111 building, check, that you use correct version of Make program. The
1112 Make older than version 3.80, could not be used. Even Make version
1113 3.80 has annoying bug which causes building fail with misleading
1114 message "virtual memory exhausted". Please, upgrade at least to
1115 version 3.81 of GNU Make.
1117 There is list of features which we want to solve with our make system:
1120 Central @file{Makefile.rules} for most of components of a bigger project.
1122 FIXME (our CAN framework includes more libraries common with our other
1123 projects, we need to separate some utility libraries etc.)
1125 The rules in more spread Makefiles are way to the hell (update for
1126 different kernel, RT-Linux etc would be nightmare in other case).
1128 Make system should allow to freely move cross-dependant components in
1129 directory structure without need to update users of moved component (I
1130 hate something like @option{-I../../sched/rtlshwq/include} in CAN makefiles for
1131 example. If a component is renamed or version is added to then name,
1132 all Makefiles in CAN will require update).
1134 Make system should be able to compile mutually cross-dependant
1135 libraries and should ensure, that change in one component sources or
1136 headers would result in relink or rebuild in components linked against
1137 that library or including modified header file.
1139 Make system has to enable compilation out of OCERA full source tree
1140 (we would lost many users of particular components in other case).
1142 Compile should be able to do all above work without need to install
1143 any files before successful finish of build.
1145 Because we use some libraries for RT-Linux build and user-space build,
1146 we need to solve how to compile from same sources to both targets.
1148 The build system should allow to call make for particular source
1149 subdirectory. Time of recursive make through all subdirectories is
1152 Make system should enable to build out of sources tree (else clean or
1153 working with CVS sandbox gets fussy and simultaneous multiple targets
1156 It would be good, if there is a possibility to call make from
1157 read-only media sources.
1159 Make system should store results of build in some separate directory
1160 structure to simple install and testing.
1162 Makefiles in sources directories should be simple.
1165 There is probably only one alternative fully supporting above requirements
1166 and it is GNU Autoheader...Automake...Autoconf... system.
1167 But it is complicated and requires big amount of support files.
1168 It would be acceptable if it could be easily used for OCERA framework.
1169 But there are important show stoppers for that system:
1172 It would require deep revision of all OCERA CVS contents and agreement
1173 on this would be problematic
1175 This system is not well prepared for dual compilation for Linux and
1176 RT-Linux sub-targets. It would mean many changes in default autoconf
1177 setup to support this. Probably simplest way would be to rebuild GCC
1178 tool chain for something like i586-elf-rtlinux. This would require
1179 even more space for OCERA development.
1182 The problem calls for some solution, which would have minimal impact
1183 on other components and would be elegant and would be maintainable
1184 and small, because our main goal is components development and not
1185 make systems development.
1187 There is result of our trial. It is OMK make system.
1188 The @file{Makefile} and @file{Makefile.omk} files should be in all source
1189 directories. Common @file{Makefile.rules} file is required in the toplevel
1190 sources directory. Alternatively this file could be moved
1191 to link tree pointing into readonly media or can be anywhere
1192 else if @code{MAKERULES_DIR} and @code{SOURCES_DIR} are specified.
1194 @c !!! tohle tam nejak zmizelo, mozna by to chtelo zkontrolovat, ze to
1195 @c sedi s aktualnim stavem
1198 Syntax of Makefile.omk files is for usual cases compatible
1199 to Automake's Makefile.am descriptions. There are specific targets
1200 for RT-Linux and Linux kernel related stuff
1202 Makefile.omk user defined variables
1205 list of subdirectories intended for make from actual directory
1207 list of the user-space libraries
1208 @item shared_LIBRARIES
1209 list of the user-space shared libraries
1210 @item kernel_LIBRARIES
1211 list of the kernel-space libraries
1212 @item rtlinux_LIBRARIES
1213 list of the RT-Linux kernel-space libraries
1214 @item include_HEADERS
1215 list of the user-space header files
1216 @item nobase_include_HEADERS
1217 headers copied even with directory part
1218 @item kernel_HEADERS
1219 list of the kernel-space header files
1220 @item rtlinux_HEADERS
1221 list of the RT-Linux kernel-space header files
1223 list of the require binary programs
1224 @item utils_PROGRAMS
1225 list of the development utility programs
1226 @item kernel_MODULES
1227 list of the kernel side modules/applications
1228 @item rtlinux_MODULES
1229 list of RT-Linux the kernel side modules/applications
1231 list of specific target sources
1233 additional include directories and defines for user-space
1234 @item kernel_INCLUDES
1235 additional include directories and defines for kernel-space
1236 @item rtlinux_INCLUDES
1237 additional include directories and defines for RT-Linux
1238 @item default_CONFIG
1239 list of default config assignments CONFIG_XXX=y/n ...
1242 The Makefile is same for all sources directories and is only 14 lines
1243 long. It is there only for convenience reasons to enable call "make"
1244 from local directory. It contains code which locates
1245 @file{Makefile.rules} in actual or any parent directory. With standard
1246 BASH environment it works such way, that if you get into sources
1247 directory over symbolic links, it is able to unwind yours steps back
1248 => you can make links to readonly media component directories, copy
1249 @file{Makefile.rules}, Makefile and toplevel Makefile.omk, adjust
1250 Makefile.omk to contain only required components and then call make in
1251 top or even directories after crossing from your tree to readonly
1254 The system compiles all files out of source directories. The actual
1255 version of system is adapted even for OCERA tree mode if
1256 @code{OCERA_DIR} variable is defined in @file{Makefile.rules}
1258 There are next predefined directory name components, which can be
1262 @item BUILD_DIR_NAME = _build
1263 prefix of directory, where temporary build files are stored
1264 @item COMPILED_DIR_NAME = _compiled
1265 prefix of directory, where final compilation results are stored
1266 @item GROUP_DIR_NAME = yyy
1267 this is used for separation of build sub-trees in OCERA environment
1268 where more @file{Makefile.rules} is spread in the tree
1271 Next directories are used:
1274 @item KERN_BUILD_DIR := $(MAKERULES_DIR)/$(BUILD_DIR_NAME)/kern
1275 directory to store intermediate files for kernel-space targets
1276 @item USER_BUILD_DIR := $(MAKERULES_DIR)/$(BUILD_DIR_NAME)/user
1277 directory to store intermediate files for user-space targets
1279 @item USER_INCLUDE_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/include
1280 directory to store exported include files which should be installed later
1281 on user-space include path
1282 @item USER_LIB_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/lib
1283 same for user-pace libraries
1284 @item USER_UTILS_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/bin-utils
1285 utilities for testing, which would not probably be installed
1286 @item USER_BIN_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/bin
1287 binaries, which should go into directory on standard system PATH
1288 (/usr/local/bin, /usr/bin or $(prefix)/bin)
1290 @item KERN_INCLUDE_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/include-kern
1291 directory to store exported include files which should be installed later
1292 on kernel-space include path
1293 @item KERN_LIB_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/lib-kern
1294 same for kernel-pace libraries
1295 @item KERN_MODULES_DIR := $(MAKERULES_DIR)/$(COMPILED_DIR_NAME)/modules
1296 builded modules for Linux kernel or RT-Linux system
1299 There is more recursive passes through directories to enable
1300 mutual dependant libraries and binaries to compile.
1301 Next passes are defined
1304 @item default-config
1305 generates @file{config.omk-default} or xxx-default (FIXME) configuration file
1307 checks and creates required build directories
1309 copies header files to @code{USER_INCLUDE_DIR} and @code{KERN_INCLUDE_DIR}
1311 builds objects in USER_BUILD_DIR/@var{relative path} and creates libraries
1313 @item binary-pass and utils-pass
1314 links respective binaries in USER_@{BIN,UTILS@}_DIR directory. If some
1315 object file is missing it compiles it in USER_BUILD_DIR/@var{relative path}
1316 @item kernel-lib-pass
1317 builds libraries for kernel space targets
1319 builds kernel modules
1322 The amount of passes is relatively high and consumes some time. But
1323 only other way to support all required features is to assemble one big
1324 toplevel Makefile, which would contain all components and targets
1327 Drawbacks of designed make system
1330 the system is not as fast as we would like
1332 it lacks Autoconf and configure extensive support for many systems
1333 from UNIX to DOS and WINDOWS
1335 it does not contain support for checking existence of target
1336 libraries and functionalities as GNU Autoconf
1338 it is heavily dependant on GNU MAKE program. But it would not be big
1339 problem, because even many commercial applications distribute GNU MAKE
1340 with them to be able to work in non-friendly systems
1342 the key drawback is dependence on recent MAKE version 3.80 and better
1343 and even version 3.80 of MAKE has important bug, which has been
1344 corrected in newer sources (FIXME)
1347 The last point is critical. I have not noticed it first, because
1348 I use Slackware-9.2 and it contains latest released version
1349 of MAKE (version 3.80).
1350 The problem appears when I have tried to build bigger libraries.
1351 There is bug in version 3.80, which results in misleading
1352 error "Virtual memory exhausted". It is known bug with ID 1517
1355 * long prerequisite inside eval(call()) => vm exhausted, Paul D. Smith
1359 I have optimized some rules to not push memory to the edge,
1360 but there could be still issues with 3.80 version.
1362 I have downloaded latest MAKE CVS sources. The compilation required
1363 separate lookup and download for .po files and full Autoheader... cycle.
1364 I have put together package similar to release. Only ./configure --prefix=...
1365 and make is required. CVS sources contains version 3.81beta1.
1366 You can download prepared sources archive from
1367 @uref{http://paulandlesley.org/make/make-3.81beta1.tar.bz2}
1368 Or you can get our local copy from
1369 @uref{http://cmp.felk.cvut.cz/~pisa/can/make-3.81beta1.tar.gz}
1371 The archive contains even "make" binary build by me, which should work
1372 on other Linux distributions as well. Older version of MAKE (3.79.x
1373 released about year 2000) found on Mandrake and RedHat are not
1374 sufficient and do not support eval feature. I do not expect, that
1375 Debian would be more up-to-date or contain fixes to MAKE vm exhausted
1378 The local CTU archive with our CAN components prepared for inclusion
1379 into OCERA SF CVS could be found in my "can" directory
1381 @uref{http://cmp.felk.cvut.cz/~pisa/can/ocera-can-031212.tar.gz}
1383 The code should build for user-space with new make on most of Linux distros
1384 when make is updated.
1386 If you want to test compile for RT-Linux targets, line
1389 #RTL_DIR := /home/cvs/ocera/ocera-build/kernel/rtlinux
1392 in @file{Makefile.rules} has to be activated and updated
1393 to point RT-Linux directory containing "rtl.mk".
1394 There is only one library ("ulutrtl") and test utility compiled for RT-Linux
1395 (@file{can/utils/ulut/ul_rtlchk.c}).
1397 The next line, if enabled, controls compilation in OCERA project tree
1400 #OCERA_DIR := $(shell ( cd -L $(MAKERULES_DIR)/../../.. ; pwd -L ) )
1403 The LinCAN driver has been updated to compile out of source directories.
1405 Please, check, if you could compile CAN package and help us with integration
1406 into OCERA SF CVS. Send your comments and objections.
1408 The OMK system has been adapted to support actual OCERA configuration process.
1409 I am not happy with ocera.mk mix of defines and poor two or three rules,
1410 but OMK is able to overcome that.
1412 The OMK system has integrated rules (default-config) to build default
1413 configuration file. The file is named @file{config.omk-default} for
1414 the stand-alone compilation. The name corresponds to OCERA config +
1415 "-default" if OCERA_DIR is defined. This file contains statements
1416 from all @code{default_CONFIG} lines in all @file{Makefile.omk}. The
1417 file should be used for building of own @file{config.omk} file, or as
1418 list for all options if Kconfig is used.
1420 @c @chapter OMK Reference
1422 @node Development, Variable Index, Original README, Top
1423 @chapter Development
1425 This section is far from complete. Its purpose is to document internals
1426 of @file{Makefile.rules} as well as other things needed only by people
1427 who hack OMK itself.
1431 A pass is created by instantiation of @code{omk_pass_template} with
1432 @var{pass-name} as one of arguments. This defines several targets which
1436 @item @var{pass-name}
1437 Target used to invoke the individual pass either from command line or
1438 from inside of @file{Makefile.rules}.
1440 @item @var{pass-name}-submakes
1441 Invoked recursively from @var{pass-name}. The reason for this is the
1444 @item @var{pass-name}-this-dir
1445 This target calls make recursively once again with @var{pass-name}-local
1446 target, which does the real-work. Make's working directory is set to the
1447 corresponding directory in @file{_build} tree and the -local
1449 @item @var{pass-name}-@var{dirname}-subdir
1450 This target is responsible for recursive invocation of @command{make} in
1451 subdirectories specified in @code{@ref{SUBDIRS}} variable.
1454 @node Variable Index, , Development, Top
1455 @unnumbered Variable Index
1459 @c @node Concept Index, , Variable Index, Top
1460 @c @unnumbered Concept Index