Package bm

package bm
Provides a simple command line wrapper Build around Machine.

The Machine (re)-creates targets if they are not up-to-date, taking dependencies into account. The following paragraphs describe what exactly up-to-date means for BuildMachine.

What is a Target?

Forget for a moment the idea of dependencies, because a Target can be understood in isolation. A target is something

  • BuildMachine shall create,
  • but only if it is not up-to-date.
How does BuildMachine know that a target is not up-to-date?
  1. Initially it assumes a target is not up-to-date and creates it.
  2. After building it, it computes and stores a state representing the target.
  3. When run again, the build system computes a fresh state from the target and compares it with the stored one. If the two are not the same, the target is not up-to-date, so it is re-created and the resulting state is stored again.
Note how the last step makes sure to re-create a target in the following cases:
  • The state got lost or was tampered with.
  • The target was lost or was changed.

What is a Dependency?

A target D can be declared to be a dependency of another target T. In this case,

  • the state of D (not D itself) is part of the state of T.
As a result, the description from above of when the target is up-to-date is extended as follows:

  • Before computing the fresh state of a target, all its dependencies are considered and re-created or not depending on the up-to-dateness. This includes updating their state.

Consider a dependency is re-created because it or its state got lost. If the resulting state is the same as it was before, the target depending on it has no state change due to the dependency being re-created, and it will not be re-created just because a dependency was created again. A typical example is a pure change of a comment in some source code. The source code will be recompiled, but steps depending on it may not need to be repeated because the output is identical to the previous compilation.

What is the State of a target?

Currently, two implementations of state are available for a target representing a file: Both are themselves stored in files, see Machine(bm.util.SupplyOrThrow<bm.machine.StateStore>).

How do I create a target?

See Also: