Wind River Linux 5.x and Intel Gateway Solutions for...

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.


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


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


© 2013 Wind River Systems, Inc

Building and Customizing a Wind River Linux Platform Lab

1



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


2 Wind River Education Services


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


Wind River Education Services 3


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.




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



…




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



…

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.




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.




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.




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.




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.




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.





Managing Wind River Linux Platforms in Workbench Lab

13



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.


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




4. In the Build type field, select Platform.

5. Click Next.

4

5




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




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




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




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




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.




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




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




25. Use the browser to navigate to the directory containing the platform project you wish to import.

26. Click OK.

26 27




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




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.




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




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.


35

36





Integrating New Applications Lab

29



Objective

In this lab you will learn the basics of how to integrate third-party software

components into Wind River Linux platforms.


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.




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.




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.




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




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




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.






Patching Packages Lab

37



Objective

In this lab you will learn how to make permanent modifications to packages that

ship with Wind River Linux.


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










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)

…




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




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.






Integrating Compiled Applications Lab

43



Objective

In this lab you will learn how to integrate software which must be compiled into

Wind River Linux platforms.


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










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




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




4. Use the file system browser to locate the archive in /Labs/Packages and click OK.

4




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




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




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




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.




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…




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:




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.




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.




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

}




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.




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




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.




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




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

Wind River Linux 5.x and Intel Gateway Solutions for...

Documents

Transcript of Wind River Linux 5.x and Intel Gateway Solutions for...