Yocto Project - User contributions [en]

Application Development with Extensible SDK

2016-09-09T19:09:56Z

L.S. Cook: /* Creating a recipe from existing source */

'''[WORK IN PROGRESS]'''

Welcome to the Yocto Project Test Kitchen! It can be a bit overwhelming to know where to start with the Yocto Project. You know you want to build an application that runs on embedded hardware, but where and how do you get started? A development environment can be an abstract, somewhat hard-to-imagine thing. This part of the wiki is intended to fill the knowledge gap between the [http://www.yoctoproject.org/docs/2.1/yocto-project-qs/yocto-project-qs.html Quick Start] and the myriad of ways to build an image and run it on real (or emulated) hardware. So what better way to do that than with a "Test Kitchen" analogy?

Our Test Kitchen must be Linux-powered, of course. And using one of the [http://www.yoctoproject.org/docs/2.1/ref-manual/ref-manual.html#detailed-supported-distros supported distributions] in our Linux-powered kitchen means that we'll already either '''have''' or have a way to '''easily get''' everything we need to follow the recipes in our Cookbook.

=== What devtool can do ===

One of the most powerful tools in our test kitchen is '''devtool'''. We can think of devtool as something that can be used to "mix" customization into our Yocto Project image. Some of the common ways to get mixing are:

* To add new applications and libraries to a Yocto Project image,
* To modify the source for an existing component,
* To test changes on target hardware, and
* To integrate that change into the rest of the OpenEmbedded (OE) build system.

In short, we can think of devtool as a single point of entry for creating, modifying and testing recipes.

=== What devtool cannot do ===

Note that devtool cannot add your recipe to a layer, nor can it update your build configuration to include it in a image. These steps are covered elsewhere in the [[Cookbook]]. Devtool can, however, be used with both the Yocto Project build environment and the [http://www.yoctoproject.org/docs/latest/sdk-manual/sdk-manual.html#sdk-extensible Extensible SDK].

(From the Yocto Project documentation: Here's a presentation by Trevor Woerner that, while somewhat dated, provides detailed background information and a complete working
[https://drive.google.com/a/linaro.org/file/d/0B3KGzY5fW7laTDVxUXo3UDRvd2s/view Yocto Project Developer Workflow Tutorial].)

== How to get devtool ==
=== Standard build environment ===
If you have set up the Yocto Project build environment using the Quick Start Guide, you already have access to devtool for qemux86 image.

=== Extensible SDK ===
Alternatively you can install an '''Extensible SDK (eSDK)'''. These come in two flavors; "minimal" and "full". The "minimal" eSDK is the preferred option as it comes as a small 30Mb installer and downloads the components it needs depending on requirements of application project. The installer contains the URL of an sstate mirror so it does not no need to build all dependencies from source code. The "full" eSDK contains all the components already built so is much larger (similar in size to traditional SDK, i.e. at least 1GB). The [http://www.yoctoproject.org/docs/2.1/sdk-manual/sdk-manual.html#sdk-extensible Yocto SDK Manual] contains more details on installing and using the eSDK.

Currently the Yocto Project autobuilder only builds "full" eSDKs. The qemux86 full eSDK can be found [http://downloads.yoctoproject.org/releases/yocto/yocto-2.1/toolchain/x86_64/poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-2.1.sh here]. There is a [https://bugzilla.yoctoproject.org/show_bug.cgi?id=9596 feature enhancement request] for the autobuilder to create minimal eSDKs.

In the meantime, an experimental minimal qemux86 eSDK can be found [https://downloads.yoctoproject.org/tools/support/workflow/poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-2.1.1.sh here].

To install the extensible SDK, make sure it is executable and then run
poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-2.1.1.sh -d /path/to/esdk
Note that installation will take 7-10 minutes.<br/>
The configure build environment, run
source /path/to/esdk/environment-setup-i586-poky-linux

== Creating a recipe from existing source ==
Let's say you have a C application that you want to add to your OS image. Assume repo is https://github.com/whbruce/bbexample.git and you want to name recipe (and thus the executable it creates) bbexample.
devtool add bbexample https://github.com/whbruce/bbexample.git
You will see the following output
NOTE: Creating workspace layer in /path/to/build/workspace
NOTE: Enabling workspace layer in bblayers.conf
NOTE: Using default source tree path /path/to/build/workspace/sources/bbexample
NOTE: Recipe /path/to/build/workspace/recipes/bbexample/bbexample_git.bb has been automatically created; further editing may be required to make it fully functional
Key entries here are the locations of the source code in <tt>/path/to/build/workspace/sources/bbexample</tt>. Note that git will create a branch named <tt>devtool</tt> for your work. The recipe is in <tt>/path/to/build/workspace/recipes/bbexample/bbexample_git.bb</tt><br/>
You can now look at the generated recipe with
devtool edit-recipe bbexample
We'll take a look at what's in the recipe. Comments and whitespace have been removed for easier reading
LICENSE = "Unknown"
LIC_FILES_CHKSUM = "file://LICENSE;md5=96af5705d6f64a88e035781ef00e98a8"
SRC_URI = "git://github.com/whbruce/bbexample.git;protocol=https"
# Modify these as desired
PV = "0.1+git${SRCPV}"
SRCREV = "${AUTOREV}"
S = "${WORKDIR}/git"
inherit autotools
EXTRA_OECONF = ""
Let's go through the bitbake commands and variables in the recipe and explain what they do:
;LICENSE
:The type of license. This is set to unknown because devtool cannot recognize the old MIT text.
;LIC_FILES_CHKSUM
:devtool looks in the root of the source folder for a file called LICENSE, and generates a checksum to ensure checkout has been successful.
;SRC_URI
:The git repo given in the 'devtool add' command. This is where the source will be pulled from.
;PV
:The package version. Usually taken from recipe filename (e.g. bbexample_0.1.bb would automatically set PV = "0.1")
;SRCREV
:the git revision to checkout. ${AUTOREV} means HEAD and must be used during app development. It should be set a specific commit before being added to a layer.
;S
:Where the source can be found after being fetched and unpacked.
;inherit autotools
:Use a bitbake class that can configure, build and install an autotools project
;EXTRA_OECONF
:Options to be passed to configure script. In this case it is empty, so is not necessary.

== Building ==
$ devtool build bbexample
Parsing recipes: 100% |#########################################| ETA: 00:00:00
Parsing of 872 .bb files complete (0 cached, 872 parsed). 1302 targets, 47 skipped, 0 masked, 0 errors.
NOTE: Resolving any missing task queue dependencies
NOTE: Preparing RunQueue
NOTE: Checking sstate mirror object availability (for 51 objects)
NOTE: Executing SetScene Tasks
NOTE: Executing RunQueue Tasks
NOTE: bbexample: compiling from external source tree /path/to/esdk/workspace/sources/bbexample
NOTE: Tasks Summary: Attempted 342 tasks of which 336 didn't need to be rerun and all succeeded.
This build command runs bitbake just as in a full Yocto Project OS image build. The key line in the output is '''Checking sstate mirror object availability (for 51 objects)'''. As the extensible SDK installer gives you a minimal build environment it has to download all the dependencies (e.g. native build tools and necessary target libraries). Here 51 objects have been found and are downloaded in their pre-built state greatly speeding up the build process (i.e. we just run 342 tasks of which 336 didn't need to be rerun). This is the extensible part of the SDK in action.

== Start QEMU (headless) ==

Before deploying, the target must be running, have a network connection, and have an ssh server running. In this case, we'll start the qemux86 target as follows.

$ runqemu qemux86 nographic

== Deploying ==

$ devtool deploy-target -s bbexample root@192.168.7.2
Parsing recipes..done.
devtool_deploy.list 100% 167 0.2KB/s 00:00
devtool_deploy.sh 100% 1002 1.0KB/s 00:00
./
./usr/
./usr/bin/
./usr/bin/bbexample
./usr/include/
./usr/include/bbexample.h
./usr/lib/
./usr/lib/libbbexample.so.1
./usr/lib/libbbexample.so
./usr/lib/libbbexample.so.1.0.0
./usr/lib/libbbexample.la
NOTE: Successfully deployed /path/to/esdk/sdk/tmp/work/i586-poky-linux/bbexample/0.1+git999-r0/image

== Running ==
root@qemux86:~# bbexample
Hello Yocto World...
Hello World (from a shared library!)

== Build Image ==
To test the updated OS image that now includes your application, you can build it as follows. If you are in a eSDK environment, devtool will automatically build the image used to create the SDK. If in the standard build environment you must specify an image.
devtool build-image [image-name]
Output will be as follows:
<pre>
Parsing recipes..done.
NOTE: Building image core-image-minimal with the following additional packages: bbexample
Loading cache: 100% |###########################################| ETA: 00:00:00
Loaded 1302 entries from dependency cache.
Parsing recipes: 100% |#########################################| Time: 00:00:00
Parsing of 872 .bb files complete (870 cached, 2 parsed). 1302 targets, 49 skipped, 0 masked, 0 errors.
NOTE: Resolving any missing task queue dependencies

Build Configuration:
BB_VERSION = "1.30.0"
BUILD_SYS = "x86_64-linux"
NATIVELSBSTRING = "universal"
TARGET_SYS = "i586-poky-linux"
MACHINE = "qemux86"
DISTRO = "poky"
DISTRO_VERSION = "2.1"
TUNE_FEATURES = "m32 i586"
TARGET_FPU = ""
meta
meta-poky
meta-yocto-bsp = "krogoth:f7b994b75261550faa3ccf9005fc174950c7bee9"
workspace = "<unknown>:<unknown>"

NOTE: Preparing RunQueue
NOTE: Executing SetScene Tasks
NOTE: Executing RunQueue Tasks
bbexample-0.1+git999-r0 do_compile: NOTE: bbexample: compiling from external source tree /path/to/build/workspace/sources/bbexample
NOTE: Tasks Summary: Attempted 2062 tasks of which 2046 didn't need to be rerun and all succeeded.
NOTE: Successfully built core-image-minimal. You can find output files in /path/to/build/tmp/deploy/images/qemux86
</pre>

== Publish Recipe ==
Once application has been tested, you can make the recipe available. It will be in /path/to/build/workspace/recipes/bbexample. Make sure you add a version tothe filename (e.g. bbexample_1.0.bb)

== Update Existing Recipe ==
Updating a recipe is similar to creating one; however, rather than using <tt>devtool add</tt> we use the <tt>devtool modify</tt> command.
devtool modify bbexample

The edit/build/test cycle is then the same as for adding a recipe.

'''[WORK IN PROGRESS]'''

<hr>
Back to the [[Cookbook]] home page.

Application Development with Extensible SDK

2016-09-09T14:27:20Z

L.S. Cook:

'''[WORK IN PROGRESS]'''

Welcome to the Yocto Project Test Kitchen! It can be a bit overwhelming to know where to start with the Yocto Project. You know you want to build an application that runs on embedded hardware, but where and how do you get started? A development environment can be an abstract, somewhat hard-to-imagine thing. This part of the wiki is intended to fill the knowledge gap between the [http://www.yoctoproject.org/docs/2.1/yocto-project-qs/yocto-project-qs.html Quick Start] and the myriad of ways to build an image and run it on real (or emulated) hardware. So what better way to do that than with a "Test Kitchen" analogy?

Our Test Kitchen must be Linux-powered, of course. And using one of the [http://www.yoctoproject.org/docs/2.1/ref-manual/ref-manual.html#detailed-supported-distros supported distributions] in our Linux-powered kitchen means that we'll already either '''have''' or have a way to '''easily get''' everything we need to follow the recipes in our Cookbook.

=== What devtool can do ===

One of the most powerful tools in our test kitchen is '''devtool'''. We can think of devtool as something that can be used to "mix" customization into our Yocto Project image. Some of the common ways to get mixing are:

* To add new applications and libraries to a Yocto Project image,
* To modify the source for an existing component,
* To test changes on target hardware, and
* To integrate that change into the rest of the OpenEmbedded (OE) build system.

In short, we can think of devtool as a single point of entry for creating, modifying and testing recipes.

=== What devtool cannot do ===

Note that devtool cannot add your recipe to a layer, nor can it update your build configuration to include it in a image. These steps are covered elsewhere in the [[Cookbook]]. Devtool can, however, be used with both the Yocto Project build environment and the [http://www.yoctoproject.org/docs/latest/sdk-manual/sdk-manual.html#sdk-extensible Extensible SDK].

(From the Yocto Project documentation: Here's a presentation by Trevor Woerner that, while somewhat dated, provides detailed background information and a complete working
[https://drive.google.com/a/linaro.org/file/d/0B3KGzY5fW7laTDVxUXo3UDRvd2s/view Yocto Project Developer Workflow Tutorial].)

== How to get devtool ==
=== Standard build environment ===
If you have set up the Yocto Project build environment using the Quick Start Guide, you already have access to devtool for qemux86 image.

=== Extensible SDK ===
Alternatively you can install an '''Extensible SDK (eSDK)'''. These come in two flavors; "minimal" and "full". The "minimal" eSDK is the preferred option as it comes as a small 30Mb installer and downloads the components it needs depending on requirements of application project. The installer contains the URL of an sstate mirror so it does not no need to build all dependencies from source code. The "full" eSDK contains all the components already built so is much larger (similar in size to traditional SDK, i.e. at least 1GB). The [http://www.yoctoproject.org/docs/2.1/sdk-manual/sdk-manual.html#sdk-extensible Yocto SDK Manual] contains more details on installing and using the eSDK.

Currently the Yocto Project autobuilder only builds "full" eSDKs. The qemux86 full eSDK can be found [http://downloads.yoctoproject.org/releases/yocto/yocto-2.1/toolchain/x86_64/poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-2.1.sh here]. There is a [https://bugzilla.yoctoproject.org/show_bug.cgi?id=9596 feature enhancement request] for the autobuilder to create minimal eSDKs.

In the meantime, an experimental minimal qemux86 eSDK can be found [https://downloads.yoctoproject.org/tools/support/workflow/poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-2.1.1.sh here].

To install the extensible SDK, make sure it is executable and then run
poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-2.1.1.sh -d /path/to/esdk
Note that installation will take 7-10 minutes.<br/>
The configure build environment, run
source /path/to/esdk/environment-setup-i586-poky-linux

== Creating a recipe from existing source ==
Let's say you have a C application that you want to add to your OS image. Assume repo is https://github.com/whbruce/bbexample.git and you want to name recipe (and thus the executable it creates) bbexample.
devtool add bbexample https://github.com/whbruce/bbexample.git
You will see the following output
NOTE: Creating workspace layer in /path/to/build/workspace
NOTE: Enabling workspace layer in bblayers.conf
NOTE: Using default source tree path /path/to/build/workspace/sources/bbexample
NOTE: Recipe /path/to/build/workspace/recipes/bbexample/bbexample_git.bb has been automatically created; further editing may be required to make it fully functional
Key entries here are the location of the source code in <tt>/path/to/build/workspace/sources/bbexample</tt>. Note that git will create a branch named devtool for your work. The recipe is in <tt>/path/to/build/workspace/recipes/bbexample/bbexample_git.bb</tt><br/>
You can now look at the generated recipe with
devtool edit-recipe bbexample
We'll take a look at what's in the recipe. Comments and whitespace have been removed for easier reading
LICENSE = "Unknown"
LIC_FILES_CHKSUM = "file://LICENSE;md5=96af5705d6f64a88e035781ef00e98a8"
SRC_URI = "git://github.com/whbruce/bbexample.git;protocol=https"
# Modify these as desired
PV = "0.1+git${SRCPV}"
SRCREV = "${AUTOREV}"
S = "${WORKDIR}/git"
inherit autotools
EXTRA_OECONF = ""
Let's go through the bitbake commands and variables in the recipe and explain what they do:
;LICENSE
:The type of licence. This is set to unknown as devtool cannot recognize the old MIT text.
;LIC_FILES_CHKSUM
:devtool looks in the root of the source folder for a file called LICENCE and generates a checksum so ensure checkout has been successful.
;SRC_URI
:The git repo given in the 'devtool add' command. This is where the source will be pulled from.
;PV
:The package version. Usually taken from recipe filename (e.g. bbexample_0.1.bb would automatically set PV = "0.1")
;SRCREV
:the git revision to checkout. ${AUTOREV} means HEAD and must be used during app development. It should be set a specific commit before being added to a layer.
;S
:Where the source can be found after being fetched and unpacked.
;inherit autotools
:Use a bitbake class that can configure, build and install an autotools project
;EXTRA_OECONF
:Options to be passed to configure script. In this case it is empty, so is not necessary.

== Building ==
$ devtool build bbexample
Parsing recipes: 100% |#########################################| ETA: 00:00:00
Parsing of 872 .bb files complete (0 cached, 872 parsed). 1302 targets, 47 skipped, 0 masked, 0 errors.
NOTE: Resolving any missing task queue dependencies
NOTE: Preparing RunQueue
NOTE: Checking sstate mirror object availability (for 51 objects)
NOTE: Executing SetScene Tasks
NOTE: Executing RunQueue Tasks
NOTE: bbexample: compiling from external source tree /path/to/esdk/workspace/sources/bbexample
NOTE: Tasks Summary: Attempted 342 tasks of which 336 didn't need to be rerun and all succeeded.
This build command runs bitbake just as in a full Yocto Project OS image build. The key line in the output is '''Checking sstate mirror object availability (for 51 objects)'''. As the extensible SDK installer gives you a minimal build environment it has to download all the dependencies (e.g. native build tools and necessary target libraries). Here 51 objects have been found and are downloaded in their pre-built state greatly speeding up the build process (i.e. we just run 342 tasks of which 336 didn't need to be rerun). This is the extensible part of the SDK in action.

== Start QEMU (headless) ==

Before deploying, the target must be running, have a network connection, and have an ssh server running. In this case, we'll start the qemux86 target as follows.

$ runqemu qemux86 nographic

== Deploying ==

$ devtool deploy-target -s bbexample root@192.168.7.2
Parsing recipes..done.
devtool_deploy.list 100% 167 0.2KB/s 00:00
devtool_deploy.sh 100% 1002 1.0KB/s 00:00
./
./usr/
./usr/bin/
./usr/bin/bbexample
./usr/include/
./usr/include/bbexample.h
./usr/lib/
./usr/lib/libbbexample.so.1
./usr/lib/libbbexample.so
./usr/lib/libbbexample.so.1.0.0
./usr/lib/libbbexample.la
NOTE: Successfully deployed /path/to/esdk/sdk/tmp/work/i586-poky-linux/bbexample/0.1+git999-r0/image

== Running ==
root@qemux86:~# bbexample
Hello Yocto World...
Hello World (from a shared library!)

== Build Image ==
To test the updated OS image that now includes your application, you can build it as follows. If you are in a eSDK environment, devtool will automatically build the image used to create the SDK. If in the standard build environment you must specify an image.
devtool build-image [image-name]
Output will be as follows:
<pre>
Parsing recipes..done.
NOTE: Building image core-image-minimal with the following additional packages: bbexample
Loading cache: 100% |###########################################| ETA: 00:00:00
Loaded 1302 entries from dependency cache.
Parsing recipes: 100% |#########################################| Time: 00:00:00
Parsing of 872 .bb files complete (870 cached, 2 parsed). 1302 targets, 49 skipped, 0 masked, 0 errors.
NOTE: Resolving any missing task queue dependencies

Build Configuration:
BB_VERSION = "1.30.0"
BUILD_SYS = "x86_64-linux"
NATIVELSBSTRING = "universal"
TARGET_SYS = "i586-poky-linux"
MACHINE = "qemux86"
DISTRO = "poky"
DISTRO_VERSION = "2.1"
TUNE_FEATURES = "m32 i586"
TARGET_FPU = ""
meta
meta-poky
meta-yocto-bsp = "krogoth:f7b994b75261550faa3ccf9005fc174950c7bee9"
workspace = "<unknown>:<unknown>"

NOTE: Preparing RunQueue
NOTE: Executing SetScene Tasks
NOTE: Executing RunQueue Tasks
bbexample-0.1+git999-r0 do_compile: NOTE: bbexample: compiling from external source tree /path/to/build/workspace/sources/bbexample
NOTE: Tasks Summary: Attempted 2062 tasks of which 2046 didn't need to be rerun and all succeeded.
NOTE: Successfully built core-image-minimal. You can find output files in /path/to/build/tmp/deploy/images/qemux86
</pre>

== Publish Recipe ==
Once application has been tested, you can make the recipe available. It will be in /path/to/build/workspace/recipes/bbexample. Make sure you add a version tothe filename (e.g. bbexample_1.0.bb)

== Update Existing Recipe ==
Updating a recipe is similar to creating one; however, rather than using <tt>devtool add</tt> we use the <tt>devtool modify</tt> command.
devtool modify bbexample

The edit/build/test cycle is then the same as for adding a recipe.

'''[WORK IN PROGRESS]'''

<hr>
Back to the [[Cookbook]] home page.

Main Page

2016-08-29T15:12:27Z

L.S. Cook: /* Where to Next? */

[http://www.example.com link title]<h1>Welcome to the Yocto Project Wiki!</h1>
The [http://yoctoproject.org Yocto Project] is an open-source project that delivers a set of tools that create operating system images for embedded Linux systems. The Yocto Project tools are based on the [http://www.openembedded.org/wiki/Main_Page OpenEmbedded] (OE) project, which uses the BitBake build tool, to construct complete Linux images. The BitBake and OE components are combined together to form a reference build host, historically known as Poky. This [https://www.youtube.com/watch?v=utZpKM7i5Z4 video] will help explain what it's all about.

===Where to Start?===
If you're new to Yocto take a look at the [[Glossary]] so you're familiar with the terms used in this wiki and the project documentation. Then take a look at the [http://www.yoctoproject.org/docs/current/yocto-project-qs/yocto-project-qs.html Quick Start Guide]. You can follow the steps in this document to clone the poky repository, quickly configure your build environment, and then try a build. Corporate firewalls can be problematic so network proxy configurations are detailed on the [[Working Behind a Network Proxy]] page. We advise you go straight for the [[Working_Behind_a_Network_Proxy#Option_2:_Chameleonsocks| Chameleonsocks option]].

===Where to Next?===
Thanks to the quick start guide, it's pretty easy to get your first Linux image and and running. Here are some places to look for help when improving your Yocto skills.
* The first tool you'll need to get familiar with is '''bitbake''', so reading through the [https://www.yoctoproject.org/docs/current/bitbake-user-manual/bitbake-user-manual.html user manual] is recommended before make any OS configuration changes. You don't need to understand it all right now, but bookmark this page for reference.
* Once you start adding packages and configuring your image to create your own distribution, things can go wrong and it can hard to track down the root cause. There is no shortage of Yocto documentation resource, but if you're not exactly sure what you're looking for this '''[[Documentation Decoder]]''' will help you out. Also take a look at the [https://wiki.yoctoproject.org/wiki/Cookbook '''Cookbook'''] and [https://wiki.yoctoproject.org/wiki/Technical_FAQ troubleshooting guide]. Also [https://www.yoctoproject.org/blogs/jefro/2016/yocto-project-books these books] are helpful.
* Some new tools such as [http://www.yoctoproject.org/docs/current/toaster-manual/toaster-manual.html Toaster], [http://www.yoctoproject.org/docs/current/sdk-manual/sdk-manual.html#sdk-extensible Extensible SDK] and [https://github.com/crops/crops CROPS] are making it easier to get the best out of Yocto on Windows and Mac OS X. Take a look at the new workflow in [[Developer Workflow Improvements]].
* There is also a [https://wiki.yoctoproject.org/wiki/TipsAndTricks '''Tips and Tricks'''] section where more experienced developers contribute to articles that will help those new to Yocto Project.

== Project planning ==

=== 2.2 (Current) Project Planning ===

* [[Planning]]

=== 2.2 Project Status and Schedule ===
* [[Yocto Project v2.2 Status]]
* [[Yocto 2.2 Schedule]]
* [[2.2 QA Status]]

== Release Engineering ==

* [[Yocto Release Engineering | Yocto Project Release Engineering]]

== QA & Automation ==

* [[QA| Yocto Project QA Main Page]]

== Wiki reference sitemap ==
* [[Glossary]]
* [[Documentation Decoder]]
* [[Working Behind a Network Proxy]]
* [[FAQ]] and [[Technical FAQ]]. These need to be unified.
* [[Cookbook]] and [[TipsAndTricks | Tips and Tricks]]. Need clear messaging on how these should be differentiated.
* [[Developer Workflow Improvements]]
* [[Planning and Governance]]
* [[Community Guidelines]]
* [[Yocto Release Engineering | Yocto Project Release Engineering]]
* [[License Infrastructure Interest Group | License Infrastructure]]
* [[Processes and Activities]]
* [[Projects]]
* [[Yocto Interest Groups]]
* [[Testopia]] - The Yocto Project's community-opened test case management platform
* [[Toaster]] - the web interface
* [[Archive]] - Graveyard for out of date articles.

== Other resources ==
* [http://yoctoproject.org Yocto Project Front Page]
* [http://git.yoctoproject.org/ Yocto Project Git Source Repos]
* [https://bugzilla.yoctoproject.org/ Yocto Project Bugzilla]
* [https://www.yoctoproject.org/tools-resources/community/mailing-lists Yocto Project Mailing Lists]
* [https://autobuilder.yoctoproject.org/main/ Yocto Project Autobuilder Waterfall Page]
* [https://autobuilder.yoctoproject.org/ Yocto Project Autobuilder Splash/Info Page]
* [http://downloads.yoctoproject.org/releases/yocto/ Yocto Project Releases]
* [http://autobuilder.yoctoproject.org/pub/nightly/ Yocto Project Nightly Build Images]
* [http://downloads.yoctoproject.org/mirror/sources/ Upstream Sources Mirror]
* [http://www.openembedded.org/wiki/Main_Page OpenEmbedded Wiki]
* [http://cgit.openembedded.org/ OpenEmbedded Git Repos]
* [http://buildbot.net/ BuildBot]

Application Development with Extensible SDK

2016-08-29T14:49:53Z

L.S. Cook: /* What devtool can do */

'''[WORK IN PROGRESS]'''

Welcome to the Yocto Project Test Kitchen! It can be a bit overwhelming to know where to start with the Yocto Project. You know you want to build an application that runs on embedded hardware, but where and how do you get started? A development environment can be an abstract, somewhat hard-to-imagine thing. This part of the wiki is intended to fill the knowledge gap between the [http://www.yoctoproject.org/docs/2.1/yocto-project-qs/yocto-project-qs.html Quick Start] and the myriad of ways to build an image and run it on real (or emulated) hardware. So what better way to do that than with a "Test Kitchen" analogy?

Our Test Kitchen must be Linux-powered, of course. And using one of the [http://www.yoctoproject.org/docs/2.1/ref-manual/ref-manual.html#detailed-supported-distros supported distributions] in our Linux-powered kitchen means that we'll already either '''have''' or have a way to '''easily get''' everything we need to follow the recipes in our Cookbook.

=== What devtool can do ===

One of the most powerful tools in our test kitchen is '''devtool'''. We can think of devtool as something that can be used to "mix" customization into our Yocto Project image. Some of the common ways to get mixing are:

* To add new applications and libraries to a Yocto Project image,
* To modify the source for an existing component,
* To test changes on target hardware, and
* To integrate that change into the rest of the OpenEmbedded (OE) build system.

In short, we can think of devtool as a single point of entry for creating, modifying and testing recipes.

=== What devtool cannot do ===

Note that devtool cannot add your recipe to a layer, nor can it update your build configuration to include it in a image. These steps are covered elsewhere in the [[Cookbook]]. devtool can, however, be used with both the Yocto Project build environment and the [http://www.yoctoproject.org/docs/latest/sdk-manual/sdk-manual.html#sdk-extensible Extensible SDK].

(From the Yocto Project documentation: Here's a presentation by Trevor Woerner that, while somewhat dated, provides detailed background information and a complete working
[https://drive.google.com/a/linaro.org/file/d/0B3KGzY5fW7laTDVxUXo3UDRvd2s/view Yocto Project Developer Workflow Tutorial].)

== How to get devtool ==

If you have set up the Yocto Project build environment using the Quick Start Guide, you already have access to devtool for qemux86 image.

Alternatively you can install an '''Extensible SDK (eSDK)'''. These come in two flavors; "minimal" and "full". The "minimal" eSDK is the preferred option as it comes as a small 30Mb installer and downloads the components it needs depending on requirements of application project. The installer contains the URL of an sstate mirror so it does not no need to build all dependencies from source code. The "full" eSDK contains all the components already built so is much larger (similar in size to traditional SDK, i.e. at least 1GB). The [http://www.yoctoproject.org/docs/2.1/sdk-manual/sdk-manual.html#sdk-extensible Yocto SDK Manual] contains more details on installing and using the eSDK.

Currently the Yocto Project autobuilder only builds "full" eSDKs. The qemux86 full eSDK can be found [http://downloads.yoctoproject.org/releases/yocto/yocto-2.1/toolchain/x86_64/poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-2.1.sh here]. There is a [https://bugzilla.yoctoproject.org/show_bug.cgi?id=9596 feature enhancement request] for the autobuilder to create minimal eSDKs.

In the meantime, an experimental minimal qemux86 eSDK can be found [http://downloads.yoctoproject.org/tools/support/workflow/esdk/poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-2.0%2bsnapshot.sh here].

== Creating a recipe from existing source ==
Let's say you have a C application that you want to add to your OS image. Assume repo is https://github.com/whbruce/bbexample.git and you want to name recipe (and thus the executable it creates) bbexample.
devtool add bbexample https://github.com/whbruce/bbexample.git
You will see the following output
NOTE: Creating workspace layer in /path/to/build/workspace
NOTE: Enabling workspace layer in bblayers.conf
NOTE: Using default source tree path /path/to/build/workspace/sources/bbexample
NOTE: Recipe /path/to/build/workspace/recipes/bbexample/bbexample_git.bb has been automatically created; further editing may be required to make it fully functional
Key entries here are the location of the source code in <tt>/path/to/build/workspace/sources/bbexample</tt>. Note that git will create a branch named devtool for your work. The recipe is in <tt>/path/to/build/workspace/recipes/bbexample/bbexample_git.bb</tt><br/>
You can now look at the generated recipe with
devtool edit-recipe bbexample
We'll take a look at what's in the recipe. Comments and whitespace have been removed for easier reading
LICENSE = "Unknown"
LIC_FILES_CHKSUM = "file://LICENSE;md5=96af5705d6f64a88e035781ef00e98a8"
SRC_URI = "git://github.com/whbruce/bbexample.git;protocol=https"
# Modify these as desired
PV = "0.1+git${SRCPV}"
SRCREV = "${AUTOREV}"
S = "${WORKDIR}/git"
inherit autotools
EXTRA_OECONF = ""
Let's go through the bitbake commands and variables in the recipe and explain what they do:
;LICENSE
:The type of licence. This is set to unknown as devtool cannot recognize the old MIT text.
;LIC_FILES_CHKSUM
:devtool looks in the root of the source folder for a file called LICENCE and generates a checksum so ensure checkout has been successful.
;SRC_URI
:The git repo given in the 'devtool add' command. This is where the source will be pulled from.
;PV
:The package version. Usually taken from recipe filename (e.g. bbexample_0.1.bb would automatically set PV = "0.1")
;SRCREV
:the git revision to checkout. ${AUTOREV} means HEAD and must be used during app development. It should be set a specific commit before being added to a layer.
;S
:Where the source can be found after being fetched and unpacked.
;inherit autotools
:Use a bitbake class that can configure, build and install an autotools project
;EXTRA_OECONF
:Options to be passed to configure script. In this case it is empty, so is not necessary.

== Building ==
$ devtool build bbexample
Parsing recipes: 100% |#########################################| ETA: 00:00:00
Parsing of 872 .bb files complete (0 cached, 872 parsed). 1302 targets, 47 skipped, 0 masked, 0 errors.
NOTE: Resolving any missing task queue dependencies
NOTE: Preparing RunQueue
NOTE: Checking sstate mirror object availability (for 51 objects)
NOTE: Executing SetScene Tasks
NOTE: Executing RunQueue Tasks
NOTE: bbexample: compiling from external source tree /path/to/esdk/workspace/sources/bbexample
NOTE: Tasks Summary: Attempted 342 tasks of which 336 didn't need to be rerun and all succeeded.
This build command runs bitbake just as in a full Yocto Project OS image build. The key line in the output is '''Checking sstate mirror object availability (for 51 objects)'''. As the extensible SDK installer gives you a minimal build environment it has to download all the dependencies (e.g. native build tools and necessary target libraries). Here 51 objects have been found and are downloaded in their pre-built state greatly speeding up the build process (i.e. we just run 342 tasks of which 336 didn't need to be rerun). This is the extensible part of the SDK in action.

== Start QEMU (headless) ==

Before deploying, the target must be running have a network connection and an ssh server running. In this case, we'll start the qemux86 target as follows.

$ runqemu qemux86 nographic

== Deploying ==

$ devtool deploy-target -s bbexample root@192.168.7.2
Parsing recipes..done.
devtool_deploy.list 100% 167 0.2KB/s 00:00
devtool_deploy.sh 100% 1002 1.0KB/s 00:00
./
./usr/
./usr/bin/
./usr/bin/bbexample
./usr/include/
./usr/include/bbexample.h
./usr/lib/
./usr/lib/libbbexample.so.1
./usr/lib/libbbexample.so
./usr/lib/libbbexample.so.1.0.0
./usr/lib/libbbexample.la
NOTE: Successfully deployed /path/to/esdk/sdk/tmp/work/i586-poky-linux/bbexample/0.1+git999-r0/image

== Running ==
root@qemux86:~# bbexample
Hello Yocto World...
Hello World (from a shared library!)

== Build Image ==
To test the updated OS image that now includes your application, you can build it as follows. If you are in a eSDK environment, devtool will automatically build the image used to create the SDK. If in the standard build environment you must specify an image.
devtool build-image [image-name]
Output will be follows
<pre>
Parsing recipes..done.
NOTE: Building image core-image-minimal with the following additional packages: bbexample
Loading cache: 100% |###########################################| ETA: 00:00:00
Loaded 1302 entries from dependency cache.
Parsing recipes: 100% |#########################################| Time: 00:00:00
Parsing of 872 .bb files complete (870 cached, 2 parsed). 1302 targets, 49 skipped, 0 masked, 0 errors.
NOTE: Resolving any missing task queue dependencies

Build Configuration:
BB_VERSION = "1.30.0"
BUILD_SYS = "x86_64-linux"
NATIVELSBSTRING = "universal"
TARGET_SYS = "i586-poky-linux"
MACHINE = "qemux86"
DISTRO = "poky"
DISTRO_VERSION = "2.1"
TUNE_FEATURES = "m32 i586"
TARGET_FPU = ""
meta
meta-poky
meta-yocto-bsp = "krogoth:f7b994b75261550faa3ccf9005fc174950c7bee9"
workspace = "<unknown>:<unknown>"

NOTE: Preparing RunQueue
NOTE: Executing SetScene Tasks
NOTE: Executing RunQueue Tasks
bbexample-0.1+git999-r0 do_compile: NOTE: bbexample: compiling from external source tree /path/to/build/workspace/sources/bbexample
NOTE: Tasks Summary: Attempted 2062 tasks of which 2046 didn't need to be rerun and all succeeded.
NOTE: Successfully built core-image-minimal. You can find output files in /path/to/build/tmp/deploy/images/qemux86
</pre>

== Publish Recipe ==
Once application has been tested, you can make the recipe available. It will be in /path/to/build/workspace/recipes/bbexample. Make sure you add a version tothe filename (e.g. bbexample_1.0.bb)

== Update Existing Recipe ==
Updating a recipe is similar to creating one, but instead iof using <tt>devtool add</tt> we use the <tt>modify</tt> command.
devtool modify bbexample

The edit/build/test cycle is then the same as for adding a recipe.

'''[WORK IN PROGRESS]'''

<hr>
Back to the [[Cookbook]] home page.

Application Development with Extensible SDK

2016-08-29T14:49:29Z

L.S. Cook: parallel formatting of this section to legacy sdk

'''[WORK IN PROGRESS]'''

Welcome to the Yocto Project Test Kitchen! It can be a bit overwhelming to know where to start with the Yocto Project. You know you want to build an application that runs on embedded hardware, but where and how do you get started? A development environment can be an abstract, somewhat hard-to-imagine thing. This part of the wiki is intended to fill the knowledge gap between the [http://www.yoctoproject.org/docs/2.1/yocto-project-qs/yocto-project-qs.html Quick Start] and the myriad of ways to build an image and run it on real (or emulated) hardware. So what better way to do that than with a "Test Kitchen" analogy?

Our Test Kitchen must be Linux-powered, of course. And using one of the [http://www.yoctoproject.org/docs/2.1/ref-manual/ref-manual.html#detailed-supported-distros supported distributions] in our Linux-powered kitchen means that we'll already either '''have''' or have a way to '''easily get''' everything we need to follow the recipes in our Cookbook.

=== What devtool can do ===

One of the most powerful tools in our test kitchen is '''devtool'''. We can think of devtool as something that can be used to "mix" customization into our Yocto Project image. Some of the common ways to get mixing are:

* To add new applications and libraries to a Yocto Project image,
* To modify the source for an existing component,
* To test changes on target hardware, and
* To integrating that change into the rest of the OpenEmbedded (OE) build system.

In short, we can think of devtool as a single point of entry for creating, modifying and testing recipes.

=== What devtool cannot do ===

Note that devtool cannot add your recipe to a layer, nor can it update your build configuration to include it in a image. These steps are covered elsewhere in the [[Cookbook]]. devtool can, however, be used with both the Yocto Project build environment and the [http://www.yoctoproject.org/docs/latest/sdk-manual/sdk-manual.html#sdk-extensible Extensible SDK].

(From the Yocto Project documentation: Here's a presentation by Trevor Woerner that, while somewhat dated, provides detailed background information and a complete working
[https://drive.google.com/a/linaro.org/file/d/0B3KGzY5fW7laTDVxUXo3UDRvd2s/view Yocto Project Developer Workflow Tutorial].)

== How to get devtool ==

If you have set up the Yocto Project build environment using the Quick Start Guide, you already have access to devtool for qemux86 image.

Alternatively you can install an '''Extensible SDK (eSDK)'''. These come in two flavors; "minimal" and "full". The "minimal" eSDK is the preferred option as it comes as a small 30Mb installer and downloads the components it needs depending on requirements of application project. The installer contains the URL of an sstate mirror so it does not no need to build all dependencies from source code. The "full" eSDK contains all the components already built so is much larger (similar in size to traditional SDK, i.e. at least 1GB). The [http://www.yoctoproject.org/docs/2.1/sdk-manual/sdk-manual.html#sdk-extensible Yocto SDK Manual] contains more details on installing and using the eSDK.

Currently the Yocto Project autobuilder only builds "full" eSDKs. The qemux86 full eSDK can be found [http://downloads.yoctoproject.org/releases/yocto/yocto-2.1/toolchain/x86_64/poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-2.1.sh here]. There is a [https://bugzilla.yoctoproject.org/show_bug.cgi?id=9596 feature enhancement request] for the autobuilder to create minimal eSDKs.

In the meantime, an experimental minimal qemux86 eSDK can be found [http://downloads.yoctoproject.org/tools/support/workflow/esdk/poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-2.0%2bsnapshot.sh here].

== Creating a recipe from existing source ==
Let's say you have a C application that you want to add to your OS image. Assume repo is https://github.com/whbruce/bbexample.git and you want to name recipe (and thus the executable it creates) bbexample.
devtool add bbexample https://github.com/whbruce/bbexample.git
You will see the following output
NOTE: Creating workspace layer in /path/to/build/workspace
NOTE: Enabling workspace layer in bblayers.conf
NOTE: Using default source tree path /path/to/build/workspace/sources/bbexample
NOTE: Recipe /path/to/build/workspace/recipes/bbexample/bbexample_git.bb has been automatically created; further editing may be required to make it fully functional
Key entries here are the location of the source code in <tt>/path/to/build/workspace/sources/bbexample</tt>. Note that git will create a branch named devtool for your work. The recipe is in <tt>/path/to/build/workspace/recipes/bbexample/bbexample_git.bb</tt><br/>
You can now look at the generated recipe with
devtool edit-recipe bbexample
We'll take a look at what's in the recipe. Comments and whitespace have been removed for easier reading
LICENSE = "Unknown"
LIC_FILES_CHKSUM = "file://LICENSE;md5=96af5705d6f64a88e035781ef00e98a8"
SRC_URI = "git://github.com/whbruce/bbexample.git;protocol=https"
# Modify these as desired
PV = "0.1+git${SRCPV}"
SRCREV = "${AUTOREV}"
S = "${WORKDIR}/git"
inherit autotools
EXTRA_OECONF = ""
Let's go through the bitbake commands and variables in the recipe and explain what they do:
;LICENSE
:The type of licence. This is set to unknown as devtool cannot recognize the old MIT text.
;LIC_FILES_CHKSUM
:devtool looks in the root of the source folder for a file called LICENCE and generates a checksum so ensure checkout has been successful.
;SRC_URI
:The git repo given in the 'devtool add' command. This is where the source will be pulled from.
;PV
:The package version. Usually taken from recipe filename (e.g. bbexample_0.1.bb would automatically set PV = "0.1")
;SRCREV
:the git revision to checkout. ${AUTOREV} means HEAD and must be used during app development. It should be set a specific commit before being added to a layer.
;S
:Where the source can be found after being fetched and unpacked.
;inherit autotools
:Use a bitbake class that can configure, build and install an autotools project
;EXTRA_OECONF
:Options to be passed to configure script. In this case it is empty, so is not necessary.

== Building ==
$ devtool build bbexample
Parsing recipes: 100% |#########################################| ETA: 00:00:00
Parsing of 872 .bb files complete (0 cached, 872 parsed). 1302 targets, 47 skipped, 0 masked, 0 errors.
NOTE: Resolving any missing task queue dependencies
NOTE: Preparing RunQueue
NOTE: Checking sstate mirror object availability (for 51 objects)
NOTE: Executing SetScene Tasks
NOTE: Executing RunQueue Tasks
NOTE: bbexample: compiling from external source tree /path/to/esdk/workspace/sources/bbexample
NOTE: Tasks Summary: Attempted 342 tasks of which 336 didn't need to be rerun and all succeeded.
This build command runs bitbake just as in a full Yocto Project OS image build. The key line in the output is '''Checking sstate mirror object availability (for 51 objects)'''. As the extensible SDK installer gives you a minimal build environment it has to download all the dependencies (e.g. native build tools and necessary target libraries). Here 51 objects have been found and are downloaded in their pre-built state greatly speeding up the build process (i.e. we just run 342 tasks of which 336 didn't need to be rerun). This is the extensible part of the SDK in action.

== Start QEMU (headless) ==

Before deploying, the target must be running have a network connection and an ssh server running. In this case, we'll start the qemux86 target as follows.

$ runqemu qemux86 nographic

== Deploying ==

$ devtool deploy-target -s bbexample root@192.168.7.2
Parsing recipes..done.
devtool_deploy.list 100% 167 0.2KB/s 00:00
devtool_deploy.sh 100% 1002 1.0KB/s 00:00
./
./usr/
./usr/bin/
./usr/bin/bbexample
./usr/include/
./usr/include/bbexample.h
./usr/lib/
./usr/lib/libbbexample.so.1
./usr/lib/libbbexample.so
./usr/lib/libbbexample.so.1.0.0
./usr/lib/libbbexample.la
NOTE: Successfully deployed /path/to/esdk/sdk/tmp/work/i586-poky-linux/bbexample/0.1+git999-r0/image

== Running ==
root@qemux86:~# bbexample
Hello Yocto World...
Hello World (from a shared library!)

== Build Image ==
To test the updated OS image that now includes your application, you can build it as follows. If you are in a eSDK environment, devtool will automatically build the image used to create the SDK. If in the standard build environment you must specify an image.
devtool build-image [image-name]
Output will be follows
<pre>
Parsing recipes..done.
NOTE: Building image core-image-minimal with the following additional packages: bbexample
Loading cache: 100% |###########################################| ETA: 00:00:00
Loaded 1302 entries from dependency cache.
Parsing recipes: 100% |#########################################| Time: 00:00:00
Parsing of 872 .bb files complete (870 cached, 2 parsed). 1302 targets, 49 skipped, 0 masked, 0 errors.
NOTE: Resolving any missing task queue dependencies

Build Configuration:
BB_VERSION = "1.30.0"
BUILD_SYS = "x86_64-linux"
NATIVELSBSTRING = "universal"
TARGET_SYS = "i586-poky-linux"
MACHINE = "qemux86"
DISTRO = "poky"
DISTRO_VERSION = "2.1"
TUNE_FEATURES = "m32 i586"
TARGET_FPU = ""
meta
meta-poky
meta-yocto-bsp = "krogoth:f7b994b75261550faa3ccf9005fc174950c7bee9"
workspace = "<unknown>:<unknown>"

NOTE: Preparing RunQueue
NOTE: Executing SetScene Tasks
NOTE: Executing RunQueue Tasks
bbexample-0.1+git999-r0 do_compile: NOTE: bbexample: compiling from external source tree /path/to/build/workspace/sources/bbexample
NOTE: Tasks Summary: Attempted 2062 tasks of which 2046 didn't need to be rerun and all succeeded.
NOTE: Successfully built core-image-minimal. You can find output files in /path/to/build/tmp/deploy/images/qemux86
</pre>

== Publish Recipe ==
Once application has been tested, you can make the recipe available. It will be in /path/to/build/workspace/recipes/bbexample. Make sure you add a version tothe filename (e.g. bbexample_1.0.bb)

== Update Existing Recipe ==
Updating a recipe is similar to creating one, but instead iof using <tt>devtool add</tt> we use the <tt>modify</tt> command.
devtool modify bbexample

The edit/build/test cycle is then the same as for adding a recipe.

'''[WORK IN PROGRESS]'''

<hr>
Back to the [[Cookbook]] home page.

Cookbook

2016-08-26T18:36:16Z

L.S. Cook: /* Cookbook Topics */

'''[WORK IN PROGRESS]
'''

This Yocto Project Cookbook collects working examples of how to use the Yocto Project, filling some of the gaps between the
[http://www.yoctoproject.org/docs/current/yocto-project-qs/yocto-project-qs.html Yocto Project Quick Start Guide] and the
[http://www.yoctoproject.org/docs/current/mega-manual/mega-manual.html full reference documentation]. Like any
cookbook, we'll include both basic and complex examples you can follow to learn about the pantry of
components and files available, and about the techniques for manipulating them using Yocto Project tools.

We encourage you, the Yocto Project community, to add

* your own examples,
* pointers to training materials,
* tips,
* and any other material that may be helpful to new and experienced users of Yocto Project.

''Please test all procedures before adding them to this page''; and if you do see a problem or improvement, start a
[https://wiki.yoctoproject.org/wiki/index.php?title=Talk:Cookbook&action=edit discussion] (use the discussion tab at the top of this page)
, or edit the page itself!

== Base recipe ==
Building a basic image usually involves these steps:

1. Selecting a target [http://www.yoctoproject.org/docs/current/bsp-guide/bsp-guide.html#bsp BSP].

2. Selecting a [http://www.yoctoproject.org/docs/2.1/ref-manual/ref-manual.html#ref-images Linux image type].

3. Gathering the required (dependency) packages (<code>opencv, java</code>, for example): [http://layers.openembedded.org/layerindex/branch/master/layers/ layer index] is good resource.

4. Updating the layer configuration (<code>build/conf/bblayers.conf</code>) to include the BSP and feature layers.

5. Updating the build configuration (<code>build/conf/local.conf</code>) to set the BSP machine, including features and any licenses they require.

Add packages and doing custom configurations on your image (creating your own distribution) is where creativity and flair come in. And as with any Linux-based process, there are innumerable ways to do things... there's not always one clear "right" way... so to help you get bearings, we're attempting to organize the initial list of examples we'd like to include in our Cookbook. Those that have been written, or those that are in progress will be linked. The others are on our list to work on. (As we get more, we may regroup the organization of these topics; but for now this should work:

== Cookbook Topics ==

* [[Cookbook:Example:Adding_packages_to_your_OS_image|Adding packages to your OS image]]
* [[Application Development with Extensible SDK]] (Test Kitchen)
* Understanding the fetch/unpack/configure/build/package pipeline
* Locating and understanding failures
* [[Cookbook:Example:Understanding the <code>tmp/work</code> directory structure]] (and what goes where)
* Intro to [[Writing Recipes|writing recipes]]
* [[Package management]]
* [[Application Development with Legacy SDK]] (Test Kitchen)
* [[Cookbook:Example:Configuring_your_kernel|Configuring your kernel]]
* What else ... ?

== Other Links ==

;[http://www.yoctoproject.org/docs/current/yocto-project-qs/yocto-project-qs.html Quick Start Guide]
:The official Yocto Project Quick Start Guide contains a step-by-step walk-through showing how to set up your environment and perform your first build

;[http://www.yoctoproject.org/docs/current/dev-manual/dev-manual.html#extendpoky Developer Manual: Common Tasks]
:The Common Tasks section of the Yocto Project Developer Manual's documentation discusses creating layers, customizing images, writing recipes, configuring and patching the kernel, performing automated runtime testing, and more.

;[https://www.yoctoproject.org/sites/default/files/ypdd-2016.04-san_diego.pdf Creating a Custom Embedded Linux Distribution for Any Embedded Device Presentation from ELC 2016 Dev Day]
:A good overview presentation from the Linux Foundation covering many topics for creating a custom embedded Linux distribution with Yocto Project.

Here are links that were in a previous version of this Cookbook. (Some seem rather outdated that we'll need to comb through, but we wanted to keep them around for now.)

;[[Yocto_BSP_One-Stop_Shop_(Documentation_Overview,_Getting_Started,_FAQs,_and_more)|Everything you need to know to create and maintain a Yocto BSP]]
:TomZ's page on how to create and maintain a Yocto Project BSP, including how to interact with the community

;[[Cookbook:Appliance:Startup_Scripts|Startup scripts]]
:How to get things to happen or start automatically:

Cookbook

2016-08-26T18:35:57Z

L.S. Cook: /* Cookbook Topics */

'''[WORK IN PROGRESS]
'''

This Yocto Project Cookbook collects working examples of how to use the Yocto Project, filling some of the gaps between the
[http://www.yoctoproject.org/docs/current/yocto-project-qs/yocto-project-qs.html Yocto Project Quick Start Guide] and the
[http://www.yoctoproject.org/docs/current/mega-manual/mega-manual.html full reference documentation]. Like any
cookbook, we'll include both basic and complex examples you can follow to learn about the pantry of
components and files available, and about the techniques for manipulating them using Yocto Project tools.

We encourage you, the Yocto Project community, to add

* your own examples,
* pointers to training materials,
* tips,
* and any other material that may be helpful to new and experienced users of Yocto Project.

''Please test all procedures before adding them to this page''; and if you do see a problem or improvement, start a
[https://wiki.yoctoproject.org/wiki/index.php?title=Talk:Cookbook&action=edit discussion] (use the discussion tab at the top of this page)
, or edit the page itself!

== Base recipe ==
Building a basic image usually involves these steps:

1. Selecting a target [http://www.yoctoproject.org/docs/current/bsp-guide/bsp-guide.html#bsp BSP].

2. Selecting a [http://www.yoctoproject.org/docs/2.1/ref-manual/ref-manual.html#ref-images Linux image type].

3. Gathering the required (dependency) packages (<code>opencv, java</code>, for example): [http://layers.openembedded.org/layerindex/branch/master/layers/ layer index] is good resource.

4. Updating the layer configuration (<code>build/conf/bblayers.conf</code>) to include the BSP and feature layers.

5. Updating the build configuration (<code>build/conf/local.conf</code>) to set the BSP machine, including features and any licenses they require.

Add packages and doing custom configurations on your image (creating your own distribution) is where creativity and flair come in. And as with any Linux-based process, there are innumerable ways to do things... there's not always one clear "right" way... so to help you get bearings, we're attempting to organize the initial list of examples we'd like to include in our Cookbook. Those that have been written, or those that are in progress will be linked. The others are on our list to work on. (As we get more, we may regroup the organization of these topics; but for now this should work:

== Cookbook Topics ==

* [[Cookbook:Example:Adding_packages_to_your_OS_image|Adding packages to your OS image]]
* [[Application Development with Extensible SDK]]
* Understanding the fetch/unpack/configure/build/package pipeline
* Locating and understanding failures
* [[Cookbook:Example:Understanding the <code>tmp/work</code> directory structure]] (and what goes where)
* Intro to [[Writing Recipes|writing recipes]]
* [[Package management]]
* [[Application Development with Legacy SDK]] (Test Kitchen)
* [[Cookbook:Example:Configuring_your_kernel|Configuring your kernel]]
* What else ... ?

== Other Links ==

;[http://www.yoctoproject.org/docs/current/yocto-project-qs/yocto-project-qs.html Quick Start Guide]
:The official Yocto Project Quick Start Guide contains a step-by-step walk-through showing how to set up your environment and perform your first build

;[http://www.yoctoproject.org/docs/current/dev-manual/dev-manual.html#extendpoky Developer Manual: Common Tasks]
:The Common Tasks section of the Yocto Project Developer Manual's documentation discusses creating layers, customizing images, writing recipes, configuring and patching the kernel, performing automated runtime testing, and more.

;[https://www.yoctoproject.org/sites/default/files/ypdd-2016.04-san_diego.pdf Creating a Custom Embedded Linux Distribution for Any Embedded Device Presentation from ELC 2016 Dev Day]
:A good overview presentation from the Linux Foundation covering many topics for creating a custom embedded Linux distribution with Yocto Project.

Here are links that were in a previous version of this Cookbook. (Some seem rather outdated that we'll need to comb through, but we wanted to keep them around for now.)

;[[Yocto_BSP_One-Stop_Shop_(Documentation_Overview,_Getting_Started,_FAQs,_and_more)|Everything you need to know to create and maintain a Yocto BSP]]
:TomZ's page on how to create and maintain a Yocto Project BSP, including how to interact with the community

;[[Cookbook:Appliance:Startup_Scripts|Startup scripts]]
:How to get things to happen or start automatically:

Cookbook:Example:Creating and updating recipes with devtool

2016-08-26T18:35:21Z

L.S. Cook: L.S. Cook moved page Cookbook:Example:Creating and updating recipes with devtool to Application Development with Extensible SDK

#REDIRECT [[Application Development with Extensible SDK]]

Application Development with Extensible SDK

2016-08-26T18:35:21Z

L.S. Cook: L.S. Cook moved page Cookbook:Example:Creating and updating recipes with devtool to Application Development with Extensible SDK

'''[WORK IN PROGRESS]'''

This example describes '''devtool''' and how to use it. This tool makes it easier to add new applications and libraries to a Yocto Project image, modify the source for an existing component, test changes on the target hardware, and ease integration into the rest of the OpenEmbedded build system. In short think of devtool as a single point of entry to creating, modifying and testing recipes. Note that devtool cannot add your recipe to a layer nor update your build configuration to include it in a image. These steps will be covered later in the [[Cookbook]]. devtool can be used with both the Yocto Project build environment and the [http://www.yoctoproject.org/docs/latest/sdk-manual/sdk-manual.html#sdk-extensible Extensible SDK].

(From the Yocto Project documentation: Here's a presentation by Trevor Woerner that, while somewhat dated, provides detailed background information and a complete working
[https://drive.google.com/a/linaro.org/file/d/0B3KGzY5fW7laTDVxUXo3UDRvd2s/view Yocto Project Developer Workflow Tutorial].)

== How to get devtool ==
If you have set up the Yocto Project build environment using the Quick Start Guide, you already have access to devtool for qemux86 image.

Alternatively you can install an '''Extensible SDK (eSDK)'''. These come in two flavors; "minimal" and "full". The "minimal" eSDK is the preferred option as it comes as a small 30Mb installer and downloads the components it needs depending on requirements of application project. The installer contains the URL of an sstate mirror so it does not no need to build all dependencies from source code. The "full" eSDK contains all the components already built so is much larger (similar in size to traditional SDK, i.e. at least 1GB). The [http://www.yoctoproject.org/docs/2.1/sdk-manual/sdk-manual.html#sdk-extensible Yocto SDK Manual] contains more details on installing and using the eSDK.

Currently the Yocto Project autobuilder only builds "full" eSDKs. The qemux86 full eSDK can be found [http://downloads.yoctoproject.org/releases/yocto/yocto-2.1/toolchain/x86_64/poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-2.1.sh here]. There is a [https://bugzilla.yoctoproject.org/show_bug.cgi?id=9596 feature enhancement request] for the autobuilder to create minimal eSDKs.

In the meantime, an experimental minimal qemux86 eSDK can be found [http://downloads.yoctoproject.org/tools/support/workflow/esdk/poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-2.0%2bsnapshot.sh here].

== Creating a recipe from existing source ==
Let's say you have a C application that you want to add to your OS image. Assume repo is https://github.com/whbruce/bbexample.git and you want to name recipe (and thus the executable it creates) bbexample.
devtool add bbexample https://github.com/whbruce/bbexample.git
You will see the following output
NOTE: Creating workspace layer in /path/to/build/workspace
NOTE: Enabling workspace layer in bblayers.conf
NOTE: Using default source tree path /path/to/build/workspace/sources/bbexample
NOTE: Recipe /path/to/build/workspace/recipes/bbexample/bbexample_git.bb has been automatically created; further editing may be required to make it fully functional
Key entries here are the location of the source code in <tt>/path/to/build/workspace/sources/bbexample</tt>. Note that git will create a branch named devtool for your work. The recipe is in <tt>/path/to/build/workspace/recipes/bbexample/bbexample_git.bb</tt><br/>
You can now look at the generated recipe with
devtool edit-recipe bbexample
We'll take a look at what's in the recipe. Comments and whitespace have been removed for easier reading
LICENSE = "Unknown"
LIC_FILES_CHKSUM = "file://LICENSE;md5=96af5705d6f64a88e035781ef00e98a8"
SRC_URI = "git://github.com/whbruce/bbexample.git;protocol=https"
# Modify these as desired
PV = "0.1+git${SRCPV}"
SRCREV = "${AUTOREV}"
S = "${WORKDIR}/git"
inherit autotools
EXTRA_OECONF = ""
Let's go through the bitbake commands and variables in the recipe and explain what they do:
;LICENSE
:The type of licence. This is set to unknown as devtool cannot recognize the old MIT text.
;LIC_FILES_CHKSUM
:devtool looks in the root of the source folder for a file called LICENCE and generates a checksum so ensure checkout has been successful.
;SRC_URI
:The git repo given in the 'devtool add' command. This is where the source will be pulled from.
;PV
:The package version. Usually taken from recipe filename (e.g. bbexample_0.1.bb would automatically set PV = "0.1")
;SRCREV
:the git revision to checkout. ${AUTOREV} means HEAD and must be used during app development. It should be set a specific commit before being added to a layer.
;S
:Where the source can be found after being fetched and unpacked.
;inherit autotools
:Use a bitbake class that can configure, build and install an autotools project
;EXTRA_OECONF
:Options to be passed to configure script. In this case it is empty, so is not necessary.

== Building ==
$ devtool build bbexample
Parsing recipes: 100% |#########################################| ETA: 00:00:00
Parsing of 872 .bb files complete (0 cached, 872 parsed). 1302 targets, 47 skipped, 0 masked, 0 errors.
NOTE: Resolving any missing task queue dependencies
NOTE: Preparing RunQueue
NOTE: Checking sstate mirror object availability (for 51 objects)
NOTE: Executing SetScene Tasks
NOTE: Executing RunQueue Tasks
NOTE: bbexample: compiling from external source tree /path/to/esdk/workspace/sources/bbexample
NOTE: Tasks Summary: Attempted 342 tasks of which 336 didn't need to be rerun and all succeeded.
This build command runs bitbake just as in a full Yocto Project OS image build. The key line in the output is '''Checking sstate mirror object availability (for 51 objects)'''. As the extensible SDK installer gives you a minimal build environment it has to download all the dependencies (e.g. native build tools and necessary target libraries). Here 51 objects have been found and are downloaded in their pre-built state greatly speeding up the build process (i.e. we just run 342 tasks of which 336 didn't need to be rerun). This is the extensible part of the SDK in action.

== Start QEMU (headless) ==

Before deploying, the target must be running have a network connection and an ssh server running. In this case, we'll start the qemux86 target as follows.

$ runqemu qemux86 nographic

== Deploying ==

$ devtool deploy-target -s bbexample root@192.168.7.2
Parsing recipes..done.
devtool_deploy.list 100% 167 0.2KB/s 00:00
devtool_deploy.sh 100% 1002 1.0KB/s 00:00
./
./usr/
./usr/bin/
./usr/bin/bbexample
./usr/include/
./usr/include/bbexample.h
./usr/lib/
./usr/lib/libbbexample.so.1
./usr/lib/libbbexample.so
./usr/lib/libbbexample.so.1.0.0
./usr/lib/libbbexample.la
NOTE: Successfully deployed /path/to/esdk/sdk/tmp/work/i586-poky-linux/bbexample/0.1+git999-r0/image

== Running ==
root@qemux86:~# bbexample
Hello Yocto World...
Hello World (from a shared library!)

== Build Image ==
To test the updated OS image that now includes your application, you can build it as follows. If you are in a eSDK environment, devtool will automatically build the image used to create the SDK. If in the standard build environment you must specify an image.
devtool build-image [image-name]
Output will be follows
<pre>
Parsing recipes..done.
NOTE: Building image core-image-minimal with the following additional packages: bbexample
Loading cache: 100% |###########################################| ETA: 00:00:00
Loaded 1302 entries from dependency cache.
Parsing recipes: 100% |#########################################| Time: 00:00:00
Parsing of 872 .bb files complete (870 cached, 2 parsed). 1302 targets, 49 skipped, 0 masked, 0 errors.
NOTE: Resolving any missing task queue dependencies

Build Configuration:
BB_VERSION = "1.30.0"
BUILD_SYS = "x86_64-linux"
NATIVELSBSTRING = "universal"
TARGET_SYS = "i586-poky-linux"
MACHINE = "qemux86"
DISTRO = "poky"
DISTRO_VERSION = "2.1"
TUNE_FEATURES = "m32 i586"
TARGET_FPU = ""
meta
meta-poky
meta-yocto-bsp = "krogoth:f7b994b75261550faa3ccf9005fc174950c7bee9"
workspace = "<unknown>:<unknown>"

NOTE: Preparing RunQueue
NOTE: Executing SetScene Tasks
NOTE: Executing RunQueue Tasks
bbexample-0.1+git999-r0 do_compile: NOTE: bbexample: compiling from external source tree /path/to/build/workspace/sources/bbexample
NOTE: Tasks Summary: Attempted 2062 tasks of which 2046 didn't need to be rerun and all succeeded.
NOTE: Successfully built core-image-minimal. You can find output files in /path/to/build/tmp/deploy/images/qemux86
</pre>

== Publish Recipe ==
Once application has been tested, you can make the recipe available. It will be in /path/to/build/workspace/recipes/bbexample. Make sure you add a version tothe filename (e.g. bbexample_1.0.bb)

== Update Existing Recipe ==
Updating a recipe is similar to creating one, but instead iof using <tt>devtool add</tt> we use the <tt>modify</tt> command.
devtool modify bbexample

The edit/build/test cycle is then the same as for adding a recipe.

'''[WORK IN PROGRESS]'''

<hr>
Back to the [[Cookbook]] home page.

Cookbook

2016-08-26T18:33:26Z

L.S. Cook: /* Cookbook Topics */

'''[WORK IN PROGRESS]
'''

This Yocto Project Cookbook collects working examples of how to use the Yocto Project, filling some of the gaps between the
[http://www.yoctoproject.org/docs/current/yocto-project-qs/yocto-project-qs.html Yocto Project Quick Start Guide] and the
[http://www.yoctoproject.org/docs/current/mega-manual/mega-manual.html full reference documentation]. Like any
cookbook, we'll include both basic and complex examples you can follow to learn about the pantry of
components and files available, and about the techniques for manipulating them using Yocto Project tools.

We encourage you, the Yocto Project community, to add

* your own examples,
* pointers to training materials,
* tips,
* and any other material that may be helpful to new and experienced users of Yocto Project.

''Please test all procedures before adding them to this page''; and if you do see a problem or improvement, start a
[https://wiki.yoctoproject.org/wiki/index.php?title=Talk:Cookbook&action=edit discussion] (use the discussion tab at the top of this page)
, or edit the page itself!

== Base recipe ==
Building a basic image usually involves these steps:

1. Selecting a target [http://www.yoctoproject.org/docs/current/bsp-guide/bsp-guide.html#bsp BSP].

2. Selecting a [http://www.yoctoproject.org/docs/2.1/ref-manual/ref-manual.html#ref-images Linux image type].

3. Gathering the required (dependency) packages (<code>opencv, java</code>, for example): [http://layers.openembedded.org/layerindex/branch/master/layers/ layer index] is good resource.

4. Updating the layer configuration (<code>build/conf/bblayers.conf</code>) to include the BSP and feature layers.

5. Updating the build configuration (<code>build/conf/local.conf</code>) to set the BSP machine, including features and any licenses they require.

Add packages and doing custom configurations on your image (creating your own distribution) is where creativity and flair come in. And as with any Linux-based process, there are innumerable ways to do things... there's not always one clear "right" way... so to help you get bearings, we're attempting to organize the initial list of examples we'd like to include in our Cookbook. Those that have been written, or those that are in progress will be linked. The others are on our list to work on. (As we get more, we may regroup the organization of these topics; but for now this should work:

== Cookbook Topics ==

* [[Cookbook:Example:Adding_packages_to_your_OS_image|Adding packages to your OS image]]
* [[Cookbook:Example:Application Development with Extensible SDK]]
* Understanding the fetch/unpack/configure/build/package pipeline
* Locating and understanding failures
* [[Cookbook:Example:Understanding the <code>tmp/work</code> directory structure]] (and what goes where)
* Intro to [[Writing Recipes|writing recipes]]
* [[Package management]]
* [[Application Development with Legacy SDK]] (Test Kitchen)
* [[Cookbook:Example:Configuring_your_kernel|Configuring your kernel]]
* What else ... ?

== Other Links ==

;[http://www.yoctoproject.org/docs/current/yocto-project-qs/yocto-project-qs.html Quick Start Guide]
:The official Yocto Project Quick Start Guide contains a step-by-step walk-through showing how to set up your environment and perform your first build

;[http://www.yoctoproject.org/docs/current/dev-manual/dev-manual.html#extendpoky Developer Manual: Common Tasks]
:The Common Tasks section of the Yocto Project Developer Manual's documentation discusses creating layers, customizing images, writing recipes, configuring and patching the kernel, performing automated runtime testing, and more.

;[https://www.yoctoproject.org/sites/default/files/ypdd-2016.04-san_diego.pdf Creating a Custom Embedded Linux Distribution for Any Embedded Device Presentation from ELC 2016 Dev Day]
:A good overview presentation from the Linux Foundation covering many topics for creating a custom embedded Linux distribution with Yocto Project.

Here are links that were in a previous version of this Cookbook. (Some seem rather outdated that we'll need to comb through, but we wanted to keep them around for now.)

;[[Yocto_BSP_One-Stop_Shop_(Documentation_Overview,_Getting_Started,_FAQs,_and_more)|Everything you need to know to create and maintain a Yocto BSP]]
:TomZ's page on how to create and maintain a Yocto Project BSP, including how to interact with the community

;[[Cookbook:Appliance:Startup_Scripts|Startup scripts]]
:How to get things to happen or start automatically:

Application Development

2016-08-26T18:31:21Z

L.S. Cook: L.S. Cook moved page Application Development to Application Development with Legacy SDK

#REDIRECT [[Application Development with Legacy SDK]]

Application Development with Legacy SDK

2016-08-26T18:31:21Z

L.S. Cook: L.S. Cook moved page Application Development to Application Development with Legacy SDK

Back to Yocto Project [[Cookbook]]

This section is currently a [ '''Work In Process''' ]

== Application Development with Legacy SDK==

Welcome to the Yocto Project Test Kitchen! It can be a bit overwhelming to know where to start with the Yocto Project. You know you want to build an application that runs on embedded hardware, but where and how do you get started? A development environment can be an abstract, somewhat hard-to-imagine thing. This part of the wiki is intended to fill the knowledge gap between the [http://www.yoctoproject.org/docs/2.1/yocto-project-qs/yocto-project-qs.html Quick Start] and the myriad of ways to build an image and run it on real (or emulated) hardware. So what better way to do that than with a "Test Kitchen" analogy?

Our Test Kitchen must be Linux-powered, of course. And using one of the [http://www.yoctoproject.org/docs/2.1/ref-manual/ref-manual.html#detailed-supported-distros supported distributions] in our Linux-powered kitchen means that we'll already either '''have''' or have a way to '''easily get''' everything we need to follow the recipes in our Cookbook.

For the first experiment in our Test Kitchen, let's assume you got through the [http://www.yoctoproject.org/docs/2.1/yocto-project-qs/yocto-project-qs.html Quick Start], and have already created an image that we'll use to build upon.

== Adding or Modifying Functionality of an Existing Image (QEMU) ==

===Prerequisites===

* '''Existing image''' -- The image that currently runs on your target hardware. This is the image to which you are adding new functionality or modifying existing functionality.
* '''Installed SDK''' -- The installed Software Development Kit. It is recommended that you grab the extensible (ext4) version of the SDK, so that you can easily add new and modify existing functionality.
* '''An initialized SDK environment''' -- The properly-initialized SDK dev environment, which is set up by running the SDK environment setup script.
* '''Source Code''': Existing source files for any new functionality or for any existing functionality you would like to add or modify, respectively. For our Test Kitchen experiment, we will add a <code>helloworld</code> module as new functionality and we will modify the existing multiple device administrator (<code>mdadm</code>) module, which is a core module included as part of the installed SDK.

===Process===

Use these steps to set up your SDK dev environment with QEMU (emulator).

1. Locate and download QEMU-compatible images from the latest Yocto releases from http://downloads.yoctoproject.org/releases/yocto/yocto-2.1/machines/qemu/qemux86-64

2. Save the file to your machine. Our example is using <code>core-image-sato-dev-qemux86-64.ext4</code>

$ wget http://downloads.yoctoproject.org/releases/yocto/yocto-2.1/machines/qemu/qemux86-64/core-image-sato-qemux86-64.ext4

3. Locate the SDK option appropriate for your target hardware from the [http://downloads.yoctoproject.org/releases/yocto/yocto-2.1/toolchain/x86_64 Yocto toolchain].

4. Download and save the SDK Installer: <code>poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-2.1.sh</code>. '''NOTE''': It is very important that when you choose the SDK, you are choosing the one appropriate for the hardware or for QEMU. In this case, you need the extensible SDK that maps to the image we are going to eventually run on QEMU. For more details on selecting and installing an SDK, see the [http://www.yoctoproject.org/docs/2.1/sdk-manual/sdk-manual.html Installing the SDK] section in the Yocto Project Software Development Kit (SDK) Developer’s Guide.

5. Make the installer executable:

$ chmod +x poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-2.1.sh

6. Install the SDK by running the script and accepting the defaults

$ . /poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-2.1.sh
Poky (Yocto Project Reference Distro) Extensible SDK installer version 2.1
Enter target directory for SDK (default: ~/poky_sdk):
You are about to install the SDK to "/home/username/poky_sdk". Proceed[Y/n]? y
Extracting SDK...
.
.
.
SDK has been successfully set up and is ready to be used.

'''NOTE''': Each time you wish to use the SDK in a new shell session, you need to source the environment setup script:
$ . /home/username/poky_sdk/environment-setup-core2-64-poky-linux

7. Initialize the SDK Development Environment

$ . $HOME/poky_sdk/environment-setup-core2-64-poky-linux
SDK environment now set up; additionally you may now run devtool to perform development tasks.
Run devtool --help for further details.

8. Ensure your new source code is available. The only requirement for the source code is that it either exists locally or can be accessed through an URL for downloading. This example assumes the source code exists at:

$HOME/mysource/helloworld

'''NOTE''': Several methods exist by which you can gain access to your source files. See the (http://www.yoctoproject.org/docs/2.1/sdk-manual/sdk-manual.html#sdk-use-devtool-to-add-an-application Use <code>devtool</code> to add an application) section in the Yocto SDK for more information.

For this example, be sure you know the URL from which your source code can be downloaded. The source files must consist of the following files: <code>hello.c</code>,
<code>Makefile.am</code>, and <code>configure.ac</code>:

The <code>helloworld/hello.c</code> file is as follows:

<pre>
#include <stdio.h>

main()
{
printf("Hello World:\n");
}
</pre>

The <code>helloworld/Makefile.am</code> file is as follows:

bin_PROGRAMS = hello
hello_SOURCES = hello.c

The <code>helloworld/configure.ac</code> file is as follows:

AC_INIT(hello,0.1)
AM_INIT_AUTOMAKE([foreign])
AC_PROG_CC
AC_PROG_INSTALL
AC_OUTPUT(Makefile)

==== Adding New Functionality ====

Now that all the pieces are in place, we can use devtool to add the new "helloworld" application to the existing image. The result will be a built object that can be integrated into an image, tested using
either actual hardware or the Quick Emulator (QEMU), and ultimately deployed to the actual hardware.

Follow these steps to add the <code>helloworld</code> functionality to the existing image:

1. Use <code>devtool add</code> to locate and set up the work environment named "workspace" for development. The command automatically creates the recipe needed to build the module:

$ devtool add helloworld $HOME/mysources/helloworld
NOTE: Recipe home/username/poky_sdk/workspace/recipes/helloworld/helloworld.bb`
has been automatically created; further editing may be required to make it
fully functional

2. Use the <code>devtool build</code> command to run the recipe using the Yocto Project build engine, which is part of the installed SDK, and create the build output for your new module:

$ devtool build helloworld
Loading cache: 100% |########################################################| ETA: 00:00:00
Loaded 1302 entries from dependency cache.
Parsing recipes: 100% |########################################################| Time: 00:00:00
Parsing of 872 .bb files complete (871 cached, 1 parsed). 1302 targets, 48 skipped, 0 masked, 0 errors.
NOTE: Resolving any missing task queue dependencies
NOTE: Preparing RunQueue
NOTE: Executing SetScene Tasks
NOTE: Executing RunQueue Tasks
helloworld-0.1-r0 do_compile: NOTE: helloworld: compiling from external source tree /home/username/mysource/helloworld
NOTE: Tasks Summary: Attempted 342 tasks of which 336 didn't need to be rerun and all succeeded.

3. Make sure the image you downloaded earlier is in the <code>poky_sdk</code> directory where the SDK was installed; then use the <code>devtool runqemu</code> command to start QEMU and boot the image:

$ cp $HOME/Downloads/core-image-sato-dev-qemux86_64.ext4 $HOME/poky_sdk
$ devtool runqemu core-image-sato-dev-qemux86-64.ext4

4. Because the previous step ties up the terminal, you need to open a new terminal window, get into the SDK development area, and run the SDK initialization script to continue:

$ cd $HOME/poky_sdk
$ . /home/username/poky_sdk/environment-setup-core2-64-poky-linux

5. Use the <code>devtool deploy-target</code> command to deploy the <code>'''helloworld'''</code> output you built earlier to QEMU so that you can test the module.

$ devtool deploy-target helloworld root@192.168.7.2

'''NOTE''': If you get an error message indicating the script failed to copy to <code>root@192.168.7.2</code>, you can run the command with <code>-c</code> option to turn off key-checking.

$ devtool deploy-target -c helloworld root@192.168.7.2

6. Inside QEMU, use the GUI to open up a terminal and then run the "hello" command:

sh-4.3# hello
Hello World:
sh-4.3#

You will see "Hello World" returned as terminal output. At this point, you have added the new functionality and proved that it works.

7. Make sure to upload the sources into a repository (e.g. Git) such that the files could be fetched by other people. This is typical practice once any new module has been created and tested and is ready for use by other developers.

8. At this point you have put the source code in a more permanent area where it can be fetched by someone using the full-blown YP development process. You need to know where the recipe is:

$HOME/poky_sdk/workspace/recipes/helloworld

==== Modifying Existing Functionality ====

Another common scenario is to modify code that already has an existing recipe in place. This is different from adding brand new functionality, as was demonstrated in the previous section.

To help demonstrate this concept, we will use a more "real-world" example: the existing multiple device administrator (<code>mdadm</code>) module, which is a core module included as part of the installed Yocto Project SDK. The steps in this section will modify <code>mdadm</code> to change the reported version, which is 3.4.

Follow these steps to modify <code>mdadm</code>:

1. Run <code>devtool modify</code> to locate, extract, and prepare all of the <code>mdadm</code> files. This command locates the source based on information in the existing recipe, unpacks the source into your workspace, applies any existing patches, and parses all related recipes:

$ devtool modify mdadm
Parsing recipes..done.
NOTE: Fetching mdadm…
NOTE: Unpacking…
NOTE: Patching…
NOTE: Adding local source files to srctree…
NOTE: Source tree extracted to /home/username/poky_sdk/workspace/sources/mdadm
NOTE: Using source tree as build directory since recipe inherits autotools-brokensep
NOTE: Recipe mdadm now set up to build from /home/username/poky_sdk/workspace/sources/mdadm.

2. In the source location <code>$HOME/poky_sdk/workspace/sources/mdadm</code>, use an editor to edit the <code>Readme.c</code> file. Change the line that specifies the version as '''3.4''' to say '''3.4a'''.

#define VERSION "3.4a"

3. Rebuild <code>mdadm</code> using the <code>devtool build</code> command:

$ devtool build mdadm
Parsing recipes: 100% |################################################################################################################| ETA: 00:00:00
Parsing of 872 .bb files complete (0 cached, 872 parsed). 1302 targets, 48 skipped, 0 masked, 0 errors.
NOTE: Resolving any missing task queue dependencies
NOTE: Preparing RunQueue
NOTE: Executing SetScene Tasks
NOTE: Executing RunQueue Tasks
mdadm-3.4-r0 do_compile: NOTE: mdadm: compiling from external source tree /home/username/poky_sdk/workspace/sources/mdadm
NOTE: Tasks Summary: Attempted 347 tasks of which 336 didn't need to be rerun and all succeeded.

4. Take note that QEMU is still assumed to be running in the shell from the previous section; use the <code>devtool deploy-target</code> command to deploy the freshly-built <code>mdadm</code> module to the already-running image:

$ devtool deploy-target mdadm root@192.168.7.2
NOTE: Successfully deployed /home/username/poky_sdk/tmp/work/core2-64-poky-linux/mdadm/3.4-r0/image

5. In the shell running QEMU, verify your changes by running <code>mdadm</code> and providing the <code>-V</code> option to return the version:

sh-4.3# mdadm -V
mdadm - v 3.4a 21 June 2016
sh-4.3#

'''NOTE''': If you try to use the previous command to see the original version of <code>mdadm</code>, you will get a message indicating the command is not found; <code>mdadm</code>. is not in the image by default.

6. At this point, you have modified the source code of an existing module all within your workspace. If you want to save your work, commit those changes. You can use the following commands to see the changes that need to be staged and committed:

$ cd /$HOME/poky_sdk/workspace/sources/mdadm
$ git status

And these two commands to stage and commit the changed file:

$ git add ReadMe.c
$ git commit -m "ReadMe.c-Updated-the-version-string"

7. Turn the commit you have made into a patch:

$ devtool update-recipe mdadm
Parsing recipes..done.
NOTE: Updating file run-ptest
NOTE: Adding new patch 0001-ReadMe.c-Updated-the-version-string.patch
NOTE: Updating recipe mdadm_3.4.bb

which will be located here:

$HOME/poky_sdk/layers/build/meta/recipes-extended/mdadm/mdadm/0001-ReadMe.c-Updated-the-version-string.patch

Application Development with Legacy SDK

2016-08-26T18:30:46Z

L.S. Cook:

2016-06-24T18:29:13Z

L.S. Cook:

'''[WORK IN PROGRESS]
'''

This Yocto Project Cookbook collects working examples of how to use the Yocto Project, filling some of the gaps between the
[http://www.yoctoproject.org/docs/current/yocto-project-qs/yocto-project-qs.html Yocto Project Quick Start Guide] and the
[http://www.yoctoproject.org/docs/current/mega-manual/mega-manual.html full reference documentation]. Like any
cookbook, we'll include both basic and complex examples you can follow to learn about the pantry of
components and files available, as well as the techniques for manipulating them using Yocto Project tools.

We encourage you, the Yocto Project community, to add your own examples to this Cookbook, or pointers to training, tips,
and other material that can help new and experienced users of Yocto Project share their knowledge and experience.

Please test all procedures before adding them to this page; and if you do see a problem or improvement, start a
[https://wiki.yoctoproject.org/wiki/index.php?title=Talk:Cookbook&action=edit discussion] (use the discussion tab at the top of this page)
, or edit the page itself!

== Cookbook Topics ==

Here's our initial list of examples we'd like to include in our cookbook. Those that have been written or that are in progress will be linked, the others are on our list to work on. (As we get more, we may regroup the organization of these topics, but for now this should work:

* [[Cookbook:Example:Adding_packages_to_your_OS_image|Adding packages to your OS image]]
* [[Cookbook:Example:Creating_and_updating_recipes_with_devtool|Creating and updating recipes with devtool]]
* Understanding the fetch/unpack/configure/build/package pipeline
* Locating and understanding failures
* Understanding the tmp/work directory structure and what goes where
* Introduction to writing recipes
* Package management
* Application Development
* Configuring your kernel
* And more....

== Other Links ==

;[http://www.yoctoproject.org/docs/current/yocto-project-qs/yocto-project-qs.html Quick Start Guide]
:The official Yocto Project Quick Start Guide contains a step-by-step walk-through showing how to set up your environment and perform your first build

;[http://www.yoctoproject.org/docs/current/dev-manual/dev-manual.html#extendpoky Developer Manual: Common Tasks]
:The Common Tasks section of the Yocto Project Developer Manual's documentation discusses creating layers, customizing images, writing recipes, configuring and patching the kernel, performing automated runtime testing, and more.

;[https://www.yoctoproject.org/sites/default/files/ypdd-2016.04-san_diego.pdf Creating a Custom Embedded Linux Distribution for Any Embedded Device Presentation from ELC 2016 Dev Day]
:A good overview presentation from the Linux Foundation covering many topics for creating a custom embedded Linux distribution with Yocto Project.

Here are links that were in a previous version of this Cookbook. (Some seem rather outdated that we'll need to comb through, but we wanted to keep them around for now.)

;[[Yocto_BSP_One-Stop_Shop_(Documentation_Overview,_Getting_Started,_FAQs,_and_more)|Everything you need to know to create and maintain a Yocto BSP]]
:TomZ's page on how to create and maintain a Yocto Project BSP, including how to interact with the community

;[[Cookbook:Appliance:Startup_Scripts|Startup scripts]]
:How to get things to happen or start automatically: