[GitHub] [buildstream] nanonyme commented on a diff in pull request #1734: buildelement.py: Documentation fixes and enhancements

[GitBox <gi...@apache.org>]

nanonyme commented on code in PR #1734:
URL: https://github.com/apache/buildstream/pull/1734#discussion_r953037934


##########
src/buildstream/buildelement.py:
##########
@@ -81,35 +81,58 @@
 
 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

Review Comment:
   Does this make any sense in BuildStream core? cmake and meson elements do not do it like this, instead they have build-dir variable which is passed to build system.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@buildstream.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org