diff options
| author | Tristan van Berkom <tristan@codethink.co.uk> | 2020-12-08 16:51:35 +0900 |
|---|---|---|
| committer | Tristan van Berkom <tristan@codethink.co.uk> | 2020-12-10 21:40:20 +0900 |
| commit | fe6523ae7cda102a290eae670e62e317966234ac (patch) | |
| tree | 3238eae2b96fcacc2c2eb0fc0988531c8a19b8be | |
| parent | 766330ffb6e5e96aec590a6588316c98a49808f0 (diff) | |
| download | buildstream-fe6523ae7cda102a290eae670e62e317966234ac.tar.gz | |
doc: Documenting "artifact names".
Added a description about artifact names at the beginning of the
artifact commands section, along with a new glossary entry for
artifact names which refers to the description.
| -rw-r--r-- | doc/source/main_glossary.rst | 4 | ||||
| -rw-r--r-- | doc/source/using_commands.rst | 23 |
2 files changed, 27 insertions, 0 deletions
diff --git a/doc/source/main_glossary.rst b/doc/source/main_glossary.rst index aa0c6da1f..f1bf4cfaf 100644 --- a/doc/source/main_glossary.rst +++ b/doc/source/main_glossary.rst @@ -18,6 +18,10 @@ Glossary Artifacts can be built from :term:`Sources <Source>`, or pulled from a :term:`Remote Cache <Remote Cache>`, if available. + Artifact name + The :ref:`name of an artifact <artifact_names>`, which can be used + in various commands to operate directly on artifacts, without requiring + the use of a :term:`Project`. Cache BuildStream leverages various caching techniques in order to avoid diff --git a/doc/source/using_commands.rst b/doc/source/using_commands.rst index 27fe692d3..1162e6c44 100644 --- a/doc/source/using_commands.rst +++ b/doc/source/using_commands.rst @@ -77,6 +77,29 @@ Top-level commands Artifact subcommands -------------------- + +.. _artifact_names: + +Artifact names +~~~~~~~~~~~~~~ +Various artifact subcommands accept either :ref:`element names <format_element_names>`, +which will operate on artifacts by deriving the artifact from local project state, +or :term:`artifact names <Artifact name>` interchangeably as targets. Artifact names allow +the user to operate directly on cached artifacts, without requiring local project data. + +An artifact name is composed of the following identifiers: + +* The :ref:`project name <project_format_name>` + +* The :ref:`element name <format_element_names>`, without any trailing ``.bst`` extension + +* The cache key of the element at the time it was built. + +To compose an artifact name, simply join these using a forward slash (``/``) character, like so: ``<project-name>/<element-name>/<cache-key>``. + +An artifact name might look like: ``project/target/788da21e7c1b5818b7e7b60f7eb75841057ff7e45d362cc223336c606fe47f27`` + + .. _invoking_artifact_checkout: .. click:: buildstream._frontend.cli:artifact_checkout |