[buildstream] branch tristan/command-subdir-docs created (now 90f4e83ad)

[tv...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

tvb pushed a change to branch tristan/command-subdir-docs
in repository https://gitbox.apache.org/repos/asf/buildstream.git


      at 90f4e83ad buildelement.py: Documentation fixes and enhancements

This branch includes the following new commits:

     new 90f4e83ad buildelement.py: Documentation fixes and enhancements

The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.

[buildstream] 01/01: buildelement.py: Documentation fixes and enhancements

[tv...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

tvb pushed a commit to branch tristan/command-subdir-docs
in repository https://gitbox.apache.org/repos/asf/buildstream.git

commit 90f4e83ad8e1a852672701af5566a93edb94c7ef
Author: Tristan van Berkom <tr...@codethink.co.uk>
AuthorDate: Tue Aug 23 17:05:08 2022 +0900

    buildelement.py: Documentation fixes and enhancements
    
     o Fix links to elements which no longer reside in BuildStream
    
     o Provide an example of running a srcdir != builddir build with autotools
    
     o Reworded some things a bit more clearly with regards to `command-subdir`,
       `conf-root` and `install-root`
---
 src/buildstream/buildelement.py | 61 ++++++++++++++++++++++++++++-------------
 1 file changed, 42 insertions(+), 19 deletions(-)

diff --git a/src/buildstream/buildelement.py b/src/buildstream/buildelement.py
index 772f7ecfd..a3bcd420e 100644
--- a/src/buildstream/buildelement.py
+++ b/src/buildstream/buildelement.py
@@ -81,35 +81,58 @@ an alternative location while staging some elements in the sandbox root.
 
 Location for running commands
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The ``command-subdir`` variable sets where the build commands will be executed,
-if the directory does not exist it will be created, it is defined relative to
-the buildroot.
+The ``command-subdir`` variable sets where commands will be executed,
+and the directory will be created automatically if it does not exist.
+
+The ``command-subdir`` is a relative path from ``%{build-root}``, and
+cannot be a parent or adjacent directory, it must expand to a subdirectory
+of ``${build-root}``.
 
 
 Location for configuring the project
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The ``conf-root`` is defined by default as ``.`` and is the location that
-specific build element can use to look for build configuration files. This is
-used by elements such as autotools, cmake, distutils, meson, pip and qmake.
+The ``conf-root`` is the location that specific build elements can use to look for build configuration files.
+This is used by elements such as `autotools <https://apache.github.io/buildstream-plugins/elements/autotools.html>`_,
+`cmake <https://apache.github.io/buildstream-plugins/elements/cmake.html>`_,
+`meson <https://apache.github.io/buildstream-plugins/elements/meson.html>`_,
+`setuptools <https://apache.github.io/buildstream-plugins/elements/setuptools.html>`_ and
+`pip <https://apache.github.io/buildstream-plugins/elements/pip.html>`_.
+
+The default value of ``conf-root`` is defined by default as ``.``. This means that if
+the ``conf-root`` is not explicitly set to another directory, the configuration
+files are expected to be found in ``command-subdir``.
+
 
-The configuration commands are run in ``command-subdir`` and by default
-``conf-root`` is ``.`` so if ``conf-root`` is not set the configuration files
-in ``command-subdir`` will be used.
+Separating source and build directories
+'''''''''''''''''''''''''''''''''''''''
+A typical example of using ``conf-root`` is when performing
+`autotools <https://apache.github.io/buildstream-plugins/elements/autotools.html>`_ builds
+where your source directory is separate from your build directory.
 
-By setting ``conf-root`` to ``"%{build-root}/Source/conf_location"`` and your
-source elements ``directory`` variable to ``Source`` then the configuration
-files in the directory ``conf_location`` with in your Source will be used.
-The current working directory when your configuration command is run will still
-be wherever you set your ``command-subdir`` to be, regardless of where the
-configure scripts are set with ``conf-root``.
+This can be achieved in build elements which use ``conf-root`` as follows:
+
+.. code:: yaml
+
+   variables:
+     # Specify that build configuration scripts are found in %{build-root}
+     conf-root: "%{build-root}"
+
+     # The build will run in the `_build` subdirectory
+     command-subdir: _build
 
 
 Install Location
 ~~~~~~~~~~~~~~~~
-You should not change the ``install-root`` variable as it is a special
-writeable location in the sandbox but it is useful when writing custom
-install instructions as it may need to be supplied as the ``DESTDIR``, please
-see the :mod:`cmake <elements.cmake>` build element for example.
+Build elements must install the build output to the directory defined by ``install-root``.
+
+You need not set or change the ``install-root`` variable as it will be defined
+automatically on your behalf, and it is used to collect build output when creating
+the resulting artifacts.
+
+It is important to know about ``install-root`` in order to write your own
+custom install instructions, for example the
+`cmake <https://apache.github.io/buildstream-plugins/elements/cmake.html>`_
+element will use it to specify the ``DESTDIR``.
 
 
 Abstract method implementations