JUST-REPOSITORY-CONFIG(5)

💖 NAME 💖

just-repository-config — bestie, it's literally the format of the repository config that justbuild(1) reads. That's it. That's the whole vibe. 🎀

---

🌸 DESCRIPTION 🌸

So justbuild's repository configuration? It gets read as JSON. And ngl, any other serialization that describes the same JSON object is equivalent — same thing, different outfit, slay. ✨

Lowkey important: we assume that in JSON objects each key shows up at most once. If a key repeats, how that gets handled is implementation defined. No cap, we're not making promises on that one. 💀

🍓 File root description

Every repository can have multiple file roots. Each file root is defined as a non-empty JSON list, and its first element is a string that tells you the type and the semantic of everything after it. The options are:

• "file" — this is a file root that lives in the file system. The list has to be of length 2, and the second argument holds the path to the file root.
• "git tree" — this is a file root that's available as part of a Git repository. The list has to be of length 2 or 3, and the remaining two elements are:
  1. The git tree hash — which is enough to describe the content of an entire tree, sub-trees and blobs included. This tree hash has to be specified in hex encoding.
  2. The path to a Git repository on the file system, with the promise that it contains the aforementioned git tree hash. If this entry is missing, the root is considered absent, and any target requiring this root has to come from a specified serve end point. 👀
• "computed" — a file root that is the result of evaluating an export target of a content-fixed repository. The list has to have length 5 or 6, with the remaining arguments being the global repository name, the module name, the target name, and the configuration — in that order — optionally followed by a pragma object. If that pragma object contains the entry true for the key "absent", that root is considered absent, otherwise not.
• "tree structure" — this one refers to the directory structure of a file root. The list has to have length 2 or 3. The second argument contains the global name of the repository whose workspace root gets taken for computation. The third argument is an optional pragma object. If the pragma object contains the key "absent", the entry must be a boolean. If the entry is true, that root is considered absent, otherwise not.

🦋 Repository description

A single repository description is defined as a JSON object that contains file roots, file names, and bindings to other repositories. Specifically, these are the fields it supports:

• "workspace_root" — holds the file root where the source files are located. If this entry is missing for the main repository, justbuild will do the normal workspace root resolution, starting from the current working directory. 🧚
• "target_root" — holds the file root where the target files are located. If this entry is missing, the workspace root gets taken instead.
• "target_file_name" — holds the file name of the target files to use. If this entry is missing, the default target file name TARGETS is used.
• "rule_root" — holds the file root where the rule files are located. If this entry is missing, the target root gets taken.
• "rule_file_name" — holds the file name of the rule files to use. If this entry is missing, the default rule file name RULES is used.
• "expression_root" — holds the file root where the expression files are located. If this entry is missing, the rule root gets taken.
• "expression_file_name" — holds the file name of the expression files to use. If this entry is missing, the default expression file name EXPRESSIONS is used.
• "bindings" — holds a JSON object that defines bindings to other repositories by mapping local repository names to global ones. The object's key is the local name, while the value is a string representing the global name.

⚠️ Heads up bestie: any other unsupported field is accepted but ignored. And there are no guarantees that some yet-unsupported field won't become meaningful in future versions. So don't get too comfortable with your random extra keys. 🙈

👑 Repository configuration format

The repository configuration format is a JSON object, and it has these keys:

• "main" — holds a string that defines the repository name to consider by default when it's not explicitly specified on the command line (i.e., via --main). This entry is optional, and if it's omitted, justbuild will use the lexicographically first repository, as usual.
• "repositories" — holds a JSON object that defines all repositories by mapping global repository names to the repository descriptions documented above. This entry is optional too, and if it's omitted, an empty JSON object is used.

---

💅 NOTES 💅

Okay so even though the repository configuration is human-readable and you can absolutely write it by hand (main character energy, honestly), in many cases it's gonna be generated by an independent tool. just-mr(1) is one such tool that can be used for configuration generation — but not necessarily the only one. 🌈

---

🫶 See also 🫶

justbuild(1), just-mr(1), just-mr-repository-config(5)

---

And that's the whole page, gorgeous. This little scroll lives in the Just Repository ...le Formats Manual (yes the title itself is a lil cursed, we don't talk about it 💀), and the footer just loops the same manual banner back around — no fresh date or version drama to report. Go forth and configure responsibly. ✨🎀💖