From d2651d134a449f7bb198c7af7899880fc9eb9a59 Mon Sep 17 00:00:00 2001 From: Sergio Schvezov Date: Fri, 19 Apr 2024 16:27:45 -0300 Subject: [PATCH 1/4] feat(docs): scons plugin reference Signed-off-by: Sergio Schvezov --- .../reference/plugins/scons_plugin.rst | 61 +++++++++++++++++++ docs/reference/plugins.rst | 1 + 2 files changed, 62 insertions(+) create mode 100644 docs/common/craft-parts/reference/plugins/scons_plugin.rst diff --git a/docs/common/craft-parts/reference/plugins/scons_plugin.rst b/docs/common/craft-parts/reference/plugins/scons_plugin.rst new file mode 100644 index 00000000..e1ff3859 --- /dev/null +++ b/docs/common/craft-parts/reference/plugins/scons_plugin.rst @@ -0,0 +1,61 @@ +.. _craft_parts_scons_plugin: + +Scons plugin +============ + +The Scons plugin builds projects using Scons_. + +After a successful build, this plugin will installs the generated +binaries in ``$CRAFT_PART_INSTALL``. + +Keywords +-------- + +In addition to the common :ref:`plugin ` and +:ref:`sources ` keywords, this plugin provides the following +plugin-specific keywords: + +scons-parameters +~~~~~~~~~~~~~~~~ +**Type:** list of strings +**Default:** [] + +Parameters to pass to scons for building and installation. + +Environment variables +--------------------- + +This plugin sets ``DESTDIR`` to ``$CRAFT_PART_INSTALL``. + +Dependencies +------------ + +The Scons plugin needs the ``scons`` executable work. + + +How it works +------------ + +During the build step the plugin performs the following actions: + +* Run ``scons`` with any ``scons-parameters`` that might have been set; +* Run ``scons install`` with any ``scons-parameters`` that might have been set, + the ``DESTDIR`` environment variable would affect the final installation path. + +Examples +-------- + +The following snippet declares a part using the ``scons`` plugin. It +sets the ``scons-parameters`` for a ``prefix`` to be set to ``/usr``: + +.. code-block:: yaml + + parts: + gpsd: + source: . + plugin: scons + scons-parameters: + - prefix=/usr + +.. _Scons: https://scons.org/ + diff --git a/docs/reference/plugins.rst b/docs/reference/plugins.rst index 4839fc27..f672772e 100644 --- a/docs/reference/plugins.rst +++ b/docs/reference/plugins.rst @@ -19,6 +19,7 @@ lifecycle. /common/craft-parts/reference/plugins/nil_plugin.rst /common/craft-parts/reference/plugins/python_plugin.rst /common/craft-parts/reference/plugins/rust_plugin.rst + /common/craft-parts/reference/plugins/scons_plugin.rst When documenting a new plugin, follow the guidelines in :ref:`how_to_document_a_plugin`. From 57ff2764188b118993fd582d0b8d0fe656763bdf Mon Sep 17 00:00:00 2001 From: Sergio Schvezov Date: Tue, 23 Apr 2024 11:45:13 -0300 Subject: [PATCH 2/4] fix: wording suggestions from review Co-authored-by: Alex Lowe Co-authored-by: Tiago Nobrega --- docs/common/craft-parts/reference/plugins/scons_plugin.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/common/craft-parts/reference/plugins/scons_plugin.rst b/docs/common/craft-parts/reference/plugins/scons_plugin.rst index e1ff3859..61d00783 100644 --- a/docs/common/craft-parts/reference/plugins/scons_plugin.rst +++ b/docs/common/craft-parts/reference/plugins/scons_plugin.rst @@ -5,7 +5,7 @@ Scons plugin The Scons plugin builds projects using Scons_. -After a successful build, this plugin will installs the generated +After a successful build, this plugin will install the generated binaries in ``$CRAFT_PART_INSTALL``. Keywords @@ -30,7 +30,7 @@ This plugin sets ``DESTDIR`` to ``$CRAFT_PART_INSTALL``. Dependencies ------------ -The Scons plugin needs the ``scons`` executable work. +The Scons plugin needs the ``scons`` executable to work. How it works From 2e29713b768f0752cbbe1c0d291165ac2b3a6b2c Mon Sep 17 00:00:00 2001 From: Sergio Schvezov Date: Tue, 23 Apr 2024 11:46:37 -0300 Subject: [PATCH 3/4] fix: correct capitalization for SCons Signed-off-by: Sergio Schvezov --- .../craft-parts/reference/plugins/scons_plugin.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/common/craft-parts/reference/plugins/scons_plugin.rst b/docs/common/craft-parts/reference/plugins/scons_plugin.rst index 61d00783..ea603b9b 100644 --- a/docs/common/craft-parts/reference/plugins/scons_plugin.rst +++ b/docs/common/craft-parts/reference/plugins/scons_plugin.rst @@ -1,9 +1,9 @@ .. _craft_parts_scons_plugin: -Scons plugin +SCons plugin ============ -The Scons plugin builds projects using Scons_. +The SCons plugin builds projects using SCons_. After a successful build, this plugin will install the generated binaries in ``$CRAFT_PART_INSTALL``. @@ -20,7 +20,7 @@ scons-parameters **Type:** list of strings **Default:** [] -Parameters to pass to scons for building and installation. +Parameters to pass to SCons for building and installation. Environment variables --------------------- @@ -30,7 +30,7 @@ This plugin sets ``DESTDIR`` to ``$CRAFT_PART_INSTALL``. Dependencies ------------ -The Scons plugin needs the ``scons`` executable to work. +The SCons plugin needs the ``scons`` executable to work. How it works @@ -57,5 +57,5 @@ sets the ``scons-parameters`` for a ``prefix`` to be set to ``/usr``: scons-parameters: - prefix=/usr -.. _Scons: https://scons.org/ +.. _SCons: https://scons.org/ From 86abdc937fe9541961abd65c30eb19df7ed5234a Mon Sep 17 00:00:00 2001 From: Sergio Schvezov Date: Tue, 23 Apr 2024 11:57:07 -0300 Subject: [PATCH 4/4] fix: details on how to provide scons Signed-off-by: Sergio Schvezov --- .../reference/plugins/scons_plugin.rst | 23 ++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/docs/common/craft-parts/reference/plugins/scons_plugin.rst b/docs/common/craft-parts/reference/plugins/scons_plugin.rst index ea603b9b..f158a8fb 100644 --- a/docs/common/craft-parts/reference/plugins/scons_plugin.rst +++ b/docs/common/craft-parts/reference/plugins/scons_plugin.rst @@ -30,7 +30,19 @@ This plugin sets ``DESTDIR`` to ``$CRAFT_PART_INSTALL``. Dependencies ------------ -The SCons plugin needs the ``scons`` executable to work. +The SCons plugin needs the ``scons`` executable to build, but does not +provision it by itself. + +The common means of providing ``scons`` is through a +:ref:`build-packages ` entry which for Ubuntu, would be ``scons``. + +Another alternative is to define another part with the name ``scons-deps``, and +declare that the part using the ``scons`` plugin comes :ref:`after ` the +``scons-deps`` part. In this case, the plugin will assume that this new part will +provide the ``scons`` executable to be used in the build step. This can be useful, +for example, in cases where a specific, unreleased version of ``scons`` is desired +but only possible by either building the tool itself from source or through some +other custom mechanism. How it works @@ -46,7 +58,9 @@ Examples -------- The following snippet declares a part using the ``scons`` plugin. It -sets the ``scons-parameters`` for a ``prefix`` to be set to ``/usr``: +sets the ``scons-parameters`` for a ``prefix`` to be set to +``/usr``. To ``scons`` executable dependency is satisfied with +:ref:`build-packages `: .. code-block:: yaml @@ -55,7 +69,10 @@ sets the ``scons-parameters`` for a ``prefix`` to be set to ``/usr``: source: . plugin: scons scons-parameters: - - prefix=/usr + - prefix=/usr + build-packages: + - scons + .. _SCons: https://scons.org/