1.1 Why to Use OMK?

Here we list some of OMK features, which we think are important for choosing of a make system.

• Makefile in source directories are usually very simple.
• There is only one Makefile.rules for most of components of a bigger project.
• OMK greatly simplifies compilation of projects, where source files are spread between multiple directories.
• OMK handles properly dependencies of source files and libraries, so it is not necessary to recompile the whole project if only several files changed.
• OMK allows to freely move cross-dependant components in directory structure without the need to update users of moved component. I hate something like -I../../sched/rtlshwq/include in makefiles for example. If a component is renamed or version is added to the name, many Makefiles in the project would require an update.
• The above feature is very helpful in combining components (libraries) from different projects/developers to a single project by simply creating symbolic links to external components.
• Compilation of an OMK based projects don’t require to install any files before successful finish of build.
• OMK allows to call make for a particular subdirectory in the source tree.
• Under OMK all products of compilation are stored out of source directories. This simplifies work with version control systems and helps when simultaneous compilation for multiple targets/platforms is needed.

1.2 Quick Start

If you get some sources, which are distributed with OMK, usually the following commands are sufficient to compile the whole project.

make default-config
make

To use OMK in your own project, follow these steps:

1. The newest version of OMK can be found at http://rtime.felk.cvut.cz/omk/.
2. Take appropriate Makefile.rules (see Properties of Specific Makefile.rules), put it together with leaf Makefile to the root directory of your project.
3. Create Makefile.omk files in all directories you want to compile something. Please refer to User’s Manual to learn what to write in Makefile.omk files.
4. Run make omkize in the root directory.

Your project is now ready to compile.

1.3 History

OMK was originally written by Pavel Píša as a solution to have one common make system for OCERA project, where we needed to compile user-space programs, Linux kernel modules and RT Linux modules in one package. Although this system was not accepted for the whole OCERA project. Several individual developers (mostly from Czech Technical University) liked it and started to use it.

As a number of projects using OMK grew it was necessary to modularize the make system to support more “targets”. Michal Sojka took care about the process of modularization.

2.1 Basic Concepts

The main concept of OMK is very simple. In the heart of OMK are two files Makefile.rules and Makefile.omk. The former one resides in project root directory and contains all compilation rules needed for compilation of the particular project. There are different Makefile.rules for different platforms (Unix, RTEMS, system-less, ...). Makefile.omk is stored in every (sub)directory and describes what should make perform in that directory (e.g. compile a program from several source files). It uses declarative syntax (assign values to variables) similar to Automake files Makefile.am. The content of Makefile.omk is described in the following sections.

Since make searches by default for a Makefile and not for Makefile.rules or Makefile.omk, there must¹ be a small generic Makefile in every directory, whose task is only to find Makefile.rules in the actual or any parent directory and include it. This search is performed only once at the beginning of compilation.

The compilation process itself is comprised of several passes. Every pass traverses the whole directory structure² and does a particular task in every directory of the project. Typically, these passes are:

include-pass

This pass takes all include files marked for “export” and copies (or links) them to the include directory under _compiled directory. See Header Files.

Also, during this pass, automatically generated header file are generated according to the current configuration. See Configuration and Conditional Compilation.

library-pass

During this pass, all include files are in place, so all libraries can be compiled.

binary-pass

Finally, programs can be compiled and linked against libraries created in the previous pass.

The results of compilation are stored under the _compiled directory. This directory is structured as a classical Unix file-system (it contains directories like bin, lib and include) and can be directly copied to the target device or to some directory on a host computer (e.g. /usr/local).

Besides _compiled directory, there in a _build directory. Under this directory are stored some temporary files and intermediate compilation products (object files, dependency files etc.).

In the next section, we provide an overview of methods, how to invoke OMK from command line. Section Interfacing OMK to popular IDEs covers running of OMK from popular IDEs.

Sections Compiling Programs through Configuration and Conditional Compilation deals with the content of Makefile.omk. Its syntax in usual cases compatible to GNU Automake’s Makefile.am syntax. Also, the scheme for naming variables was inspired by Automake so most OMK variables have the name like ‘target_TYPE’.

2.2 Invoking OMK

Before using OMK for the first time, you have to call:

make default-config

See Configuration and Conditional Compilation for details. If you forget to do this, OMK will notice you.

To compile the whole project or only some subtree of the project, call

make

in the appropriate directory.

To clean files in _build directory but not in _compiled one, use:

make clean

To clean the compilation completely, you can either remove _compiled and _build directories manually, or call

make distclean

which does the same. This command removes these directories even if you call it from a subdirectory.

To debug compilation problems, you can use V variable (see V):

make V=1

You can also set values of some other variables on command line for temporary change something. The example below compiles the code temporarily with debugging information:

make CFLAGS="-g -O0 -Wall"

If your project uses an alternative make-system (e.g. Automake or custom makefiles), it might be useful for you to use the command:

make omkize

This will find all Makefile.omk files in all subdirectories and copies generic Makefile from the root directory to that subdirectories. This way you can easily switch your project to use OMK.

Variable: V ¶

If this variable equals to ‘1’, the whole command lines for all executed commands are displayed. When not set or zero, only short messages are printed. Value of ‘2’ displays the whole command lines as with ‘1’ and in addition directory navigation messages are printed.

2.3 Compiling Programs

To tell OMK to compile a program, you need to set some variables in Makefile.omk (usually) in the directory where program sources are located.

In the example bellow program test will be compiled from source test.c.

bin_PROGRAMS = test
test_SOURCES = test.c

The variables are:

Variable: bin_PROGRAMS ¶

Contains a list of names (whitespace separated) of programs to be compiled in this directory.

Variable: test_PROGRAMS ¶

Almost the same as bin_PROGRAMS, but resulting binaries are stored in bin-tests directory instead of bin. This variable is intended for various test programs not to be mixed with the final product.

Variable: utils_PROGRAMS ¶

Almost the same as bin_PROGRAMS, but resulting binaries are stored in bin-utils directory instead of bin. This variable is intended for various development utilities not to be mixed with the final product.

Variable: xxx_SOURCES ¶

For every program name xxx in bin_PROGRAMS, test_PROGRAMS or utils_PROGRAMS, this variable contains a list of sources that are needed to compile the program. OMK uses an extension of the filename to determine the compiler to compile this source.

Variable: xxx_LIBS ¶

This variable contains a list of libraries the program xxx will be linked with.

  test_LIBS = m curses
  

Variable: xxx_CFLAGS ¶

CFLAGS specific for the compiler program. If this variable is set, its value efectively overrides the value of OMK_CFLAGS variable.

Variable: xxx_CXXFLAGS ¶

CXXFLAGS specific for the compiler program. If this variable is set, its value efectively overrides the value of OMK_CXXFLAGS variable.

Variable: xxx_CPPFLAGS ¶

CPPFLAGS specific for the compiler program. If this variable is set, its value efectively overrides the value of OMK_CPPFLAGS variable.

Variable: xxx_GEN_SOURCES ¶

Program sources generated (by other rules) in the build directory. See the following example.

bin_PROGRAMS = p
p_GEN_SOURCES = gen.c

gen.c:
	echo "int main() { return 0; }" > $@

Variable: lib_LOADLIBES ¶

This variable contains a list of libraries which needs to be linked to to all programs or shared libraries in this directory.

Variable: LOADLIBES ¶

This variable contains a list linker switches to load additional libraries. You usually specify here -L and -l switches.

Note: The value of this variable is not used used by OMK for any purpose other than linker invocation. Therefore dependency handling of shared libraries does not work if the library is specified in LOADLIBES instead of lib_LOADLIBES.

2.4 Compiling Libraries

With OMK, you can easily create statically or dynamically linked libraries. The way of creating libraries is very similar to how programs are created. See Compiling Programs.

In Makefile.omk, you specify several variables, which defines how the libraries should be compiled. In the example below the library ‘mylib’ (full filename will be libmylib.a) is created from two sources funca.c and funcb.c. Interface of this library is defined in myfunc.h. Therefore, we export this header for use by other programs.

lib_LIBRARIES = mylib
mylib_SOURCES = funca.c funcb.c
include_HEADERS = mylib.h

Variables for use with libraries are:

Variable: lib_LIBRARIES ¶

Specifies a list of statically linked libraries to be compiled. OMK automatically prepends lib prefix library names.

Variable: shared_LIBRARIES ¶

Specifies a list of dynamically linked libraries to be compiled.

Variable: xxx_SOURCES ¶

For every library name xxx in lib_LIBRARIES or shared_LIBRARIES, this variable contains a list of sources that are needed to compile the library. OMK uses an extension of the filename to determine the compiler to compile this source.

• Header Files

2.5 Compiler Flags

OMK follows the same philosophy for flag variables as does Automake. The variables with OMK_ prefix (e.g. OMK_CPPFLAGS) are supposed to be used by the package developer and variable without that prefix (e.g. CPPFLAGS) are reserved for the user. The following

Variable: OMK_CPPFLAGS ¶

Preprocessor switches.

Variable: OMK_CFLAGS ¶

C compiler switches.

Variable: INCLUDES ¶

Directives passed to the C or C++ compiler with additional directories to be searched for header files. In most cases you need to specify an absolute path. To specify a directory relative to the source directory, you can use the $(SOURCES_DIR) variable, which refers to the directory, where Makefile.omk is located. This variable applies to all compilations invoked in the current directory.

  INCLUDES = -I$(SOURCES_DIR)/my_include_dir
  

Variable: DEFS ¶

Directives passed to the C or C++ compiler with preprocessor macro definitions. This variable applies to all compilations invoked in the current directory.

  DEFS = -DDEBUG=1
  

2.6 Recursing into Subdirectories

OMK is probably most useful in projects consisting of multiple directories. For such projects, it is not easy to write from scratch classic Makefiles that provides all the needed features.

You can instruct OMK to descend to a (sub)directory by setting the SUBDIRS variable in Makefile.omk.

Variable: SUBDIRS ¶

This variable contains a list of directories, in which compilation must be also invoked. Usually, names of subdirectories are used, but you can use any path specification here.

Compilation is invoked in these directories before it is invoked in the current directory.

See also AUTOMATIC_SUBDIRS.

Variable: ALL_OMK_SUBDIRS ¶

This variable is set by OMK and can be used as the value of SUBDIRS variable. It contains a list of all direct subdirectories, which contain Makefile.omk. This is especially useful if you are combining several projects or components together. In the root directory of your project, you just create symbolic links the components from other projects and all the linked directories automatically appears as the value of this variable.

  SUBDIRS = $(ALL_OMK_SUBDIRS)
  

Variable: AUTOMATIC_SUBDIRS ¶

If this variable is set to ‘y’ and SUBDIRS is not assigned in Makefile.omk, then SUBDIRS is assigned a default value $(ALL_OMK_SUBDIRS).

2.7 Dependency Tracking

OMK automatically tracks dependencies of files in the project. Dependencies of object files are produced with gcc’s -Mx options. This means that whenever a header file is changed, OMK recompiles only those files, which included that file.

Dependencies are also maintained for libraries and binaries. To find the dependencies, OMK parses linker map files, so a change to some library causes relinking of all programs using that library.

2.8 Configuration and Conditional Compilation

In many projects, it is necessary to configure the compilation process. By this configuring we mean, setting some parameters that influence the output of compilation process. In GNU projects, configure script is usually responsible for configuration. User provides some parameters to configure, which is run before compilation, and this script does all steps needed to configure the sources and make-system in the desired way.

OMK has its own configuration mechanism, which is described in this section. For future releases, we plan that this mechanism can make use of GNU Autoconf, but currently there is no directly integrated support for it.

There exist three different configuration files config.omk-default, config.target and config.omk. All of these have to be stored in the same directory as Makefile.rules. During compilation, these files are included in Makefile.rules in this order which means that variables assigned in the former files are overridden by those from later ones. All settings specified here apply to the whole compilation tree. Each file is intended for a different kind of configuration values:

config.omk-default

Stores default configuration of compiled components. This file is automatically generated (see below) and should not be edited by users.

config.target

Stores default configuration for a project or target hardware. This file is intended to be stored in a version control system and should be modified only by the maintainer of the project.

For cross compiled projects, this file typically contains settings of variables like CC and CFLAGS.

config.omk

This is a file for end users, where any default settings set in the above files can be overridden. This file should not be stored in version control system. The project should compile without having this file.

Besides variables defined in config.target, Makefile.omk in any subdirectory can specify some configuration parameters. When make default-config is run, all these parameters are found and together with their default values are stored as makefile variables in config.omk-default. This file is included during compilation, so if you don’t specify other values, these defaults are used. If you are not satisfied with these defaults, you can override the values of parameters either locally for your build in config.omk or globally for all people working with the project in config.target.

• Specifying Configuration Parameters
• Using Configuration Parameters
• Common Variables

default_CONFIG = CONFIG_DEBUG=y CONFIG_SLOW=n
default_CONFIG += CONFIG_NUM=123 CONFIG_ARCH=arm
default_CONFIG += CONFIG_QUOTES="Text+quotes"

SUBDIRS=subdir

default_CONFIG = CONFIG_SUBDIR=y CONFIG_DEBUG=x

# Start of OMK config file
# This file should not be altered manually
# Overrides should be stored in file config.omk

# Config for subdir
CONFIG_SUBDIR=y
#CONFIG_DEBUG=x
# Config for 
CONFIG_DEBUG=y
CONFIG_SLOW=n
CONFIG_NUM=123
CONFIG_ARCH=arm
CONFIG_QUOTES="Text+quotes"

SUBDIRS = arch/$(CONFIG_ARCH)

ifeq ($(CONFIG_DEBUG),y)
DEFS += -DUSE_SIMULATOR
endif

default_CONFIG = CONFIG_LINCAN=y CONFIG_LINCANRTL=n CONFIG_LINCANVME=n
config_include_HEADERS = global.h
global_DEFINES = CONFIG_OC_LINCAN CONFIG_OC_LINCANRTL

2.9 Advanced OMK Features

In this section we list several OMK features, which are more complicated or rarely used so they were omitted in previous sections.

• Organization of the Source Tree
• Additional Variables
• Adding Hooks to Passes
• Integration of Wvtest Framework

2.10 Properties of Specific Makefile.rules

In previous sections, general properties of Makefile.rules were documented. This section contains documentation to features found only in some particular Makefile.rules.

• Linux
• System-Less
• RTEMS

2.11 Running OMK under Windows OS

It is possible to use OMK under Windows OS with MinGW (see http://www.mingw.org/). Unfortunately, the compilation speed is much lower than on UNIX systems.

TODO: Is it necessary to install anything special?

2.12 Interfacing OMK to popular IDEs

• KDevelop
• Eclipse/CDT
• Emacs, VIM, etc.

2.13 Troubleshooting & Knows Bugs

• If you rename some file or directory and then you can’t compile your project, call make clean in the directory with errors. The reason for this behavior is that OMK remembers dependencies of every file. After renaming something, the original name is still stored in dependencies, but make doesn’t know how to create this non-existent source.
• Sometimes, you may want to compile one file the same way as OMK does it, but run the compilation manually from command line. For example, you want to debug some preprocessor macros and you only want to produce preprocessed source instead of an object file.

  To compile something manually, you can run OMK by make V=2. This will print all commands executed together with directory navigation messages. Find the command you want to execute manually in the output. To run it, you need to change the working directory to the correct one in the _build tree. The correct directory can be found in make output on the line ‘Entering directory’ preceding the desired command.

• Currently, C++ sources are supposed to have .cc or .cxx extensions. The .cpp extension is not supported (yet).
• Removing of library source file does not cause the library to be rebuild. You need to manually delete the library or run make distclean before you run make.

4.1 Passes

A pass is created by instantiation of omk_pass_template with pass-name as one of arguments. This defines several targets which are described here:

pass-name

Target used to invoke the individual pass either from command line or from inside of Makefile.rules.

pass-name-submakes

Invoked recursively from pass-name. The reason for this is the fact that

pass-name-this-dir

This target calls make recursively once again with pass-name-local target, which does the real-work. Make’s working directory is set to the corresponding directory in _build tree and the -local

pass-name-dirname-subdir

This target is responsible for recursive invocation of make in subdirectories specified in SUBDIRS variable.