Overview of Rmk¶ ↑

Tools¶ ↑

Tools create rules and define build targets. Examples are compilers, linker, code generators. Tools may require other tools (e.g., the C++ compiler cxx requires the linker tool ld). Requirements are satisfied automatically by rmk.

Packages¶ ↑

Packages configure tools, e.g., they set flags, include paths, libraries. Generally, packages refer to external libraries. Packages may require other packages (e.g., glut requires opengl) or the use of tools (e.g., the qt package requires use of the moc tool). Requirements are satisfied automatically by rmk.

Configurations¶ ↑

Tools and packages can be setup in different configurations. These refer to, e.g., building a project in “debug” or “release” mode. In rmk these two refer to the default and the max configuration. For each of them, e.g., the C++ compiler cxx uses different flags. The setup of packages is often same for different configuration, but they can be configured (e.g., setting preprocessor definitions).

rmk provides a predefined set of possible configurations, at present default and max. There is currently no way to extend this set elegantly via the DSL by user- or platform-defined configurations. There are plans to support such extensions without modifying the core of rmk, e.g., to have configurations for different compilers/tool chains.

You can select configurations that rmk should process with the -c (--configs) switch. Not using the switch refers to using the default configuration.

Rmk DSL¶ ↑

rmk defines a simple DSL to specify projects. Generally, this could contain any Ruby code. The Rmk namespace provides, e.g., functions for using and configuring tools and packages. For every tool there a class instance, which usually provides methods for configuration.

Project specification¶ ↑

A project is described by an RMakefile, which specifies tools, packages, sub-projects and used projects. In addition, RMakefile.proj defines the project root directory and possibly global settings, which may be overruled in RMakefile.priv files. The latter are used for local customization that is typically not under version control.

You find details in the project setup section. The rmk-example repository contains few example projects in a common project root directory. The projects

Ninja and Rmk¶ ↑

Generation¶ ↑

Starting rmk with the -g (--generate) switch will generate a Ninja file builddir/build.ninja for the selected configurations. Then rmk spawns Ninja to build the project.

If the project contains sub-projects, rmk generates Ninja files and executes ninja recursively.

Generation is required whenever the project structure changes (e.g., new source files, new dependencies). The -gn switch generates without building, and -gnc all for all configurations.

Building¶ ↑

Starting rmk without -g switch will only build the project. In this case, rmk immediately spawns a Ninja process, i.e., starts ninja -f builddir/build.ninja (possibly with additional command line options to ninja passed after --).

rmk uses special names for Ninja targets that include the project name as prefix. If you decide to build directly with ninja for non-default targets you have to follow this naming scheme. (You can use a prefix %, which is substituted by the project id, e.g., in -- %all). If you use rmk to spawn ninja, target names will be prefixed automatically.

Building starts only one single Ninja process regardless if there are sub-projects or not. There is no recursive spawning for sub-projects. (An exception is automatic regeneration, see below.)

Limits of automatic regeneration¶ ↑

If the RMakefile is changed, building by rmk or ninja will regenerate the build.ninja file. This is executed as a Ninja rule.

Regeneration, however, does not take place automatically if new source files are added! Ninja will not be aware of them, and rmk does not check for such changes for performance reasons!

Details¶ ↑

There is variety of available tools that can be used. If a tools is used it may require additional tools (e.g., the C compiler tool cc requires use of the linker tool ld).

The setting is similar for available packages: used packages may require other packages (e.g., glut requires opengl) but also tools (e.g., the qt package requires use of the moc tool. There is no need to explicitly specift required packages or tools (e.g., its is enough to specify use_package 'glut' or use_package 'qt' for the two examples).

Every tool has its slot that defines the order of evaluation for all used tools. Here, evaluation refers to generating part of the Ninja file.

The sequence of all tools in use ordered by their slots is also called tool chain.