doc/source/projectconf.rst: Added documentation about customizing the shell

2 files changed, 57 insertions, 0 deletions

diff --git a/doc/source/main_authoring.rst b/doc/source/main_authoring.rst
index 5482e902e..73d37f4d0 100644
--- a/doc/source/main_authoring.rst
+++ b/doc/source/main_authoring.rst
@@ -20,6 +20,7 @@ Project format
 * :ref:`projectconf`
 
   * :ref:`project_essentials`
+  * :ref:`project_shell`
   * :ref:`project_plugins`
   * :ref:`project_options`
   * :ref:`project_defaults`
diff --git a/doc/source/projectconf.rst b/doc/source/projectconf.rst
index 1faaf88fa..17abf997b 100644
--- a/doc/source/projectconf.rst
+++ b/doc/source/projectconf.rst
@@ -34,6 +34,8 @@ The project name will be used in user configuration and anywhere
 that a project needs to be specified.
 
 
+.. _project_format_version:
+
 Format Version
 ~~~~~~~~~~~~~~
 The BuildStream format is guaranteed to be backwards compatible
@@ -124,6 +126,60 @@ and the order that the elements were overlapped.
   fail-on-overlap: true
 
 
+.. _project_shell:
+
+Customizing the shell
+---------------------
+Since BuildStream cannot know intimate details about your host or about
+the nature of the runtime and software that you are building, the shell
+environment for debugging and testing applications may need some help.
+
+The ``shell`` section allows some customization of the shell environment.
+
+.. note::
+
+   The ``shell`` section is available since :ref:`format version 1 <project_format_version>`
+
+
+Interactive Shell Command
+~~~~~~~~~~~~~~~~~~~~~~~~~
+By default, BuildStream will use ``sh -i`` when running an interactive
+shell, unless a specific command is given to the ``bst shell`` command.
+
+BuildStream will automatically set a convenient prompt via the ``PS1``
+environment variable for interactive shells; which might be overwritten
+depending on the shell you use in your runtime.
+
+If you are using ``bash``, we recommend the following configuration to
+ensure that the customized prompt is not overwritten:
+
+.. code:: yaml
+
+   shell:
+
+     # Specify the command to run by default for interactive shells
+     command: [ 'bash', '--noprofile', '--norc', '-i' ]
+
+
+Environment Inheritance
+~~~~~~~~~~~~~~~~~~~~~~~
+In order to cooperate with your host environment, a debugging shell
+sometimes needs to know some of your host environment variables in
+order to be more useful.
+
+For example, to share your host ``DISPLAY`` and ``DBUS_SESSION_BUS_ADDRESS``
+environments with debugging shells for your project, specify the following:
+
+.. code:: yaml
+
+   shell:
+
+     # Environment variables to inherit from the host environment
+     environment-inherit:
+     - DISPLAY
+     - DBUS_SESSION_BUS_ADDRESS
+
+
 .. _project_plugins:
 
 External Plugins