@@ -1,11 +1,17 @@
.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
-******************************
-Customizing the Extensible SDK
-******************************
+***************************************************
+Customizing the Extensible SDK standalone installer
+***************************************************
This appendix describes customizations you can apply to the extensible
-SDK.
+SDK when using in the standalone installer version.
+
+.. note::
+
+ It is also possible to use the Extensible SDK functionality directly in a
+ Yocto build, avoiding separate installer artefacts. Please refer to
+ ":ref:`sdk-manual/extensible:Installing the Extensible SDK`"
Configuring the Extensible SDK
==============================
@@ -4,8 +4,22 @@
Obtaining the SDK
*****************
+Working with the SDK components directly in a Yocto build
+=========================================================
+
+Please refer to section
+":ref:`sdk-manual/extensible:Setting up the Extensible SDK environment directly in a Yocto build`"
+
+Note that to use this feature effectively either a powerful build
+machine, or a well-functioning sstate cache infrastructure is required:
+otherwise significant time could be spent waiting for components to be built
+by bitbake from source code.
+
+Working with standalone SDK Installers
+======================================
+
Locating Pre-Built SDK Installers
-=================================
+---------------------------------
You can use existing, pre-built toolchains by locating and running an
SDK installer script that ships with the Yocto Project. Using this
@@ -72,7 +86,7 @@ Follow these steps to locate and hand-install the toolchain:
section for more information.
Building an SDK Installer
-=========================
+-------------------------
As an alternative to locating and downloading an SDK installer, you can
build the SDK installer. Follow these steps:
@@ -41,6 +41,42 @@ functionality.
Installing the Extensible SDK
=============================
+Two ways to install the Extensible SDK
+--------------------------------------
+
+Extensible SDK can be installed in two different ways, and both have
+their own pros and cons:
+
+1. *Setting up the Extensible SDK environment directly in a Yocto build*. This
+avoids having to produce, test, distribute and maintain separate SDK installer
+archives, which can get very large. There is only one environment for the regular
+yocto build and the SDK and less code paths where things can go not according to plan.
+It's easier to update the SDK: it simply means updating the yocto layers with
+git fetch or layer management tooling. The SDK extensibility is better than in the
+second option: just run ``bitbake`` again to add more things to the sysroot, or add layers
+if even more things are required.
+
+2. *Setting up the Extensible SDK from a standalone installer*. This has the benefit of
+having a single, self-contained archive that includes all the needed binary artifacts.
+So nothing needs to be rebuild, and there is no need to provide a well-functioning
+binary artefact cache over the network for developers with underpowered laptops.
+
+Setting up the Extensible SDK environment directly in a Yocto build
+-------------------------------------------------------------------
+
+1. Set up all the needed layers and a yocto build directory, e.g. a regular yocto
+ build where ``bitbake`` can be executed.
+
+2. Run:
+ $ bitbake meta-ide-support
+ $ bitbake -c populate_sysroot gtk+3
+ (or any other target or native item that the application developer would need)
+ $ bitbake populate-sysroots
+
+
+Setting up the Extensible SDK from a standalone installer
+---------------------------------------------------------
+
The first thing you need to do is install the SDK on your :term:`Build
Host` by running the ``*.sh`` installation script.
@@ -136,7 +172,12 @@ Running the Extensible SDK Environment Setup Script
===================================================
Once you have the SDK installed, you must run the SDK environment setup
-script before you can actually use the SDK. This setup script resides in
+script before you can actually use the SDK.
+
+When using a SDK directly in a Yocto build, you will find the script in
+``tmp/deploy/images/qemux86-64/`` in your build directory.
+
+When using a standalone SDK installer, this setup script resides in
the directory you chose when you installed the SDK, which is either the
default ``poky_sdk`` directory or the directory you chose during
installation.
@@ -154,6 +195,11 @@ script is for an IA-based target machine using i586 tuning::
SDK environment now set up; additionally you may now run devtool to perform development tasks.
Run devtool --help for further details.
+When using the environment script directly in a Yocto build, it can
+be run similarly:
+
+ $ source tmp/deploy/images/qemux86-64/environment-setup-core2-64-poky-linux
+
Running the setup script defines many environment variables needed in
order to use the SDK (e.g. ``PATH``,
:term:`CC`,
@@ -1215,10 +1261,24 @@ need to link to libGL but you are not sure which recipe provides libGL.
You can use the following command to find out::
$ devtool search libGL mesa
+ A free implementation of the OpenGL API
-A free implementation of the OpenGL API Once you know the recipe
+Once you know the recipe
(i.e. ``mesa`` in this example), you can install it::
+When using the extensible SDK directly in a Yocto build
+-------------------------------------------------------
+
+In this scenario, the Yocto build tooling, e.g. ``bitbake``
+is directly accessible to build additional items, and it
+can simply be executed directly:
+
+ $ bitbake mesa
+ $ bitbake populate-sysroots
+
+When using a standalone installer for the Extensible SDK
+--------------------------------------------------------
+
$ devtool sdk-install mesa
By default, the ``devtool sdk-install`` command assumes
@@ -88,6 +88,10 @@ project:
$ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
+ Another example is sourcing the environment setup directly in a yocto
+ build::
+ $ source tmp/deploy/images/qemux86-64/environment-setup-core2-64-poky-linux
+
3. *Create the configure Script:* Use the ``autoreconf`` command to
generate the ``configure`` script.
::
@@ -279,6 +283,10 @@ example:
$ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
+ Another example is sourcing the environment setup directly in a yocto
+ build::
+ $ source tmp/deploy/images/qemux86-64/environment-setup-core2-64-poky-linux
+
3. *Create the Makefile:* For this example, the Makefile contains
two lines that can be used to set the :term:`CC` variable. One line is
identical to the value that is set when you run the SDK environment
Signed-off-by: Alexander Kanavin <alex@linutronix.de> --- .../sdk-manual/appendix-customizing.rst | 14 ++-- documentation/sdk-manual/appendix-obtain.rst | 18 +++++- documentation/sdk-manual/extensible.rst | 64 ++++++++++++++++++- documentation/sdk-manual/working-projects.rst | 8 +++ 4 files changed, 96 insertions(+), 8 deletions(-)