reggae

This package implements a meta-build system in D, with the build descriptions in D. At its core is a set of data definitions that allow a user to specify arbitrary build descriptions at compile-time, including the usage of functions that only run at run-time (so a build can, for example, automatically include every file in a directory).

The build is contained in a reggaefile.d file, which must define one and only one function returning an object of type Build. This function is usually generated from the provided build template mixin for maximum convenience.

A Build struct only serves as a top-level container for $(Target) structs. Each one of these can include other dependent $(Target) structs recursively and form the basis of the build descripton. The build module contains these data definitions, please refer to the documentation therein for more information.

As well as these low-level data definitions, reggae provides built-in high-level rules to automate common build system tasks for D, C, and C++. These can be found in the reggae.rules package and its subpackages. There is also a reggae.rules.dub package for accessing targets defined in/by dub.

Right now the objectFile and objectFiles rules generate the appropriate commands to build an object file (or object files in the case of the latter) for a given source language. There is no current mechanism to support other languages as plugins but that's how it's planned to be in the future.

End-users will probably not use objectFile directly, there are higher level rules for compiling all or nearly all source files in a directory and its subdirectories. For D there is even a rule to compile, link and find all dependencies for a D executable called executable. There are many examples in the Cucumber tests.

Reggae works by using backends. Currently, there are three: the ninja, make and binary backends. The first two generate files for those two build systems in the same manner as CMake and Premake do. The latter produces a binary executable that when run will check dependencies and execute build commands as appropriate.

Modules

backend
module reggae.backend
Undocumented in source.
build
module reggae.build

This module contains the core data definitions that allow a build to be expressed in. Build is a container struct for top-level targets, Target is the heart of the system.

buildgen
module reggae.buildgen

This module implements the binary that is used to generate the build in the case of the make, ninja and tup backends, i.e. it translates D code into the respective output.

config
module reggae.config

This file is never actually used in production. It owes its existence to allowing the UTs to build and flycheck to not complain.

core
module reggae.core

Public imports for only the core packages to enable reggae to be a D build system. Only support for D is imported, not even dub is supported.

ctaa
module reggae.ctaa
Undocumented in source.
dcompile
module reggae.dcompile
Undocumented in source.
dependencies
module reggae.dependencies
Undocumented in source.
dub
module reggae.dub
file
module reggae.file
Undocumented in source.
from
module reggae.from
Undocumented in source.
io
module reggae.io
Undocumented in source.
json_build
module reggae.json_build

This module is responsible for the output of a build system from a JSON description

options
module reggae.options
Undocumented in source.
path
module reggae.path
Undocumented in source.
range
module reggae.range
Undocumented in source.
reflect
module reggae.reflect
Undocumented in source.
reggae
module reggae.reggae

The main entry point for the reggae tool. Its tasks are:

  • Verify that a reggafile.d exists in the selected directory
  • Generate a reggaefile.d for dub projects
  • Write out the reggae library files and config.d
  • Compile the build description with the reggae library files to produce buildgen
  • Produce dcompile, a binary to call the D compiler to obtain dependencies during compilation
  • Call the produced buildgen binary
rules
module reggae.rules

This package and its modules provide high-level rules for building software written in C, C++ and D. For obtaining object files from any of these, please consult targetsFromSourceFiles in common.d. For D-specific rules, consult d.d. For dub, dub.d.

sorting
module reggae.sorting
Undocumented in source.
types
module reggae.types

Wrapper structs to ensure type-safety and readability, as well as helper types to use as arguments to build commands.

Public Imports

reggae.core
public import reggae.core;
reggae.rules
public import reggae.rules;
reggae.reggae
public import reggae.reggae;

Meta