From 8d27cf5a73454c6580954dfe539075ecbc54a785 Mon Sep 17 00:00:00 2001 From: Chandan Singh Date: Mon, 11 Nov 2019 21:04:36 +0000 Subject: doc: Add glossary of common terms Start a new glossary document, aimed at helping newcomers relevant links to more detailed documents. --- doc/source/advanced-features/junction-elements.rst | 2 + doc/source/core_plugins.rst | 2 + doc/source/index.rst | 1 + doc/source/main_glossary.rst | 134 +++++++++++++++++++++ doc/source/using_config.rst | 2 + 5 files changed, 141 insertions(+) create mode 100644 doc/source/main_glossary.rst (limited to 'doc') diff --git a/doc/source/advanced-features/junction-elements.rst b/doc/source/advanced-features/junction-elements.rst index b6065d344..6bdc962fb 100644 --- a/doc/source/advanced-features/junction-elements.rst +++ b/doc/source/advanced-features/junction-elements.rst @@ -1,5 +1,7 @@ +.. _advanced_junction: + Junction elements ================= BuildStream's junction elements are used to import other BuildStream diff --git a/doc/source/core_plugins.rst b/doc/source/core_plugins.rst index 00d7c7f6d..682c9970f 100644 --- a/doc/source/core_plugins.rst +++ b/doc/source/core_plugins.rst @@ -53,6 +53,8 @@ Sources sources/pip +.. _plugins_external: + External plugins ---------------- External plugins need to be installed separately, here is diff --git a/doc/source/index.rst b/doc/source/index.rst index 4d5fe9ac2..4d4e24ac2 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -21,6 +21,7 @@ Later sections provide detailed information on BuildStream internals. main_core CONTRIBUTING main_architecture + main_glossary For any other information, including `how to install BuildStream `_, refer to `the BuildStream website `_. diff --git a/doc/source/main_glossary.rst b/doc/source/main_glossary.rst new file mode 100644 index 000000000..d4b315d8c --- /dev/null +++ b/doc/source/main_glossary.rst @@ -0,0 +1,134 @@ + + +Glossary +======== + +.. glossary:: + :sorted: + + + ``.bst`` file + The configuration for an :term:`Element `, represented + in YAML format. + + + Artifact + The output collected after building an :term:`Element`. + + Artifacts can be built from :term:`Sources `, or pulled from a + :term:`Remote Cache `, if available. + + + Cache + BuildStream leverages various caching techniques in order to avoid + duplicating work. + + Depending on context, "Cache" might refer to BuildStream's :term:`local + cache ` or a :term:`Remote Cache `. + + + Core Plugin + A :term:`Plugin ` that is contained in the BuildStream + package. These are built-in and don't need to be defined in the + project configuration. + + See :ref:`plugin documentation ` for more details on core + plugins. + + + Dependency + :term:`Elements ` in a BuildStream project can depend + on other elements from the same project. The element dependent upon is + called a dependency. + + See :ref:`Dependencies document ` for more + details. + + + Element + An atom of a :term:`BuildStream project `. Projects consist of + zero or more elements. + + During the build process, BuildStream transforms :term:`Sources + ` and :term:`Dependencies ` of an + element into its output. The output is called an + :term:`Artifact `. + + Configuration for elements is stored in form of :term:```.bst`` files + <``.bst`` file>` See :ref:`Declaring Elements document ` + for more details on element configurtion. + + + External Plugin + A :term:`Plugin ` that is defined in some package other + than BuildStream. + + External plugins must be declared in :ref:`the project configuration + `. + + For a list of known external plugin repositories, see + :ref:`plugins_external`. + + + Junction + A special kind of :term:`Element `, that allows you to + depend on elements from another project. + + See :mod:`Junction reference ` for details on how to + configure junction elements. + + See :ref:`Junction guide ` for details on how to use + junction elements. + + + Local Cache + To avoid duplicating work, BuildStream will cache sources, artifacts, + logs, buildtrees etc. in a local cache directory. If these sources or + artifacts are needed another time, BuildStream will use them from the + cache. + + See :ref:`Local cache expiry ` section of the user + guide for details on how to configure the local cache. + + + Plugin + BuildStream Plugins define types of :term:`Elements ` + and :term:`Sources `. Hence, they come in two distinct + varities - Element Plugins and Source Plugins. + + BuildStream supports some plugins :term:`out of the box + `. It also has support for :term:`third party + plugins `. + + + Project + A collection of :term:`Elements `. + + Elements in a project share some central configuration. See + :ref:`projectconf` to learn how to configure BuildStream projects. + + + Remote Cache + A server setup for sharing BuildStream :term:`Sources ` + and/or :term:`Artifacts `. + + See :ref:`cache server documentation ` for details on + artifact caches. + + + Source + Sources describe the input to the build of an :term:`Element`. + + In general, an element can have zero or more sources. But, certain + element plugins may restrict the number of allowed sources. + + Sources are defined in the :ref:`Sources ` section of + :term:`Element ` configuration. + + + Workspace + Workspaces allow building one or more elements using a local, and + potentially modified, copy of their sources. + + See :ref:`Workspaces guide ` for more details on + how to use workspaces. diff --git a/doc/source/using_config.rst b/doc/source/using_config.rst index 967dde2ed..302abb2f1 100644 --- a/doc/source/using_config.rst +++ b/doc/source/using_config.rst @@ -248,6 +248,8 @@ The default mirror is defined by its name, e.g. ``--default-mirror`` command-line option. +.. _config_local_cache: + Local cache expiry ~~~~~~~~~~~~~~~~~~ BuildStream locally caches artifacts, build trees, log files and sources within a -- cgit v1.2.1