summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorChandan Singh <chandan@chandansingh.net>2019-11-11 21:04:36 +0000
committerChandan Singh <chandan@chandansingh.net>2019-11-27 18:03:59 +0000
commit8d27cf5a73454c6580954dfe539075ecbc54a785 (patch)
tree86d7999b13659038f7c0829ad57462c04b819d7c
parent85a29b48ed3b8f524e2aaa815517a904b0e55c7b (diff)
downloadbuildstream-8d27cf5a73454c6580954dfe539075ecbc54a785.tar.gz
doc: Add glossary of common terms
Start a new glossary document, aimed at helping newcomers relevant links to more detailed documents.
-rw-r--r--doc/source/advanced-features/junction-elements.rst2
-rw-r--r--doc/source/core_plugins.rst2
-rw-r--r--doc/source/index.rst1
-rw-r--r--doc/source/main_glossary.rst134
-rw-r--r--doc/source/using_config.rst2
5 files changed, 141 insertions, 0 deletions
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 <https://buildstream.build/install.html>`_,
refer to `the BuildStream website <https://buildstream.build>`_.
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 <Element>`, represented
+ in YAML format.
+
+
+ Artifact
+ The output collected after building an :term:`Element`.
+
+ Artifacts can be built from :term:`Sources <Source>`, or pulled from a
+ :term:`Remote Cache <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 <Local Cache>` or a :term:`Remote Cache <Remote Cache>`.
+
+
+ Core Plugin
+ A :term:`Plugin <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 <plugins>` for more details on core
+ plugins.
+
+
+ Dependency
+ :term:`Elements <Element>` 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 <format_dependencies>` for more
+ details.
+
+
+ Element
+ An atom of a :term:`BuildStream project <Project>`. Projects consist of
+ zero or more elements.
+
+ During the build process, BuildStream transforms :term:`Sources
+ <Source>` and :term:`Dependencies <Dependency>` of an
+ element into its output. The output is called an
+ :term:`Artifact <Artifact>`.
+
+ Configuration for elements is stored in form of :term:```.bst`` files
+ <``.bst`` file>` See :ref:`Declaring Elements document <format_basics>`
+ for more details on element configurtion.
+
+
+ External Plugin
+ A :term:`Plugin <Plugin>` that is defined in some package other
+ than BuildStream.
+
+ External plugins must be declared in :ref:`the project configuration
+ <project_plugins>`.
+
+ For a list of known external plugin repositories, see
+ :ref:`plugins_external`.
+
+
+ Junction
+ A special kind of :term:`Element <Element>`, that allows you to
+ depend on elements from another project.
+
+ See :mod:`Junction reference <elements.junction>` for details on how to
+ configure junction elements.
+
+ See :ref:`Junction guide <advanced_junction>` 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 <config_local_cache>` section of the user
+ guide for details on how to configure the local cache.
+
+
+ Plugin
+ BuildStream Plugins define types of :term:`Elements <Element>`
+ and :term:`Sources <Source>`. Hence, they come in two distinct
+ varities - Element Plugins and Source Plugins.
+
+ BuildStream supports some plugins :term:`out of the box
+ <Core plugin>`. It also has support for :term:`third party
+ plugins <External plugin>`.
+
+
+ Project
+ A collection of :term:`Elements <Element>`.
+
+ 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 <Source>`
+ and/or :term:`Artifacts <Artifact>`.
+
+ See :ref:`cache server documentation <cache_servers>` 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 <format_sources>` section of
+ :term:`Element <Element>` configuration.
+
+
+ Workspace
+ Workspaces allow building one or more elements using a local, and
+ potentially modified, copy of their sources.
+
+ See :ref:`Workspaces guide <developing_workspaces>` 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