JUST-GRAPH-FILE(5)

📦
version 1.6.5 · 4 versions
, in ubuntu stonking

💖 NAME 💖

just-graph-file — the format of the action graph used by justbuild(1). Yeah, this is a section 5 (File Formats Manual) situation and honestly? iconic. 👑

✨ DESCRIPTION ✨

okay so bestie, first thing's first: the file is read as JSON. That's it, that's the vibe. Any other serialization that describes the same JSON object is equivalent — same JSON, same meaning, periodt. 💅

And we assume that in JSON objects, each key occurs at most once. If a key gets repeated? That's implementation defined, so how repetitions of the same key get treated is entirely up to whoever's reading it. Not our problem, lowkey. 🫶

🦋 Artifacts and their serialization 🦋

There are five different kind of artifacts. And here's the cute part: no matter which one you're looking at, the serialization of the artifact is always a JSON object with two keys — "type" and "data". 💖

The value for "type" is always one of the strings "LOCAL", "KNOWN", "ACTION", "TREE", or "TREE_OVERLAY". The value for "data" is a JSON object with keys depending on which type the artifact is of.

  • "LOCAL" — these refer to source files in a logical repository. The describing data are:
    • the "repository", given as its global name, and
    • the "path", given as path relative to the root of that repository.
  • "KNOWN" — these are described by the hash of their content. The describing data are:
    • the "file_type", which is a one-letter string,
      • "f" for regular, non-executable files,
      • "x" for executable files, or
      • "t" for trees.
    • the "id" specifying the (applicable) hash of the file, given as its hexadecimal encoding, a string, and
    • the "size" of the artifact, a number, in bytes.
  • "ACTION" — these are the outputs of actions. The defining data are:
    • the "id", a string with the name of the action, and
    • the "path", specifying the path of this output artifact, relative to the root of the action directory.
  • "TREE" — these refer to trees defined in the action graph. The defining data are:
    • the "id", a string with the name of the tree.
  • "TREE_OVERLAY" — these refer to trees defined as the result of overlaying earlier trees. The defining data are:
    • the "id", a string with the name of the tree overlay.

💅 Actions and their serialization 💅

Actions are given by the data described in the following sections. For each item a key is associated, and the serialization of the action is a JSON object mapping those keys to the respective serialization of the values. 🌈

And listen — for some data items there are default values given. If the value for the respective item equals the default, then the respective key-value pair may be omitted in the serialization. Free real estate. ✨

  • "command" — specifies the command to be executed. It's a non-empty list of strings that forms the argument vector; the first entry is taken as program. This key is mandatory, no skipping it bestie. 🚨
  • "env" — specifies the environment variables the command should be executed with. It's given as map from strings to strings. The default is the empty map.
  • "input" — describes the files available to the action. ⚠️ The action must not modify them in any way. They're specified as map from paths to artifacts (the latter serialized as described above). Paths have to be relative paths and are taken relative to the working directory of the action. The default is the empty map.
  • "output" — describes the files the action is supposed to generate, if any. It's given as a list of strings, each specifying a file name by a path relative to the working directory of the action. The default is the empty list. However, every action has to produce some form of output, so if "output" is empty, "output_dirs" cannot be empty.
  • "output_dirs" — describes the directory output of the action, if any. It's given as a list of strings, each specifying the a directory name by a path relative to the working directory of the action. The "output_dirs" may also specify directories from which individual files are specified as "output". The default value for "output_dirs" is the empty list. However, every action to produce some form of output, so if "output_dirs" is empty, "output" cannot be empty.
  • "may_fail" — can either be null or a string. If it is a string, the build should be continued, even if that action returns a non-zero exit state. And if the action returns a non-zero exit code, that string should be shown to the user in a suitable way (e.g., printing on the console). Otherwise (i.e., if no "may_fail" string is given), the build should be aborted if the action returns a non-zero exit code. The default for "may_fail" is null, i.e., abort on non-zero exit code. 💀
  • "no_cache" — is a boolean. If true, the action should never be cached, not even on success. The default is false.

🌸 The graph format 🌸

The action graph is given by a JSON object. Simple as that, bestie.

  • "blobs" — the value for this key is a list of strings. Those strings should be considered known; they might (additionally to what was agreed ahead of time as known) referred to as "KNOWN" artifacts.
  • "trees" — the value for this key is a JSON object, mapping the names of trees to their definition. The definition of a tree is JSON object mapping paths to artifacts (serialized in the way described earlier). The paths are always interpreted as relative paths, relative to the root of the tree.

It is not a requirement that a new tree is defined for every subdirectory; if a path contains the hierarchy separator, which is slash, then implicitly a subdirectory is present, and all path going through that subdirectory contribute to its content. It is, however, an error, if the a path is a prefix of another one (with the comparison done in the canonical form of that path). 🚩

  • "actions" — the value for this key is a JSON object, mapping names of actions to their respective definition (serialized as JSON).
  • "tree_overlays" — the optional value (with default {}) for this key is a JSON object mapping the names of tree overlay to their definition. The definition is a JSON object with the following keys:
    • For the key "trees" — a JSON array of the artifacts to be overlayed in the order they are to be overlayed (with latest-wins semantics for each path). 👑
    • For the key "disjoint" — a boolean indicating if it is to be considered an error of a conflict arises on any path of the trees to be overlayed.

🧚 Additional keys 🧚

Surprise bestie — any JSON object described here might have additional keys on top of the ones described. 💖

Implementations reading the graph have to accept and ignore those. Implementations writing action-graph files should be aware that a future version of this file format might give a specific meaning to those extra keys. So like, don't get too attached to them. 🙈

Graphs written by justbuild(1) have the additional key "origins" in each action. The value is a list of all places where this action was requested (so often, but not always, the list has length 1). Each such place is described by a JSON object with the following keys: ⭐

  • "target" — The target in which the action was requested. It is given as a list, either a full qualified named target given as "@" followed by global repository name, module, and target name, or an anonymous target, given by "#" followed by a hash of the rule binding and the node name.
  • "subtask" — The running number, starting from 0, of the action, as given by the (deterministic) evaluation order of he defining expression for the rule that defined the target.
  • "config" — The effective configuration for that target, a JSON object.

🎀 See also 🎀

okay bestie that's the whole page, you ate it 💅 this one lives in section 5 of the File Formats Manual, and ngl the footer is literally just the page title again — no version, no date, it's giving mysterious 🦋✨

📦 where this page comes from