Merge branch 'aevri/doc_arch_deps' into 'master'

Architecture docs: minor corrections, clarifications, and nitpicks

See merge request BuildStream/buildstream!1170

4 files changed, 24 insertions, 20 deletions

diff --git a/doc/source/arch_cachekeys.rst b/doc/source/arch_cachekeys.rst
index f0df796c5..0d469de4b 100644
--- a/doc/source/arch_cachekeys.rst
+++ b/doc/source/arch_cachekeys.rst
@@ -10,14 +10,14 @@ for the purpose of reusing artifacts in a well-defined, predictable way.
 
 Structure
 ---------
-Cache keys are SHA256 hash values generated from a pickled Python dict that
+Cache keys are SHA256 hash values generated from a UTF-8 JSON document that
 includes:
 
-* Environment (e.g., project configuration and variables)
-* Element configuration (details depend on element kind, ``Element.get_unique_key()``)
-* Sources (``Source.get_unique_key()``)
-* Dependencies (depending on cache key type, see below)
-* Public data
+* Environment (e.g., project configuration and variables).
+* Element configuration (details depend on element kind, ``Element.get_unique_key()``).
+* Sources (``Source.get_unique_key()``).
+* Dependencies (depending on cache key type, see below).
+* Public data.
 
 Cache key types
 ---------------
@@ -42,6 +42,9 @@ or the environment changes but it will not change when a dependency is updated.
 For elements without build dependencies the ``strong`` cache key is identical
 to the ``weak`` cache key.
 
+Note that dependencies which are not required at build time do not affect
+either kind of key.
+
 Strict build plan
 -----------------
 This is the default build plan that exclusively uses ``strong`` cache keys
diff --git a/doc/source/arch_dependency_model.rst b/doc/source/arch_dependency_model.rst
index ff802660c..2b80564c1 100644
--- a/doc/source/arch_dependency_model.rst
+++ b/doc/source/arch_dependency_model.rst
@@ -42,7 +42,8 @@ Scope
 * **Scope.RUN**
 
   In the :func:`Scope.RUN <buildstream.types.Scope.RUN>` scope, only elements
-  which are required to run are considered, including the element itself.
+  which are required to run are considered, including the element itself. Note
+  that these are transitive - the service also requires the base runtime.
 
   This is used when for example, launching a ``bst shell`` environment
   for the purpose of running, or in any case we need to consider which
@@ -60,7 +61,7 @@ Scope
   .. image:: images/arch-dependency-model-build.svg
      :align: center
 
-  Note that build type dependencies are not transient, which is why the
+  Note that build type dependencies are not transitive, which is why the
   *Bootstrap* element is not selected when pulling in the *Compiler* to
   build the *Application*.
 
diff --git a/doc/source/arch_sandboxing.rst b/doc/source/arch_sandboxing.rst
index 531a3e5d5..52679dedd 100644
--- a/doc/source/arch_sandboxing.rst
+++ b/doc/source/arch_sandboxing.rst
@@ -51,7 +51,7 @@ well.
 Filesystem access
 ~~~~~~~~~~~~~~~~~
 
-The filesystem inside sandboxes should be read only during element assembly,
+The filesystem inside sandboxes should be read-only during element assembly,
 except for certain directories which element plugins can mark as being
 read/write. Most elements plugins derive from :mod:`BuildElement
 <buildstream.buildelement>`, which marks ``%{build-root}`` and
@@ -158,17 +158,17 @@ and will refuse to push any artifacts built on such a system to a remote cache.
 For more information, see `issue #92
 <https://gitlab.com/BuildStream/buildstream/issues/92>`_.
 
-The Linux platform can operate as a standard user provided user namespace
+The Linux platform can operate as a standard user, if user namespace
 support is available. If user namespace support is not available you have the
 option of installing bubblewrap as a setuid binary to avoid needing to run the
 entire ``bst`` process as the ``root`` user.
 
-The artifact cache on Linux systems is implemented using `OSTree
-<https://github.com/ostreedev/ostree>`_, which can allow us to stage artifacts
-using hardlinks instead of copying them. To avoid cache corruption it is
-vital that hardlinked files cannot be overwritten. In cases where the root
-filesystem inside the sandbox needs to be writable, a custom FUSE filesystem
-named SafeHardlinks is used which provides a copy-on-write layer.
+The artifact cache on Linux systems is implemented using a content-addressable
+hardlink farm, which can allow us to stage artifacts using hardlinks instead of
+copying them. To avoid cache corruption it is vital that hardlinked files
+cannot be overwritten. In cases where the root filesystem inside the sandbox
+needs to be writable, a custom FUSE filesystem named SafeHardlinks is used
+which provides a copy-on-write layer.
 
 Some of the operations on filesystem metadata listed above are not prohibited
 by the sandbox, but will instead be silently dropped when an artifact is
diff --git a/doc/source/arch_scheduler.rst b/doc/source/arch_scheduler.rst
index bc1a3efcd..59efd68c2 100644
--- a/doc/source/arch_scheduler.rst
+++ b/doc/source/arch_scheduler.rst
@@ -19,9 +19,9 @@ The Job class has the following responsibilities:
 * Offering an abstract method for subclasses to handle the outcome of
   a job when it completes.
 
-* Forcefully terminating it's subprocess.
+* Forcefully terminating its subprocess.
 
-* Suspending and resuming it's subprocess.
+* Suspending and resuming its subprocess.
 
 * Declaring the types of resources it will require, and which resources
   it will require exclusively.
@@ -73,7 +73,7 @@ The Queue implementations are:
 
   The pull queue tries to obtain a built artifact from a remote artifact server,
   it should be placed in advance of the fetch queue if used, since we can safely
-  avoid fetching if fetching is not imerative, and we already have a cached
+  avoid fetching if fetching is not imperative, and we already have a cached
   artifact.
 
 * **Fetch**
@@ -84,7 +84,7 @@ The Queue implementations are:
 
 * **Build**
 
-  The build queue attempts to build the element if it's artifact is not locally
+  The build queue attempts to build the element if its artifact is not locally
   present.
 
 * **Push**