From 6babbc3f7b4cafd4192d30d130fd24cd93773df8 Mon Sep 17 00:00:00 2001
From: William Salmon <will.salmon@codethink.co.uk>
Date: Tue, 11 Sep 2018 11:40:56 +0100
Subject: [PATCH] Extended the Documentation to cover out of source builds
---
buildstream/buildelement.py | 32 ++++++++++++++++++++++++++++++++
buildstream/source.py | 13 +++++++++++++
2 files changed, 45 insertions(+)
diff --git a/buildstream/buildelement.py b/buildstream/buildelement.py
index 5447c13be6..12b867d707 100644
--- a/buildstream/buildelement.py
+++ b/buildstream/buildelement.py
@@ -23,6 +23,38 @@ BuildElement - Abstract class for build elements
The BuildElement class is a convenience element one can derive from for
implementing the most common case of element.
+Built-in functionality
+----------------------
+
+The BuildElement base class provides built in functionality that could be overridden by the
+individual plugins.
+
+This section will give a brief summary of how some of the common features work, some of them or the variables they
+use will be further detailed in the following sections.
+
+* Location for running commands
+
+ The ``command-subdir`` variable sets where the build commands will be executed, if the directory dose not exist it
+ will be created, it is defined relative to the buildroot.
+
+* 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, currently autotools and cmake use this.
+
+ 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.
+
+ 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.
+ However the location where your configuration command will be run will still be wherever you set your
+ ``command-subdir`` to be.
+
+* 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
+ cmake build element for example.
Abstract method implementations
-------------------------------
diff --git a/buildstream/source.py b/buildstream/source.py
index e6350161f8..e8f69c2612 100644
--- a/buildstream/source.py
+++ b/buildstream/source.py
@@ -20,6 +20,19 @@
Source - Base source class
==========================
+Built-in functionality
+----------------------
+
+The Source base class provides built in functionality that could be overridden by the
+individual plugins.
+
+* Directory
+
+ The ``directory`` variable can be set for all sources of a type in project.conf
+ or per source within a element.
+
+ This sets the location with in the build root that the content of the source will be
+ loaded in to. If the location dose not exist it will be created.
.. _core_source_abstract_methods:
--
GitLab