[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