blob: 799b5e76197325ce57d18a8fc6a5e84e9b496b6b (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
|
.. _projectrefs:
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:`ref-storage configuration <project_format_ref_storage>`
Sources for :mod:`junction <elements.junction>` elements are stored
separately in an adjacent ``junction.refs`` file of the same format.
.. _projectrefs_basics:
Basic behavior
--------------
When a ``project.refs`` file is in use, any source references found
in the :ref:`inline source declarations <format_sources>` 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 :mod:`junction <elements.junction>`, without actually modifying the
junctioned project.
.. _projectrefs_format:
Format
------
The ``project.refs`` uses the same YAML format used throughout BuildStream,
and supports the same :ref:`directives <format_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 :ref:`project names <project_format_name>`.
Each *project name* is a dictionary of *element names*, and each *element name* holds
a list of dictionaries corresponding to the element's :ref:`sources <format_sources>`.
**Example**
.. code:: yaml
# 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...
|
