diff options
author | Tristan Van Berkom <tristan.vanberkom@codethink.co.uk> | 2018-02-23 20:57:45 +0900 |
---|---|---|
committer | Tristan Van Berkom <tristan.vanberkom@codethink.co.uk> | 2018-02-23 22:14:53 +0900 |
commit | 00c6f4689cd107a81a05c07bbf73afe4ad347341 (patch) | |
tree | 6220b24b465708e834fb0e72fb20cf3cd55629e2 | |
parent | b65d2c45c47055d0bb0bf967392591db3e606cdf (diff) | |
download | buildstream-00c6f4689cd107a81a05c07bbf73afe4ad347341.tar.gz |
doc/source/projectconf.rst: Added documentation about customizing the shell
-rw-r--r-- | doc/source/main_authoring.rst | 1 | ||||
-rw-r--r-- | doc/source/projectconf.rst | 50 |
2 files changed, 51 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..10eac4979 100644 --- a/doc/source/projectconf.rst +++ b/doc/source/projectconf.rst @@ -124,6 +124,56 @@ 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. + + +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 + inherit-environment: + - DISPLAY + - DBUS_SESSION_BUS_ADDRESS + + .. _project_plugins: External Plugins |