diff mbox series

[2/2] sdk-manual: describe how to use extensible SDK functionality directly in a Yocto build

Message ID 20220802083803.2773818-2-alex@linutronix.de
State New
Headers show
Series [1/2] kernel-dev: working with kernel using devtool does not require building and installing eSDK | expand

Commit Message

Alexander Kanavin Aug. 2, 2022, 8:38 a.m. UTC 
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(-)

Comments

Michael Opdenacker Aug. 3, 2022, 2:52 p.m. UTC | #1 
Hi Alex,

On 8/2/22 10:38, Alexander Kanavin wrote:
> 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(-)


Thanks for the patch!

I had a few issues indentation issues but I fixed them:

/home/mike/work/git/git.yoctoproject.org/yocto-docs/documentation/sdk-manual/extensible.rst:1269: 
WARNING: Literal block expected; none found.
/home/mike/work/git/git.yoctoproject.org/yocto-docs/documentation/sdk-manual/working-projects.rst:93: 
ERROR: Unexpected indentation.
/home/mike/work/git/git.yoctoproject.org/yocto-docs/documentation/sdk-manual/working-projects.rst:288: 
ERROR: Unexpected indentation.

> diff --git a/documentation/sdk-manual/appendix-obtain.rst b/documentation/sdk-manual/appendix-obtain.rst
> index ece378c75..9b7717a4c 100644
> --- a/documentation/sdk-manual/appendix-obtain.rst
> +++ b/documentation/sdk-manual/appendix-obtain.rst
> @@ -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.


I replaced "bitbake" by "BitBake" here. That's how we usually refer to 
the tool.

>
> diff --git a/documentation/sdk-manual/extensible.rst b/documentation/sdk-manual/extensible.rst
> index ed9e43a2d..ae0587fec 100644
> --- a/documentation/sdk-manual/extensible.rst
> +++ b/documentation/sdk-manual/extensible.rst
> @@ -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

Here, I replaced "yocto" by "Yocto" too (4 times in this file).

> +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

s/rebuild/rebuilt/
Fixed

> diff --git a/documentation/sdk-manual/working-projects.rst b/documentation/sdk-manual/working-projects.rst
> index 7f8d9b849..12cb2efee 100644
> --- a/documentation/sdk-manual/working-projects.rst
> +++ b/documentation/sdk-manual/working-projects.rst
> @@ -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


Missing an empty line after "::" here. Fixed.

> +
>   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


Same here. Fixed too.

After the fixes: Reviewed-by: Michael Opdenacker 
<michael.opdenacker@bootlin.com>
... and merged into master-next.

Thanks again!
Michael.
diff mbox series

Patch

diff --git a/documentation/sdk-manual/appendix-customizing.rst b/documentation/sdk-manual/appendix-customizing.rst
index 9a76cc59d..23a437eb9 100644
--- a/documentation/sdk-manual/appendix-customizing.rst
+++ b/documentation/sdk-manual/appendix-customizing.rst
@@ -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
 ==============================
diff --git a/documentation/sdk-manual/appendix-obtain.rst b/documentation/sdk-manual/appendix-obtain.rst
index ece378c75..9b7717a4c 100644
--- a/documentation/sdk-manual/appendix-obtain.rst
+++ b/documentation/sdk-manual/appendix-obtain.rst
@@ -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:
diff --git a/documentation/sdk-manual/extensible.rst b/documentation/sdk-manual/extensible.rst
index ed9e43a2d..ae0587fec 100644
--- a/documentation/sdk-manual/extensible.rst
+++ b/documentation/sdk-manual/extensible.rst
@@ -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
diff --git a/documentation/sdk-manual/working-projects.rst b/documentation/sdk-manual/working-projects.rst
index 7f8d9b849..12cb2efee 100644
--- a/documentation/sdk-manual/working-projects.rst
+++ b/documentation/sdk-manual/working-projects.rst
@@ -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