diff options
author | Tristan Van Berkom <tristan.vanberkom@codethink.co.uk> | 2018-03-02 20:49:31 +0900 |
---|---|---|
committer | Tristan Van Berkom <tristan.vanberkom@codethink.co.uk> | 2018-03-04 21:15:04 +0900 |
commit | 83370f55eccdd5c617ca20c025d623ba64a225df (patch) | |
tree | 784742fa2ee6d05179c3e32c63d319c073088ea2 | |
parent | bc0c4b714509862efcb20df82e11eca1e628a90d (diff) | |
download | buildstream-83370f55eccdd5c617ca20c025d623ba64a225df.tar.gz |
projectconf.rst: Amending documentation for `host-files`
This is now enhanced and an API change was introduced.
-rw-r--r-- | doc/source/projectconf.rst | 72 |
1 files changed, 54 insertions, 18 deletions
diff --git a/doc/source/projectconf.rst b/doc/source/projectconf.rst index 518e243f4..bfe416015 100644 --- a/doc/source/projectconf.rst +++ b/doc/source/projectconf.rst @@ -185,41 +185,77 @@ Host Files It can be useful to share some files on the host with a shell so that it can integrate better with the host environment. -The ``host-files`` configuration allows one to specify files on -the host to be bind mounted into the sandbox. If a file listed here -is found to be a directory on the host, or if the file does not exist -on the host at all; then a warning message will be printed and the shell -will still be launched. +The ``host-files`` configuration allows one to specify files and +directories on the host to be bind mounted into the sandbox. -The ``host-files`` configuration can be specified as a list -of filenames to be mirrored into the sandbox at the same location: +.. warning:: + + One should never mount directories where one expects to + find data and files which belong to the user, such as ``/home`` + on POSIX platforms. + + This is because the unsuspecting user may corrupt their own + files accidentally as a result. Instead users can use the + ``--mount`` option of ``bst shell`` to mount data into the shell. + + +The ``host-files`` configuration is an ordered list of *mount specifications*. + +Members of the list can be *fully specified* as a dictionary, or a simple +string can be used if only the defaults are required. + +The fully specified dictionary has the following members: + +* ``path`` + + The path inside the sandbox. This is the only mandatory + member of the mount specification. + +* ``host_path`` + + The host path to mount at ``path`` in the sandbox. This + will default to ``path`` if left unspecified. + +* ``optional`` + + Whether the mount should be considered optional. This + is ``False`` by default. + + +Here is an example of a *fully specified mount specification*: .. code:: yaml shell: - # Specify a list of files to mount in the sandbox - # directory from the host. + # Mount an arbitrary resolv.conf from the host to + # /etc/resolv.conf in the sandbox, and avoid any + # warnings if the host resolv.conf doesnt exist. host-files: - - '/etc/resolv.conf' - - '/etc/passwd' + - host_path: '/usr/local/work/etc/resolv.conf' + path: '/etc/resolv.conf' + optional: True -Alternatively, one can specify a dictionary with the ``host`` and ``sandbox`` -attributes for a bit more flexibility, allowing one to mount a file -from the host to an alternative location in the sandbox: +Here is an example of using *shorthand mount specifications*: .. code:: yaml shell: - # Mount the host's resolv.conf in a different location + # Specify a list of files to mount in the sandbox + # directory from the host. + # + # If these do not exist on the host, a warning will + # be issued but the shell will still be launched. host-files: - - host: '/etc/resolv.conf' - sandbox: '/usr/local/etc/resolv.conf' + - '/etc/passwd' + - '/etc/group' + - '/etc/resolv.conf' + .. note:: - The ``host-files`` configuration is available since :ref:`format version 2 <project_format_version>` + The ``host-files`` configuration is available since :ref:`format version 3 <project_format_version>` .. _project_plugins: |