Local configuration and rmk setup¶ ↑

Rmk build setup¶ ↑

When rmk starts for generation of Ninja files (-g switch), it will try to read the following files in this order

rmk/tools/*.rb
rmk/config/{HOST,localhost,default}/init.rb
rmk/config/{HOST,localhost,default}/packages/*.rb
rmk/config/{HOST,localhost,default}/tools/*.rb
~/.rmk/config/{HOST,localhost,default}/init.rb
~/.rmk/config/{HOST,localhost,default}/packages/*.rb
~/.rmk/config/{HOST,localhost,default}/tools/*.rb

• rmk is the installation directory.

• rmk examines the first existing directory in {HOST,localhost,default} and ignores the remaining directories.

• HOST is the host name, and ~/ is the HOME directory.

• Note that the rmk repository's git configuration ignores any localhost/ directory. We recommend a separate repository for local configuration(s) and have a symbolic link localhost or HOST.

• Files that are read later may “patch” the configuration that was read earlier.

• You can always use Ruby load and require or Rmk.import_files to read additional files.

Next, rmk proceeds by reading

PROJDIR/project-name/RMakefile.spawn
PROJDIR/project-name/RMakefile.proj
PROJDIR/project-name/{.../}RMakefile.priv
PROJDIR/project-name/{.../}RMakefile

Project setup¶ ↑

RMakefile.spawn¶ ↑

• This file is optional. In constrast to other files, it does not contain Ruby code! Instead it contains a list of directories.

• Directories are listed in lines. Empty lines and lines starting with # are ignored.

• For each directory dir, rmk changes to dir and executes the rmk command (with the given options).

• Explicit spawning is not recursive: The option -no-explicit-spawn is added when executing rmk in an other directory to prevent this.

• If RMakefile.spawn but no RMakefile exists, then rmk exits after all directories are processed.

• One possible application for RMakefile.spawn is to easily trigger rmk from within "data directories" of a project (e.g., compile sources in another directory from a directory of OpenGL shaders, which don't require compiling).

RMakefile.proj¶ ↑

• This file defines the project root as the parent directory of its directory.

• Nested projects have one single RMakefile.proj in the “top” project.

• RMakefile.proj may be empty then it defines the project root.

• RMakefile.proj may also contain project-global settings: Every nested project will include this file. RMakefile.proj is the first project configuration file that is read and evaluated by rmk.

• If rmk does not find RMakefile.proj in any path toward the root directory /, the parent of the current directory is assumed to be the project root. Although rmk will issue only a warning, we suggest to not treat RMakefile.proj optional.

RMakefile.priv¶ ↑

• This file is optional: RMakefile.priv typically contains local settings that is not under revision control.

• If RMakefile.priv exists then it is read and evaluated after RMakefile.proj.

• If the project contains sub-projects there may be multiple RMakefile.priv files, one per sub-directory. They are evaluated "top-down" from the project root directory.

• RMakefile.priv is supposed to store project settings. We recommend to have no more than one RMakefile.priv (in the same directory as RMakefile.proj) for a project with sub-projects.

RMakefile¶ ↑

• This file defines your project or sub-project.

• It contains specifications of used tools and packages. In addition, it specifies use of other projects (i.e., project libraries).

• This is the most important file.

Remarks¶ ↑

• For building (no -g switch), rmk acts only as a "wrapper" that starts the Ninja. For this, configuration of rmk and its tools and packages is not required and will not be not performed!

• Use the verbose option -v3 to see which files are read.

• You can always place Ruby code in any configuration file to trace execution. Output via RMK.logger evaluates level of verbosity. Besides that, Rmk.dump(available_packages) stores package information to a YAML file for inspection.