Ruler
Ruler is a tool for managing a dependence graph of files. It fits any situation where a commandline executable takes files as input (sources) and generates files as output (targets). A large-scale C/C++ project is a good example. C/C++ projects are usually subdivided into libraries and object files. With the right dependence graph, Ruler can help speed up incremental builds by only re-building when necessary. C/C++ is not the only use-case, however. Many problems can be solved by dependence management.
Dependencies are encoded in a .rules file. A .rules file contains newline-separated blocks called rules. Each rule consists of three sections: targets, sources and command. Targets and sources are newline-separated lists of file paths. Command is a command-line invocation that presumably takes the sources as input and updates the targets. Each section ends with a single ":" alone on a line. For example, a `.rules` might contain this single rule:
```rules
build/game
:
src/game.h
src/game.cpp
:
c++
src/game.cpp
--std=c++17
-o build/game
:
```
That rule declares that the executable `build/game` depends on three source files, and builds by this line:
```sh
c++ game.cpp --std=c++17 -o build/game
```
(Note: Ruler uses slightly unconventional syntax for the commandline so that one invocation can span multiple lines without the need for backslashes. To get a multi-line invocation, separate by a ";" alone on a line.)
With the above`.rules` file, if we type this:
```sh
ruler build
```
Ruler checks whether the target file `build/game` is up-to-date with its source files:
```
src/game.h
src/game.cpp
```
If it is not up-to-date, Ruler runs the command:
```sh
c++ game.cpp --std=c++17 -o build/game
```
In general, a `.rules` file can contain lots of rules, each separated from the next by a single empty line, like this:
```rules
build/game
:
src/include/math.h
src/include/physics.h
build/math.o
build/physics.o
src/game.cpp
:
c++
build/math.o
build/physics.o
src/game.cpp
--std=c++17
-o
build/game
:
build/math.o
:
src/include/math.h
src/math.cpp
:
c++
--std=c++17
-c
src/math.cpp
-o
build/math.o
:
build/physics.o
:
src/include/math.h
src/physics.cpp
:
c++
--std=c++17
-c
src/physics.cpp
-o
build/physics.o
:
```
With that `.rules` file, if we type...
```sh
ruler build
```
... Ruler will execute the commands to build the intermeidate targets: build/math.o and build/physics.o before finally building build/game. What's more, Ruler will only execute the command to build a target that is out-of-date, so if build/math.o and build/physics.o have already been built, Ruler will not bother building them again.
This line:
```sh
ruler clean
```
removes all files listed as targets in the .rules file. Actually, that is only partly true. Rather than delete the files, it relocates them to a cache. If a build is invoked and Ruler determines that some files already reside in the cache, Ruler recovers them, rather than rebuilding.
The cache also gets populated when intermediate build results are replaced. So, if you edit a source file, type `ruler build`, then undo the edit and `ruler build` again, Ruler appeals to the cache and recovers the target instead of rebuilding it.