The project.refs file
If one has elected to store source references in a single project.refs
file, then it will be stored at the toplevel of your project directory
adjacent to project.conf
. This can be configured in your project
using the ref-storage configuration
Sources for junction
elements are stored
separately in an adjacent junction.refs
file of the same format.
Basic behavior
When a project.refs
file is in use, any source references found
in the inline source declarations are considered
invalid and will be ignored, and a warning will be emitted for them.
When bst track
is run for your project, the project.refs
file
will be updated instead of the inline source declarations. In the absence
of a project.refs
file, bst track
will create one automatically
with the tracking results.
An interesting property of project.refs
is that it allows for
cross junction tracking. This is to say that it is possible to override
the ref of a given source in a project that your project depends on via
a junction
, without actually modifying the
junctioned project.
Format
The project.refs
uses the same YAML format used throughout BuildStream,
and supports the same directives which apply to
project.conf
and element declaration files (i.e. element.bst files).
The project.refs
file format itself is very simple, it contains a single projects
key at the toplevel, which is a dictionary of project names.
Each project name is a dictionary of element names, and each element name holds
a list of dictionaries corresponding to the element’s sources.
Example
# Main toplevel "projects" key
projects:
# The local project's name is "core"
core:
# A dictionary of element names
base/automake.bst:
# A list of sources corresponding to the element
# in the same order in which they were declared.
#
# The values of this list are dictionaries of the
# symbolic "ref" portion understood by the given
# source plugin implementation.
#
- ref: af6ba39142220687c500f79b4aa2f181d9b24e4...
# The "core" project depends on the "bootstrap" project,
# here we are allowed to override the refs for the projects
# we depend on through junctions.
bootstrap:
zlib.bst:
- ref: 4ff941449631ace0d4d203e3483be9dbc9da4540...