Improve documentation for autotools, cmake and meson elements

The key change is to document the correct usage of the conf-local
and conf-global style options, as it was previously impossible to
figure that out from the documentation.

6 files changed, 101 insertions, 13 deletions

diff --git a/buildstream/plugins/elements/autotools.py b/buildstream/plugins/elements/autotools.py
index 992858e06..058c92a60 100644
--- a/buildstream/plugins/elements/autotools.py
+++ b/buildstream/plugins/elements/autotools.py
@@ -20,10 +20,34 @@
 
 """Autotools build element
 
-A :mod:`BuildElement <buildstream.buildelement>` implementation for using
-autotools build scripts
+This is a :mod:`BuildElement <buildstream.buildelement>` implementation for
+using Autotools build scripts (also known as the `GNU Build System
+<https://en.wikipedia.org/wiki/GNU_Build_System>`_).
+
+You will often want to pass additional arguments to ``configure``. This should
+be done on a per-element basis by setting the ``conf-local`` variable.  Here is
+an example:
+
+.. code:: yaml
+
+   variables:
+     conf-local: |
+       --disable-foo --enable-bar
+
+If you want to pass extra options to ``configure`` for every element in your
+project, set the ``conf-global`` variable in your project.conf file. Here is
+an example of that:
+
+.. code:: yaml
+
+   elements:
+     autotools:
+       variables:
+         conf-global: |
+           --disable-gtk-doc --disable-static
+
+Here is the default configuration for the ``autotools`` element in full:
 
-The autotools default configuration:
   .. literalinclude:: ../../../buildstream/plugins/elements/autotools.yaml
      :language: yaml
 """
diff --git a/buildstream/plugins/elements/autotools.yaml b/buildstream/plugins/elements/autotools.yaml
index 6a1664883..97ab0664c 100644
--- a/buildstream/plugins/elements/autotools.yaml
+++ b/buildstream/plugins/elements/autotools.yaml
@@ -11,10 +11,16 @@ variables:
     else autoreconf -ivf;
     fi
 
-  conf-cmd: ./configure
-  conf-extra: ''
+  # Project-wide extra arguments to be passed to `configure`
   conf-global: ''
+
+  # Element-specific extra arguments to be passed to `configure`.
   conf-local: ''
+
+  # For backwards compatibility only, do not use.
+  conf-extra: ''
+
+  conf-cmd: ./configure
   conf-args: |
 
     --prefix=%{prefix} \
diff --git a/buildstream/plugins/elements/cmake.py b/buildstream/plugins/elements/cmake.py
index b13a25abf..9b284891a 100644
--- a/buildstream/plugins/elements/cmake.py
+++ b/buildstream/plugins/elements/cmake.py
@@ -20,10 +20,33 @@
 
 """CMake build element
 
-A :mod:`BuildElement <buildstream.buildelement>` implementation for using
-cmake build scripts
+This is a :mod:`BuildElement <buildstream.buildelement>` implementation for
+using the `CMake <https://cmake.org/>`_ build system.
+
+You will often want to pass additional arguments to the ``cmake`` program for
+specific configuration options. This should be done on a per-element basis by
+setting the ``cmake-local`` variable.  Here is an example:
+
+.. code:: yaml
+
+   variables:
+     cmake-local: |
+       -DCMAKE_BUILD_TYPE=Debug
+
+If you want to pass extra options to ``cmake`` for every element in your
+project, set the ``cmake-global`` variable in your project.conf file. Here is
+an example of that:
+
+.. code:: yaml
+
+   elements:
+     cmake:
+       variables:
+         cmake-global: |
+           -DCMAKE_BUILD_TYPE=Release
+
+Here is the default configuration for the ``cmake`` element in full:
 
-The cmake default configuration:
   .. literalinclude:: ../../../buildstream/plugins/elements/cmake.yaml
      :language: yaml
 """
diff --git a/buildstream/plugins/elements/cmake.yaml b/buildstream/plugins/elements/cmake.yaml
index 1bddc0857..234aa1770 100644
--- a/buildstream/plugins/elements/cmake.yaml
+++ b/buildstream/plugins/elements/cmake.yaml
@@ -4,9 +4,15 @@ variables:
 
   build-dir: _builddir
 
-  cmake-extra: ''
+  # Project-wide extra arguments to be passed to `cmake`
   cmake-global: ''
+
+  # Element-specific extra arguments to be passed to `cmake`.
   cmake-local: ''
+
+  # For backwards compatibility only, do not use.
+  cmake-extra: ''
+
   cmake-args: |
 
     -DCMAKE_INSTALL_PREFIX:PATH="%{prefix}" \
diff --git a/buildstream/plugins/elements/meson.py b/buildstream/plugins/elements/meson.py
index 4b9c21fb9..af10fabc3 100644
--- a/buildstream/plugins/elements/meson.py
+++ b/buildstream/plugins/elements/meson.py
@@ -15,10 +15,33 @@
 
 """Meson build element
 
-A :mod:`BuildElement <buildstream.buildelement>` implementation for using
-Meson build scripts
+This is a :mod:`BuildElement <buildstream.buildelement>` implementation for
+using `Meson <http://mesonbuild.com/>`_ build scripts.
+
+You will often want to pass additional arguments to ``meson``. This should
+be done on a per-element basis by setting the ``meson-local`` variable.  Here is
+an example:
+
+.. code:: yaml
+
+   variables:
+     meson-local: |
+       -Dmonkeys=yes
+
+If you want to pass extra options to ``meson`` for every element in your
+project, set the ``meson-global`` variable in your project.conf file. Here is
+an example of that:
+
+.. code:: yaml
+
+   elements:
+     meson:
+       variables:
+         meson-global: |
+           -Dmonkeys=always
+
+Here is the default configuration for the ``meson`` element in full:
 
-The meson default configuration:
   .. literalinclude:: ../../../buildstream/plugins/elements/meson.yaml
      :language: yaml
 """
diff --git a/buildstream/plugins/elements/meson.yaml b/buildstream/plugins/elements/meson.yaml
index 57d09dd1c..7af9a76e4 100644
--- a/buildstream/plugins/elements/meson.yaml
+++ b/buildstream/plugins/elements/meson.yaml
@@ -4,9 +4,15 @@ variables:
 
   build-dir: _builddir
 
-  meson-extra: ''
+  # Project-wide extra arguments to be passed to `meson`
   meson-global: ''
+
+  # Element-specific extra arguments to be passed to `meson`.
   meson-local: ''
+
+  # For backwards compatibility only, do not use.
+  meson-extra: ''
+
   meson-args: |
 
     --prefix=%{prefix} \