EDUCATION SERVICES
Wind River Linux 5.x and Intel GatewaySolutions for IoT
Version 1.0 A
LAB GUIDE
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
LAB GUIDEWind River Linux 5.x and Intel Gateway Solutions for IoT, Version 1.0 AEducation ServicesProduction Date: October 2014
Copyright c©2014 Wind River Systems, Inc.
All rights reserved. No part of this publication may be reproduced or transmitted in any form orby any means without the prior written permission of Wind River Systems, Inc.
Wind River, Tornado, and VxWorks are registered trademarks of Wind River Systems, Inc. TheWind River logo is a trademark of Wind River Systems, Inc. Any third-party trademarks refer-enced are the property of their respective owners. For further information regarding Wind Rivertrademarks, please see:
http://www.windriver.com/company/terms/trademark.htmlhttp://www.windriver.com/company/terms/trademark.html
Wind River may refer to third-party documentation by listing publications or providing links tothird-party Web sites for informational purposes. Wind River accepts no responsibility for theinformation provided in such third-party documentation.
This document is designed to support the Wind River Linux 5.x and Intel Gateway Solutions forIoT course. It is not designed as a stand-alone document, nor is it intended as a substitutefor documentation that accompanies Tornado, VxWorks, or Wind River Workbench or any otherWind River Systems, Inc. software or hardware product.
http://education.windriver.comhttp://education.windriver.comEducation Services Department
Wind River Systems, Inc.500 Wind River Way, Alameda, CA 94501510-748-4100 (phone) 510-749-2454 (fax)
E-mail: [email protected]@windriver.comFor training outside of North America, please contact your local sales office.
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
http://www.windriver.com/company/terms/trademark.htmlhttp://education.windriver.commailto:[email protected]
Contents
1 Building and Customizing a Wind River Linux Platform Lab1 Building and Customizing a Wind River Linux Platform Lab 1
2 Managing Wind River Linux Platforms in Workbench Lab2 Managing Wind River Linux Platforms in Workbench Lab 13
3 Integrating New Applications Lab3 Integrating New Applications Lab 29
4 Patching Packages Lab4 Patching Packages Lab 37
5 Integrating Compiled Applications Lab5 Integrating Compiled Applications Lab 43
6 Integrating Python Applications Lab6 Integrating Python Applications Lab 65
7 Reconfiguring Projects Lab7 Reconfiguring Projects Lab 73
8 Creating Layers Lab8 Creating Layers Lab 85
9 Getting Started with IDP9 Getting Started with IDP 99
10 Generating Keys for IDP10 Generating Keys for IDP 117
11 Tamper-proof File System11 Tamper-proof File System 127
12 Deploying Signed RPMS12 Deploying Signed RPMS 133
13 Using McAfee Embedded Control13 Using McAfee Embedded Control 139
14 Configuring Encrypted Storage14 Configuring Encrypted Storage 155
15 Exploring Webif15 Exploring Webif 171
16 Using IDP MultiWAN16 Using IDP MultiWAN 187
17 Working with Lua and MQTT Software17 Working with Lua and MQTT Software 199
18 Using OpenJDK18 Using OpenJDK 205
19 Integrating Python Applications19 Integrating Python Applications 213
v
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
Wind River Linux 5.x and Intel Gateway Solutions for IoT
20 Integrating SQLite3 Applications20 Integrating SQLite3 Applications 221
21 Using grsecurity21 Using grsecurity 229
vi Wind River Education Services
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
© 2013 Wind River Systems, Inc
Building and Customizing a Wind River Linux Platform Lab
1
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
Building and Customizing a Wind River Linux Platform Lab
Objective
In this lab, you will create, build, and test a new Wind River Linux platform using
a simulated target. You will also learn how to:
make changes to the target file system
configure and build individual packages
NOTE: This lab should take approximately 45 minutes.
Setting Up the Build Environment
In this section, you will set up a new Wind River Linux platform build environment using
command line tools provided with the Wind River Linux product. The build environment
provides all the tools and configuration needed to cross compile and deploy a Wind River
Linux kernel and user space for a particular target.
1. In a shell on the host, create a new directory structure to house your platform build. This can be located anywhere you like, but in this example, use the directory
$HOME/myplatform:
mkdir -p $HOME/myplatform
cd $HOME/myplatform
Wind River Linux 5.x and Intel Gateway Solutions for IoT
2 Wind River Education Services
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
2. To establish the build environment for building the platform, you must invoke the Wind River Linux configure script. This script is located within the Wind River
Linux product installation. Using syntax similar to GNU autoconf, configure
supports a number of command-line arguments for selecting a BSP, kernel type, and
file system profile, as well as many other settings. Commonly used options are
summarized in the table below:
Option Name Purpose
--help Display an extensive list of supported options.
--enable-board Specify the target BSP.
--enable-kernel Select the type of Wind River Linux kernel to use.
--enable-rootfs Select the type of Wind River Linux user space to use.
--enable-build Select how software should be built.
--with-layer Include an additional layer.
--with-template Include an additional template.
--enable-ccache Enable the compiler cache (ccache) to speed up build time.
--with-ccache-dir Specify an external compiler cache directory.
--with-sstate-dir Bitbake shared state cache directory. Using a shared state cache significantly improves build times.
View the complete list of options available:
$WIND_BASE/wrlinux/configure --help
3. In this example, you will create a platform similar to the one shipped with the lab environment. Doing so will significantly reduce build time since the shared state
cache found at /Labs/sstate can be used to accelerate the build.
$WIND_BASE/wrlinux/configure --enable-board=$BSP \
--enable-kernel=$KERNEL \
--enable-rootfs=glibc_small \
--with-sstate-dir=/Labs/sstate
The output of configure will stream by. Once configure finishes, your directory will
contain the infrastructure needed to build and deploy your own customized Linux
distribution. Take the time to familiarize yourself with the build environment. There
are a few important directories to note:
The build directory hosts soft links to the build directories for each package. This subdirectory also hosts a Makefile used to build special targets associated with
the packages. For more details, execute the following command:
make -C build help
Building and Customizing a Wind River Linux Platform Lab
Wind River Education Services 3
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
The bitbake_build/conf directory contains the following important files:
local.conf, which contains crucial build configuration information. A soft link to this file is created in the top-level directory for your convenience.
bblayers.conf file lists the layers used in constructing the build environment.
The export directory will contain the output of the build, including:
An archive containing the target file system, which can be extracted directly to a device file system or NFS share
dist, a directory containing the target file system. When using a simulator such as QEMU, it mounts this directory as a root file system during boot.
The Linux kernel image. The name of this image might vary, depending on your target.
An archive containing the kernel modules.
The host-cross directory contains tools used to build the platform, including (but not limited to) the cross-compiling toolchain used to build programs for your
target. Note that the directories inside host-cross are soft links to corresponding
directories in bitbake_build/tmp/sysroots.
The directory layers/local constitutes a “local layer” which functions as a container for your project-specific customizations.
The layers directory also contains additional layers used in your project; the stock layers are all provided by the standard Wind River Linux installation, although
you may include additional custom layers if needed.
Wind River Linux 5.x and Intel Gateway Solutions for IoT
4 Wind River Education Services
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
Building the Platform
With a configured build environment in place, you may now build your platform. The
output of this stage will be a Wind River Linux kernel image and root file system that are
ready to use by the target; both will be found in the export directory as noted in the
previous section.
The time required to build a platform varies on a number of factors, not the least of which
being the overall speed of your host. Other factors that have an impact are:
Whether or not the kernel needs to be built from source; a complete build of the kernel typically takes in the order of a half hour to an hour.
The number of target user-space packages that need to be built from source. A basic glibc_small system can be built entirely from source in about one to two
hours. A glibc_std system, on the other hand, can take many hours.
Whether or not you are using a prepopulated shared state cache. If using a shared state cache containing all the needed objects, the above build time for a
glibc_small system takes only minutes.
To provide for a better lab experience, the lab environment you are using includes a
shared state cache that prepopulated with all the objects needed to build a glibc_small
system for your target. Leveraging this using the --with-sstate-dir argument minimizes
the build time required.
4. To build your platform image, simply invoke make as follows:
make
5. After the build finishes, explore the contents of the export directory. In particular, take note of export/dist, which contains a complete copy of your target file system.
Note however, that some file attributes aren’t quiet as expected. For example:
ls –l export/dist/dev
-rw-------. 1 wruser wruser 0 Jan 13 22:39 apm_bios
-rw-------. 1 wruser wruser 0 Jan 13 22:39 console
-rw-------. 1 wruser wruser 0 Jan 13 22:39 fb0
-rw-------. 1 wruser wruser 0 Jan 13 22:39 hda
-rw-------. 1 wruser wruser 0 Jan 13 22:39 hda1
-rw-------. 1 wruser wruser 0 Jan 13 22:39 hda10
-rw-------. 1 wruser wruser 0 Jan 13 22:39 hda11
…
Building and Customizing a Wind River Linux Platform Lab
Wind River Education Services 5
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
Compare this to what you see in /dev on your host:
ls –l /dev
crw-rw----. 1 root video 10, 175 Jan 11 06:26 agpgart
crw-------. 1 root root 10, 235 Jan 11 06:26 autofs
drwxr-xr-x. 2 root root 300 Jan 11 06:26 block
drwxr-xr-x. 2 root root 80 Jan 11 06:26 bsg
c---------. 1 root root 10, 234 Jan 11 06:26 btrfs-control
drwxr-xr-x. 3 root root 60 Jan 11 06:26 bus
lrwxrwxrwx. 1 root root 3 Jan 11 06:26 cdrom -> sr0
drwxr-xr-x. 2 root root 3120 Jan 16 17:05 char
crw-------. 1 root root 5, 1 Jan 11 09:56 console
…
Focus not on the entries themselves, but rather the ownerships and attributes. Notice that
the entries in /dev on your host:
Have root:root ownership
Are primarily pipes or block or character device nodes rather than regular files (as evidenced by the b , c and p bits in the leftmost column)
The device nodes have major and minor numers associated with them (10,175, 5,1, etc)
Whereas the entries in export/dist/dev all appear as regular files owned by
wruser:wruser.
The reason for this is because the entire build, including the generation of export/dist,
was done as a regular user (wruser). Under these conditions, it would be impossible to
generate device nodes or any files owned by root. Instead, the file system is built in a
fake root environment called pseudo. To see the effect pseudo has on your view of the
files, enter the pseudo environment and then reexamine the directory:
scripts/fakestart.sh
ls –l export/dist/dev
crw-rw---- 1 root 46 10, 134 Jan 13 22:39 apm_bios
crw-rw--w- 1 root tty 5, 1 Jan 13 22:39 console
crw------- 1 root root 29, 0 Jan 13 22:39 fb0
brw-rw---- 1 root disk 3, 0 Jan 13 22:39 hda
brw-rw---- 1 root root 3, 1 Jan 13 22:39 hda1
brw-rw---- 1 root root 3, 10 Jan 13 22:39 hda10
brw-rw---- 1 root root 3, 11 Jan 13 22:39 hda11
…
Like magic, all is as it should be. Always remember that if you want to see the file system
exactly as it was meant to be, that you must first enter the pseudo environment in which it
was generated.
Wind River Linux 5.x and Intel Gateway Solutions for IoT
6 Wind River Education Services
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
6. To leave the pseudo environment, simply issue the command exit.
Deploying Your Platform
With a built platform project in place, it is time to deploy and test your image on your
target. For hardware targets, additional steps may be required as detailed in the Working
with a Hardware Target lab. Otherwise, you can use the simulator to test your platform.
7. Test your platform in the simulator using the following command:
make start-target
8. Once your target boots, log in using the credentials root and password root.
9. Feel free to explore your target using the command-line shell. When done, the preferred method of shutting a Linux system is always using the poweroff command,
although you can use other methods as well, as outlined in the Simulating Targets
with QEMU lab.
Customizing the File System with changelist.xml
In this section, you will tweak the target file system with the help of a changelist.xml
file. This file will be located in the local layer and will be executed by the build system
just before the final file system image is generated.
Although these XML files might seem awkward to work with and edit, the main benefit
is that they integrate nicely with the Workbench file system management tools.
10. Use a changelist.xml file to copy the README.txt file found in /Labs/BuildSystemLab directory into the /root directory of the target file system.
To do this, create a file called changelist.xml in the conf/image_final subdirectory of
the local layer (that is, layers/local/conf/image_final relative to the top-level
directory of the project). Populate the file with the following content:
NOTE: This is important: the cl action line must be entered as one continuous line. Due to printing restrictions, it is broken across two lines in this document.
11. Once you have made your changes, rebuild the platform and start the target to test your changes. Verify that the file /root/README.txt can be found on the target, and
that its contents match those on the host.
Building and Customizing a Wind River Linux Platform Lab
Wind River Education Services 7
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
Customizing the File System with fs_final Scripts
In this section, you will tweak the target file system with the help of some fs_final_*.sh
scripts. Like changelist.xml files, these scripts will be located in the local layer and will
be executed by the build system just before the final file system image is generated.
Unlike changelist.xml files, fs_final scripts are plain shell scripts and are easier to write.
But there is no integration with the Workbench file system management tools.
12. Use an fs_final script to add an /etc/motd file to your target file system. The contents of /etc/motd is displayed on the console right after you log in (motd originates from
the phrase, “Message Of The Day”).
To do this, create a file called fs_final_motd.sh in the same directory you used to
create the changelist.xml file in the previous section. Populate the file with the
following contents:
echo “Welcome to your Wind River Linux 5.x image” > etc/motd
NOTE: The lack of a leading slash in etc/motd is intentional. The fs_final scripts are executed in the root directory of the target file system, but are not executed
within a chrooted environment. This allows fs_final scripts to have full
access to the host file system as changelist.xml files do; but careful attention
must be paid when referencing files. In this example, if you inadvertently
wrote /etc/motd, you would actually be referring to /etc/motd in the host file
system.
13. Rebuild your image and redeploy the updated image to your target. Log in to verify
that your changes have taken effect; you should see the contents of the motd file
display after you log in.
14. To see the benefits of the fs_final mechanism, suppose you want to embed
information into your root file system that is not static. Suppose, for example, that
you wanted to embed the build date and board name into the motd. Add the following
code to fs_final_motd.sh:
echo “This image was built on $(date)” >> etc/motd
15. Now rebuild and redeploy the updated image to your target again. Log in to verify
that your changes have taken effect. Notice that the date in the motd is hard-coded to
the exact time that the fs_final_motd.sh script was executed in building the file
system image.
Wind River Linux 5.x and Intel Gateway Solutions for IoT
8 Wind River Education Services
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
16. Now, apply what you’ve learned to create a new fs_final script that creates a FIFO
entry, /mypipe with mode 0777. If you’re having difficulty, consult the online
manual:
man mkfifo
If you’re stuck, a solution can be found in /Labs/BuildSystemLab/fs_final_fifo.sh.
Simply copy this solution into the same directory as fs_final_motd.sh, rebuild the file
system, and deploy the image to the target.
Customizing and Building Individual Packages
Currently, your platform is built using the packages that ship with the Wind River Linux
product. It’s possible to rebuild individual packages from source if needed. Common
reasons for wanting to do this include:
You wish to apply a patch to the source of a particular package
You want to make configuration changes to a package
You want to be able to debug the software provided by a particular package.
In this section, you will focus on the busybox package, which provides the core run-time
for glibc_small systems. In this exercise, you will modify the source of the ls program to
print an additional message when run.
17. To modify the source to busybox, open a development shell for the package, as follows:
$ make -C build busybox.devshell
This will open a new terminal where the busybox source is located with all relevant
patches already applied. Note the name of the directory where the terminal opens,
busybox-1.19.4, which will be used in a later exercise.
18. Edit the code which implements the ls command provided by coreutils/ls.c. Add an additional message to beginning of the ls_main() function; for example:
init_unicode();
fprintf(stderr, "Hello from ls\n");
if (ENABLE_FEATURE_LS_SORTFILES)
…
19. Once you finish editing the file, exit the development shell by typing exit or pressing CTRL+D. You will be taken back to your original shell.
Building and Customizing a Wind River Linux Platform Lab
Wind River Education Services 9
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
20. Now, rebuild busybox with your source changes:
make -C build busybox.rebuild
With the package rebuilt, once again rebuild the image and deploy it to the target to
test your changes. Verify that every time you invoke the ls command, your message
appears.
Note that the changes you have made are only temporary. If you do a clean,
distclean, or cleansstate, your changes will be lost, and the original behavior of ls
will be restored.
21. Now that you have seen how to modify software for your platform, clean the build area as follows:
make -C build busybox.clean
22. Rebuild busybox, then rebuild the image and deploy it to your target. Now you will notice that the behavior of ls is restored to its original state.
Building a Boot Image
As you have seen, building a kernel and target file system is relatively straightforward.
The product of this build is:
A target file system rooted at export/dist
A compressed archive containing the file system contents in the export directory
When deploying to hardware, you will often need a boot image; that is, a self-contained
file system image for deploying on to some form of medium; for example, flash storage.
Wind River Linux provides support for many common boot image formats:
JFFS2 is derived from the original Linux flash file system, JFFS. JFFS2 is a journaling read-write file system which performs on-the-fly compression.
Operating on top of the MTD subsystem, JFFS2 addresses the unique
requirements of flash, such as wear leveling.
UBIFS is a read-write file system designed specifically for raw NAND flash. It takes care of bad sectors in flash by implementing a logical layer that maps used
flash sector numbers to only good sectors in the physical media. UBIFS is
supported natively by the Linux kernel. Note that to deploy a UBIFS file on the
target’s NAND you need to “ubinize” the UBIFS file first to generate a .ubi file.
CPIO is a common packing format used to pack the root file system into a single file. This file, usually in a compressed form, can then be appended to the kernel
image itself in such a way that the Linux boot logic can use it as a root file system
contained entirely in RAM.
Wind River Linux 5.x and Intel Gateway Solutions for IoT
10 Wind River Education Services
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
23. Reconfigure the project to generate JFFS2 and CPIO images by editing the file local.conf in your project directory and appending the following:
IMAGE_FSTYPES += “jffs2 cpio.gz”
Again, the syntax might seem a little peculiar, but this is again a fragment of Python
code used by bitbake At a high level, IMAGE_FSTYPES lists the types of images to
build. Refer to local.conf for a full list of supported types.
24. Once you have saved your changes to the file local.conf, rebuilt your project. When this finishes, you will see three files in the export/images directory with the suffixes
.jffs2 and .cpio.gz.
This concludes the lab. Do not proceed.
Building and Customizing a Wind River Linux Platform Lab
Wind River Education Services 11
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
Wind River Linux 5.x and Intel Gateway Solutions for IoT
12 Wind River Education Services
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
© 2013 Wind River Systems, Inc
Managing Wind River Linux Platforms in Workbench Lab
13
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
Managing Wind River Linux Platforms in Workbench Lab
Objective
In this lab, you will learn how to create and manage Wind River Linux
platform projects in Workbench. You will also learn how to import existing
Wind River Linux platforms into your Wind River Workbench workspace.
NOTE: This lab should take approximately 30 minutes.
Creating New Platform Projects
In this section, we will set up a new Wind River Linux platform project in Workbench.
1. From the Workbench menu, select File > New > Wind River Workbench Project.
2. In the New Wind River Workbench Project dialog, select Wind River Linux Platform Base 5.0.1.
3. Click Next.
2
3
Wind River Linux 5.x and Intel Gateway Solutions for IoT
14 Wind River Education Services
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
4. In the Build type field, select Platform.
5. Click Next.
4
5
Managing Wind River Linux Platforms in Workbench Lab
Wind River Education Services 15
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
6. In the Project name field, enter myplatform_wb as the name for your new project and select Create project in workspace.
7. Click Next.
6
7
6
Wind River Linux 5.x and Intel Gateway Solutions for IoT
16 Wind River Education Services
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
8. The next stage of the wizard provides access to all of the options that the command-line configure utility provides, the most important ones being incorporated directly
into the GUI. For example:
The Board field corresponds to --enable-board.
The Production build setting corresponds to --enable-build=production.
The Layers and Templates lists provide interfaces to --with-layer and --with-template, respectively.
For all the rest, there is a generic UI near the bottom which allows you to specify arbitrary configuration options
In the Board field, select a value matching $BSP in your lab environment.
NOTE: Use the shell command echo $BSP to obtain a value for the Board field.
9. In the RootFS field, select glibc_small. In the Kernel field, select $KERNEL.
NOTE: Use the shell command echo $KERNEL to obtain a value for the Kernel field.
10. Lastly, specify your sstate cache to expedite the build, as you did in the Building and Customizing a Wind River Linux Platform lab. Since there is no direct option for this
in the main window, select Add.
If the Add button is not visible, collapse the dialog to bring it into view by clicking
the
8
11 11
10
9
Wind River Linux 5.x and Intel Gateway Solutions for IoT
18 Wind River Education Services
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
11. In the Configure Options dialog, scroll down to locate and select the option --with-sstate-dir.
12. In the Options field, enter the value /Labs/sstate, or click Browse to navigate to the directory.
13. Click OK.
12
13
14
Managing Wind River Linux Platforms in Workbench Lab
Wind River Education Services 19
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
14. In the New Wind River Linux Platform Project dialog, focus on the Configure command field (you may have to collapse the Advanced panel to see it). Notice how
the command correlates to the command you used to configure a new platform
project in the Building and Customizing a Wind River Linux Platform lab.
NOTE: Your exact command may appear differently, depending on the value of $BSP and $KERNEL in your lab environment.
15. Click Finish.
13 15
16
Wind River Linux 5.x and Intel Gateway Solutions for IoT
20 Wind River Education Services
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
16. Workbench will call out to configure to generate your build environment. This may take a few moments.
17. Using a file browser or a command-line terminal, navigate to your workspace directory. Note that Workbench has actually created two directories in the workspace
for your new project:
The first directory, myplatform_wb, is named to match the project you created. This directory contains a small Workbench project that functions as a wrapper for
the real platform project.
The second directory, suffixed with myplatform_wb_prj, contains the actual Wind River Linux platform project, and is identical in every respect to a platform
project created from the command-line. In fact, you can manage this project
outside of Workbench using techniques learned in the Building and Customizing a
Wind River Linux Platform lab.
Managing Wind River Linux Platforms in Workbench Lab
Wind River Education Services 21
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
Building the Platform
With a configured build environment in place, you may now build your platform.
18. In the Project Explorer view, under the myplatform_wb project, right-click on the fs project.
19. From the context menu, select Build Target.
20. As discussed previously, a platform build can be very quick or time-consuming, depending on a number of factors. The Build Console view displays the build output.
19
20
Wind River Linux 5.x and Intel Gateway Solutions for IoT
22 Wind River Education Services
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
Importing Existing Platforms into Workbench
Sometimes you may have a Wind River Linux platform which you configured from the
command line. Workbench allows you to remotely control the platform by importing it
into your workspace, leaving the original platform in its original spot on the file system.
In this section, you will import the platform project you created in the Building and
Customizing a Wind River Linux Platform lab, which you created in the directory
/home/wruser/myplatform.
21. From the main Workbench menu, select File > Import.
22. In the Import dialog, select Wind River Linux > Existing Wind River Linux Platform Project from the Wind River Linux group.
23. Click Next.
24. Click Browse, then navigate to the directory containing the existing platform.
23 24
25
Managing Wind River Linux Platforms in Workbench Lab
Wind River Education Services 23
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
25. Use the browser to navigate to the directory containing the platform project you wish to import.
26. Click OK.
26 27
Wind River Linux 5.x and Intel Gateway Solutions for IoT
24 Wind River Education Services
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
27. In the Import dialog, you may now change the default name assigned to the project if you wish. This is the name of the Workbench project that displays in your workspace,
and it has no effect on the original Wind River Linux platform.
28. Click Finish.
28 29
Managing Wind River Linux Platforms in Workbench Lab
Wind River Education Services 25
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
29. Once the project creation finishes, the result will be as if you’d created the project from scratch using Workbench. You can manage the project from within Workbench
via the myplatform-import project, or you can manage the platform at
/home/wruser/myplatform using command-line techniques. The notable exception
here is that the actual platform directory remains where it was originally, rather than
residing in the workspace directory.
Deploying Your Platform
With a built platform project in place, it is time to deploy and test your image on your
target. For hardware targets, additional steps may be required as detailed in the Working
with a Hardware Target lab. Otherwise, you can use the simulator to test your platform,
as outlined in the Simulating Targets with QEMU lab.
30. Once your target boots, the following greeting displays.
Wind River Linux 5.0.1.0 qemu0 console
qemu0 login:
Log in as the user root, with the password root.
31. Feel free to explore your target using the command-line shell. When you are done, the preferred method of shutting a Linux system is always using the poweroff command,
although you can use other methods as well, as outlined in the Simulating Targets
with QEMU lab.
Wind River Linux 5.x and Intel Gateway Solutions for IoT
26 Wind River Education Services
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
Deleting Projects
To manage your workspace and disk space usage, you may need to delete projects from
time to time, since built Wind River Linux platform projects can occupy several
gigabytes of storages space.
32. In the Project Explorer view, right-click on the project you wish to delete.
33. In the context menu, select Delete.
33 34
Managing Wind River Linux Platforms in Workbench Lab
Wind River Education Services 27
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
34. The Confirm Platform Project Delete dialog provides the following options:
Select Delete project description files on disk to delete the Workbench wrapper project (the myplatform_wb directory in this case) from the disk.
Select Also delete complete contents of platform projects to delete both the wrapper and the underlying Wind River Linux platform project (the
myplatform_wb_prj directory in this case).
Select neither item to delete only the project from the workspace.
35. Click Yes.
This concludes the lab. Do not proceed.
35
36
Wind River Linux 5.x and Intel Gateway Solutions for IoT
28 Wind River Education Services
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
© 2013 Wind River Systems, Inc
Integrating New Applications Lab
29
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
Integrating New Applications Lab
Objective
In this lab you will learn the basics of how to integrate third-party software
components into Wind River Linux platforms.
NOTE: This lab should take approximately 30 minutes.
Lab Overview
Wind River Linux comes with hundreds of validated software packages that are
ready to use in Wind River Linux platforms. If you need a software package that is
not included, or if you must integrate an application being developed in-house,
you must integrate the package into the Wind River Linux build system and cross-
compile it along with the rest of your platform software. A properly integrated
package makes it easy to include the package into other projects as well.
This lab uses a simple C application as a way to introduce the basic concepts
behind the application integration process. The application is an implementation
of the Tic-Tac-Toe game where the computer is the O player and you are the X
player. You always have the advantage of the first move. The application is
entirely contained in a single C file. All the integration steps will be done
manually.
Before You Begin
This lab modifies the configuration of an existing platform project. Use the pre-built
project provided with your lab environment. Refer to the Getting Started lab to identify
where to find this project in your lab environment. The location of this project will be
referenced as $TARGET_BASE throughout this lab.
This lab uses a command-line environment. Take the time now to open a command-line
terminal and navigate to this directory.
The Packaging Workflow
The purpose of this lab is to create a package for the application that you can integrate
into the build system so you can operate on it as you would on any package normally
bundled with Wind River Linux. The following describes the general packaging
workflow:
Select a name for the application. You will use this name when creating the directories and files associated with the package. In this lab you will use the name
tic-tac-toe.
Wind River Linux 5.x and Intel Gateway Solutions for IoT
30 Wind River Education Services
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
Select the build layer where you will maintain the new package. When you configure a platform project, Wind River Linux enables the local layer by default
(in the directory layers/local of your platform project). In this lab you will
maintain the tic-tac-toe application in the local layer.
If you use any other layer you must use the option --with-layer when you
configure your project (so the build system knows about it).
Define the license to associate with the application, and ensure that you have the full text of the license agreement available as one or more text files. Remember
that it is a good practice to add an abridged version of the license at the beginning
of all your source files. In this lab you will use the GPLv3 license.
Make the application source code and support files available to the build system in some convenient location (using a URL pointing to the location) in a format
supported by the build system (a local or remote tar file, a Git repository and
branch, or a subversion repository and commit number). In this lab you will use a
URL pointing to a tar file in the directory /Labs/Packages.
Build the directory infrastructure inside the selected layer to tell bitbake about the new package, (including a new bitbake recipe file with the package details) and
add all the support files.
Test the build and fix any problems. Repeat this workflow until your new package works as expected.
About the Tar File
You can use any name for the application tar file — however, the general convention is
to use the name of the application and the version number, separated by either a hyphen
or an underscore character. In this lab you will use the base name tic-tac-toe-1.0.
The file extension must be a recognized format so that bitbake can use the appropriate set
of tools to extract the source code. Valid extensions include .tar, .tar.gz, .tar.bz2, .cpio,
and .zip. In this lab you will use the extension .tar.gz.
The tar file for the application is /Labs/Packages/tic-tac-toe-1.0.tar.gz.
After bitbake extracts the tar file it expects to see a top directory named the same as the
name and version number of the application (for example, tic-tac-toe-1.0). bitbake then
looks inside for files with well-known names (such as Makefile, configure, and files
with extensions such as .c or .cpp) to determine how to build the package.
You can always make things differently and override how bitbake unpacks your
application and how it analyzes the structure of the application. However, by following
the default conventions you make the packaging exercise much easier.
Integrating New Applications Lab
Wind River Education Services 31
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
The following figure shows the content of the tar file /Labs/Packages/tic-tac-toe-
1.0.tar.gz.
|-- tic-tac-toe-1.0
|-- COPYING
|-- Makefile
`-- ttt.c
About bitbake Recipe Files
A recipe file provides bitbake with the necessary details to build the package (such as
where to find the source, the license details, and the version number).
Recipe files names have three components — the package name and the version number
(separated by an underscore character) and the file extension. In this lab the recipe file
name is tic-tac-toe_1.0.bb. The extension bb in the file name stands for bitbake and
identifies this file as a bitbake recipe.
You can use the extension .bbappend with a bitbake recipe file when the recipe file adds
application context to an original .bb file located somewhere else. Typically this occurs
when you want to add or modify the default build steps of a recipe provided by Wind
River Linux or some third party organization. In these cases you create a .bbappend file
that describes only the pieces you want to add, knowing that the .bb file provides the bulk
of the recipe. This lab does not use .bbappend recipe files.
Creating the Layer Structure
1. Open a command-line terminal and navigate to the directory $TARGET_BASE directory.
2. Execute the following command to add the directory structure to your platform project. Note that the local layer already has several other directories and files on it —
do not touch them.
mkdir -p layers/local/recipes-applications/tic-tac-toe/files
The directory recipes-applications is the directory where you will maintain your own
application packages. You can use any other directory name, but it must follow the
pattern recipes-* for bitbake to recognize it as a source of packages. The file
layers/local/layer.conf defines the valid patterns.
The subdirectory tic-tac-toe is where you will maintain the application. It hosts the
bitbake recipe file and other support files that you may need in the future.
The subdirectory files is a utilitarian directory found in most maintenance directories.
As the application evolves over time you will likely create patches, documentation
files, and other objects that you want to keep together inside the build system. This
lab does not use this directory, but you will include it in the bitbake search path for
future use.
Wind River Linux 5.x and Intel Gateway Solutions for IoT
32 Wind River Education Services
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
3. Create the recipe file layers/local/recipes-applications/tic-tac-toe/tic-tac-toe_1.0.bb for the package with the following content. The file is also available from the
directory /Labs/Packages.
# Copyright (C) 2013 Wind River Systems
# Release under the GPLv3 license
SUMMARY = "The TIC-TAC-TOE game, console edition"
DESCRIPTION = "An engaging and time killer console game"
HOMEPAGE = "http://apps.company.com/tic-tac-toe"
FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
LICENSE = "GPLv3"
LIC_FILES_CHKSUM = "file://COPYING;md5=d32239..."
PR = "r1"
SRC_URI = "file:///Labs/Packages/${PN}-${PV}.tar.gz"
SRC_URI[md5sum] = "f4368e..."
SRC_URI[sha256sum] = "b2c702..."
do_install() {
install –d ${D}${bindir}
install –m 0755 tic-tac-toe ${D}${bindir}
}
4. The code above omits the full checksum values for clarity purposes. Execute the following commands to retrieve them from the application tar file, then update the
values in the recipe file (the two lines with the variables SRC_URI[md5sum] and
SRC_URI[sha256sum]) to match the retrieved values.
md5sum /Labs/Packages/tic-tac-toe-1.0.tar.gz
sha256sum /Labs/Packages/tic-tac-toe-1.0.tar.gz
5. Execute the following command to unpack the application so that you have access to the source code.
make -C build tic-tac-toe.unpack
6. Execute the following command to retrieve the checksum value of the license file.
md5sum build/tic-tac-toe-1.0-r1/tic-tac-toe-1.0/COPYING
7. Update the value of the variable LIC_FILES_CHECKSUM in the recipe and save the file.
Understanding the Recipe File
The sample recipe file you just created is about the minimum size you can have. It can be
shorter if you remove comments and some documentation string variables, or as complex
Integrating New Applications Lab
Wind River Education Services 33
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
as you need it to be. The following provides short descriptions of the variables in the
recipe:
SUMMARY, DESCRIPTION, HOMEPAGE — These are description variables that you can omit. They provide information about the recipe, and some
tools may use them — you should always define these variables.
FILESEXTRAPATHS_prepend — bitbake prepends the value of this variable to the list of paths it uses when searching for source and support files. Note the
colon at the end, which separates entries in the path expression.
The expression ${THISDIR} is expanded to contain the directory where the
recipe file is located (in this lab,
/home/wruser/myplatform/layers/local/recipes-applications/tic-tac-toe). The
whole expression ${THISDIR}/files then adds the subdirectory files to the search
path.
LICENSE and LIC_FILES_CHKSUM — These variables define the licenses to apply to the application. Most well-known open source licenses (such as GPLv2,
LGPLv2.1, BSD, and MIT) are predefined. The variable LICENSE accepts
complex expressions — for example, a dual license (with a value like GPLv2 +
MIT) or multiple licenses (with a value like BSD & MIT).
PR — The name of this variable represents the product revision. The default value is r0 — for clarity you should make this variable explicit in the recipe.
SRC_URI — This variable lists the source files that make up the package. This lab uses the URL prefix file:// but you can use other values such us http://, git://,
and ftp://. It also uses the automatic variables PN (the package name) and PV
(the package version) —this lab uses the values tic-tac-toe and 1.0 (as indicated
by the name of the bitbake recipe file).
SRC_URI[md5sum] and SRC_URI[sha256sum] — These variables provide the checksum values of the source file. bitbake uses these values to verify the
integrity of the source files.
do_install() — bitbake invokes this shell function to install the executable files of the application in the final target image. This lab uses the command install to
create the destination directory (if it does not already exist) and to copy the binary
file tic-tac-toe. The function uses D and bindir. The variable D expands to the
destination directory where the target image is assembled. The variable bindir
expands to /usr/bin. When the target boots, the application binary will be
/usr/bin/tic-tac-toe.
Building the Tic-Tac-Toe Package
8. Execute the following command to add the package tic-tac-toe to the list of packages to build in your platform project.
make -C build tic-tac-toe.addpkg
Wind River Linux 5.x and Intel Gateway Solutions for IoT
34 Wind River Education Services
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
9. Execute the following command to build the package.
make -C build tic-tac-toe
10. Execute the following command to build the project.
make
After the platform project builds, the directory export/dist contains a copy of the
target root file system.
11. Execute the following command to verify that the binary tic-tac-toe is part of the new target image.
ls -l export/dist/usr/bin/tic-tac-toe
-rwxr-xr-x 1 wruser wruser 10392 Aug 2 14:40 ...
12. If time permits, try the program on your target. The tic-tac-toe binary found in /usr/bin on the target file system.
This concludes the lab. Do not proceed.
Integrating New Applications Lab
Wind River Education Services 35
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
Wind River Linux 5.x and Intel Gateway Solutions for IoT
36 Wind River Education Services
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
© 2013 Wind River Systems, Inc
Patching Packages Lab
37
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
Patching Packages Lab
Objective
In this lab you will learn how to make permanent modifications to packages that
ship with Wind River Linux.
NOTE: This lab should take approximately 30 minutes.
Lab Overview
In the Building and Customizing a Wind River Linux Platform lab, you learned
how to change the source code for a package included with the standard Wind
River Linux product. Knowing how to do this comes in handy in situations like the
following:
you find a bug that you must fix
you wish to add functionality not present in the standard package distribution
you want to change some aspect of the package configuration
The techniques learned in the Building and Customizing a Wind River Linux
Platform lab were only temporary — your changes were lost when you cleaned
the package build directory.
This lab will show you how to capture changes into patches that you can place
into a layer, where you can be keep the changes indefinitely or share them with
other projects.
Before You Begin
This lab modifies the configuration of an existing platform project. Use the pre-built
project provided with your lab environment. Refer to the Getting Started lab to identify
where to find this project in your lab environment. The location of this project will be
referenced as $TARGET_BASE throughout this lab.
This lab uses a command-line environment. Take the time now to open a command-line
terminal and navigate to this directory.
Wind River Linux 5.x and Intel Gateway Solutions for IoT
38 Wind River Education Services
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
Capturing Source Changes as a Patch
In the Building and Customizing a Wind River Linux Platform lab, you saw that changes
you make to packages in their build directory persist only as long as the package is not
cleaned up with a command such as make -C build .clean.
Often you will want your changes to be more permanent. You may also want to
propagate these changes to other projects or other developers in your team. In this section,
you will learn how to capture your changes into a patch. You can readily share patches
with others, or embed them into a layer to easily reproduce your patch in other projects.
In this section, you will focus on the busybox package, which provides the core run time
for glibc_small systems. In this section you will modify the source of the program ls to
print an additional message when you run it.
1. To modify the source to busybox, execute the following command to open a development shell for the package.
make -C build busybox.devshell
This opens a new terminal where the busybox source is located with all relevant
patches already applied. Note the name of the directory where the terminal opens
(busybox-1.19.4), which you will use in another exercise.
2. In the development shell, use the quilt utility (included with Wind River Linux) to assist in generating the patch. You can generate patches yourself manually, but the
quilt utility simplifies the process greatly, particularly when you are working with
several patches.
Execute the following command to initialize a new patch.
quilt new add-ls-banner.patch
Patch patches/add-ls-banner.patch is now on top
3. Now, execute the following command to instruct quilt to begin watching ls.c for changes.
quilt add coreutils/ls.c
File coreutils/ls.c added to patch patches/add-ls-banner.patch
4. Edit the code that implements the ls command provided by coreutils/ls.c. Add an additional message like the following to the beginning of the function ls_main().
init_unicode();
fprintf(stderr, "Hello from ls\n");
if (ENABLE_FEATURE_LS_SORTFILES)
…
Patching Packages Lab
Wind River Education Services 39
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
5. With your changes saved, instruct quilt to update the patch file based on the current state of the files being watched:
quilt refresh
Refreshed patch patches/add-ls-banner.patch
Examine the contents of patches/add-ls-banner.patch. You will see that it describes
the changes you have made to ls.c.
6. Execute the following command to copy the patch to your home directory.
cp patches/add-ls-banner.patch ~
7. Exit the development shell.
Saving Source Changes in the Local layer
In this section, you will learn how to make source changes permanent within your project
by embedded them into the local layer. Once there, the changes are in a format that you
can easily migrate to a custom layer to share with other projects.
To accomplish this task, you must do the following:
Create a directory structure in the local layer to host your changes.
Add patch file(s) describing your changes.
Create a .bbappend file describing the name and the location of the patch file(s).
8. Execute the following command to make a directory.
mkdir –p layers/local/recipes-local/busybox
9. Execute the following command to copy the patch from the previous section and place it in the directory you just created.
cp ~/add-ls-banner.patch \
layers/local/recipes-local/busybox
Wind River Linux 5.x and Intel Gateway Solutions for IoT
40 Wind River Education Services
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
10. As a last step, create the file layers/local/recipes-local/busybox/busybox_1.19.4.bbappend with the following content.
FILESEXTRAPATHS_prepend := “${THISDIR}:”
SRC_URI += “file://add-ls-banner.patch”
Although the syntax might seem a little peculiar at first, particularly if you’re not
familiar with the Python programming language, it should seem pretty clear what
these two lines of code are accomplishing. At a higher level:
The bitbake construct FILESEXTRAPATHS_prepend adds the directory containing your .bbappend file (referenced by ${THISDIR}) to the head of the
list of paths to search for content (that is, your patch file).
SRC_URI is updated to include your patch file.
11. With your .bbappend and patch files in place, rebuild the busybox package.
make -C build busybox.rebuild
12. Build the project.
make
13. Try your new implementation of the ls command using busybox. Start the target, as outlined in the Getting Started lab, and execute the following command on the target:
busybox ls
Hello from ls
bin dev home ...
boot etc lib ...
NOTE: The native command ls in this configuration is implemented by a package called coreutils, not by busybox. By invoking the command busybox ls
above you are invoking the busybox implementation of ls which is the one
you want to test. If you want to modify the command ls used by the system
you can follow the procedure in this lab but operating on the coreutils
package instead.
This concludes the lab. Do not proceed.
Patching Packages Lab
Wind River Education Services 41
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
Wind River Linux 5.x and Intel Gateway Solutions for IoT
42 Wind River Education Services
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
© 2013 Wind River Systems, Inc
Integrating Compiled Applications Lab
43
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
Integrating Compiled Applications Lab
Objective
In this lab you will learn how to integrate software which must be compiled into
Wind River Linux platforms.
NOTE: This lab should take approximately 90 minutes.
Lab Overview
Wind River Linux comes with hundreds of validated software packages which are
ready to use in Wind River Linux platforms. Still, you will likely one day need a
software package that is not included, or, you will be asked to integrate an
application being developed in house. When that happens, you must integrate the
package into the Wind River Linux build system, so that the package can be cross-
compiled along with the rest of your platform software. A properly integrated
package makes it easy to include the package into other projects as well.
This lab will walk you through the integration of three examples you’re likely to
encounter:
Packages driven by autoconf. These packages include a configure script, which you run before building the software with make. Configure probes
the characteristics of the system it is running on, and generates
customized Makefile and header files to enable the software to be built on
that system.
Packages driven by a Makefile. In this scenario, the package does not automatically configure itself for the system it is being built on; rather it
relies on the skills of the person who wrote the Makefile to ensure that it
will compile on a wide variety of platforms.
A Wind River Workbench application project. These projects are based on Makefiles, but have unique constraints on how they are built, due to the
managed build system that Workbench provides.
Before You Begin
This lab modifies the configuration of an existing platform project. Use the pre-built
project provided with your lab environment. Refer to the Getting Started lab to identify
where to find this project in your lab environment. The location of this project will be
referenced as $TARGET_BASE throughout this lab.
This lab uses a command-line environment. Take the time now to open a command-line
terminal and navigate to this directory.
Wind River Linux 5.x and Intel Gateway Solutions for IoT
44 Wind River Education Services
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
Integrating Packages Driven by Autoconf
In this section, you will work with a package called links, which implements a text-based
web browser. This package can be downloaded using the following URL:
http://www.jikos.cz/~mikulas/links/download/links-1.00pre23.tar.gz. For your
convenience, a pristine copy of the upstream source is provided in the directory
/Labs/Packages.
The build system for links is configurable using autconf. autoconf provides a framework
for generating a configure script, which the builder runs before building the software for
the first time. This configure script detects and records various system settings needed to
build the software, and generates custom Makefiles and header files according to those
settings. This makes building the software easier on a variety of different systems, and
also works well in a cross compiling environment like Wind River Linux.
In this exercise, you will integrate this package using the local layer provided by all Wind
River Linux platform projects.
1. Run the following command to start the package importing tool. This tool simplifies the task of integrating a new package by performing many of the routine initialization
tasks.
make import-package
Integrating Compiled Applications Lab
Wind River Education Services 45
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
2. The package importer GUI will appear. Set the Package Type field to Source Package.
3. If you have network access, you can enter the URL of the package into the Package Location text field. Otherwise, you may type the location of the package archive, or
click Browse to use the GUI to locate the archive file.
2 3
Wind River Linux 5.x and Intel Gateway Solutions for IoT
46 Wind River Education Services
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
4. Use the file system browser to locate the archive in /Labs/Packages and click OK.
4
Integrating Compiled Applications Lab
Wind River Education Services 47
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
5. Back in the main window, click Update to ensure that the tool picks up settings from the package location you entered.
6. Notice that the tool has automatically picked up proper values for Package Name and Version.
7. Now click IMPORT.
6 5 7
Wind River Linux 5.x and Intel Gateway Solutions for IoT
48 Wind River Education Services
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
8. The tool will now copy the archive and generate a recipe template in your project’s local layer. You will see a progress report in the Progress area of the GUI. Once the
operation succeeds you will see that the last log line says Package Import
Completed!
9. Press Close to dismiss the window.
9 8
Integrating Compiled Applications Lab
Wind River Education Services 49
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
10. Take note of the files which the package import tool added to your project:
layers/local/downloads/links-1.00pre23.tar.gz, which contains a local copy of the upstream source.
layers/local/recipes-local/links/links_1.00pre23.bb, which is a recipe template that you will have to finish customizing before you can proceed to build the links
package.
NOTE: The package import tool also adds the new package to your image automatically.
Open the links_1.00pre23.bb file in the editor of your choice. The main objective at
this point is to proceed through this file and customize the settings for your package.
11. The first items that need consideration are LICENSE and LIC_FILES_CHKSUM. These properties relate to the license associated with the software you’re importing.
Because licensing is such an important consideration when deploying devices based
on open source software, the notion of license awareness is tightly coupled into the
build system. This awareness manifests itself at the package level in these two
properties, which must be set accordingly:
LICENSE: this must describe the type of license governing the distribution of the package you’ve imported.
LIC_FILES_CHKSUM: this specifies the file containing the license terms as well as a reference MD5 checksum of the license text. This is used to authenticate
the license text. If the licensing terms change in a future revision of the package,
the MD5 checksum will no longer match the value recorded in the recipe, and the
builder of the software will be warned.
12. To determine appropriate settings for LICENSE and LIC_FILES_CHKSUM, you must consult the package contents to determine the licensing terms and where these
terms are recorded. With the package added to the local layer, you can easily extract
the package source at this point:
make -C build links.unpack
Wind River Linux 5.x and Intel Gateway Solutions for IoT
50 Wind River Education Services
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
The extracted source of the package can now be found in the directory build/links-
1.00pre23-r0/links-1.00pre23.
The exact location of the licensing terms varies by package, although you will often
find a file called LICENSE, license.txt, or COPYING which specifies the license
terms. Sometimes it is even specified at the top of source, header, or Makefiles.
You will find that the license for links is disclosed in the file COPYING. Referring
to this file, the license disclosed is clearly GPLv2. So, set the values for the two
license-related properties in links_1.00pre23.bb accordingly.
SUMMARY = "The links package"
DESCRIPTION = "The links package"
HOMEPAGE = "http://www.your_company_here.com"
LICENSE = "GPLv2"
SECTION = "devel"
# You need to checksum the license for this package. Leave
the…
# and on the first compile pass bitbake will tell you what
value…
# This example is for a whole file...
LIC_FILES_CHKSUM = "file://COPYING;md5="
# This example is for a section of a file...
#LIC_FILES_CHKSUM =
"file://Makefile;beginline=3;endline=9;md5="
13. Because there is a dedicated file for the license, calculating the required checksum is a straightforward process using the md5sum utility:
md5sum build/links-1.00pre23-r0/links-1.00pre23/COPYING
b0c80473f97008e42e29a9f80fcc55ff COPYING
Complete the LIC_FILES_CHKSUM line in links_1.00pre23.bb using the value
you obtained:
# This example is for a whole file...
LIC_FILES_CHKSUM = "file://COPYING;md5=
b0c80473f97008e42e29a9f80f…"
# This example is for a section of a file...
NOTE: You can also let bitbake calculate the value for you by leaving this field empty. The first time you attempt to build the package, bitbake will complain.
In the error message, it will tell you what the expected value should be, which
you can then copy and paste into your recipe.
Integrating Compiled Applications Lab
Wind River Education Services 51
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
14. Proceeding further down the recipe you will see places to declare package dependencies.
#DEPENDS = ""
#RDEPENDS_links=""
If your package has build time dependencies (for example, it needs a particular library
to link against, or requires some unusual host tool to build), DEPENDS is how you
declare these requirements.
If, on the other hand, the package has run time dependencies (for example, it needs a
particular system utility or shared library to function properly), RDEPENDS is how
you declare these requirements.
For now, leave these fields commented out. Dependencies can be fleshed out later
when you attempt to build or run the software.
15. Next, adjust SRC_URI to reflect the URL of the package. This was provided in the beginning of this section. It is important to fill this out, even if a local copy of the
archive is provided, since bitbake uses this value to determine the filename of the
archive to search for in the downloads directory.
# This is were you set the package tarball upstream location…
# name at the end of the path is used as the package's tarba…
# searched in the local 'download' directories.
SRC_URI = "http://www.jikos.cz/…/links-1.00pre23.tar.gz"
16. To validate the integrity of the archive, bitbake uses SRC_URI[md5sum] and SRC_URI[sha256sum]. As before, you can leave these blank and allow bitbake to
tell you the values to fill in, or you can obtain these values and fill them in now as
follows.
Obtain the value for SRC_URI[md5sum]:
md5sum layers/local/downloads/links-1.00pre23.tar.gz
4311895409dcf03125d767d645fdabf6 links-1.00pre23.tar.gz
Execute the following command to obtain the value for SRC_URI[sha256sum].
sha256sum layers/local/downloads/links-1.00pre23.tar.gz
6c90e08a0fd96bafb0878529ff855c36b8881762d75b1c6fc609209b2e05254a
links…
Wind River Linux 5.x and Intel Gateway Solutions for IoT
52 Wind River Education Services
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
17. Often, packages need additional arguments passed in when their makefile is invoked. EXTRA_OECONF is provided for this purpose. Without close examination of the
makefile, it’s difficult to know what arguments (if any) to provide here. So it might
be just as easy to leave this value alone until you attempt to build the package. If the
do_build or do_install tasks are misbehaving, it’s often because some additional
argument must be passed in. At that point, you would study the makefile to see if any
additional arguments must be passed in.
18. Examining the package source code, you will see by the structure that it is clearly driven by autoconf, as evidenced by the presence of configure, Makefile.in, etc.
Thus, you must enable autotools functionality by uncommenting the line in the
recipe:
# Enable this if the package uses automake/configure
inherit autotools
19. Lastly, you will see that the tool has provided a do_install() task, which is populated with code which copies out a binary called my_bin. Clearly this is boilerplate code
which must be customized for your package.
Studying the package’s Makefile (or in this case, Makefile.in, since a custom
Makefile is generated when configure is run) is the best way to determine what needs
to be done in a do_install task. If the Makefile has an install rule (which most well-
written Makefiles do), then you can usually just use the default do_install task
provided by the autotools class, which is shown below:
autotools_do_install() {
oe_runmake 'DESTDIR=${D}' install
# Info dir listing isn't interesting at this point so…
if [ -e "${D}${infodir}/dir" ]; then
rm -f ${D}${infodir}/dir
fi
}
NOTE: You can see this code, as well as all the code that implements the autotools class, in the file layers/oe-core/meta/classes/autotools.bbclass.
To use the default do_install() task, simply delete the do_install task that was
provided by the import-package tool.
20. Save the changes to links_1.00pre23.bb and make your first attempt to build the package.
make -C build links
If you chose to leave the MD5 value for LIC_FILES_CHKSUM blank, the build
will fail immediately with error reports associated with the license checksum similar
to the following:
Integrating Compiled Applications Lab
Wind River Education Services 53
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
ERROR: links: md5 data is not matching for file://COPYING;md5=
ERROR: links: the new md5 checksum is b0c8047...
In that case, copy the MD5 checksum value listed in the error report into the
appropriate place in links_1.00pre23.bb.
Otherwise, the build will proceed through the various stages, which consists of the
following tasks:
Unpack the source archive into the build stage directory, which you already did this manually earlier in this section.
Patch the extracted source with patches listed in the recipe, if applicable. In this case, there were no patches to apply.
Configure the source for the build environment. In this case, bitbake calls the configure script in the build stage directory.
Compile the source contained in the build stage directory by calling make.
Install the software into an install stage directory by invoking make install, as specified in the do_install task you created.
Generate binary RPMs based on the contents of the install stage.
21. Since the package import tool automatically adds the package to your image, you do not need to add it to your image explicitly. Instead, go ahead and build your image.
make
22. Once the build completes, perform a quick sanity check to verify that the links executable can be found within the target file system:
find export/dist -name links
export/dist/usr/bin/links
23. Feel free to take the time to deploy your new image to the target to test links.
Assuming that you followed the instructions carefully, this exercise likely seemed
unexpectedly easy. The reality is that packages driven by autoconf are usually very easy
to integrate, as the bitbake build engine is designed to work harmoniously with these
types of packages.
Integrating Packages Driven by a Makefile
For this example, you will import a package called figlet, which is a program that renders
large decorative printing using standard ASCII characters. Figlet can be downloaded
from ftp://ftp.figlet.org/pub/figlet/program/unix/figlet-2.2.5.tar.gz, but a pristine copy
in contained in the directory /Labs/Packages.
Wind River Linux 5.x and Intel Gateway Solutions for IoT
54 Wind River Education Services
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
This package, like many open source packages, has not been developed to use autoconf.
Rather, the build is driven by a static makefile. The degree of difficulty involved in
integrating packages like this one largely depends on how mindful the author was to
flexibility when writing the makefile.
For example, if the makefile uses conventional macros (like $(CC), shown below) in
invoking build tools, it can adapt easily to the Wind River Linux cross compiling build
environment.
all: $(OBJS) libs ../config.mk
$(CC) -o menu $(OBJS) input.a draw.a $(LDFLAGS) $(LDLIBS)
By contrast, if the makefile is “hard-coded” as shown below, then it will require some
degree of patching in order for it to cross compile smoothly. In other words, you will
have to create a patch which modifies the Makefile to change gcc to $(CC).
all: $(OBJS) libs ../config.mk
gcc -o menu $(OBJS) input.a draw.a $(LDFLAGS) $(LDLIBS)
In this scenario, the integration effort then depends on the number and complexity of the
makefiles that need to be patched.
A list of common macros supported by Wind River Linux is summarized below:
Macro Native Equivalent
Tool
$(CC) gcc C compiler
$(CXX) g++ C++ compiler
$(CPP) gcc -E C preprocessor
$(AS) as Assembler
$(LD) ld Linker
$(GDB) gdb Debugger
$(AR) ar Archiver for generating static libraries
$(NM) nm List symbols in object files
$(OBJCOPY) objcopy Copy and translate object files
$(OBJDUMP) objdump Display information from object files
$(RANLIB) ranlib Index symbols in an archive
$(STRIP) strip Remove symbol information from object files
In summary, the common goals to keep in mind when approaching packages with static
makefiles are:
Makefiles must invoke the appropriate cross-compiling tools as specified by the build environment, rather than native tools.
Software must install correctly to the install stage directory, rather than absolute paths within the host file system.
Pay attention to any other installation actions the package might perform – these must be applied to the target file system, not the host.
Integrating Compiled Applications Lab
Wind River Education Services 55
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
24. Run the package importer tool as you did in the previous section, this time using the file /Labs/Packages/figlet-2.2.5.tar.gz for the Package Location.
25. For reference in editing the recipe, extract the source for the newly imported package.
make -C build figlet.unpack
The extracted source of the package can now be referred to at build/figlet-2.2.5-
r0/figlet-2.2.5.
26. Now, open the recipe layers/local/recipes-local/figlet/figlet_2.2.5.bb in the editor of your choice.
27. As in the previous section, the first issue which needs to be addressed relates to the license file. This can be handled in exactly the same way that it was done when
importing the links package; identify the file within build/figlet-2.2.5-r0/figlet-2.2.5
containing the license text, and set LIC_FILES_CHKSUM to point to this file.
Populate the MD5 checksum value at this time if you wish, or defer it and let bitbake
disclose the value for you when you attempt to build the package.
28. By default, the value for LICENSE is set to GPLv2 by the package import tool, but it really should be set to accurately reflect the actual package license. Referring to the
license file, build/figlet-2.2.5-r0/figlet-2.2.5/LICENSE, you will see that it is
definitely not a GPLv2 license. It is, in fact, a 3-clause BSD license. Populate the
value for LICENSE accordingly.
LICENSE = "BSD-3-Clause"
NOTE: There are numerous open source licenses in circulation. Some are easy to identify, but recognizing all of them is not always easy. To see the complete
list of standard open-source licenses known to the bitbake authors, check the
contents of the directory layers/oe-core/meta/files/common-licenses. This
resource provides you with the names of the licenses (to fill in the field
LICENSE) as well as the license text. Open-source license recognition tools
like Ninka (http://ninka.turingmachine.org/) can also be helpful.
29. Because this package is not driven by autotools, leave the inherit autotools line commented out, unlike the previous example.
# Enable this if the package uses automake/configure
#inherit autotools
30. Lastly, you must address the do_install task. Referring to this package’s Makefile , you will see that it provides an install rule. Rather than manually copying the files out,
leverage the install rule with a simple do_install task like this:
do_install() {
oe_runmake 'DESTDIR=${D}' install
}
Wind River Linux 5.x and Intel Gateway Solutions for IoT
56 Wind River Education Services
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
31. With the changes to the recipe saved, attempt to build your package. Supply missing MD5 values, if needed.
32. Ultimately you will be met with a compile problem:
…/i686-wrs-linux-gnu-ld: unrecognized option '-Wl,-O1'
…/i686-wrs-linux-gnu-ld: use the --help option for usage
information
make: *** [figlet] Error 1
Notice two things from the output:
The linker (in this case, i686-wrs-linux-gnu-ld; ppc-wrs-linux-gnu-ld if using a powerpc target) is being invoked directly.
The options being passed in to the linker (-Wl,-O1) are compiler options, not linker options.
Referring to the Makefile for figlet, found at build/figlet-2.2.5-r0/figlet-
2.2.5/Makefile, you will see that it is invoking the linker directly in two places:
figlet: $(OBJS)
$(LD) $(LDFLAGS) -o $@ $(OBJS)
chkfont: chkfont.o
$(LD) $(LDFLAGS) -o $@ chkfont.o
It is generally not recommended to invoke $(LD) directly from a Makefile, unless
you have a very good reason for doing so. Rather, it is advisable to use $(CC), since
it handles setting additional flags that may get missed otherwise.
To handle this situation properly, you are going to need to patch the Makefile.
33. Please refer to the Patching a Package lab to see how to develop a patch which makes the necessary changes to the Makefile before proceeding.
34. With your patch in place, rebuild the package.
NOTE: To fully test all cycles of a package build, it’s a good idea to “really clean” the package from your build environment after a period of incremental
development. The clean target isn’t sufficient, because it merely cleans the
build directory. To ensure that the build directory and sstate cache are clean,
you should use distclean or cleanssstate (the two are synonymous). That is,
make -C build figlet.cleanssate.
Integrating Compiled Applications Lab
Wind River Education Services 57
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
35. This time, your package should build cleanly. Feel free to test it by rebuilding your image and deploying it to your target. Try figlet by running the following on the
target:
echo "Hello" | figlet
Patching Package Source
In integrating new packages and maintaining your project, it is not uncommon to need to
modify the package source to get it to build or run properly.
Because the package source is always assumed to be unmodified upstream source, the
only way to modify source in an automated manner between source extraction and build
is to supply a patch that makes these modifications for you. Patches are useful for both:
Fixing integration issues (fixing a Makefile or some other build related issue)
Fixing run time bugs or adding features that have not yet been incorporated upstream
In this section you will patch the source for the figlet package, used in the previous
section. In this particular use case, you will make a small fix to the Makefile to enable it
to build properly. However, the same approach applies for any changes you wish to make
to the source code, no matter how big or small.
36. To modify the source to figlet, open a development shell for the package, as follows:
make -C build figlet.devshell
This will open a new terminal where the figlet source is located with any existing
patches already applied.
37. To generate the patches, you will be using the quilt utility, which is used extensively throughout Wind River Linux to manage patches. The workflow for generating a
patch with quilt involves:
Initializing a new patch
Telling quilt which file(s) you are going to modify
Making your changes
Telling quilt to “refresh” the patch; that is, to capture the differences into the patch you initialized in the first step
Begin by initializing the new patch in the development shell:
quilt new makefile-integration.patch
Patch patches/makefile-integration.patch is now on top
Wind River Linux 5.x and Intel Gateway Solutions for IoT
58 Wind River Education Services
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
38. Now, inform quilt that you want to include the modifications you are about to make to the Makefile in the patch.
quilt add Makefile
File Makefile added to patch patches/makefile-integration.patch
39. Open the Makefile in the editor of your choice, and make the needed changes. In this particular case, you are going to replace the two invocations of $(LD) with $(CC). So,
the lines that read:
figlet: $(OBJS)
$(LD) $(LDFLAGS) -o $@ $(OBJS)
chkfont: chkfont.o
$(LD) $(LDFLAGS) -o $@ chkfont.o
should read as follows once you are done:
figlet: $(OBJS)
$(CC) $(LDFLAGS) -o $@ $(OBJS)
chkfont: chkfont.o
$(CC) $(LDFLAGS) -o $@ chkfont.o
When done, save your changes and exit the editor.
40. Now, instruct quilt to capture your changes into the patch:
quilt refresh
Refreshed patch patches/makefile-integration.patch
Examine the contents of the patch, found at patches/makefile-integration.patch, to
ensure that everything got captured the way you intended.
41. When done, copy the patch into your project’s local layer.
cp patches/makefile-integration.patch \
$TARGET_BASE/layers/local/recipes-local/figlet/files
42. With patch generation complete, you may now exit the development shell by executing the command exit.
Integrating Compiled Applications Lab
Wind River Education Services 59
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
43. In the package recipe (in this case, figlet_2.2.5.bb, you will add the new patch file to the existing set of resources listed in SRC_URI, as follows:
SRC_URI = "ftp://ftp.figlet.org/pub/figlet/…/figlet-
2.2.5.tar.gz \
file://makefile-integration.patch"
44. With that, your patch is complete, integrated into your package recipe, and ready to test.
Integrating Workbench Application Projects
For this example, you will work with a Wind River Linux Application Project developed
using Wind River Workbench. This application contains a simple, console-based
implementation of the game Minesweeper. Although the project is fairly simple, the
approach outlined in this section can be applied to Workbench projects of any level of
complexity.
A copy of the application can be found in in contained in the directory
/Labs/Packages/fkmines. Although you don’t have to, you can import it into your
workspace within Workbench to satisfy yourself that it’s a genuine application project
that you can build within Workbench.
45. Run the package importer tool as you did in previous sections.
make import-package
Wind River Linux 5.x and Intel Gateway Solutions for IoT
60 Wind River Education Services
Subject to Wind River Terms of Use - Do Not Copy – Do Not Distribute
46. This time, set Package Type to Workbench Application Project.
47. For the Package Location field to, specify /Labs/Packages/fkmines. You may use the Browse button, or simply type the location in manually.
NOTE: If you type the Package Location manually, you must click Update afterward.
48. M