OPEN SOURCE SOFTWARE DEVELOPMENT SERIES

Embedded
Linux Systems with
the Yocto Project"

FREE SAMPLE CHAPTER

SHARE WITH OTHERS

�f, � � � �
Embedded Linux
Systems with the
TM

Yocto Project
This page intentionally left blank
 Embedded Linux
Systems with the
TM

Yocto Project

Rudolf J. Streif

Boston • Columbus • Indianapolis • New York • San Francisco • Amsterdam • Cape Town
Dubai • London • Madrid • Milan • Munich • Paris • Montreal • Toronto • Delhi • Mexico City
São Paulo • Sidney • Hong Kong • Seoul • Singapore • Taipei • Tokyo
Many of the designations used by manufacturers and sellers to distinguish their products are
claimed as trademarks. Where those designations appear in this book, and the publisher was
aware of a trademark claim, the designations have been printed with initial capital letters or in all
capitals.
The author and publisher have taken care in the preparation of this book, but make no expressed
or implied warranty of any kind and assume no responsibility for errors or omissions. No liability is
assumed for incidental or consequential damages in connection with or arising out of the use of the
information or programs contained herein.
For information about buying this title in bulk quantities, or for special sales opportunities (which
may include electronic versions; custom cover designs; and content particular to your business,
training goals, marketing focus, or branding interests), please contact our corporate sales depart-
ment at [email protected] or (800) 382-3419.
For government sales inquiries, please contact [email protected].
For questions about sales outside the U.S., please contact [email protected].
Visit us on the Web: informit.com
Cataloging-in-Publication Data is on file with the Library of Congress.
Copyright © 2016 Pearson Education, Inc.
All rights reserved. Printed in the United States of America. This publication is protected by copy-
right, and permission must be obtained from the publisher prior to any prohibited reproduction,
storage in a retrieval system, or transmission in any form or by any means, electronic, mechanical,
photocopying, recording, or likewise. For information regarding permissions, request forms and
the appropriate contacts within the Pearson Education Global Rights & Permissions Department,
please visit www.pearsoned.com/permissions/.
ISBN-13: 978-0-13-344324-0
ISBN-10: 0-13-344324-8
Text printed in the United States on recycled paper at RR Donnelley in Crawfordsville, Indiana.
First printing, May 2016
 ❖
To Janan, Dominic, Daniel, and Jonas
❖
This page intentionally left blank
Contents
Foreword xv
Preface xvii
Acknowledgments xxi
About the Author xxiii

1 Linux for Embedded Systems 1

1.1 Why Linux for Embedded Systems? 1
1.2 Embedded Linux Landscape 3
1.2.1 Embedded Linux Distributions 3
1.2.2 Embedded Linux Development Tools 5
1.3 A Custom Linux Distribution—Why Is It Hard? 8
1.4 A Word about Open Source Licensing 9
1.5 Organizations, Relevant Bodies, and
Standards 11
1.5.1 The Linux Foundation 11
1.5.2 The Apache Software Foundation 11
1.5.3 Eclipse Foundation 12
1.5.4 Linux Standard Base 12
1.5.5 Consumer Electronics Workgroup 13
1.6 Summary 13
1.7 References 14

2 The Yocto Project 15

2.1 Jumpstarting Your First Yocto Project Build 15
2.1.1 Prerequisites 16
2.1.2 Obtaining the Yocto Project Tools 17
2.1.3 Setting Up the Build Host 18
2.1.4 Configuring a Build Environment 20
2.1.5 Launching the Build 23
2.1.6 Verifying the Build Results 24
2.1.7 Yocto Project Build Appliance 24
2.2 The Yocto Project Family 26
2.3 A Little Bit of History 28
2.3.1 OpenEmbedded 29
2.3.2 BitBake 29
2.3.3 Poky Linux 29
viii Contents

2.3.4 The Yocto Project 30

2.3.5 The OpenEmbedded and Yocto Project
Relationship 30
2.4 Yocto Project Terms 31
2.5 Summary 33
2.6 References 34

3 OpenEmbedded Build System 35

3.1 Building Open Source Software Packages 35
3.1.1 Fetch 36
3.1.2 Extract 36
3.1.3 Patch 37
3.1.4 Configure 37
3.1.5 Build 38
3.1.6 Install 38
3.1.7 Package 38
3.2 OpenEmbedded Workflow 39
3.2.1 Metadata Files 41
3.2.2 Workflow Process Steps 43
3.3 OpenEmbedded Build System Architecture 45
3.3.1 Build System Structure 47
3.3.2 Build Environment Structure 50
3.3.3 Metadata Layer Structure 53
3.4 Summary 56
3.5 References 57

4 BitBake Build Engine 59

4.1 Obtaining and Installing BitBake 59
4.1.1 Using a Release Snapshot 60
4.1.2 Cloning the BitBake Development
Repository 60
4.1.3 Building and Installing BitBake 60
4.2 Running BitBake 61
4.2.1 BitBake Execution Environment 61
4.2.2 BitBake Command Line 63
4.3 BitBake Metadata 70
4.4 Metadata Syntax 71
4.4.1 Comments 71
4.4.2 Variables 72
 Contents ix

4.4.3 Inclusion 76
4.4.4 Inheritance 77
4.4.5 Executable Metadata 79
4.4.6 Metadata Attributes 85
4.4.7 Metadata Name (Key) Expansion 86
4.5 Source Download 86
4.5.1 Using the Fetch Class 87
4.5.2 Fetcher Implementations 88
4.5.3 Mirrors 94
4.6 HelloWorld—BitBake Style 95
4.7 Dependency Handling 99
4.7.1 Provisioning 99
4.7.2 Declaring Dependencies 101
4.7.3 Multiple Providers 101
4.8 Version Selection 102
4.9 Variants 103
4.10 Default Metadata 103
4.10.1 Variables 103
4.10.2 Tasks 107
4.11 Summary 107
4.12 References 108

5 Troubleshooting 109
5.1 Logging 110
5.1.1 Log Files 110
5.1.2 Using Logging Statements 114
5.2 Task Execution 116
5.2.1 Executing Specific Tasks 118
5.2.2 Task Script Files 118
5.3 Analyzing Metadata 119
5.4 Development Shell 120
5.5 Dependency Graphs 121
5.6 Debugging Layers 122
5.7 Summary 124

6 Linux System Architecture 127

6.1 Linux or GNU/Linux? 127
6.2 Anatomy of a Linux System 128
x Contents

6.3 Bootloader 129

6.3.1 Role of the Bootloader 130
6.3.2 Linux Bootloaders 130
6.4 Kernel 134
6.4.1 Major Linux Kernel Subsystems 136
6.4.2 Linux Kernel Startup 140
6.5 User Space 141
6.6 Summary 143
6.7 References 144

7 Building a Custom Linux Distribution 145

7.1 Core Images—Linux Distribution Blueprints 146
7.1.1 Extending a Core Image through Local
Configuration 149
7.1.2 Testing Your Image with QEMU 150
7.1.3 Verifying and Comparing Images Using the Build
History 151
7.1.4 Extending a Core Image with a Recipe 152
7.1.5 Image Features 153
7.1.6 Package Groups 155
7.2 Building Images from Scratch 160
7.3 Image Options 161
7.3.1 Languages and Locales 162
7.3.2 Package Management 162
7.3.3 Image Size 163
7.3.4 Root Filesystem Types 164
7.3.5 Users, Groups, and Passwords 166
7.3.6 Tweaking the Root Filesystem 167
7.4 Distribution Configuration 169
7.4.1 Standard Distribution Policies 169
7.4.2 Poky Distribution Policy 170
7.4.3 Distribution Features 176
7.4.4 System Manager 179
7.4.5 Default Distribution Setup 179
7.5 External Layers 181
7.6 Hob 181
7.7 Summary 184
 Contents xi

8 Software Package Recipes 185

8.1 Recipe Layout and Conventions 185
8.1.1 Recipe Filename 186
8.1.2 Recipe Layout 186
8.1.3 Formatting Guidelines 195
8.2 Writing a New Recipe 196
8.2.1 Establish the Recipe 198
8.2.2 Fetch the Source Code 199
8.2.3 Unpack the Source Code 200
8.2.4 Patch the Source Code 201
8.2.5 Add Licensing Information 201
8.2.6 Configure the Source Code 202
8.2.7 Compile 203
8.2.8 Install the Build Output 204
8.2.9 Setup System Services 206
8.2.10 Package the Build Output 207
8.2.11 Custom Installation Scripts 210
8.2.12 Variants 211
8.3 Recipe Examples 212
8.3.1 C File Software Package 212
8.3.2 Makefile-Based Software Package 213
8.3.3 CMake-Based Software Package 215
8.3.4 GNU Autotools-Based Software Package 216
8.3.5 Externally Built Software Package 217
8.4 Devtool 218
8.4.1 Round-Trip Development Using Devtool 219
8.4.2 Workflow for Existing Recipes 223
8.5 Summary 224
8.6 References 224

9 Kernel Recipes 225

9.1 Kernel Configuration 226
9.1.1 Menu Configuration 227
9.1.2 Configuration Fragments 228
9.2 Kernel Patches 231
9.3 Kernel Recipes 233
9.3.1 Building from a Linux Kernel Tree 234
9.3.2 Building from Yocto Project Kernel
Repositories 238
xii Contents

9.4 Out-of-Tree Modules 251

9.4.1 Developing a Kernel Module 251
9.4.2 Creating a Recipe for a Third-Party
Module 254
9.4.3 Including the Module with the Root
Filesystem 256
9.4.4 Module Autoloading 257
9.5 Device Tree 257
9.6 Summary 258
9.7 References 259

10 Board Support Packages 261

10.1 Yocto Project BSP Philosophy 261
10.1.1 BSP Dependency Handling 263
10.2 Building with a BSP 265
10.2.1 Building for the BeagleBone 265
10.2.2 External Yocto Project BSP 272
10.3 Inside a Yocto Project BSP 277
10.3.1 License Files 279
10.3.2 Maintainers File 279
10.3.3 README File 279
10.3.4 README.sources File 280
10.3.5 Prebuilt Binaries 280
10.3.6 Layer Configuration File 280
10.3.7 Machine Configuration Files 280
10.3.8 Classes 281
10.3.9 Recipe Files 281
10.4 Creating a Yocto Project BSP 282
10.4.1 Yocto Project BSP Tools 282
10.4.2 Creating a BSP with the Yocto Project BSP
Tools 286
10.5 Tuning 289
10.6 Creating Bootable Media Images 290
10.6.1 Creating an Image with Cooked Mode 292
10.6.2 Creating an Image with Raw Mode 292
10.6.3 Kickstart Files 293
10.6.4 Kickstart File Directives 295
10.6.5 Plugins 297
10.6.6 Transferring Images 298
 Contents xiii

10.7 Summary 299

10.8 References 299

11 Application Development 301

11.1 Inside a Yocto Project ADT 302
11.2 Setting Up a Yocto Project ADT 304
11.2.1 Building a Toolchain Installer 304
11.2.2 Installing the Toolchain 305
11.2.3 Working with the Toolchain 307
11.2.4 On-Target Execution 310
11.2.5 Remote On-Target Debugging 311
11.3 Building Applications 315
11.3.1 Makefile-Based Applications 315
11.3.2 Autotools-Based Applications 316
11.4 Eclipse Integration 317
11.4.1 Installing the Eclipse IDE 317
11.4.2 Integrating a Yocto Project ADT 319
11.4.3 Developing Applications 321
11.4.4 Deploying, Running, and Testing on the
Target 323
11.5 Application Development Using an Emulated
Target 331
11.5.1 Preparing for Application Development
with QEMU 331
11.5.2 Building an Application and Launching It
in QEMU 333
11.6 Summary 333
11.7 References 334

12 Licensing and Compliance 335

12.1 Managing Licenses 335
12.1.1 License Tracking 337
12.1.2 Common Licenses 338
12.1.3 Commercially Licensed Packages 339
12.1.4 License Deployment 340
12.1.5 Blacklisting Licenses 340
12.1.6 Providing License Manifest and Texts 341
12.2 Managing Source Code 341
12.3 Summary 343
12.4 References 344
xiv Contents

13 Advanced Topics 345

13.1 Toaster 345
13.1.1 Toaster Operational Modes 346
13.1.2 Toaster Setup 347
13.1.3 Local Toaster Development 348
13.1.4 Toaster Configuration 349
13.1.5 Toaster Production Deployment 351
13.1.6 Toaster Web User Interface 356
13.2 Build History 358
13.2.1 Enabling Build History 358
13.2.2 Configuring Build History 359
13.2.3 Pushing Build History to a Git Repository
Server 360
13.2.4 Understanding the Build History 361
13.3 Source Mirrors 366
13.3.1 Using Source Mirrors 366
13.3.2 Setting Up Source Mirrors 368
13.4 Autobuilder 368
13.4.1 Installing Autobuilder 369
13.4.2 Configuring Autobuilder 370
13.5 Summary 374
13.6 References 375

A Open Source Licenses 377

A.1 MIT License (MIT) 377
A.2 GNU General Public License (GPL) Version 2 378
A.3 GNU General Public License (GPL) Version 3 384
A.4 Apache License Version 2.0 397

B Metadata Reference 403

Index 429
 Foreword

Ttechnology
he embedded Linux landscape is a little bit like the Old West: different outposts of
scattered here and there, with barren and often dangerous landscape in
between. If you’re going to travel there, you need to be well stocked, be familiar with
the territory, and have a reliable guide.
Just as people moved West during the Gold Rush in the mid-1800s, developers are
moving into the embedded Linux world with the rush to the Internet of Things. As
increased population brought law, order, and civilization to the Old West, important
new open source software projects are bringing order to embedded Linux.
The Yocto Project is a significant order-bringer. Its tools let you focus on designing
your project (what you want to build) and devote only the necessary minimum of your
time and effort to putting it all together (how you build what you want to build).
This book is your reliable guide. In logically ordered chapters with clear and com-
plete instructions, it will help you get your work done and your IoT project to market.
And with some luck, you’ll have fun along the way!
Enjoy your adventure!
Arnold Robbins
Series Editor
This page intentionally left blank
 Preface

S mart home. Smart car. Smart phone. Smart TV. Smart thermostat. Smart lights.
Smart watch. Smart washer. Smart dryer. Smart fridge. Smart basketball. Welcome to
the brave new world of smart everything!
The proliferation of embedded computers in almost everything we touch and inter-
act with in our daily lives has moved embedded systems engineering and embedded
software development into the spotlight. Hidden from the direct sight of their users,
embedded systems lack the attractiveness of web applications with their f lashy user
interfaces or the coolness of computer games with their animations and immersive
graphics. It comes as no surprise that computer science students and software developers
hardly ever think of embedded software engineering as their first career choice. How-
ever, the “smart-everything revolution” and the Internet of Things (IoT) are driving
the demand for specialists who can bridge hardware and software worlds. Experts who
speak the language of electric schematics as well as programming languages are sought
after by employers.
Linux has become the first choice for an explosively growing number of embedded
applications. There are good reasons for this choice, upon which we will elaborate in the
coming chapters. Through my journey as an embedded software developer for vari-
ous industries, I have learned Linux for embedded systems the hard way. There is no
shortage of excellent development tools for virtually any programming language. The
vast majority of libraries and applications for Linux can easily be built natively because
of their tooling. Even building the Linux kernel from scratch is almost a breeze with
the kernel’s own build system. However, when it comes to putting it all together into a
bootable system, the choices are scarce.
The Yocto Project closes that gap by providing a comprehensive set of integrated
tools with the OpenEmbedded build system at its center. From source code to bootable
system in a matter of a few hours—I wish I had that luxury when I started out with
embedded Linux!

What This Book Is and What It Is Not

A build system that integrates many different steps necessary to create a fully functional
Linux OS stack from scratch is rather complex. This book is dedicated to the build sys-
tem itself and how you can effectively use it to build your own custom Linux distribu-
tions. This book is not a tutorial on embedded Linux. Although Chapter 6 explains the
basics of the Linux system architecture (as this foundation is necessary to understanding
xviii Preface

how the build system assembles the many different components into an operational
system), I do not go into the details of embedded Linux as such. If you are a beginning
embedded Linux developer, I strongly recommend Christopher Hallinan’s excellent
Embedded Linux Primer, published in this same book series.
In this book, you will learn how the OpenEmbedded build system works, how you
can write recipes to build your own software components, how to use and create Yocto
Project board support packages to support different hardware platforms, and how to
debug build failures. You will learn how to build software development kits for applica-
tion development and integrate them with the popular Eclipse integrated development
environment (IDE) for seamless round-trip development.

Who Should Read This Book

This book is intended for software developers and programmers who have a working
knowledge of Linux. I assume that you know your way around the Linux command
line, that you can build programs on a Linux system using the typical tools, such as
Make and a C/C++ compiler, and that you can read and understand basic shell scripts.
The build system is written entirely in Python. While you do not need to be a
Python expert to use it and to understand how it works, having some core knowledge
about Python is certainly advantageous.

How This Book Is Organized

Chapter 1, “Linux for Embedded Systems,” provides a brief look at the adoption of
Linux for embedded systems. An overview of the embedded Linux landscape and the
challenges of creating custom embedded Linux distributions set the stage.
Chapter 2, “The Yocto Project,” introduces the Yocto Project by jumpstarting an
initial build of a Linux OS stack using the build system. It also gives an overview of the
Yocto Project family of projects and its history.
Chapter 3, “OpenEmbedded Build System,” explains the fundamentals of the build
system, its workf low, and its architecture.
Chapter 4, “BitBake Build Engine,” gives insight into BitBake, the build engine at
the core of the OpenEmbedded build system. It explains the metadata concept of reci-
pes, classes, and configuration files and their syntax. A Hello World project in BitBake
style illustrates the build workf low. Through the information provided, you gain the
necessary knowledge for understanding provided recipes and for writing your own.
Chapter 5, “Troubleshooting,” introduces tools and mechanisms available to
troubleshoot build problems and provides practical advice on how to use the tools
effectively.
Chapter 6, “Linux System Architecture,” provides the basics of a Linux operating
system stack and explains how the different components are layered. It discusses the
concepts of kernel space and user space and how application programs interact with the
Linux kernel through system calls provided by the standard C library.
 Preface xix

Chapter 7, “Building a Custom Linux Distribution,” details how to use the Yocto
Project to create your own customized Linux distribution. It starts with an overview of
the Linux distribution blueprints available with the build system and how to customize
them. It then demonstrates how to create a Linux distribution entirely from scratch
using the build system tools. After completing this chapter, you will know how to build
your own operating system images.
Chapter 8, “Software Package Recipes,” explains BitBake recipes and how to write
them to build your own software packages with the build system. The chapter provides
various real-world recipe examples that you can try.
Chapter 9, “Kernel Recipes,” examines the details of building the Linux kernel with
the OpenEmbedded build system. It explains how the build system tooling interacts
with the kernel’s own build environment to set kernel configuration and apply patches.
A discussion of how the build system handles out-of-tree kernel modules and incorpo-
rates building device trees with the build process closes this chapter.
Chapter 10, “Board Support Packages,” introduces how the build system supports
building for different hardware—that is, CPU architectures and systems. After an
explanation of the Yocto Project board support package concepts, the chapter details
how you can build a project using a board support package. We then look into the
internals of Yocto Project board support packages and explain how to create your own
with a practical example that you can put to use with actual hardware. The chapter
concludes with creating bootable media images for different hardware configurations.
Chapter 11, “Application Development,” describes Yocto Project support for
developing applications for Linux OS stacks created with the build system. It provides
hands-on instructions on how to build application development toolkits (ADT) that
include all the necessary tools for round-trip application development. Examples illus-
trate how to use an ADT for application development using the command-line tools as
well as with the Eclipse IDE. Step-by-step instructions teach how to remotely run and
debug applications on an actual hardware target.
Chapter 12, “Licensing and Compliance,” discusses requirements for compliance
with open source licenses and the tools the Yocto Project provides to facilitate meeting
them.
Chapter 13, “Advanced Topics,” introduces several tools that help you scale the
Yocto Project to teams. Toaster is a web-based graphical user interface that can be used
to create build systems that can be controlled remotely from a web browser. Build
history is a tool that provides tracking and audit capabilities. With source mirrors, you can
share source packages to avoid repeated downloads and to control source versions for
product delivery. Last but not least, Autobuilder provides an out-of-the-box continuous
build and integration framework for automating builds, quality assurance, and release
processes. Equipped with the knowledge from this chapter, you can effectively set up
team environments for the Yocto Project.
The appendices cover popular open source licenses and alphabetical references of
build system metadata layers and machines.
xx Preface

Hands-on Experience
The book is written to provide you with hands-on experience using the Yocto Project.
You will benefit the most if you follow along and try out the examples. The majority
of them you can work through simply with an x86-based workstation running a recent
Linux distribution (detailed requirements are provided in Chapter 2). For an even bet-
ter experience, grab one of the popular development boards, such as the BeagleBone,
the MinnowBoard Max, or the Wandboard. The BeagleBone makes an excellent low-
cost experimental platform. The other two boards offer more performance and let you
gain experience with multicore systems.
Analyze the code and try to understand the examples produced in the book. Follow the
steps and then veer off on your own by changing settings, applying your own configu-
ration, and more. It is the best way to learn, and I can tell you, it is a lot of fun too. It is
a great feeling to get your first own Linux distribution to work on a piece of hardware
of your choice.

Register your copy of Embedded Linux Systems with the Yocto Project at informit.com
TM

for convenient access to downloads, updates, and corrections as they become

available. To start the registration process, go to informit.com/register and log in
or create an account. Enter the product ISBN (9780133443240) and click Submit.
Once the process is complete, you will find any available bonus content under
“Registered Products.”
 Acknowledgments

W hat you are holding in your hands is my first attempt at writing a technical book. Well,
any book, for that matter. I humbly have to admit that I greatly underestimated the effort
that goes into a project like this, the hours spent experimenting with things, finding the
best way to make them work, and documenting everything in a concise and understandable
fashion. During the process, I have come to truly appreciate the work of the many authors
and technical writers whose books and manuals I have read and continue reading.
Foremost, I want to express my gratitude to my family, my loving wife, Janan, and
my three wonderful boys, Dominic, Daniel, and Jonas. Without their support and their
understanding, it would not have been possible for me to spend the many hours writing
this text.
Special thanks go to the Yocto Project team. When I approached Dave Stewart,
Project Manager for the Yocto Project at the time, and Jeffrey Osier-Mixon, the Yocto
Project’s Community Manager, they immediately welcomed the idea for the book and
offered their support. Several individuals from the team were especially helpful with
advice and answers to my questions: Beth Flanagan for Autobuilder, Belen Barros Pena
and Ed Bartosh for Toaster, and Paul Eggleton and Khem Raj who jumped on many of
the questions I posted to the Yocto Project mailing list.
Special thanks to Christopher Hallinan whose Embedded Linux Primer: A Practical Real-
World Approach (Prentice Hall, 2006) inspired me to write this book on the Yocto Project.
I especially want to thank Debra Williams Cauley, Executive Acquisitions Editor,
for her guidance and particularly her patience while this book was in the works. It took
much longer than expected, and I am the only one to blame for the missed deadlines.
I cannot thank and praise enough my dedicated review team, Chris Zahn, Jeffrey
Osier-Mixon, Robert Berger, and Bryan Smith, for their valuable contributions to the
quality of the book in the form of corrections and suggestions for improvements.
I also want to thank the production team at Prentice Hall, Julie Nahil and Anna Popick,
for their coordination and guidance through the process, and in particular Carol Lallier
for her diligence in copyediting the manuscript.
Thanks also to the Linux Foundation and Jerry Cooperstein, who gave me the
opportunity to develop the Linux Foundation’s training course on the Yocto Project.
Nothing teaches as well as teaching somebody else. Thank you to the students of the
classes that I taught. Through your critical questions and feedback, I gained a lot of
understanding for the many different problems you are facing when developing prod-
ucts with embedded Linux. One of your most asked questions was, “Is there a book on
the Yocto Project?” Finally, I can say, “Yes.”
This page intentionally left blank
 About the Author

Rudolf Streif has more than twenty years of experience in software engineering as a
developer as well as a manager leading cross-functional engineering teams with more
than one hundred members. Currently, he is an independent consultant for software
technology and system architecture specializing in open source.
He previously served as the Linux Foundation’s Director of Embedded Solutions,
coordinating the Foundation’s efforts for Linux in embedded systems. Rudolf devel-
oped the Linux Foundation’s training course on the Yocto Project, which he delivered
multiple times to companies and in a crash-course variant during Linux Foundation
events.
Rudolf has been working with Linux and open source since the early 1990s and
developing commercial products since 2000. The projects he has been involved with
include high-speed industrial image processing systems, IPTV head-end system and
customer premises equipment, and connected car and in-vehicle infotainment.
In 2014, Rudolf was listed by PC World among the 50 most interesting people in the
world of technology (http://tinyurl.com/z3tbtns).
Rudolf lives with his wife and three children in San Diego, California.
This page intentionally left blank
 7
Building a Custom Linux
Distribution
In This Chapter
7.1 Core Images—Linux Distribution Blueprints
7.2 Building Images from Scratch
7.3 Image Options
7.4 Distribution Configuration
7.5 External Layers
7.6 Hob
7.7 Summary

In the preceding chapters, we laid the foundation for using the Yocto Project tools to
build custom Linux distributions. Now it is time that we put that knowledge to work.
Chapter 2, “The Yocto Project,” outlined the prerequisites for the build system and
how to set up your build host, configure a build environment, and launch a build that
creates a system ready to run in the QEMU emulator. In this chapter, we reuse that
build environment. If you have not yet prepared your build system, we recommend that
you go back to Chapter 2 and follow the steps. Performing a build using Poky’s default
settings validates your setup. It also downloads the majority of the source code packages
and establishes a shared state cache, both of which speed up build time for the examples
presented in this chapter.
In Chapter 3, “OpenEmbedded Build System,” and Chapter 4, “BitBake Build
Engine,” we explained the OpenEmbedded build system and the BitBake syntax. This
and following chapters show examples or snippets of BitBake recipes utilizing that syntax.
While the syntax is mostly straightforward and resembles typical scripting languages,
there are some constructs that are particular to BitBake. Referring to Chapter 4, you
find syntax examples and explanations.
When experimenting with the Yocto Project, you eventually encounter build fail-
ures. They can occur for various reasons, and troubleshooting can be challenging. You
may want to refer to Chapter 5, “Troubleshooting,” for the debugging tools to help you
track down build failures.
Chapter 6, “Linux System Architecture,” outlined the building blocks of a Linux
distribution. While bootloader and the Linux kernel are indispensable for a working
146 Chapter 7 Building a Custom Linux Distribution

Linux OS stack, user space makes up its majority. In this chapter, we focus on custom-
izing Linux OS stacks with user space libraries and applications from recipes provided
by the Yocto Project and other compatible layers from the OpenEmbedded project.

7.1 Core Images—Linux Distribution Blueprints

The OpenEmbedded Core (OE Core) and other Yocto Project layers include several
example images. These images offer root filesystem configurations for typical Linux OS
stacks. They range from very basic images that just boot a device to a command-line
prompt to images that include the X Window System (X11) server and a graphical user
interface. These reference images are called the core images because the names of their
respective recipes begin with core-image. You can easily locate the recipes for the core
images with the find command from within the installation directory of your build
system (see Listing 7-1).

Listing 7-1 Core Image Recipes

user@buildhost:~/yocto/poky$ find ./meta*/recipes*/images -name "*.bb" \
-print
./meta/recipes-core/images/core-image-minimal-initramfs.bb
./meta/recipes-core/images/core-image-minimal-mtdutils.bb
./meta/recipes-core/images/build-appliance-image_8.0.bb
./meta/recipes-core/images/core-image-minimal-dev.bb
./meta/recipes-core/images/core-image-minimal.bb
./meta/recipes-core/images/core-image-base.bb
./meta/recipes-extended/images/core-image-full-cmdline.bb
./meta/recipes-extended/images/core-image-testmaster-initramfs.bb
./meta/recipes-extended/images/core-image-lsb-sdk.bb
./meta/recipes-extended/images/core-image-lsb-dev.bb
./meta/recipes-extended/images/core-image-lsb.bb
./meta/recipes-extended/images/core-image-testmaster.bb
./meta/recipes-graphics/images/core-image-x11.bb
./meta/recipes-graphics/images/core-image-directfb.bb
./meta/recipes-graphics/images/core-image-weston.bb
./meta/recipes-graphics/images/core-image-clutter.bb
./meta/recipes-qt/images/qt4e-demo-image.bb
./meta/recipes-rt/images/core-image-rt-sdk.bb
./meta/recipes-rt/images/core-image-rt.bb
./meta/recipes-sato/images/core-image-sato-dev.bb
./meta/recipes-sato/images/core-image-sato-sdk.bb
./meta/recipes-sato/images/core-image-sato.bb
./meta-skeleton/recipes-multilib/images/core-image-multilib-example.bb

You can look at the core images as Linux distribution blueprints from which you
can derive your own distribution by extending them. All core image recipes inherit
the core-image class, which itself inherits from image class. All images set the IMAGE_
INSTALL variable to specify what packages are to be installed into the root filesystem.
IMAGE_INSTALL is a list of packages and package groups. Package groups are collections
 7.1 Core Images—Linux Distribution Blueprints 147

of packages. Defining package groups alleviates the need to potentially list hundreds of
single packages in the IMAGE_INSTALL variable. We explain package groups in a coming
section of this chapter. Image recipes either explicitly set Image_INSTALL or extend its
default value provided by the core-image class, which installs the two package groups
packagegroup-core-boot and packagegroup-base-extended . The default creates a
working root filesystem that boots to the console.
Let’s have a closer look at the various core images:

n core-image-minimal: This is the most basic image allowing a device to boot to a

Linux command-line login. Login and command-line interpreter are provided by
BusyBox.
n core-image-minimal-initramfs: This image is essentially the same as core-image-
minimal but with a Linux kernel that includes a RAM-based initial root filesystem
(initramfs).
n core-image-minimal-mtdutils: Based on core-image-minimal, this image also
includes user space tools to interact with the memory technology device (MTD)
subsystem in the Linux kernel to perform operations on f lash memory devices.
n core-image-minimal-dev: Based on core-image-minimal, this image also includes
all the development packages (header files, etc.) for all the packages installed in the
root filesystem. If deployed on the target together with a native target toolchain, it
allows software development on the target. Together with a cross-toolchain, it can
be used for software development on the development host.
n core-image-rt: Based on core-image-minimal, this image target builds the
Yocto Project real-time kernel and includes a test suite and tools for real-time
applications.
n core-image-rt-sdk : In addition to core-image-rt, this image includes the system
development kit (SDK) consisting of the development packages for all packages
installed; development tools such as compilers, assemblers, and linkers; as well as
performance test tools and Linux kernel development packages. This image allows
for software development on the target.
n core-image-base: Essentially a core-image-minimal, this image also includes middle-
ware and application packages to support a variety of hardware such as WiFi,
Bluetooth, sound, and serial ports. The target device must include the necessary
hardware components, and the Linux kernel must provide the device drivers for
them.
n core-image-full-cmdline : This minimal image adds typical Linux command-line
tools—bash, acl, attr, grep, sed, tar, and many more—to the root filesystem.
n core-image-lsb : This image contains packages required for conformance with the
Linux Standard Base (LSB) specification.
n core-image-lsb-dev: This image is the same as the core-image-lsb but also
includes the development packages for all packages installed in the root filesystem.
148 Chapter 7 Building a Custom Linux Distribution

n core-image-lsb-sdk : In addition to core-image-lsb-dev, this image includes

development tools such as compilers, assemblers, and linkers as well as perfor-
mance test tools and Linux kernel development packages.
n core-image-x11: This basic graphical image includes the X11 server and an X11
terminal application.
n core-image-sato: This image provides X11 support that includes the OpenedHand
Sato user experience for mobile devices. Besides the Sato screen manager, the
image also provides several applications using the Sato theme, such as a terminal,
editor, file manager, and several games.
n core-image-sato-dev: This image is the same as core-image-sato but also includes
the development packages for all packages installed in the root filesystem.
n core-image-sato-sdk : In addition to core-image-sato-dev, this image includes
development tools such as compilers, assemblers, and linkers as well as performance
test tools and Linux kernel development packages.
n core-image-directfb : An image that uses DirectFB for graphics and input device
management, DirectFB may include graphics acceleration and a windowing
system. Because of its much smaller footprint compared to X11, DirectFB is the
preferred choice for lower-end embedded systems that need graphics support but
not the entire functionality of X11.
n core-image-clutter: This is an X11-based image that also includes the Clutter
toolkit. Clutter is based on OpenGL and provides functionality for animated
graphical user interfaces.
n core-image-weston : This image uses Weston instead of X11. Weston is a compos-
itor that uses the Wayland protocol and implementation to exchange data with its
clients. This image also includes a Wayland-capable terminal program.
n qt4e-demo-image : This image launches a demo application for the embedded Qt
toolkit after completing the boot process. Qt for embedded Linux provides a
development framework of graphical applications that directly write to the frame-
buffer instead of using the X11.
n core-image-multilib-example : This image is an example of the support of multi-
ple libraries, typically 32-bit support on an otherwise 64-bit system. The image is
based on a core image and adds the desired multilib packages to IMAGE_INSTALL.

The following three images are not reference images for embedded Linux systems.
We include them in this discussion for completeness purposes.

n core-image-testmaster, core-image-testmaster-initramfs : These images are

references for testing other images on actual hardware devices or in QEMU. They
are deployed to a separate partition to boot into and then use scripts to deploy the
image under test. This approach is useful for automated testing.
 7.1 Core Images—Linux Distribution Blueprints 149

n build-appliance-image : This recipe creates the Yocto Project Build Appliance

virtual machine images that include everything needed for the Yocto Project
build system. The images can be launched using VMware Player or VMware
Workstation.

Studying the reference image recipes is a good way to learn how these images are
built and what packages comprise them. The core images are also a good starting point
for your own Linux OS stack. You can easily extend them by adding packages and
package groups to IMAGE_INSTALL. Images can only be extended, not shrunk. To build
an image with less functionality, you have to start from a smaller core image and add
only the packages you need. There is no simple way to remove packages. The majority
of them are added through package groups, and you would need to split up the package
group if you do not want to install a package included with it. Of course, if you are
removing a package, you also have to remove any other packages that depend on it.
There are several ways you can add packages and package groups to be included with
your root filesystem. The following sections explain them and also provide information
on why you would want to use one method over another.

7.1.1 Extending a Core Image through Local Configuration

The simplest method for adding packages and package groups to images is to add
IMAGE_INSTALL to the conf/local.conf file of your build environment:

IMAGE_INSTALL_append = " <package> <package group>"

As we have seen, image recipes set the IMAGE_INSTALL variable adding packages and
package groups. To extend an image, you have to append your packages and packages
group to the variable. You may wonder why we use the explicit _append operator
instead of the += or .+ operators. Using the _append operator unconditionally appends
the specified value to the IMAGE_INSTALL variable after all recipes and configuration
files have been processed. Image recipes commonly explicitly set the IMAGE_INSTALL
variable using the = or ?= operators, which may happen after BitBake processed the
settings in conf/local.conf.
For example, adding
IMAGE_INSTALL_append = " strace sudo sqlite3"

installs the strace and sudo tools as well as SQLite in the root filesystem. When using
the _append operator, you always have to remember to add a space in front of the first
package or package group, as this operator does not automatically include a space.
Using IMAGE_INSTALL in the conf/local.conf of your build environment uncondi-
tionally affects all images you are going to build with this build environment. If you
are looking to install additional packages only to a certain image, you can use condi-
tional appending:
IMAGE_INSTALL_append_pn-<image> = " <package> <package group>"
150 Chapter 7 Building a Custom Linux Distribution

This installs the specified packages and package groups only into the root filesystem of
image. For example,

IMAGE_INSTALL_append_pn-core-image-minimal = " strace"

installs the strace tool only into the root filesystem of core-image-minimal. All other
images are unaffected.
Using IMAGE_INSTALL also affects core images, that is, images that inherit from the
core-image class, as well as images that inherit directly from the image class. For conve-
nience purposes, the core-image class defines the variable CORE_IMAGE_EXTRA_INSTALL.
All packages and package groups added to this variable are appended to IMAGE_INSTALL
by the class. Using
CORE_IMAGE_EXTRA_INSTALL = "strace sudo sqlite3"

adds these packages to all images that inherit from core-image. Images that inherit
directly from image are not affected. Using CORE_IMAGE_EXTRA_INSTALL is a safer and
easier method for core images than appending directly to IMAGE_INSTALL.

7.1.2 Testing Your Image with QEMU

You can easily test your image with the QEMU emulator. Even though you eventually
build a system for the target hardware of your product, using QEMU for testing makes
good sense for the following reasons:

n The round-trip time for launching QEMU is much quicker than deploying an
image to actual hardware.
n Frequently, hardware is not yet available when software development begins.
n Yocto Project board support packages (BSP) make it simple to switch from
QEMU to hardware and back.

In Chapter 2, when performing our first build, we used QEMU to verify the build
output. The Poky reference distribution provides the script runqemu that greatly simpli-
fies the task of launching QEMU by providing the necessary parameters. In its simplest
form, you launch the script with a single parameter
$ runqemu qemux86

which tells the script to locate the latest kernel and root filesystem image builds for the
provided QEMU machine and otherwise launch QEMU with default parameters. The
parameter values match the QEMU machine types in conf/local.conf.
When working with different root filesystem images, you probably want to select the
particular image when running QEMU. For example, you have built core-image-minimal
and core-image-base using the preceding command line, since runqemu launches what-
ever image you last built. Using the command as follows lets you choose the image:
$ runqemu qemux86 core-image-minimal
 7.1 Core Images—Linux Distribution Blueprints 151

The script automatically selects the correct kernel and uses the latest core-image-
minimal root filesystem. For even more control, you can directly specify the kernel
image and root filesystem image file:
$ runqemu <path>/bzImage-qemux86.bin <path>/core-image-minimal-qemux86.ext3

QEMU and the runqemu script are handy tools for rapid round-trip application
development, which we explore in Chapter 11, “Application Development.”

7.1.3 Verifying and Comparing Images Using the Build History

When building a product, you find yourself frequently modifying your images, adding
new packages, and removing extraneous packages to trim the footprint. A tool that
enables you to easily verify and compare image builds with each other can simplify that
otherwise tedious task.
To help maintain build output quality and enable comparison between different
builds, BitBake provides build history, which is implemented by the buildhistory
class. This class records information about the contents of all packages built and about
the images created by the build system in a Git repository where you can examine
them. Build history is disabled by default. To enable it, you need to add
INHERIT += "buildhistory"
BUILDHISTORY_COMMIT = "1"

to the conf/local.conf file of your build environment. Please note that INHERIT
(uppercase) is a variable to which you have to add the buildhistory class. It is different
from the inherit (lowercase) directive used by recipes and classes to inherit functional-
ity from classes. Every time you do a build, buildhistory creates a commit to the
Git repository with the changes.
The buildhistory Git repository is stored in a directory as defined by the BUILDHISTORY_
DIR variable. The default value of this variable is set to
BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory"

After enabling buildhistory and running a build, you see a buildhistory directory
added to the top-level directory of your build environment. The directory contains
the two subdirectories images and packages. The former contains build information
about the images you build, the latter information on the packages. We analyze the
buildhistory Git repository in Chapter 13, “Advanced Topics.” Here we just look at
the images subdirectory. Inside the images subdirectory, the images are sorted into
further subdirectories by target machine, target C library, and image name:
${TOPDIR}/buildhistory/images/<machine>/<clib>/<image>

For the build of our core-image-minimal for qemux86 using the default EGLIBC
target library, you find the image history in
${TOPDIR}/buildhistory/images/qemux86/eglibc/core-image-mininal
152 Chapter 7 Building a Custom Linux Distribution

The files in that directory give you detailed information on what makes up your
image:

n image-info.txt: Overview information about the image in form of the most

important variables, such as DISTRO, DISTRO_VERSION, and IMAGE_INSTALL
n installed-packages.txt: A list of the package files installed in the image, includ-
ing version and target information
n installed-package-names.txt: Similar to the previous file but contains only the
names of the packages without version and target information
n files-in-image.txt: A list of the root filesystem with directory names, file sizes,
file permissions, and file owner

Simply searching the file installed-package-names.txt gives you information on

whether or not a package has been installed.

7.1.4 Extending a Core Image with a Recipe

Adding packages and package groups to CORE_IMAGE_EXTRA_INSTALL and IMAGE_INSTALL
and in conf/local.conf may be straightforward and quick, but doing so makes a project
hard to maintain and complicates reuse. A better way is to extend a predefined image
through a recipe. Listing 7-2 shows a simple recipe that extends core-image-base.

Listing 7-2 Recipe Extending core-image-base

DESCRIPTION = "A console image with hardware support for our IoT device"

require recipes-core/images/core-image-base.bb

IMAGE_INSTALL += "sqlite3 mtd-utils coreutils"

IMAGE_FEATURES = "dev-pkgs"

The example includes the recipe for core-image-base and adds packages to IMAGE_
INSTALL and an image feature to IMAGE_FEATURES. We explain what image features are
and how to utilize them to customize image in the next section.
A couple of things to consider when extending images with recipes:

n Unlike classes, you need to provide the path relative to the layer for BitBake to
find the recipe file to include, and you need to add the .bb file extension.
n While you can use either include or require to include the recipe you are
extending, we recommend the use of require, since it causes BitBake to exit with
an explicit error message if it cannot locate the included recipe file.
n Remember to use the += operator to add to IMAGE_INSTALL. Do not use = or :=
because they overwrite the content of the variable defined by the included recipe.
 7.1 Core Images—Linux Distribution Blueprints 153

For BitBake to actually be able to use this recipe as a build target, you have to add it
to a layer that is included into your build environment via the conf/bblayers.conf file.
It is not recommended that you add your recipes to the core Yocto Project layers, such
as meta, meta-yocto, and others, because it makes it hard to maintain your build envi-
ronment if you upgrade to a newer version of the Yocto Project. Instead, you should
create a layer in which to put your recipes.
Creating a layer for one recipe may seem like a lot of overhead, but hardly any proj-
ect ever stays small. What may start with one recipe eventually grows into a sophisti-
cated project with recipes for images, packages, and package groups. In Chapter 3, we
introduced the yocto-layer, which makes creating layers a breeze.

7.1.5 Image Features

Image features provide certain functionality that you can add to your target images.
This can be additional packages to be installed, modification of configuration files, and
more.
For example, the dev-pkgs image feature adds the development packages, which
typically include headers and other files required for development, for all packages
installed in the root filesystem. Using this image feature is a convenient way to enable
a target image for development without having to explicitly specify the development
packages in the IMAGE_INSTALL variable. For deployment, you can then simply remove
the dev-pkgs image feature.
Installation of image features is controlled by the two variables IMAGE_FEATURES and
EXTRA_IMAGE_FEATURES. The former is used in image recipes to define the required set of
image features. The latter is typically used in the conf/local.conf file to define additional
image features that, of course, then affect all images built with that build environment.
The content of EXTRA_IMAGE_FEATURES is simply added to IMAGE_FEATURES by the meta/
conf/bitbake.conf configuration file.
Image features are defined by different classes. The list of currently available image
features contains the following:

n Defined by image.bbclass:
n debug-tweaks : Prepares an image for development purposes. In particular, it sets

empty root passwords for console and Secure Shell (SSH) login.
n package-management : Installs the package management system according to the

package management class defined by PACKAGE_CLASSES for the root filesystem.

n read-only-rootfs : Creates a read-only root filesystem. This image feature

works only if System V Init (SysVinit) system is used rather than sytemd.
n splash : Enables showing a splash screen instead of the boot messages during

boot. By default, the splash screen is provided by the psplash package, which
can be customized. You can also define an alternative splash screen package by
setting the SPLASH variable to a different package name.
154 Chapter 7 Building a Custom Linux Distribution

n Defined by populate_sdk_base.bbclass:
n dbg-pkgs : Installs the debug packages containing symbols for all packages

installed in the root filesystem.

n dev-pgks : Installs the development packages containing headers and other

development files for all packages installed in the root filesystem.

n doc-pkgs : Installs the documentation packages for all packages installed in the

root filesystem.
n staticdev-pkgs : Installs the static development packages such as static library

files ending in *.a for all packages installed in the root filesystem.
n ptest-pkgs : Installs the package test (ptest) packages for all packages installed in

the root filesystem.

n Defined by core-image.bbclass:
n eclipse-debug : Installs remote debugging tools for integration with the Eclipse

IDE, namely the GDB debugging server, the Eclipse Target Communication
Framework (TCF) agent, and the OpenSSH SFTP server.
n hwcodecs : Installs the hardware decoders and encoders for audio, images, and

video if the hardware platform provides them.

n nfs-server : Installs Network File System (NFS) server, utilities, and client.

n qt4-pkgs : Installs the Qt4 framework and demo applications.

n ssh-server-dropbear : Installs the lightweight SSH server Dropbear, which

is popular for embedded systems. This image feature is incompatible with

ssh-server-openssh. Either one of the two, but not both, can be used.
n ssh-server-openssh : Installs the OpenSSH server. This image feature is incom-

patible with ssh-server-dropbear. Either one of the two, but not both, can be
used.
n tools-debug : Installs debugging tools, namely the GDB debugger, the GDB

remote debugging server, the system call tracing tool strace, and the memory
tracing tool mtrace for the GLIBC library if it is the target library.
n tools-profile : Installs common profiling tools such as oprofile , powertop,

latencytop, lttng-ust, and valgrind.

n tools-sdk : Installs software development tools such as the GCC compiler,

Make, autoconf, automake, libtool, and many more.

n tools-testapps : Installs test applications such as tests for X11 and middleware

packages like the telephony manager oFono and the connection manager
ConnMan.
n x11 : Installs the X11 server.

n x11-base : Installs the X11 server with windowing system.

n x11-sato : Installs the OpenedHand Sato user experience for mobile devices.
 7.1 Core Images—Linux Distribution Blueprints 155

It matters what classes define the image features when creating your own image
recipes and choosing the image class to inherit. The class image inherits populate_sdk_
base and thus all image features defined by those two classes are available to images
that inherit image. Image features defined by core-image are available only to images
that inherit that class, which in turn inherits image and with it also populate_sdk_base.

7.1.6 Package Groups

We have touched on package groups a couple of times during this discussion of creat-
ing custom Linux distribution images. Package groups are bundles of packages that are
referenced by a name. Using that name in the IMAGE_INSTALL variable installs all the
packages defined by the package group into the root filesystem of your target image.
The Yocto Project and OE Core layers define a common set of package groups that
you can readily use for your images. You can also create your own package groups
containing packages from any layer, including your own. We first describe the package
groups defined by the Yocto Project and OE Core layers and then look into the details
on how package groups are defined.

Predefined Package Groups

Package groups are defined by recipes. Conventionally, the recipe files begin with
packagegroup- and are placed inside packagegroup subdirectories of the respective
recipe categories. For instance, you can find package group recipes related to the Qt
development framework in the subdirectory meta/recipes-qt/packagegroups.
Using
find . -name "packagegroup-*" -print

from the installation directory of the Yocto Project build system gives you a list of all
the package group recipes for the predefined package groups of the Yocto Project build
system.
Following are the most common predefined package groups:

n packagegroup-core-ssh-dropbear: Provides packages for the Dropbear SSH server

popular for embedded systems because of its smaller footprint compared to the
OpenSSH server. This package group conf licts with packagegroup-core-ssh-
openssh. You can include only one of the two in your image. The ssh-server-
dropbear image feature installs this package group.
n packagegroup-core-ssh-openssh : Provides packages for the standard OpenSSH
server. This package group conf licts with packagegroup-core-ssh-dropbear. You
can include only one of the two in your image. The ssh-server-openssh image
feature installs this package group.
n packagegroup-core-buildessential: Provides the essential development tools,
namely the GNU Autotools utilities autoconf, automake, and libtool; the GNU
binary tool set binutils which includes the linker ld, assembler as, and other tools;
156 Chapter 7 Building a Custom Linux Distribution

the compiler collection cpp; gcc; g++; the GNU internationalization and localiza-
tion tool gettext; make; libstc++ with development packages; and pkgconfig.
n packagegroup-core-tools-debug : Provides the essential debugging tools, namely
the GDB debugger, the GDB remote debugging server, the system call tracing
tool strace, and, for the GLIBC target library, the memory tracing tool mtrace.
n packagegroup-core-sdk : This package group combines the packagegroup-core-
buildessential package group with additional tools for development such as
GNU Core Utilities coreutils with shell, file, and text manipulation utilities;
dynamic linker ldd; and others. Together with packagegroup-core-standalone-
sdk-target, this package group forms the tools-sdk image feature.
n packagegroup-core-standalone-sdk-target: Provides the GCC and standard
C++ libraries. Together with packagegroup-core-sdk, this package group forms
the tools-sdk image feature.
n packagegroup-core-eclipse-debug : Provides the GDB debugging server,
the Eclipse TCF agent, and the OpenSSH SFTP server for integration with
the Eclipse IDE for remote deployment and debugging. The image feature
eclipse-debug installs this package group.
n packagegroup-core-tools-testapps : Provides test applications such as tests for
X11 and middleware packages like the telephony manager oFono and the connec-
tion manager ConnMan. The tools-testapps image feature installs this package
group.
n packagegroup-self-hosted : Provides all necessary packages for a self-hosted build
system. The build-appliance image target uses this package group.
n packagegroup-core-boot: Provides the minimum set of packages necessary to
create a bootable image with console. All core-image targets install this package
group. The core-image-minimal installs just this package group and the postinstal-
lation scripts.
n packagegroup-core-nfs : Provides NFS server, utilities, and client. The nfs-server
image feature installs this package group.
n packagegroup-base : This recipe provides multiple package groups that depend
on each other as well as on machine and distribution configuration. The purpose
of these package groups is to add hardware, networking protocol, USB, filesystem,
and other support to the images dependent on the machine and distribution
configuration. The two top-level package groups are packagegroup-base and
packagegroup-base-extended . The former adds hardware support for Blue-
tooth, WiFi, 3G, and NFC only if both the machine configuration and the
distribution configuration require them. The latter also adds configuration for
those technologies if the distribution configuration requires them. However, the
machine configuration does not support them directly but provides support for PCI,
PCMCIA, or USB host. This package group allows you to create an image with
support for devices that can physically be added to the target device; for exam-
ple, via USB hotplug. Most commonly, images providing hardware support use
 7.1 Core Images—Linux Distribution Blueprints 157

packagegroup-base-extended rather than packagegroup-base for dynamic hard-

ware support; for example, core-image-base.
n packagegroup-cross-canadian : Provides SDK packages for creating a toolchain
using the Canadian Cross technique, which is building a toolchain on system A
that executes on system B to create binaries for system C. A use case for this pack-
age group is to build a toolchain with the Yocto Project on your build host that
runs on your image target but produces output for a third system with a different
architecture than your image target.
n packagegroup-core-tools-profile: Provides common profiling tools such as oPro-
file, PowerTOP, LatencyTOP, LTTng-UST, and Valgrind. The tools-profile
image feature uses this package group.
n packagegroup-core-device-devel: Provides distcc support for an image. Distcc
allows distribution of compilation across several machines on a network. The
distcc must be installed, configured, and running on your build host. On the target
you must define the cross-compiler variable to use distcc instead of the local com-
piler (e.g., export CC="distcc").
n packagegroup-qt-toolchain-target: Provides the package to build applications for
the X11-based version of the Qt development toolkit on the target system.
n packagegroup-qte-toolchain-target: Provides the package to build applications
for the embedded version of the Qt development toolkit on the target system.
n packagegroup-core-qt: Provides all necessary packages for a target system using
the X11-based version of the Qt development toolkit.
n packagegroup-core-qt4e : Provides all necessary packages for a target system using
the embedded Qt toolkit. The qt4e-demo-image installs this package group.
n packagegroup-core-x11-xserver: Provides the X.Org X11 server only.
n packagegroup-core-x11: Provides packagegroup-core-x11-xserver plus basic utili-
ties such as xhost, xauth, xset, xrandr, and initialization on startup. The x11 image
feature installs this package group.
n packagegroup-core-x11-base : Provides packagegroup-core-x11 plus middleware
and application clients for a working X11 environment that includes the Matchbox
Window Manager, Matchbox Terminal, and a fonts package. The x11-base image
feature installs this package group.
n packagegroup-core-x11-sato : Provides the OpenedHand Sato user experience
for mobile devices, which includes the Matchbox Window Manager, Matchbox
Desktop, and a variety of applications. The x11-sato image feature installs this
package group. To utilize this package group for your target image, you also have
to install packagegroup-core-x11-base.
n packagegroup-core-clutter-core : Provides packages for the Clutter graphical
toolkit. To use the toolkit for your target image, you also have to install
packagegroup-core-x11-base.
158 Chapter 7 Building a Custom Linux Distribution

n packagegroup-core-directfb : Provides packages for the DirectFB support with-

out X11. Among others, the package group includes the directfb package and
the directfb-example package, and it adds touchscreen support if provided by the
machine configuration.
n packagegroup-core-lsb : Provides all packages required for LSB support.
n packagegroup-core-full-cmdline : Provides packages for a more traditional Linux
system by installing the full command-line utilities rather than the more compact
BusyBox variant.

When explaining the different package groups, we used the terms provide and install
somewhat liberally, since the package group recipes actually do not provide or install
any packages. They only create dependencies that cause the build system to process the
respective package recipes, as we see in the next section.
Several of the package groups are used by image features, which raises the question
whether to use an image feature or to use the package group the image feature uses.

Package Group Recipes

Package groups are defined by recipes that inherit the packagegroup class. Package
group recipes are different from typical package recipes, as they do not build anything
or create any output. Package group recipes only create dependencies that trigger the
build system to process the recipes of the packages the package groups reference.
Listing 7-3 shows a typical package group recipe.

Listing 7-3 Package Group Recipe

SUMMARY = "Custom package group for our IoT devices"
DESCRIPTION = "This package group adds standard functionality required by \
our IoT devices."

LICENSE = "MIT"

inherit packagegroup
PACKAGES = "\
packagegroup-databases \
packagegroup-python \
packagegroup-servers"

RDEPENDS_packagegroup-databases = "\
db \
sqlite3"

RDEPENDS_packagegroup-python = "\
python \
python-sqlite3"

RDEPENDS_packagegroup-servers = "\
openssh \
openssh-sftp-server"
 7.1 Core Images—Linux Distribution Blueprints 159

RRECOMMENDS_packagegroup-python = "\
ncurses \
readline \
zip"

Names of package group recipes, although not enforced or required by the build sys-
tem, should adhere to the convention packagegroup-<name>.bb. You also would want
to place them in the subdirectory packagegroup of the recipe category the package
groups are integrating. If package groups span recipes and possibly package groups from
multiple categories, it is good practice to place them into the recipes-core category.
The basic structure of package group recipes is rather simple. As should any recipe
(and we go into the details of writing recipes in Chapter 8, “Software Package Reci-
pes”), a package group recipe should provide a SUMMARY of what the recipe does. The
DESCRIPTION, which can provide a longer, more detailed explanation, is optional, but
it is good practice to add it. Any recipe also needs to provide a LICENSE for the recipe
itself. All package group recipes must inherit the packagegroup class.
The names of the actual package groups are defined by the PACKAGES variable.
This variable contains a space-delimited list of the package group names. In the
case of Listing 7-3, these are packagegroup-databases, packagegroup-python, and
packagegroup-servers. By convention, package group names begin with packagegroup-.
Although the build system does not require it, it is good practice if you adhere to it for
your own package group names.
For each package group, the recipe must define its dependencies in a conditional
RDEPENDS_<package-group-name> variable. These variables list the required dependen-
cies, which can be packages or package groups.
The RRECOMMENDS_<package-group-name> definitions are optional. As we saw
in Chapter 3, recommendations are weak dependencies that cause a package to be
included only if it already has been built.
You can reference package groups from other variables, such as IMAGE_INSTALL,
which of course causes these package groups to be installed in a target image. You can
also use them to create dependencies for other package groups for a hierarchy. You must
avoid circular dependencies of package groups. That may sound simple and straightfor-
ward but can easily happen by mistake in rather complex environments. BitBake, how-
ever, aborts with an error message in the case of a circular package group dependency.
Package group recipes can also be directly used as BitBake build targets. For exam-
ple, if the name of the package group recipe is packagegroup-core-iot.bb, you can
build all the packages of the package groups defined by the recipe using
$ bitbake packagegroup-core-iot

Doing so allows testing the package groups before referencing them by image builds,
which simplifies debugging.
160 Chapter 7 Building a Custom Linux Distribution

7.2 Building Images from Scratch

Section 7.1 detailed the Yocto Project core images and how to extend them through
setting IMAGE_INSTALL, CORE_IMAGE_EXTRA_INSTALL , IMAGE_FEATURES, and EXTRA_
IMAGE_FEATURES in conf/local.conf and in recipes extending predefined image recipes.
Eventually, you may want to create your custom Linux distribution image from scratch
without relying on one of the reference images.
A custom image recipe must inherit either the image or the core-image class. The
latter is essentially an extension of the former and defines additional image features,
as described earlier in Section 7.1.5. Which one to choose for custom image recipes
depends on your requirements. However, inheriting core-image generally is sound
advice, since the image features are made available but only installed if explicitly
requested.
Listing 7-4 shows the simplest image recipe that creates a bootable console image.

Listing 7-4 Basic Image Recipe

SUMMARY = "Custom image recipe that does not get any simpler"
DESCRIPTION = "Well yes, you could remove SUMMARY, DESCRIPTION, LICENSE."

LICENSE = "MIT"

inherit core-image

The recipe creates an image with the core packages to boot and hardware sup-
port for the target device because the core-image class adds the two package groups
packagegroup-core-boot and packagegroup-base-extended to IMAGE_INSTALL by
default. Also added to IMAGE_INSTALL by the class is the variable CORE_IMAGE_EXTRA_
INSTALL , which allows for simple image modification through conf/local.conf, as
described earlier.
The basic image with package-group-core-boot and package-base-extended pro-
vides a good starting point that easily can be extended by adding to IMAGE_INSTALL and
IMAGE_FEATURES, as shown in Listing 7-5.

Listing 7-5 Adding to the Basic Image

SUMMARY = "Custom image recipe adding packages and features"
DESCRIPTION = "Append to IMAGE_INSTALL and IMAGE_FEATURES for \
further customization. "

LICENSE = "MIT"

# We are using the append operator (+=) below to preserve the default
# values set by the core-image class we are inheriting.
IMAGE_INSTALL += "mtd-utils"
IMAGE_FEATURES += "splash"

inherit core-image
 7.3 Image Options 161

Within image recipes, you append directly to IMAGE_INSTALL and IMAGE_FEATURES

using the += operator. Do not use EXTRA_IMAGE_FEATURES or CORE_IMAGE_EXTRA_INSTALL
in your image recipe. These variables are reserved for use in conf/local.conf where
they are directly assigned and overwrite any values assigned by the image recipe.
An image recipe that does not rely on the default values for IMAGE_INSTALL and
IMAGE_FEATURES is equally simple, as Listing 7-6 shows.

Listing 7-6 Core Image from Scratch

SUMMARY = "Custom image recipe from scratch"
DESCRIPTION = "Directly assign IMAGE_INSTALL and IMAGE_FEATURES for \
for direct control over image contents."

LICENSE = "MIT"

# We are using the assignment operator (=) below to purposely overwrite

# the default from the core-image class.
IMAGE_INSTALL = "packagegroup-core-boot packagegroup-base-extended \
${CORE_IMAGE_EXTRA_INSTALL} mtd-utils"
IMAGE_FEATURES = "${EXTRA_IMAGE_FEATURES} splash"

inherit core-image

At first glance, the image recipes of Listings 7-5 and 7-6 look rather similar. In fact,
the two recipes produce exactly the same image. The differences are subtle but signifi-
cant. Listing 7-5 uses the append operator += for IMAGE_INSTALL and IMAGE_FEATURES to
take advantage of the default values provided by the core-image class. Listing 7-6 uses
the assignment operator = to purposely overwrite the default values.
Overwriting the default values gives you the most control over the content of your
image, but you also have to take care of the basics yourself. For any image, you would
most likely always want to include packagegroup-core-boot to get a bootable image.
Whether you want the hardware support that packagegroup-base-extended provides
depends on your requirements. Also at your disposal is CORE_IMAGE_EXTRA_INSTALL : if
you do not explicitly add it to IMAGE_FEATURES, you will not be able to use this variable
in conf/local.conf for local customization of your target image, but it may make sense
to do so for a controlled build environment for production.
The same holds true for IMAGE_FEATURES and EXTRA_IMAGE_FEATURES. If you use the
assignment operator with IMAGE_FEATURES and purposely do not add EXTRA_IMAGE_
FEATURES, it is not included, which means that the debug-tweaks image feature is not
applied, and you need to provide passwords for shell and SSH logins. Again, this makes
sense for production build environments where you do not want local configuration
settings to override the settings of your production images.

7.3 Image Options

The following sections discuss a list of options that affect how the Yocto Project build
system creates your root filesystem images.
162 Chapter 7 Building a Custom Linux Distribution

7.3.1 Languages and Locales

Additional languages for different territories can easily be added to a root filesystem or
your image by adding the IMAGE_LINGUAS variable to an image recipe. Using
IMAGE_LINGUAS = "en-gb pt-br"

adds the specific language packages for British English and Brazilian Portuguese to the
image. However, not all software packages provide locales separated by language and
territory. Some of them provide the locale files only by language. In this case, the build
system defaults to installing the correct language local files regardless of the territory.
The minimum default for all packages is en-us and is always installed. In addition,
the image class defines
IMAGE_LINGUAS ?= "de-de fr-fr en-gb"

Any additional locale packages, of course, occupy additional space in your root
filesystem image. Therefore, if your device does not require any additional language
support, it is good practice to set
IMAGE_LINGUAS = ""

in image recipes.
The build system ignores the languages for packages that do not provide them.

7.3.2 Package Management

The build system can package software packages using the four different packaging for-
mats dpkg (Debian Package Management), opkg (Open Package Management), RPM
(Red Hat Package Manager), and tar. Only the first three can be used to create root
filesystems. Tar does not provide the necessary metadata package information and data-
base to log what packages in what versions have been installed, which packages conf lict
with each other, and so on.
The variable PACKAGE_CLASSES in conf/local.conf of your build environment con-
trols what package management systems are used for your builds:
PACKAGE_CLASSES = "package_rpm package_ipk package_tar"

You can declare more than one packaging class, but you have to provide at least one.
The build system creates packages for all classes specified; however, only the first pack-
aging class in the list is used to create the root filesystem of your distribution images.
The first packaging class in the list must not be tar.
The build system stores the package feeds organized by the package management
system in separate directories in tmp/deploy/<pms>, where <pms> is the name of the
respective package management system. Inside those directories, the packages are fur-
ther subdivided into common, architecture, and machine-dependent packages.
What package management system should you choose for your project? That
depends on the requirements of your project. Here are some considerations you may
want to take into account:
 7.3 Image Options 163

n Opkg creates and utilizes less package metadata than dpkg and RPM. That makes
building faster, and the packages are smaller.
n Dpkg and RPM offer better dependency handling and version management than
opkg because of the enhanced package metadata.
n The RPM package manager is written in Python and requires Python to be
installed on the target to install packages during runtime of the system.

By default, the build system does not install the package manager on your target
system. If you are looking to install packages during runtime of your embedded system,
you have to add the package manager using its image feature:
IMAGE_FEATURES += "package_management"

The build system automatically installs the correct package manager depending on
the first entry of PACKAGE_CLASSES.
The package management system for your root filesystem is ultimately controlled
by the variable IMAGE_PKGTYPE. This variable is set automatically by the order of the
packaging classes defined by PACKAGE_CLASSES. The first packaging class in the list sets
the variable. We recommend that you do not set this variable directly.

7.3.3 Image Size

The final size of the root filesystem is dependent on multiple factors and is computed
by the build system using the function _get_rootfs_size() in the Python module
meta/lib/oe/image.py. The computation takes into account the actual space required
by the root filesystem and the following variable settings. It also ensures that the final
root filesystem image size is always sufficient to hold the entire image. Hence, even if
you set IMAGE_ROOTFS_SIZE to a specific value, the final image may be larger than that
value, but it is never smaller.

n IMAGE_ROOTFS_SIZE : Defines the size in kilobytes of the created root filesystem

image. The build system uses this value as a request or recommendation. The final
root filesystem image size may be larger depending on the actual space required.
The default value is 65536.
n IMAGE_ROOTFS_ALIGNMENT : Defines the alignment of the root filesystem image
in kilobytes. If the final size of the root filesystem image is not a multiple of this
value, it is rounded up to the nearest multiple of it. The default value is 1.
n IMAGE_ROOTFS_EXTRA_SPACE : Adds extra free space to the root filesystem image.
The variable specifies the value in kilobytes. For example, to add an additional
4 GB of space, set the variable to IMAGE_ROOTFS_EXTRA_SPACE = "4194304". The
default value is 0.
n IMAGE_OVERHEAD_FACTOR : This variable specifies a multiplicator for the root
filesystem image. The factor is applied after the actual space required by the root
filesystem has been determined. The default value is 1.3.
164 Chapter 7 Building a Custom Linux Distribution

After the build system has created the root filesystem in the staging area, a directory
specified by the variable IMAGE_ROOTFS, it calculates its actual size in kilobytes using
du -ks ${IMAGE_ROOTFS}. The function _get_rootfs_size() computes the final root
filesystem image size, as shown by Listing 7-7 in pseudocode.

Listing 7-7 Root Filesystem Image Size Computation in Pseudocode

_get_rootfs_size():
ROOTFS_SIZE =`du -ks ${IMAGE_ROOTFS}`
BASE_SIZE = ROOTFS_SIZE * IMAGE_OVERHEAD_FACTOR

if (BASE_SIZE < IMAGE_ROOTFS_SIZE):

IMG_SIZE = IMAGE_ROOTFS_SIZE + IMAGE_ROOTFS_EXTRA_SPACE
else:
IMG_SIZE = BASE_SIZE + IMAGE_ROOTFS_EXTRA_SPACE

IMG_SIZE = IMG_SIZE + IMAGE_ROOTFS_ALIGNMENT – 1

IMG_SIZE = IMG_SIZE % IMAGE_ROOTFS_ALIGNMENT

return IMG_SIZE

Most commonly, your image recipes set IMAGE_ROOTFS_SIZE and IMAGE_ROOTFS_

EXTRA_SPACE to adjust the final root filesystem image size. If you are concerned with the
footprint of your root filesystem, then you may also want to reduce IMAGE_OVERHEAD_
FACTOR or set it to 1 to shrink your image.

7.3.4 Root Filesystem Types

Eventually, you use the root filesystem image to create a bootable medium for your tar-
get or to launch the QEMU emulator. For that purpose, the build system provides the
image_types class that can create a root filesystem for various filesystem types.
Your image recipes do not use the image_types class directly but rather set the vari-
able IMAGE_FSTYPES to one or more of the filesystem types provided by the class. Using
IMAGE_FSTYPES = "ext3 tar.bz2"

creates two root filesystem images, one using the ext3 filesystem and one that is a tar
archive compressed using the bzip2 algorithm.
The image_types class defines the variable IMAGE_TYPES, which contains a list of
all image types you can specify in IMAGE_FSTYPES. The list shows the filesystem types
ordered by core type. Commonly, some of the core types are also used in compressed for-
mats to preserve space. If a compression algorithm is used for the filesystem, the name of
the core type is appended with the compression type: <core name>.<compression type>.

n tar, tar.gz, tar.bz2, tar.xz, tar.lz3: Create uncompressed and compressed root
filesystem images in the form of tar archives.
n ext2, ext2.gz, ext2.bz2, ext2.lzma : Root filesystem images using the ext2 filesys-
tem without or with compression.
 7.3 Image Options 165

n ext3, ext3.gz : Root filesystem images using the ext3 filesystem without or with
compression.
n btrfs: Root filesystem image with B-tree filesystem.
n jffs2, jffs2.sum : Uncompressed or compressed root filesystems based on the sec-
ond generation of the Journaling Flash File System ( JFFS2). Since JFFS2 directly
supports NAND f lash devices, it is a popular choice for embedded systems. It also
provides journaling and wear-leveling.
n cramfs : Root filesystem image using the compressed ROM filesystem (cramfs).
The Linux kernel can mount this filesystem without prior decompression. The
compression uses the zlib algorithm that compresses files one page at a time to
allow random access. This filesystem is read-only to simplify its design, as random
write access with compression is difficult to implement.
n iso : Root filesystem image type using the ISO 9660 standard for bootable
CD-ROM. This filesystem type is not a standalone format. It uses ext3 as the
underlying filesystem type.
n hddimg : Root filesystem image for bootable hard drives. It uses ext3 as the actual
filesystem type.
n squashfs, squashfs-xz : Compressed read-only root filesystem type specifically for
Linux, similar to cramfs but with better compression and support for larger files
and filesystems. SquashFS also has a variable block size from 0.5 kB to 64 kB over
the fixed 4 kB block size of cramfs, which allows for larger file and filesystem sizes.
SquashFS uses gzip compression, while squashfs-xz uses Lempel–Ziv–Markov
(LZMA) compression for even smaller images.
n ubi, ubifs: Root filesystem images using the unsorted block image (UBI) format
for raw f lash devices. UBI File System (UBIFS) is essentially a successor to JFFS2.
The main differences between the two is that UBIFS supports write caching.
Using ubifs in IMAGE_FSTYPES just creates the ubifs root filesystem image. Using
ubi creates the ubifs root filesystem image and also runs the ubinize utility to
create an image that can be written directly to a f lash device.
n cpio, cpio.gz, cpio.xz, cpio.lzma : Root filesystem images using uncompressed or
compressed copy in and out (CPIO) streams.
n vmdk : Root filesystem image using the VMware virtual machine disk format. It
uses ext3 as the underlying filesystem format.
n elf: Bootable root filesystem image created with the mkelf Image utility from the
Coreboot project (www.coreboot.org).

Once again, which image types to use depends entirely on the requirements of
your project, particularly on your target hardware. Boot device, bootloader, memory
constraints, and other factors determine what root filesystem types are appropriate for
your project. Our recommendation is to specify the root filesystem types ext3 and
tar, or better, one of the compressed formats such as tar.bz2, in the image recipe. The
166 Chapter 7 Building a Custom Linux Distribution

ext3 format allows you to easily boot your root filesystem with the QEMU emulator
for testing. The tar filesystem can easily be extracted onto partitioned and formatted
media. The machine configuration files for your target hardware can then add addi-
tional root filesystem types appropriate for it.

7.3.5 Users, Groups, and Passwords

The class extrausers provides a comfortable mechanism for adding users and groups to
an image as well as setting passwords for user accounts (see Listing 7-8).

Listing 7-8 Modifying Users, Groups, and Passwords

SUMMARY = "Custom image recipe from scratch"
DESCRIPTION = "Directly assign IMAGE_INSTALL and IMAGE_FEATURES for \
for direct control over image contents."

LICENSE = "MIT"

# We are using the assignment operator (=) below to purposely overwrite

# the default from the core-image class.
IMAGE_INSTALL = "packagegroup-core-boot packagegroup-base-extended \
${CORE_IMAGE_EXTRA_INSTALL}"

inherit core-image
inherit extrausers

# set image root password

ROOT_PASSWORD = "secret"
DEV_PASSWORD = "hackme"

EXTRA_USERS_PARAMS = "\
groupadd developers; \
useradd -p `openssl passwd ${DEV_PASSWORD}` developer; \
useradd -g developers developer; \
usermod -p `openssl passwd ${ROOT_PASSWORD}` root; \
"

The listing adds a group named developers and a user account named developer
and adds the user account to the group. It also changes the password for the root
account. Commands for adding and modifying groups, users, and passwords are added
to the variable EXTRA_USERS_PARMS, which is interpreted by the class. The commands
understood by the class are

n useradd : Add user account

n usermod : Modify user account
n userdel: Remove user account
n groupadd : Add user group
 7.3 Image Options 167

n groupmod : Modify user group

n groupdel: Remove user group

The class executes the respective Linux utilities with the corresponding names.
Hence, the options are exactly the same and can easily be found in the Linux man
pages. Note that the individual commands must be separated with a semicolon.
Using the option -p with the commands useradd and usermod sets the password of
the user account. The password must be provided as the password hash. You can either
calculate the password hash manually and add it to the recipe or, as shown in the exam-
ple, have the recipe calculate it.
A word about the root user account: the build system sets up the root user for an
image with an empty password if debug-tweaks is included with IMAGE_FEATURES.
Removing debug-tweaks replaces the empty root password with *, which disables the
account, so logging in as root from the console is no longer possible. For production
use, we strongly recommend removing debug-tweaks from the build. If your embedded
system requires console login capability, you can either set the root password as shown
previously or add the sudo recipe and set up user accounts as sudoers.
For example, if you want to give the developer user account sudoer privileges, simply
add sudo to IMAGE_INSTALL and usermod -a -G sudo developer to EXTRA_USERS_PARAMS.

7.3.6 Tweaking the Root Filesystem

For further customization of the root filesystem after it has been created by the build
system and before the actual root filesystem images are created, ROOTFS_POSTPROCESS_
COMMAND is available (see Listing 7-9). The variable holds a list of shell functions sepa-
rated by semicolons.

Listing 7-9 ROOTFS_POSTPROCESS_COMMAND

SUMMARY = "Custom image recipe from scratch"
DESCRIPTION = "Directly assign IMAGE_INSTALL and IMAGE_FEATURES for \
for direct control over image contents."

LICENSE = "MIT"

# We are using the assignment operator (=) below to purposely overwrite

# the default from the core-image class.
IMAGE_INSTALL = "packagegroup-core-boot packagegroup-base-extended \
${CORE_IMAGE_EXTRA_INSTALL}"

inherit core-image

# Additional root filesystem processing

modify_shells() {
printf "# /etc/shells: valid login shells\n/bin/sh\n/bin/bash\n" \
> ${IMAGE_ROOTFS}/etc/shells
}
ROOTFS_POSTPROCESS_COMMAND += "modify_shells;"
168 Chapter 7 Building a Custom Linux Distribution

The example adds the bash shell to /etc/shells. Be sure to always use the += operator
to add to ROOTFS_POSTPROCESS_COMMAND, as the build system adds its own postprocessing
commands to it.

Sudo Configuration
If you followed the example on giving a user sudoer privileges in the previous paragraph,
you probably noticed that it does not work unless you uncomment the line %sudo
ALL=(ALL) ALL in /etc/sudoers. A simple shell function added to ROOTFS_POSTPROCESS_
COMMAND takes care of that when the root filesystem image is created (see Listing 7-10).

Listing 7-10 Sudo Configuration

modify_sudoers() {
sed 's/# %sudo/%sudo/' < ${IMAGE_ROOTFS}/etc/sudoers > \
${IMAGE_ROOTFS}/etc/sudoers.tmp
mv ${IMAGE_ROOTFS}/etc/sudoers.tmp ${IMAGE_ROOTFS}/etc/sudoers
}
ROOTFS_POSTPROCESS_COMMAND += "modify_sudoers;"

The script simply uncomments the line using sed.

SSH Server Configuration

All core images automatically include an SSH server for remote shell access to the system.
By default, the server is configured to allow login with user name and password. Using
public key infrastructure (PKI) provides an additional level of security but requires con-
figuration of the root server and installation of keys into the root filesystem. A ROOTFS_
POSTPROCESS_COMMAND can also easily be used to accomplish that task (see Listing 7-11).

Listing 7-11 SSH Server Configuration

configure_sshd() {
# disallow password authentication
echo "PasswordAuthentication no" >> ${IMAGE_ROOTFS}/etc/ssh/sshd_config
# create keys in tmp/deploy/keys
mkdir -p ${DEPLOY_DIR}/keys
if [ ! -f ${DEPLOY_DIR}/keys/${IMAGE_BASENAME}-sshroot ]; then
ssh-keygen -t rsa -N '' \
-f ${DEPLOY_DIR}/keys/${IMAGE_BASENAME}-sshroot
fi
# add public key to authorized_keys for root
mkdir -p ${IMAGE_ROOTFS}/home/root/.ssh
cat ${DEPLOY_DIR}/keys/${IMAGE_BASENAME}-sshroot.pub \
>> ${IMAGE_ROOTFS}/home/root/.ssh/authorized_keys
}
ROOTFS_POSTPROCESS_COMMAND += "configure_sshd;"

The script first disables authentication with user name and password for SSH. It then
creates a key pair in tmp/deploy/keys inside the build environment using the name of
 7.4 Distribution Configuration 169

the root filesystem image, essentially the name of the image recipe. If a previous build
has already created a set of keys, they are preserved. Finally, the script adds the public
key to the authorized_keys file in /home/root/.ssh, which is typical for SSH configu-
ration. Login keys for other users can be created in a similar way.
This method works well if you do not require different keys for each device that you
build, as every copy of the root filesystem of course contains the same keys. If you need
different keys or, in general, individual configuration for your devices, then you need
to devise a provisioning system for your device production.

7.4 Distribution Configuration

The build system provides a mechanism for global configuration that applies to all
images built. This mechanism is called distribution configuration or distribution policy. It is
simply a configuration file that contains variable settings. The distribution configuration
is included through the DISTRO variable setting in the build environment configuration
file conf/local.conf:
DISTRO = "poky"

The variable setting corresponds to a distribution configuration file whose base name
is the same as the variable’s argument with the file extension .conf. For the preceding
example, the build system searches for a distribution configuration file with the name
poky.conf in the subdirectory conf/distro in all metadata layers included by the build
environment.

7.4.1 Standard Distribution Policies

The Yocto Project provides several distribution configuration files for standard config-
uration policies:

n poky: Poky is the default policy for the Yocto Project’s reference distribution Poky.
It is a good choice for getting started with the Yocto Project and as a template for
your own distribution configuration files.
n poky-bleeding : This distribution configuration is based on poky but sets the
versions for all packages to the latest revision. It is commonly used by the Yocto
Project developers for integration test purposes. You may, of course, use it, but be
aware that there could be issues with packages with incompatible versions.
n poky-lsb : This distribution configuration is for a stack that complies with LSB. It
is preferably used with the core-image-lsb image target and image targets derived
from it. It inherits the base settings from poky and adds global configuration set-
tings to enable security and includes default libraries required for LSB compliance.
n poky-tiny: This distribution configuration tailors the settings to yield a very com-
pact Linux OS stack for embedded devices. It is based on poky but provides only
the bare minimum functionality necessary to support the hardware and a BusyBox
170 Chapter 7 Building a Custom Linux Distribution

environment. It does not support any video but only a serial console. Because of
its slim configuration, only the core-image-minimal image target and image tar-
gets based on it can be built with the poky-tiny distribution configuration.

The standard distribution policies, particularly poky, are good starting points for
your own distribution configuration. Let’s have a closer look at the poky distribution
configuration to understand how distribution policies are set and how we can use them
for our own projects.

7.4.2 Poky Distribution Policy

You can find the file poky.conf containing the Poky distribution policy in the meta-
yocto/conf/distro directory of the build system. We replicated its contents here for
convenience, reformatted the file to fit on the page, grouped the variable settings into
logical blocks, and added some comments (see Listing 7-12).

Listing 7-12 Poky Distribution Policy meta-yocto/conf/distro/poky.conf

# Distribution Information
DISTRO = "poky"
DISTRO_NAME = "Poky (Yocto Project Reference Distro)"
DISTRO_VERSION = "1.6+snapshot-${DATE}"
DISTRO_CODENAME = "next"
MAINTAINER = "Poky <[email protected]>"
TARGET_VENDOR = "-poky"

# SDK Information
SDK_NAME = \
"${DISTRO}-${TCLIBC}-${SDK_ARCH}-${IMAGE_BASENAME}-${TUNE_PKGARCH}"
SDK_VERSION := \
"${@'${DISTRO_VERSION}'.replace('snapshot-${DATE}','snapshot')}"
SDK_VENDOR = "-pokysdk"
SDKPATH = "/opt/${DISTRO}/${SDK_VERSION}"

# Distribution Features
# Override these in poky based distros
POKY_DEFAULT_DISTRO_FEATURES = "largefile opengl ptest multiarch wayland"
POKY_DEFAULT_EXTRA_RDEPENDS = "packagegroup-core-boot"
POKY_DEFAULT_EXTRA_RRECOMMENDS = "kernel-module-af-packet"

DISTRO_FEATURES ?= "${DISTRO_FEATURES_DEFAULT} ${DISTRO_FEATURES_LIBC} \

${POKY_DEFAULT_DISTRO_FEATURES}"

# Preferred Versions for Packages

PREFERRED_VERSION_linux-yocto ?= "3.14%"
PREFERRED_VERSION_linux-yocto_qemux86 ?= "3.14%"
PREFERRED_VERSION_linux-yocto_qemux86-64 ?= "3.14%"
PREFERRED_VERSION_linux-yocto_qemuarm ?= "3.14%"
PREFERRED_VERSION_linux-yocto_qemumips ?= "3.14%"
PREFERRED_VERSION_linux-yocto_qemumips64 ?= "3.14%"
PREFERRED_VERSION_linux-yocto_qemuppc ?= "3.14%"
 7.4 Distribution Configuration 171

# Dependencies
DISTRO_EXTRA_RDEPENDS += " ${POKY_DEFAULT_EXTRA_RDEPENDS}"
DISTRO_EXTRA_RRECOMMENDS += " ${POKY_DEFAULT_EXTRA_RRECOMMENDS}"

POKYQEMUDEPS = "${@bb.utils.contains( \
"INCOMPATIBLE_LICENSE", "GPLv3", "", "qemu-config",d)}"
DISTRO_EXTRA_RDEPENDS_append_qemuarm = " ${POKYQEMUDEPS}"
DISTRO_EXTRA_RDEPENDS_append_qemumips = " ${POKYQEMUDEPS}"
DISTRO_EXTRA_RDEPENDS_append_qemuppc = " ${POKYQEMUDEPS}"
DISTRO_EXTRA_RDEPENDS_append_qemux86 = " ${POKYQEMUDEPS}"
DISTRO_EXTRA_RDEPENDS_append_qemux86-64 = " ${POKYQEMUDEPS}"

# Target C Library Configuration

TCLIBCAPPEND = ""

# Target Architectures for QEMU

# (see meta/recipes-devtools/qemu/qemu-targets.inc)
QEMU_TARGETS ?= "arm i386 mips mipsel ppc x86_64"
# Other QEMU_TARGETS "mips64 mips64el sh4"

# Package Manager Configuration

EXTRAOPKGCONFIG = "poky-feed-config-opkg"

# Source Mirrors
PREMIRRORS ??= "\
bzr://.*/.* http://downloads.yoctoproject.org/mirror/sources/ \n \
cvs://.*/.* http://downloads.yoctoproject.org/mirror/sources/ \n \
git://.*/.* http://downloads.yoctoproject.org/mirror/sources/ \n \
gitsm://.*/.* http://downloads.yoctoproject.org/mirror/sources/ \n \
hg://.*/.* http://downloads.yoctoproject.org/mirror/sources/ \n \
osc://.*/.* http://downloads.yoctoproject.org/mirror/sources/ \n \
p4://.*/.* http://downloads.yoctoproject.org/mirror/sources/ \n \
svk://.*/.* http://downloads.yoctoproject.org/mirror/sources/ \n \
svn://.*/.* http://downloads.yoctoproject.org/mirror/sources/ \n"

MIRRORS =+ "\
ftp://.*/.* http://downloads.yoctoproject.org/mirror/sources/ \n \
http://.*/.* http://downloads.yoctoproject.org/mirror/sources/ \n \
https://.*/.* http://downloads.yoctoproject.org/mirror/sources/ \n"

# Build System Configuration

# Configuration File and Directory Layout Versions

LOCALCONF_VERSION = "1"
LAYER_CONF_VERSION ?= "6"
#
# OELAYOUT_ABI allows us to notify users when the format of TMPDIR changes
# in an incompatible way. Such changes should usually be detailed in the
# commit that breaks the format and have been previously discussed on the
# mailing list with general agreement from the core team.
#
OELAYOUT_ABI = "8"

# Default hash policy for distro

BB_SIGNATURE_HANDLER ?= 'OEBasicHash'

# Build System Checks

172 Chapter 7 Building a Custom Linux Distribution

# add poky sanity bbclass

INHERIT += "poky-sanity"

# The CONNECTIVITY_CHECK_URIs are used to test whether we can successfully

# fetch from the network (and warn you if not). To disable the test, set
# the variable to be empty.
# Git example url: \
git://git.yoctoproject.org/yocto-firewall-test;protocol=git;rev=HEAD

CONNECTIVITY_CHECK_URIS ?= " \
https://eula-downloads.yoctoproject.org/index.php \
http://bugzilla.yoctoproject.org/report.cgi"

SANITY_TESTED_DISTROS ?= " \
Poky-1.4 \n \
Poky-1.5 \n \
Poky-1.6 \n \
Ubuntu-12.04 \n \
Ubuntu-13.10 \n \
Ubuntu-14.04 \n \
Fedora-19 \n \
Fedora-20 \n \
CentOS-6.4 \n \
CentOS-6.5 \n \
Debian-7.0 \n \
Debian-7.1 \n \
Debian-7.2 \n \
Debian-7.3 \n \
Debian-7.4 \n \
SUSE-LINUX-12.2 \n \
openSUSE-project-12.3 \n \
openSUSE-project-13.1 \n \
"

# QA check settings - a little stricter than the OE-Core defaults

WARN_QA = "textrel files-invalid incompatible-license xorg-driver-abi \
libdir unknown-configure-option"
ERROR_QA = "dev-so debug-deps dev-deps debug-files arch pkgconfig la \
perms useless-rpaths rpaths staticdev ldflags pkgvarcheck \
already-stripped compile-host-path dep-cmp \
installed-vs-shipped install-host-path packages-list \
perm-config perm-line perm-link pkgv-undefined \
pn-overrides split-strip var-undefined version-going-backwards"

The file shown in the listing is from the head of the Yocto Project Git repository
at the writing of this book. Depending on what version of the Yocto Project tools you
are using, this file may look slightly different. The file is an example of a distribution
policy only. It provides the variable settings most commonly associated with the con-
figuration of a distribution. You are not limited to using just the settings shown in the
listing, and you can remove settings if you do not need them for your project.

Distribution Information
This section of the distribution policy file contains settings for general information
about the distribution.
 7.4 Distribution Configuration 173

n DISTRO : Short name of the distribution. The value must match the base name of
the distribution configuration file.
n DISTRO_NAME : The long name of the distribution. Various recipes reference this
variable. Its contents are shown on the console boot prompt.
n DISTRO_VERSION : Distribution version string. It is referenced by various recipes and
used in filenames’ distribution artifacts. It is shown on the console boot prompt.
n DISTRO_CODENAME : A code name for the distribution. It is currently used only by
the LSB recipes and copied into the lsb-release system configuration file.
n MAINTAINER : Name and e-mail address of the distribution maintainer.
n TARGET_VENDOR : Target vendor string that is concatenated with various variables,
most notably target system (TARGET_SYS). TARGET_SYS is a concatenation of target
architecture (TARGET_ARCH), target vendor (TARGET_VENDOR), and target operat-
ing system (TARGET_OS), such as i586-poky-linux. The three parts are delimited
by hyphens. The TARGET_VENDOR string must be prefixed with the hyphen, and
TARGET_OS must not. This is one of the many unfortunate inconsistencies of the
OpenEmbedded build system. You may want to set this variable to your or your
company’s name.

SDK Information
The settings in this section provide the base configuration for the SDK.

n SDK_NAME : The base name that the build system uses for SDK output files. It is
derived by concatenating the DISTRO, TCLIBC, SDK_ARCH , IMAGE_BASENAME , and
TUNE_PKGARCH variables with hyphens. There is not much reason for you to change
that string from its default setting, as it provides all the information needed to
distinguish different SDKs.
n SDK_VERSION : SDK version string, which is commonly set to DISTRO_VERSION.
n SDK_VENDOR : SDK vendor string, which serves a similar purpose as TARGET_VENDOR .
Like TARGET_VENDOR , the string must be prefixed with a hyphen.
n SDKPATH : Default installation path for the SDK. The SDK installer offers this path
to the user during installation of an SDK. The user can accept it or enter an alter-
native path. The default value /opt/${DISTRO}/${SDK_VERSION} installs the SDK
into the /opt system directory, which requires root privileges. A viable alternative
would be to install the SDK into the user’s home directory by setting SDKPATH =
"${HOME}/${DISTRO}/${SDK_VERSION}".

Distribution Features
These feature settings provide specific functionality for the distribution.

n DISTRO_FEATURES : A list of distribution features that enable support for certain

functionality within software packages. The assignment in the poky.conf distri-
bution policy file includes DISTRO_FEATURES_DEFAULT and DISTRO_FEATURES_LIBC.
174 Chapter 7 Building a Custom Linux Distribution

Both contain default distribution feature settings. We discuss distribution features

and how they work and the default configuration in the next two sections.

Preferred Versions
Version settings prescribe particular versions for packages rather than the default
versions.

n PREFERRED_VERSION : Using PREFERRED_VERSION allows setting particular versions

for software packages if you do not want to use the latest version, as it is the
default. Commonly, that is done for the Linux kernel but also for software pack-
ages on which your application software has strong version dependencies.

Dependencies
These settings are declarations for dependencies required for distribution runtime.

n DISTRO_EXTRA_RDEPENDS : Sets runtime dependencies for the distribution. Depen-

dencies declared with this variable are required for the distribution. If these
dependencies are not met, building the distributions fails.
n DISTRO_EXTRA_RRECOMMENDS : Packages that are recommended for the distribution
to provide additional useful functionality. These dependencies are added if avail-
able but building the distribution does not fail if they are not met.

Toolchain Configuration
These settings configure the toolchain used for building the distribution.

n TCMODE : This variable selects the toolchain that the build system uses. The default
value is default, which selects the internal toolchain built by the build system
(gcc, binutils, etc.). The setting of the variable corresponds to a configuration file
tcmode-${TCMODE}.inc, which the build system locates in the path conf/distro/
include. This allows including an external toolchain with the build system by
including a toolchain layer that provides the necessary tools as well as the con-
figuration file. If you are using an external toolchain, you must ensure that it is
compatible with the Poky build system.
n TCLIBC : Specifies the C library to be used. The build system currently supports
EGLIBC, uClibc, and musl. The setting of the variable corresponds to a config-
uration file tclibc-${TCLIBC).inc that the build system locates in the path conf/
distro/include. These configuration files set preferred providers for libraries and
more.
n TCLIBCAPPEND : The build system appends this string to other variables to dis-
tinguish build artifacts by C library. If you are experimenting with different C
libraries, you may want to use the settings
TCLIBCAPPEND = "-${TCLIBC}"
TMPDIR .= "${TCLIBCAPPEND}"
 7.4 Distribution Configuration 175

in your distribution configuration, which creates a separate build output directory

structure for each C library.

Mirror Configuration
The settings in this section configure the mirrors for downloading source packages.

n PREMIRRORS and MIRRORS : The Poky distribution adds these variables to set its mir-
ror configuration to use the Yocto Project repositories as a source for downloads.
If you want to use your own mirrors, you can add them to your distribution con-
figuration file. However, since mirrors are not strictly distribution settings, you
may want to add these variables to the local.conf file of your build environment.
Another alternative would be to add them to the layer.conf file of a custom layer.

Build System Configuration

These settings define the requirements for the build system.

n LOCALCONF_VERSION : Sets the expected or required version for the build environ-
ment configuration file local.conf. The build system compares this value to the
value of the variable CONF_VERSION in local.conf. If LOCALCONF_VERSION is a later
version than CONF_VERSION, the build system may be able to automatically upgrade
local.conf to the newer version. Otherwise, the build system exits with an error
message.
n LAYER_CONF_VERSION : Sets the expected or required version for the bblayers.conf
configuration file of a build environment. The build system compares this version
to the value of LCONF_VERSION set by bblayers.conf. If LAYER_CONF_VERSION is a
later version than LCONF_VERSION, the build system may be able to automatically
upgrade bblayers.conf to the newer version. Otherwise, the build system exits
with an error message.
n OELAYOUT_ABI : Sets the expected or required version for the layout of the output
directory TMPDIR . The build system stores the actual layout version in the file
abi_version inside of TMPDIR . If the two are incompatible, the build system exits
with an error message. This typically happens only if you are using a newer ver-
sion of the build system with a build environment that was created by a previous
version and the layout changed incompatibly. Deleting TMPDIR resolves the issue by
re-creating the directory.
n BB_SIGNATURE_HANDLER : The signature handler used for signing shared state cache
entries and creating stamp files. The value references a signature handler function
that, because of its complexity, is typically implemented in Python. The code in
meta/lib/oe/sstatesig.py implements OEBasic and OEBasicHash based on the BitBake
signature generators SignatureGeneratorBasic and SignatureGeneratorBasicHash
defined by bitbake/lib/bb/siggen.py and illustrates how to insert your own sig-
nature handler function. The two signature handlers are principally the same, but
OEBasicHash includes the task code in the signature, which causes any change to
176 Chapter 7 Building a Custom Linux Distribution

metadata to invalidate stamp files and shared state cache entries without explicitly
changing package revision numbers. Using the default value of OEBasicHash is
typically sufficient for most applications.

Build System Checks

These configuration variables control various validators to catch build system
misconfigurations.

n INHERIT += "poky-sanity": Inherits the class poky-sanity, which is required to

perform the build system checks. It is recommended that you include this directive
in your own distribution configuration files.
n CONNECTIVITY_CHECK_URIS : A list of URIs that the build system tries to verify net-
work connectivity. In the case of Poky, these point to files on the Yocto Project’s
high-availability infrastructure. If you intend to use your own mirrors for down-
loading source packages, you could use URIs pointing to files on your mirror
servers to verify proper connectivity.
n SANITY_TESTED_DISTROS : A list of Linux distributions the Poky build system has
been tested on. The build system verifies the Linux distribution it is running
on against this list. If that distribution is not in the list, Poky displays a warning
message and starts the build process regardless. Poky runs on most current Linux
distributions, and in most cases, building works just fine even if the distribution is
not officially supported.

QA Checks
The QA checks are defined and implemented by meta/classes/insane.bbclass. This
class also defines the QA tasks that are included with the build process. QA checks are
performed after configuration, packaging, and other build tasks. The following two
variables define which QA checks cause warning messages and which checks cause the
build system to terminate the build with an error message:

n WARN_QA : A list of QA checks that create warning messages, but the build
continues
n ERROR_QA : A list of QA checks that create error messages, and the build terminates

The preceding list represents the most common variable settings used by a distribu-
tion configuration. For your own distribution configuration, you may add and/or omit
variables as needed.

7.4.3 Distribution Features

Distribution features enable support for certain functionality within software packages.
Adding a distribution feature to the variable DISTRO_FEATURES adds the functionality
of this feature to software packages that support it during build time. For instance, if
a software package can be built for console as well as graphical user interfaces, then
 7.4 Distribution Configuration 177

adding x11 to DISTRO_FEATURES configures that software package so that it is built with
X11 support. Unlike the x11 image feature, this does not mean that the X11 packages
are installed in your target root filesystem. The distribution feature only prepares a
software package for X11 support so that it uses X11 on a system where the X11 base
packages are installed.
Using DISTRO_FEATURES gives you granular control over how software packages are
built. If you do not need a particular functionality, omitting the distribution feature
enabling it typically results in a smaller footprint for a particular software package.
Using
$ grep -R DISTRO_FEATURES *

from the installation directory of your build system gives you a list of all the recipes and
include files that use DISTRO_FEATURES to conditionally modify configuration settings
or build processes dependent on what distribution features are enabled.
Recipes typically scan DISTRO_FEATURES using
bb.utils.contains('DISTRO_FEATURES', <feature>, <true_val>, <false_val>)

to determine if a particular distribution feature is enabled by DISTRO_FEATURES. The

function returns true_val if DISTRO_FEATURES contains feature and false_val other-
wise. That makes it convenient for the developer to assign values to BitBake variables or
use the function in if-then-else statements. Typically, this is used by the do_configure
task to modify the configuration based on DISTRO_FEATURES. For some packages, it may
provide f lags to makefiles.
A prime example is the recipe to build the EGLIBC library. EGLIBC allows
enabling functionality by setting configuration options. The file meta/recipes-core/
egligc/egilbc-options.inc, which is included by the recipe, sets the configuration
options based on the distribution features provided by DISTRO_FEATURES.
The following list shows the most common distribution features that you can add
to DISTRO_FEATURES to enable functionality in software packages globally across your
distribution:

n alsa : Enable support for the Advanced Linux Sound Architecture (ALSA), includ-
ing the installation of open source compatibility modules if available.
n bluetooth : Enable support for Bluetooth.
n cramfs : Enable support for the compressed filesystem CramFS.
n directfb : Enable support for DirectFB.
n ext2 : Enable support and include tools for devices with internal mass storage
devices such as hard disks instead of f lash devices only.
n ipsec : Enable support for authentication and encryption using Internet Protocol
Security (IPSec).
n ipv6: Enable support for Internet Protocol version 6 (IPv6).
178 Chapter 7 Building a Custom Linux Distribution

n irda : Enable support for wireless infrared data communication as specified by the
Infrared Data Association (IrDA).
n keyboard : Enable keyboard support, which includes loading of keymaps during
boot of the system.
n nfs: Enable client NFS support for mounting NFS exports on the system.
n opengl: Include the Open Graphics Library (OpenGL), which is an application
programming interface for rendering 2D and 3D graphics. OpenGL runs on dif-
ferent platforms and provides bindings for most common programming languages.
n pci: Enable support for the PCI bus.
n pcmcia : Enable PCMCIA and CompactFlash support.
n ppp : Enable Point-to-Point Protocol (PPP) support for dial-up networking.
n smbfs : Enable support and include clients for Microsoft’s Server Message Block
(SMB) for sharing remote filesystems, printers, and other devices over networks.
n systemd : Include support for the system management daemon (systemd) that
replaces the SysVinit script-based system for starting up and shutting down a
system.
n sysvinit: Include support for the SysVinit system manager.
n usbgadget: Enable support for the Linux-USB Gadget API Framework that allows
a Linux device to act like a USB device (slave role) when connected to another
system.
n usbhost: Enable USB host support allowing client devices such as keyboards,
mice, cameras, and more to be connected to the system’s USB ports and detected
by it.
n wayland : Enable support for the Wayland compositor protocol and include the
Weston compositor.
n wifi: Enable WiFi support.
n x11: Include the X11 server and libraries.

The list does not include the distribution features for the configuration of the C
library. These distribution features all begin with libc-. They enable support for
functionality provided by the C library if the C library is configurable like the Yocto
Project’s default C library glibc. If you are using glibc, then you do not have to worry
about setting these distribution features, as they are inherited from the default distribu-
tion setup, which is covered in the next section.
If you have already been working with the Yocto Project, you may have noticed
that there is also a variable called MACHINE_FEATURES and that the permissible list of
machine features has a large intersection with the distribution feature list. For example,
both MACHINE_FEATURES and DISTRO_FEATURES provide the feature bluetooth. Enabling
Bluetooth in DISTRO_FEATURES causes the Bluetooth packages for hardware support to
be installed and also enables Bluetooth support for various software packages. However,
 7.4 Distribution Configuration 179

enabling Bluetooth in MACHINE_FEATURES only causes the Bluetooth packages for hard-
ware support to be installed. This gives you control over functionality on the machine
and the distribution level. We discuss machine features in detail when we are looking
into Yocto Project board support packages.

7.4.4 System Manager

The build system supports SysVinit, the traditional script-based system manager, as well
as the system management daemon (systemd), a replacement for SysVinit that offers
better prioritization and dependency handling between services and the ability to start
services in parallel to speed up the boot sequence.
SysVinit is the default system manager for Linux distributions built by Poky. You do
not have to change the configuration if you want to use SysVinit.
To enable systemd, you need to add it to the distribution features and set it as the
system manager. Add the following to your distribution configuration file:
DISTRO_FEATURES_append = " systemd"
VIRTUAL-RUNTIME_init_manager = "systemd"

The first line installs systemd in the root filesystem. The second line enables it as the
system manager. Installing and enabling systemd does not remove SysVinit from your
root filesystem if it is also included in DISTRO_FEATURES. If you are using one of the
standard distribution configurations, such as poky, then you can remove it from DISTRO_
FEATURES with
DISTRO_FEATURES_BACKFULL_CONSIDERED = "sysvinit"

which is easier than redefining DISTRO_FEATURES altogether. For your own distribution
configuration, you can of course simply omit SysVinit from the DISTRO_FEATURES list.
The SysVinit initscripts to start the individual system services are typically part of
the package that provides the service. To conserve space in the root filesystem, you may
not want to install the initscripts if you want to use systemd exclusively. Use
VIRTUAL-RUNTIME_initscripts = ""

to prevent the build system from installing the SysVinit initscripts.

A word of caution: some daemons may not yet have been adapted for use with
systemd and therefore systemd service files are not available. If you come across such
software, you may have to do the adaptation yourself. If you do so, please consider
submitting your work to upstream.

7.4.5 Default Distribution Setup

The OE Core metadata layer provides default distribution setup through the file meta/
conf/distro/defaultsetup.conf and a series of other files included by it (see Listing 7-13).
It is not quite obvious how this default distribution setup is included into the build
configuration, as this file is not included by distribution policy configuration files such
180 Chapter 7 Building a Custom Linux Distribution

as poky.conf, which we discussed earlier. Instead, the file is included by BitBake’s main
configuration file, bitbake.conf.
Knowing about defaultsetup.conf and understanding its settings is important
because your own distribution policy configuration may extend or overwrite some of
the default variable settings provided by it. If you do not set up the default distribution
correctly, you may inadvertently lose important default settings, and your distribution
build may fail or not yield the desired results.

Listing 7-13 Default Distribution Setup meta/conf/distro/defaultsetup.conf

include conf/distro/include/default-providers.inc
include conf/distro/include/default-versions.inc
include conf/distro/include/default-distrovars.inc
include conf/distro/include/world-broken.inc

TCMODE ?= "default"
require conf/distro/include/tcmode-${TCMODE}.inc

TCLIBC ?= "eglibc"
require conf/distro/include/tclibc-${TCLIBC}.inc

# Allow single libc distros to disable this code

TCLIBCAPPEND ?= "-${TCLIBC}"
TMPDIR .= "${TCLIBCAPPEND}"

CACHE = "${TMPDIR}/cache/${TCMODE}-${TCLIBC}${@['', '/' + \

str(d.getVar('MACHINE', True))][bool(d.getVar('MACHINE', \
True))]}${@['', '/' + str(d.getVar('SDKMACHINE', True))] \
[bool(d.getVar('SDKMACHINE', True))]}"

USER_CLASSES ?= ""
PACKAGE_CLASSES ?= "package_ipk"
INHERIT_BLACKLIST = "blacklist"
INHERIT_DISTRO ?= "debian devshell sstate license"
INHERIT += "${PACKAGE_CLASSES} ${USER_CLASSES} ${INHERIT_DISTRO} \
${INHERIT_BLACKLIST}"

The file first includes three other files with default settings: default-providers.inc,
default-versions.inc, and default-distrovars.inc. The names for these files are
indicative of what the file content is providing.
The file default-distrovars.inc in particular provides default settings for DISTRO_
FEATURES, DISTRO_FEATURES_DEFAULT, DISTRO_FEATURES_LIBC, and DISTRO_FEATURES_
LIBC_DEFAULT. If you are going to set DISTRO_FEATURES in your own distribution policy
configuration file, you need to pay attention that you do not inadvertently remove the
default settings by overwriting the variable. A safe way of doing so is to use an assign-
ment like
DISTRO_FEATURES ?= "${DISTRO_FEATURES_DEFAULT} ${DISTRO_FEATURES_LIBC} \
${MY_DISTRO_FEATURES}"
MY_DISTRO_FEATURES = "<distro features>"
 7.6 Hob 181

which includes all default settings and adds another variable to include additional distri-
bution features as needed.
The configuration file defaultsetup.conf also sets the defaults for TCMODE and
TCLIBC and includes their respective configuration files, as described earlier.

7.5 External Layers

For the examples in the preceding sections, we used software packages and package
groups from the OE Core layer meta and the Yocto Project base layer meta-yocto.
With steadily increasing support and contributions to the Yocto Project and Open-
Embedded, a growing number of additional layers with hundreds of recipes for myriad
software packages are now available. Many of them are cataloged on the OpenEmbedded
website. If you are looking for a recipe to build a specific software package, chances are
that someone has already done the work.
The OpenEmbedded website’s metadata index1 lets you search by layer, recipe, and
machine. For example, searching for Java by layer gives you a list of the layers that
provide Java. Searching for JDK by recipes gives you a list of all recipes that build JDK
packages together with the layer that provides the recipe.
The metadata index also lets you filter for the supported Yocto Project release to see
if a recipe or layer is compatible with that particular release. Once you find the layer
containing the software package recipe you are looking for, all you need to do is down-
load the layer, include its path into the BBLAYERS variable of the conf/bblayers.conf of
your build environment, and add the desired software package to your image using one
of the methods described earlier.

7.6 Hob
Hob is a graphical user interface for BitBake provided by the Yocto Project. It is one of
the Yocto Project’s subprojects and is maintained by the Yocto Project development team.
Why is it called Hob? In the early days of Hob, the three letters stood for
Human-Oriented Builder. However, that does not really sound too appealing and now the
name of the tool is commonly associated with hob, the British English word for cook-
top. And that fits well into the scheme of BitBake and recipes.
With Hob you can conveniently customize your root filesystem images using your
mouse rather than editing text files. If that’s the case, why didn’t we introduce Hob
first rather than explain how to build your custom Linux distribution the “hard” way?
There are a couple of reasons:

n You can do a lot with Hob, but not everything.

n Hob is a frontend to BitBake and your build environment. It manipulates
files in your build environment, launches BitBake, and collects build results.

1. http://layers.openembedded.org
182 Chapter 7 Building a Custom Linux Distribution

Understanding how this is done manually helps you understand what Hob does in
particular if something goes wrong.
n Although Hob may hide some of the complexity, you still need to know the ter-
minology and how certain variable settings inf luence your build results.

Using Hob is rather simple. First, set up a build environment and then launch Hob
from inside it:
$ source oe-init-build-env build
$ hob

Hob launches and then verifies your build environment. After that check is com-
pleted, you see a screen similar to the one in Figure 7-1 (we already made choices for
the machine and image recipe).
The Hob user interface is easy to understand:

n Select a machine: From the drop-down menu, choose the machine you want
to build for. The list shows all the machines that are defined by any layer included
with the build environment. Selecting the machine changes the MACHINE variable
setting in the con/local.conf file.

Figure 7-1 Hob

 7.6 Hob 183

n Layers: Click this button to open a graphical editor that lets you include layers
with and remove them from your build environment. Doing so modifies the
conf/bblayers.conf file in your build environment.
n Select an image recipe: From this drop-down menu, you can choose the image
that you want to build. This provides the image target to BitBake similar to run-
ning bitbake <image-target>. The menu contains image targets from all layers
included with your build environment.
n Advanced configuration: Clicking on this button opens a menu that lets you
select root filesystem types, packaging format, distribution policy, image size, and
more, as outlined in Sections 7.3 and 7.4. Hob adds these options to the conf/
local.conf file of the build environment.
n Edit image recipe: This button at the bottom of the screen lets you modify the
image recipe by adding and/or removing packages and/or package groups. Doing
so effectively modifies the IMAGE_INSTALL variable of the image target. You can-
not, however, define new package groups from the Hob user interface. For that
task, you have to write your package group recipe as explained in Section 7.1.6.
But, of course, if you wrote your package recipe and included the layer it resides
in with Hob, then you are able to select it from the package groups list.
n Settings: This button in the upper right corner of the user interface allows you to
modify general settings contained in conf/local.conf such as parallelism, down-
load directory, shared state cache, mirrors, and network proxies. Using the Others
tab, you can add any variable to conf/local.conf and assign a value to it.
n Images: This button next to the Settings button in the upper right corner of the
Hob user interface displays a list of previously built images. The list is created by
parsing the tmp/deploy/images/<machine> subdirectories of the build environment.
You can select an image from the list, run it if it is a QEMU image, or rebuild it.
n Build image: This button launches BitBake with the selected configuration and
image target. The user interface switches to the Log tab of the build view from
which you can follow the build process. This view has a major advantage over the
BitBake output when started from the command line: not only do you see the tasks
that are currently run but also the pending tasks and the ones that already have com-
pleted. If there are any build issues, warnings, or errors, they are logged underneath
the Issues tab. There you can examine build issues and directly view the entire log
file of a task without navigating through the build environment directory structure.

After the build finishes, Hob presents you with a summary page where you can view
the created files in the file browser of your build system. You can also examine a sum-
mary log showing the run results for each task as well as any notes, warnings, or error
messages. If you used Hob to build a root filesystem image and Linux kernel for the
QEMU emulator, you can launch QEMU directly from Hob to verify your image by
clicking on the Run image button in the lower right corner of the user interface. From the
summary page, you can also make changes to your configuration and run a new build.
184 Chapter 7 Building a Custom Linux Distribution

Whether you prefer Hob over configuring your build environment, customizing
your target images, and launching BitBake manually is entirely up to you. Hob is great
for rapid prototyping and to quickly enable somebody who is not all that familiar with
BitBake and the Yocto Project to build predefined root filesystem image targets. Hob
does not allow you to create your own image recipes, nor can you create your own
distribution policy files with it (or even edit them). For these tasks, you need to set up
your own layer and create the necessary files and recipes manually.
From Yocto Project version 2.1 on, Hob is being deprecated in favor of the web-
based Toaster, which we explore in detail in Chapter 13.

7.7 Summary
The largest building block of a Linux distribution is the user space that contains the
various libraries and applications that provide the essential functionality of the system.
This chapter presented the fundamental concepts on how the Poky build system creates
root filesystem images and how you can customize them to meet your requirements.
n The OpenEmbedded build system’s core images provide distribution blueprints
that you can extend and modify.
n Core images can easily be extended by appending packages and package groups to
the list contained in the variable IMAGE_INSTALL.
n The QEMU emulator is a convenient and quick way to test your root file before
booting it on an actual device.
n Enabling the build history lets you track changes to your images and compare
subsequent executions of the build process.
n Creating your own image recipes that build on core image recipes by including
them provides you with more control over what packages your root filesystem
image contains. Image recipes that directly inherit the core-image class let you
build root filesystem images from scratch.
n Package groups are a mechanism to bundle multiple packages and reference
them by a single name, which greatly simplifies image customization with the
IMAGE_INSTALL variable. Poky provides a series of predefined package groups that
organize common packages.
n The build system can produce root filesystem images in various output formats. Some
of them can be written directly to storage media such as flash devices to boot a system.
n Setting up a distribution policy allows operating system configuration indepen-
dent of the content of the root filesystem. It also provides the means to use an
external toolchain with the build system and to change the C library.
n Hob is a graphical user interface for BitBake. Launched from within an initialized
build environment, it allows configuring and building of root filesystem images
without modifying files using a text editor.
 Index

Symbols A
" (double quote) ABI (application binary interface), 289
in assignments, 195–196 abi_version file, 52
variable delimiter, 72 --active parameter, 296
/ (forward slash), in symbolic names, 100 Administrative privileges for ordinary users,
- (hyphen), in variable names, 72 28
( ) (parentheses), in license names, 201 ADT (Application Development Toolkit), 26.
:= (colon equal sign), variable expansion, 74 See also SDK (software development kit).
?= (question mark equal), default value components, 302–304
assignment, 73 cross-development toolchain, 302
??= (question marks equal), weak default definition, 301
assignment, 73 description, 26
.= (dot equal), appending variables, 75 Eclipse IDE plugin, 302
' (single quote), variable delimiter, 72 environment setup, 302
@ (at sign), variable expansion, 74 integrating into Eclipse, 27
\ (backslash), line continuation, 195–196 ADT (Application Development Toolkit),
# (hash mark), comment indicator, 21, 71, 19 building applications
% (percent sign), in BitBake version strings, Autotools based, 316, 322–323
102 makefile based, 315–316
+= (plus equal), appending variables, 74 ADT (Application Development Toolkit),
= (equal sign), direct value assignment, 73 Eclipse integration
=. (equal dot), prepending variables, 75 Arguments tab, 326
=+ (equal plus), prepending variables, 74 Autotools-based applications, 322–323
${} (dollar sign curly braces), variable CMake-based applications, 321–322
expansion, 74 Common tab, 326–327
_ (underscore) configuration screen, 320–321
conditional variable setting, 76 Debugger tab, 328–329
in variable names, 72 debugging applications on the target,
. (dot) 327–330
in hidden file names, 226 developing applications, 321–323
in variable names, 72 GDB/CLI command line interpreter, 328
& (ampersand), concatenating license names, GDB/MI command line interpreter, 328
201, 337 Gdbserver Settings subtab, 329
| (pipe symbol) inspecting the target system, 324–325
concatenating license names, 201, 337 installing Eclipse IDE, 317–319
separating kernel names, 237 Main subtab, 329
~ (tilde), in variable names, 72 Main tab, 326
430 Index

ADT (Application Development Toolkit), Android distribution, 4

Eclipse integration (continued) Ångström Distribution, 4
overview, 317 _anonymous keyword, 80
preparing the target for remote control, Apache Licenses, 12, 397–401
323–324 Apache Software Foundation, 11–12
running applications on the target, 325–327 Append files
Shared Libraries subtab, 329 definition, 31
Source tab, 330 description, 43, 71
Target Explorer, 324–325 file extension, 43
TCF network protocol, 323 _append operator, 75, 84–85, 149–150
tracing library functions, 330–331 --append parameter, 297
Yocto Project Eclipse, 319–321 Appending
ADT (Application Development Toolkit), BitBake variables, 74–75, 76
setting up functions, 84–85
building a toolchain installer, 304 Appends, recipe layout, 194
cross-canadian toolchain binaries, 306 Application binary interface (ABI), 289
debugging standard libraries, 314–315 Application development. See ADT
Eclipse IDE, 311 (Application Development Toolkit).
environment variables, 308–309 Application software management, embedded
file and subdirectory categories, 307 Linux, 8
GDB (GNU Debugger), 311–315 Application space. See User space.
gdbserver, 311–315 AR variable, 308
inferior processes, 311 arch subdirectory, 249
installing the toolchain, 305–307 ARCH variable, 308
non-stripped binary information, 311 Architecture-dependent code, 136
on-target execution, 310 Architecture-independent packaging, 210
overview, 304 ARCHIVER_MODE f lags, 341
post-mortem debugging, 311 arch-x86.inc file, 289
remote on-target debugging, 311–315 Arguments tab, 326
working with toolchains, 307–310 AS variable, 308
ADT (Application Development Toolkit), Assigning values, to BitBake variables, 72–73
with emulated targets Assignments, formatting guidelines, 195
application development with QEMU, At sign (@), variable expansion, 74
331–333 Attributes, BitBake metadata, 85
extracting the root filesystem, 332 Attribution, open source licenses, 10
integrating with Eclipse, 332–333 Auditing. See Build history.
launching applications with QEMU, 333 Authentication category, Toaster, 350
NFS (Network File System), 332 AUTHOR variable, 189
overview, 331 Autobuilder
--align parameter, 296 description, 26, 368
Aligned development, 30 environment variables, 370
alsa feature, 177 installing, 369–370
Ampersand (&), concatenating license names, passwords, 369–370
201, 337 user names, 369–370
Analysis mode, Toaster, 346, 348 Autobuilder, configuring
Android devices, licensing and compliance, buildset configuration, 373–374
336 controller configuration file, 372
 Index 431

global configuration file, 370–371 BeagleBone development board, 273

worker configuration file, 372–373 Berkeley Software Distribution (BSD), 10
Automated build systems, Buildbot, 368–369. Binaries, BSP (board support packages), 262
See also Autobuilder. Bionic libc, C library, 142
Autotools, 37–38, 203, 205 BitBake
Autotools-based ADT applications, 316, classes, 27
322–323 definition, 31
Autotools-based recipe, example, 216–217 description, 26
directives for building software packages.
B See Recipes.
-b parameter, 64–66, 293 documentation and man pages, 48
B variable, 104, 192 execution environment, 61–63
backports subdirectory, 249 graphical user interface, 27, 28
Backslash (\), line continuation, 195–196 HelloWorld program, 95–99
bareclone parameter, 91 history of Yocto Project, 29
Base branches, kernel recipes, 239–240 launching a build, 23
Baserock, 6 layer configuration file, 61–63
.bb files, 70–71 layers, 27
.bbappend file extension, 43 metadata layers, 31
.bbappend files, 56, 71 scripts, 27
.bbclass file extension, 78–79 variants, 103
BBCLASSEXTEND variable, 103, 211 version selection, 102
BBFILE_COLLECTIONS variable, 62 working directory, specifying, 22
BBFILE_PATTERN variable, 62–63 BitBake, command line
BBFILE_PRIORITY variable, 63 BitBake server, starting, 69–70
BBFILES variable, 62, 104 configuration data, providing and
BBLAYERS variable, 51, 104 overriding, 68–69
bblayers.conf file, 40–41, 51 dependency graphs, creating, 67–68
BB_NUMBER_THREADS variable, 22 dependency handling, 65
BBPATH variable, 62, 104 displaying program version, 65
BB_SIGNATURE_HANDLER variable, 175 executing specific tasks, 66
BB_VERSION variable, 111–112 forcing execution, 66
BeagleBoard-xM development board, 273 --help option, 63–65
BeagleBone Black development board, 273 metadata, displaying, 67
BeagleBone boards obtaining and restoring task output, 64
boot order, changing, 272 omitting common packages, 68
boot process, 266–267 overview of options, 63–65
boot SD card, 267–269 package dependencies, graphing, 67–68
booting, 269, 271 set-scene, 64
connecting to your development computer, BitBake, dependency handling
269 build dependencies, 99
display, 266 declaring dependencies, 101
FTDI cables, 270 multiple providers, 101–102
images, 267 overview, 99
overview, 266–267 provisioning, 99–101
serial-to-USB cable, 270 runtime dependencies, 99
terminal emulation, 270–272 types of dependencies, 99
432 Index

BitBake, obtaining and installing SFTP fetcher, 90

building and installing, 60–61 SVK fetcher, 93
cloning the development repository, 60 SVN (Subversion) fetcher, 91–92
release snapshot, 60 upstream repositories, 86
bitbake directory, 48 BitBake metadata syntax
BitBake metadata attributes, 85
append files, 71 comments, 71–72
class files, 71 including other metadata files, 76–77
classes, 78–79 inheritance, 77–79
configuration files, 70 name (key) expansion, 86
executable, 70 optional inclusion, 77
file categories, 70–71 required inclusion, 77
f lags, 85 BitBake metadata syntax, variables
include files, 71 accessing from functions, 82
recipe files, 70–71 accessing from Python functions, 83
sharing settings, 76–77 accessing from shell functions, 82–83
types of, 70 appending and prepending, 74–75, 76
variables, 70 assignment, 72–73
BitBake metadata, executable conditional setting, 76
anonymous Python functions, 80 containing value lists, 84
appending functions, 84–85 defaults, 103–107
global Python functions, 80 expansion, 73–74
local data dictionary, creating, 83 internally derived, 104
prepending functions, 84–85 naming conventions, 72
Python functions, 79–80 project specific, 104
shell functions, 79 referencing other variables, 73–74
tasks, 81–82, 107 removing values from, 75
variables containing value lists, 84 scope, 72
BitBake metadata, source download standard runtime, 104
Bazaar fetcher, 93 string literals, 72
checksums for download verification, 89–90 BitBake server, starting, 69–70
CVS (Current Versions System) fetcher, bitbake.conf file, 40
92–93 bitbake-whatchanged script, 50
fetch class, 87–88 Blacklisting licenses, 340
fetchers, 88–93 bluetooth feature, 177
Git fetcher, 90–91 Board support packages (BSPs). See BSPs
Git submodules fetcher, 91 (board support packages).
HTTP/HTTPS/FTP fetcher, 89–90 Books and publications. See Documentation
local file fetcher, 88–89 and man pages.
Mercurial fetcher, 93 Bootable media images, creating
mirrors, 94–95 Cooked mode, 292
OBS (Open Build Service) fetcher, 93 kickstart file directives, 295–297
overview, 86–87 kickstart files, 293–295
password requirements, 90 operational modes, 291–293
Perforce fetcher, 93 overview, 290–291
Repo fetcher, 93 plugins, 297–298
from secure FTP sites, 90 Raw mode, 292–293
 Index 433

transferring images, 298–299 Build configuration, Toaster, 356

--bootimg-dir parameter, 293 Build control category, Toaster, 350
bootloader directive, 296–297 Build dependencies, 99
Bootloaders Build environments
bootrom, 130 configuring, 20–23, 41
choosing, 130–131 deleting, 22
commonly used, 131–134. See also specific layer configuration, 41
bootloaders. Build history
EEPROM (electrically erasable configuring, 359–360
programmable read-only memory), 130 core images, 151–152
embedded Linux, 8 description, 358
first stage, 130 directory and file structure, 361–363
f lash memory, 130 enabling, 358
loaders, 129 overview, 358
monitors, 129 package information, 364–365
overview, 129 pushing changes to a Git repository,
role of, 130 360–361
Bootrom, 130 SDK information, 365
Bootstrap loader, 140 Build host, setting up, 18–20
Bottom-up approach to embedded Linux, 9 Build log, Toaster, 357
branch parameter, 90 Build machine type, selecting, 22
Branches, kernel recipes, 239–244 Build mode, Toaster, 346–347, 348, 349
BSD (Berkeley Software Distribution), 10 Build results, verifying, 24
BSPs (board support packages). See also Yocto Build statistics
Project BSPs. storing, 52
binaries, 262 Toaster, 357
building with BeagleBone boards, 265–272 Build system. See OpenEmbedded system.
components, 262 build task, 107
definition, 31 BUILD_ARCH variable, 105
dependency handling, 263–264 Buildbot, 368–369
development tools, 262 --buildfile option, 64–66
documentation, 262 buildhistory class, 151–152
filesystem images, 262. See also Bootable BUILD_HISTORY_COLLECT parameter, 371
media images. BUILDHISTORY_COMMIT variable, 359
operating system source code, 262 BUILDHISTORY_COMMIT_AUTHOR variable, 359
orthogonality, 264 BUILD_HISTORY_DIR parameter, 371
overview, 261–263 BUILDHISTORY_DIR variable, 151, 359
source code patches, 262 BUILDHISTORY_FEATURES variable, 359
tuning, 289–290 BUILDHISTORY_IMAGE_FILES variable, 359
BSP branches, kernel recipes, 240 BUILDHISTORY_PUSH_REPO variable, 359–360
BSP collection description, kernel recipes, BUILD_HISTORY_REPO parameter, 371
246–247 build-id.txt file, 363
BSP layers, Yocto Project kernel recipes, Buildroot, 6
configuring, 50 --build-rootfs parameter, 292–293
bsp subdirectory, 249 Buildset configuration, 373–374
btrfs compression, 165 buildstats directory, 52
BUGTRACKER variable, 189 BUILD_SYS variable, 112
434 Index

BURG bootloader, 131, 134 Commercially licensed packages, 339

BusyBox, 6 Common licenses, 338–339
Common tab, 326–327
C COMMON_LICENSE_DIR variable, 338
C file software recipes, example, 212–213 Comparing core images, 151–152
-c parameter, 64, 66, 284, 292–293 COMPATIBLE_MACHINE variable, 236, 237, 243
C standard libraries, 142–143 Compile step, OpenEmbedded workf low, 44
cache directory, 52 Compiling, recipe source code, 203–204
CACHE variable, 105 Compression
Caching, metadata, 52 algorithms, 164–165. See also specific algorithms.
CC variable, 308 common formats, 36. See also specific formats.
CCACHE_PATH variable, 308 --compress-with parameter, 292–293
CE (Consumer Electronics) Workgroup, 13 .conf file extension, 40
CELF (Consumer Electronics Linux Forum), 13 .conf files, 41–42, 70, 72
cfg subdirectory, 249 conf/bblayers.conf file, 61–62
CFLAGS variable, 308 config subcommands, 285
CGL (Carrier-Grade Linux), 2 config/autobuilder.conf file, 370–371
checksettings command, 354, 356 CONFIG_SITE variable, 308
Class extensions, recipe layout, 194 Configuration collection description, kernel
Class files, 71 recipes, 245
Classes Configuration files
BitBake, 27, 78–79 BitBake metadata, 70
definition, 32 definition, 32
formatting guidelines, 195–196 formatting guidelines, 195–196
Yocto Project BSPs, 281 OpenEmbedded workf low, 40
classes subdirectory, 281 Configuration step, OpenEmbedded
cleanup-workdir script, 50 workf low, 44
--clear-stamp option, 64, 66 configure.ac file, 203
Cloning, development repository, 60 CONFIGURE_FLAGS variable, 308
CMake configuration system, 203, 205 Configuring
CMake-based ADT applications, 321–322 Autobuilder. See Autobuilder, configuring.
CMake-based recipes, example, 215–216 BitBake, 68–69
CMakeLists.txt file, 203 distributions, 42
--cmd option, 64, 66 layers, 40
Code names for Yocto Project releases, 277 machines, 42
--codedump parameter, 284 open source software packages, 37–38
collectstatic checksettings command, 354 recipe source code, 202–203
Colon equal sign (:=), variable expansion, 74 Toaster, 349–354
Command line utility applications, tools and Toaster web server, 354–355
utilities, 6 tools, 7
Commands. See BitBake, command line; user interface, 6
specific commands. Yocto Project kernel recipes, 50
Comments Configuring, kernel recipes
# (hash mark), comment indicator, 21, 71, configuration fragments, 228–231
196 menu configuration, 227–228
BitBake metadata, 71–72 merging partial configurations, 228–231
Commercial support for embedded Linux, 3 overview, 226–227
 Index 435

conf/layer.conf file, 62 Core images, options

CONNECTIVITY_CHECK_URIS variable, 176 compression algorithms, 164–165
Consumer Electronics Linux Forum (CELF), groups, 166–167
13 image size, 163–164
Consumer Electronics (CE) Workgroup, 13 languages and locales, 162
Continuation, formatting guidelines, 195 package management, 162–163
Controller configuration file, 372 passwords, 166–167
Conveyance, open source licenses, 10 root filesystem tweaks, 167–169
Cooked mode, 292 root filesystem types, 164–166
Cooker process SSH server configuration, 168
definition, 69–70 sudo configuration, 168
logging information, 52 users, 166–167
starting, 69–70 core-image images, 146–149
COPYLEFT_LICENSE_EXCLUDE variable, 342–343 core-image.bbclass class, 154
COPYLEFT_LICENSE_INCLUDE variable, 342–343 CORE_IMAGE_EXTRA_INSTALL variable,
COPYLEFT_TARGET_TYPES variable, 343 160–161
COPY_LIC_DIRS variable, 340–341 cpio compression, 165
COPY_LIC_MANIFEST variable, 340–341 cpio.gz compression, 165
Core images cpio.lzma compression, 165
build history, 151–152 cpio.xz compression, 165
building from scratch, 160–161 CPP variable, 308
comparing, 151–152 CPPFLAGS variable, 308
examples, 146–149 CPU, 135
external layers, 181 cramfs compression, 165
graphical user interface, 181–184 cramfs feature, 177
image features, 153–155 createCopy method, 83
package groups, 155–159 create-recipe script, 50
packages, 149–150 Cross-build access, detecting, 28
testing with QEMU, 150–151 Cross-development toolchains, 32, 302
verifying, 151–152 Cross-prelink, description, 27
Core images, distribution configuration Cross-prelinking memory addresses, 27
build system checks, 176 crosstool.ng, 6
build system configuration, 175–176 CubieBoard 2 development board, 274
default setup, 179–181 CubieBoard 3 development board, 274
dependencies, 174 CubieTruck development board, 274
distribution features, 173–174, 176–179 CVSDIR variable, 105
general information settings, 172–173 CXX variable, 308
information, 173 CXXFLAGS variable, 308
mirror configuration, 175
Poky distribution policy, 170–176 D
preferred versions, 174 -D parameter, 292–293
standard distribution policies, 169–170 D variable, 105
system manager, 179 Das U-Boot. See U-Boot bootloader.
toolchain configuration, 174–175 Data dictionary
Core images, extending local, creating, 83
with a recipe, 152–153 printing, 119
through local configuration, 149–150 date parameter, 92
436 Index

dbg-pkgs feature, 154 DEPLOY_DIR_IMAGE variable, 105

Debian distribution, 5, 39 Deploying. See also Toaster, production
Debian Package Management (dpkg), deployment.
162–163 licenses, 340
--debug parameter, 292–293 packages, 222
Debugger tab, 328–329 Deployment output, directory for, 52
Debugging. See also Troubleshooting. Derivative works, open source licenses, 10
applications on the target, 327–330 Description files, kernel recipes, 244
GDB (GNU Debugger), 311–315 DESCRIPTION variable, 189
message severity, 114–115 Determinism, 2
post-mortem, 311 Developer support for embedded Linux, 3
remote on-target, 311–315 Development shell
standard libraries, 314–315 disabling, 121
debug-tweaks feature, 153 troubleshooting, 120–121
Declaring dependencies, 101 Development tools. See Tools and utilities.
def keyword, 80 Device drivers, 8, 136
DEFAULT_PREFERENCE variable, 102 Device management, kernel function, 8
defaultsetup.conf file, 181 Device tree compiler (DTC), 257
DEFAULT_TUNE variable, 289–290 Device trees, 133, 257–258
define keyword, 244 dev-pkgs feature, 154
Deleting. See also Removing. devshell command, 120–121
build environments, 22 Devtool
user accounts, 166–167 deploying packages, 222
user groups, 167 for existing recipes, 223–224
Dependencies images, building, 222
build, 99 overview, 218–219
declaring, 101 recipes, building, 222
runtime, 99 recipes, updating, 223–224
types of, 99 removing packages, 222
Dependency graphs round-trip development, 219–223
creating, 67–68 Devtool, workspace layers
troubleshooting, 121–122 adding recipes, 220–221, 223
visual representation, 122 creating, 219–220
Dependency handling displaying information about, 223
BitBake command line, 65. See also dietlibc, C library, 143
BitBake, dependency handling. diffconfig command, 231
BSPs (board support packages), 263–264 Digital assistant, first Linux based, 28
DEPENDS variable, 101, 105, 191 directfb feature, 177
depends.dot file, 363, 365 Directives for building software packages. See
depends-nokernel.dot file, 363 Recipes.
depends-nokernel-nolibc.dot file, 363 Directories, removing obsolete, 50. See also
depends-nokernel-nolibc-noupdate.dot file, specific directories.
363 Disk space, 16
depends-nokernel-nolibc-noupdate- Dispatching, 135
nomodules.dot file, 363 Display support recipes, Yocto Project BSPs,
deploy directory, 52 281
DEPLOY_DIR variable, 105 Displays, BeagleBone boards, 266
 Index 437

Distribution configuration, OpenEmbedded Dot equal (.=), appending variables, 75

workf low, 42 Download location, specifying, 22
Distribution policy. See Distribution downloadfilename parameter, 89
configuration. Downloading, BitBake metadata. See BitBake
DISTRO variable metadata, source download.
distribution configuration, 169 dpkg (Debian Package Management), 39,
in log files, 112 162–163
Poky distribution, 173 .dtb file extension, 258
SDK information, 365 DTC (device tree compiler), 257
DISTRO_CODENAME variable, 173 .dts file extension, 257
DISTRO_EXTRA_RDEPENDS variable, 174 DULG (DENX U-Boot and Linux Guide), 133
DISTRO_EXTRA_RRECOMMENDS variable, 174
DISTRO_FEATURES variable E
adding features to, 176–179 -e option, 64, 67
default settings, 179–180 ebuild, history of Yocto Project, 29
description, 173 Eclipse IDE plugin. See also ADT
DISTRO_NAME variable, 173 (Application Development Toolkit),
DISTRO_VERSION variable, 112, 173, 365 Eclipse integration; Yocto Project Eclipse.
Django framework, administering in Toaster, for ADT applications, 302, 311
350–351 description, 27, 317
DL_DIR variable, 22, 105 installing, 317–319
dmesg command, 268 integrating ADT, 27
doc directory, 48 Eclipse Project, 12
do_configure_partition() method, 297–298 eclipse-debug feature, 154
doc-pkgs feature, 154 Edison development board, 274
Documentation and man pages EEPROM (electrically erasable
BitBake, 48 programmable read-only memory), 130
BSPs (board support packages), 262 EFI LILO bootloader, 131, 132
Buildbot, 372 EGLIBC, C library, 27, 142
DULG (DENX U-Boot and Linux Guide), elf compression, 165
133 ELILO bootloader, 131, 132
Embedded Linux Primer, xviii Embedded Linux. See also Linux.
U-Boot bootloader, 133 commercial support, 3
Yocto Project Application Developer’s Guide, developer support, 3
304 development tools. See Tools and utilities.
Yocto Project Board Support Package, 264 hardware support, 2
Yocto Project Reference Manual, 209 kernel function, 8
do_fetch task, 199–200 modularity, 3
do_install task, 204, 205 networking, 3
do_install_disk() method, 297–298 reasons for rapid growth, 2–3
Dollar sign curly braces (${}), variable royalties, 2
expansion, 74 scalability, 3
do_prepare_partition() method, 297–298 source code, 3
do_stage_partition() method, 297–298 tooling, 3
Dot (.) Embedded Linux distributions
in hidden file names, 226 Android, 4
in variable names, 72 Ångström Distribution, 4
438 Index

Embedded Linux distributions (continued) Extracting open source code, 36

Debian, 5 EXTRA_IMAGE_FEATURES variable, 153, 161
embedded full distributions, 5 EXTRA_OECMAKE variable, 192
Fedora, 5 EXTRA_OECONF variable, 192
Gentoo, 5 EXTRA_OEMAKE variable, 192
for mobile phones and tablet computers, 4 --extra-space parameter, 296
online image assembly, 4–5 extrausers class, 166–167
OpenWrt, 5
routing network traffic, 5 F
SUSE, 5 -f parameter, 292–293
Ubuntu, 5 Fatal message severity, 114–115
Embedded Linux distributions, components FDT (f lattened device tree), 257. See also
application software management, 8 Device trees.
bootloader, 8 Feature collection description, kernel recipes,
device drivers, 8 246
kernel, 8 feature command, 285–286
life cycle management, 8 features subdirectory, 249
Embedded Linux distributions, creating Fedora distribution, 5, 19
bottom-up approach, 9 Fetching
design strategies, 8–9 open source code, 36
top-down approach, 8–9 recipe source code, 199–200
Embedded Linux Primer, xviii source code, OpenEmbedded workf low,
emerge, history of Yocto Project, 29 43–44
--environment option, 64, 67 File categories, BitBake, 70–71
environment-setup-* scripts, 307 FILE_DIRNAME variable, 105
Equal dot (=.), prepending variables, 75 Files, unified format, 37
Equal plus (=+), prepending variables, 74 FILES variable, 193, 208
Equal sign (=), direct value assignment, 73 FILESDIR variable, 88–89, 105
Error checking, 209–210 FILESEXTRAPATHS variable, 192
Error message severity, 114–115 files-in-image.txt file, 152, 363
ERROR_QA variable, 176, 209 files-in-package.txt file, 364
ERROR_REPORT_COLLECT parameter, 371 files-in-sdk.txt file, 365
ERROR_REPORT_EMAIL parameter, 371 FILESPATH variable, 88–89, 105
EULA (End-User License Agreement), 335 Filesystem, Linux, 2
Executable metadata, 70 Filesystem images, 262. See also Bootable
Expansion, BitBake variables, 73–74 media images.
ext2 compression, 164 Filtering licenses, 342–343
ext2 feature, 177 First-stage bootloader, 130
ext2.bz2 compression, 164 Flags, 85
ext2.gz compression, 164 Flash memory, 130
ext2.lzma compression, 164 flatten command, 124
ext3 compression, 165 Flattened device tree (FDT), 257. See also
ext3.gz compression, 165 Device trees.
External layers, core images, 181 Fragmentation, 30
Externally built recipe package, example, Free software, definition, 10
217–218 --fsoptions parameter, 296
EXTLINUX bootloader, 133 --fstype parameter, 296
 Index 439

FTDI cables, 270 Graphical user interface. See also Toaster.

fullpath parameter, 93 BitBake, 27, 28
Functions. See also Python functions; Shell core images, 181–184
functions. Hob, 27, 50, 181–184
accessing BitBake variables, 82 --graphviz option, 64, 67–68, 121–122
appending, 84–85 groupadd command, 166
prepending, 84–85 groupdel command, 167
groupmod command, 167
G Groups, user accounts, 166–167
-g option, 64, 67–68, 121–122 GRUB bootloader, 131, 132
Galileo development board, 274 GRUB 2 bootloader, 132
gconfig command, 6 GRUB Legacy bootloader, 132
GDB (GNU Debugger)
DDD (Data Display Debugger), 313–314 H
debugging applications, 311–315 -h option, 64–65
debugging standard libraries, 314–315 Hallinan, Chris, xviii
graphical user interface, 313–314 Hard real-time systems, 2
launching on the development host, Hardware requirements, 16
312–314 Hardware support for embedded Linux, 2
GDB variable, 308 Hash mark (#), comment indicator, 21, 71,
GDB/CLI command line interpreter, 328 196
GDB/MI command line interpreter, 328 hddimg compression, 165
gdbserver head.o module, 140–141
debugging applications, 311–315 HelloWorld program, 95–99
installing, 312 Help. See Documentation and man pages.
launching, 312 help command, bitbake-layers tool, 123
Gdbserver Settings subtab, 329 --help option, BitBake, 63–65
General-purpose operating system (GPOS), 1 Hob
Gentoo distribution, 5 description, 27, 181–184
getVar function, 83 launching, 50
git clone command, 60 hob script, 50
GITDIR variable, 105 HOMEPAGE variable, 189
GitHub repository server, 360–361 host directory, 365
GLIBC (GNU C Library), 27, 142 Host leakage, 204
Global configuration file, 370–371 Host pollution, 28
GNU Autotools. See Autotools. hwcodecs feature, 154
GNU Debugger (GDB). See GDB (GNU
Debugger). I
GNU General Public License (GPL), 10 -i parameter, 64, 68, 284
GNU General Public License (GPL) Version if...then keywords, 244
2, 377–384 --ignore-deps option, 64, 68
GNU General Public License (GPL) Version I/O devices, 135
3, 384–397 image.bbclass class, 153–155
GNU GRUB bootloader, 131, 132 IMAGE_FEATURES variable, 153, 161
GNU/Linux, vs. Linux, 127–128 image-info.txt file, 152, 363
GPOS (general-purpose operating system), 1 IMAGE_LINGUAS variable, 162
440 Index

IMAGE_OVERHEAD_FACTOR variable, 163 Poky Linux, 19–20

IMAGE_PKGTYPE variable, 163 recipe build output, 204–206
IMAGE_ROOTFS_ALIGNMENT variable, 163 software packages, 19, 29
IMAGE_ROOTFS_EXTRA_SPACE variable, 163 Toaster, 352–354
IMAGE_ROOTFS_SIZE variable, 163 Toaster build runner service, 355–356
Images. See also Bootable media images, Toaster requirements, 348
creating; Core images. toolchains, 305–307
BeagleBone boards, 267 Integration and support scripts, 50
building, 222 Internally derived BitBake variables, 104
creating, OpenEmbedded workf low, 45 Internet connection, Yocto Projects
definition, 32 requirements, 16–17
features, core images, 153–155 Interprocess communication, 139
filesystem, 262 In-tree configuration files, 238
information about, Toaster, 357 In-tree metadata, kernel recipes, 248–250
size, 163–164 ipkg (Itsy Package Management System), 39
targets, Toaster, 357 ipsec feature, 177
transferring, 298–299 ipv6 feature, 177
.inc files, 71 irda feature, 178
include directive, 77 iso compression, 165
Include files, 71 ISOLINUX bootloader, 133
include keyword, 244
Includes, recipe layout, 190 J
INCOMPATIBLE_LICENSE variable, 340 jffs2 compression, 165
Inferior processes, 311 jffs2.sum compression, 165
--infile parameter, 284 Jitter, 2
inherit directive, 77–78
INHERIT variable, 151, 176 K
Inheritance, BitBake metadata, 77–79 -k parameter, 64–65, 293
Inheritance directives, recipe layout, 190 KBRANCH variable, 242
INITSCRIPT_NAME variable, 206 KCFLAGS variable, 308
INITSCRIPT_PACKAGES variable, 206 kconf keyword, 244
INITSCRIPT_PARAMS variable, 207 KCONF_BSP_AUDIT_LEVEL variable, 243
In-recipe space metadata, kernel recipes, kconfig configuration system, 226–227
247–248 Kernel. See also Linux architecture, kernel.
insane class, 208 device management, 8
INSANE_SKIP variable, 209 embedded Linux, 8
Installation step, OpenEmbedded workf low, main functions, 8
44 memory management, 8
installed-package-names.txt file, 152, 363, responding to system calls, 8
365 Kernel recipes. See also Recipes.
installed-package-sizes.txt file, 363, 365 device tree, 257–258
installed-packages.txt file, 152, 363, 365 factors to consider, 225–226
Installing overview, 225–226
Autobuilder, 369–370 patching, 231–233
BitBake, 60–61 Kernel recipes, building
Eclipse IDE, 317–319 configuration settings, 237
open source software packages, 38 from a Git repository, 236–237
 Index 441

in-tree configuration files, 238 kernel.bbclass class, 233

from a Linux kernel tarball, 235–236 kernel_configme command, 227
from a Linux kernel tree, 234–238 --kernel-dir parameter, 293
overview, 233–234 KERNEL_FEATURES variable, 243, 250
patching, 237 kernel-module-split class, 254
Kernel recipes, building from Yocto Project KERNEL_PATH variable, 254
repositories KERNEL_SRC variable, 254
base branches, 239–240 keyboard feature, 178
branches, 239–244 KFEATURE_COMPATIBILITY variable, 245
BSP branches, 240 KFEATURE_DESCRIPTION variable, 245
BSP collection description, 246–247 Kickstart file directives, 295–297
configuration collection description, 245 Kickstart files, 293–295
description files, 244 klibc, C library, 143
feature collection description, 246 KMACHINE variable, 243–244
in-recipe space metadata, 247–248 KMETA variable, 243
in-tree metadata, 248–250 ktypes subdirectory, 249
kernel infrastructure, 238–244 kver file, 249
kernel type collection description, 246
LTSI (Long-Term Support Initiative), L
250–251 --label parameter, 296
master branch, 239 Languages and locales, configuring, 162
meta branch, 240 LatencyTOP, 302
metadata application, 250 latest file, 364
metadata organization, 247–250 latest.pkg_* files, 364
metadata syntax, 244–247 Launching a build, 23
orphan branches, 240, 250 Layer configuration file, 61–63, 280
overview, 238 Layer layout
patch collection description, 245–246 OpenEmbedded system, 53–55
Kernel recipes, configuration Yocto Project BSPs, 277–278
configuration fragments, 228–231 Layer management, Toaster, 357
menu configuration, 227–228 layer.conf file, 40, 54–55
merging partial configurations, 228–231 LAYER_CONF_VERSION variable, 175
overview, 226–227 Layers
Kernel recipes, out-of-tree modules base layers for OpenEmbedded system, 47
build targets, 254 BitBake, 27
developing a kernel module, 251–254 configuration, OpenEmbedded workf low,
including with the root filesystem, 40
256–257 creating, OpenEmbedded system, 56
install targets, 255 debugging, 122–124
kernel source directory, 254 definition, 32
license file, 255 f lattening hierarchy, 124
module autoloading, 257 listing, 123
subdirectory structure, 255 metadata reference, 404–414
third-party modules, 254–256 LD variable, 308
Kernel space, 129 LDFLAGS variable, 193, 308
Kernel type collection description, kernel LIBC (C Standard Library), 142
recipes, 246 LICENSE file, 48–49, 337
442 Index

License files portability, 1

kernel recipes, 255 real time operation, 2
Yocto Project BSPs, 278 Linux architecture. See also Bootloaders.
LICENSE variable, 190, 201, 337–338 C standard libraries, 142–143
LICENSE_FLAGS variable, 339 core computer resources, 135
LICENSE_FLAGS_WHITELIST variable, 339 CPU, 135
Licensing and compliance. See also Open dispatching, 135
source licenses. I/O devices, 135
Android devices, 336 Linux vs. GNU/Linux, 127–128
Apache Licenses, 12 memory, 135
attribution, 10 overview, 128–129
blacklisting licenses, 340 privileged mode, 129
BSD (Berkeley Software Distribution), 10 restricted mode, 129
commercially licensed packages, 339 scheduling, 135
common licenses, 338–339 unrestricted mode, 129
conveyance, 10 user mode, 129
derivative works, 10 user space, 140
EULA (End-User License Agreement), 335 Linux architecture, kernel
filtering licenses, 342–343 architecture-dependent code, 136
first open source, 10 bootstrap loader, 140
GPL (GNU General Public License), 10 default page size, 137–138
license deployment, 340 device drivers, 136
license manifests and texts, 341 interprocess communication, 139
license naming conventions, 201 kernel space, 129
license tracking, 337–338 memory management, 136–137
managing source code, 341–343 microkernels, 135
multiple license schemes, 336–337 monolithic kernels, 135
OSI (Open Source Initiative), 336 network stack, 138–139
overview, 335–337 primary functions, 134
permissive licenses, 10 process management, 138
Poky Linux, 48–49 SCI (system call interface), 139–140
recipe layout, 190 slab allocator, 137
recipes, 201–202 socket layer, 138–139
self-perpetuating licenses, 10 startup, 140–141
SPDX (Software Package Data Exchange), subsystems, 136–140
337 system call slot, 139
LIC_FILES_CHKSUM variable, 190, 201, 235, threads, 138
237, 337–338 VFS (virtual filesystem), 137–138
Life cycle management, embedded Linux, 8 virtual addressing, 136–137
LILO (LInux LOader), 131, 132 Linux Foundation, 11
Linux Linux kernel recipes, Yocto Project BSPs,
CGL (Carrier-Grade Linux), 2 282
for embedded devices, 2. See also LInux LOader (LILO), 131, 132
Embedded Linux. Linux Standard Base (LSB), 12–13
filesystem, 2 Linux Trace Toolkit—Next Generation
vs. GNU/Linux, 127–128 (LTTng), 303
MMU (memory management unit), 2 LINUX_KERNEL_TYPE variable, 243
 Index 443

LINUX_RC variable, 236 Main tab, 326

LINUX_VERSION variable, 235, 237, 242 main.c file, 141
Listing MAINTAINER variable, 173
changed components, 50 Maintainers file, Yocto Project BSPs, 279
recipes, 123 Make build system, 205
tasks, 116–117 make gconfig command, 227
listtasks command, 107, 116–117 make menuconfig command, 227
Loaders, 129 make xconfig command, 227
local.conf file, 41–42 Makefile-based ADT applications, 315–316
LOCALCONF_VERSION variable, 175 Makefile-based recipe package, example,
localdir parameter, 92 213–215
log directory, 52 Man pages. See Documentation and man
Log files pages.
cooker, 110–112 Manuals. See Documentation and man pages.
general, 110–112 Master branch, kernel recipes, 239
tasks, 112–114 Matchbox, description, 27
LOG_DIR variable, 110 md5sum parameter, 89
log.do files, 112 Memory
Logging, cooker process information, 52 description, 135
Logging statements Linux architecture, 135
message severity, 114–115 virtual, 135
Python example, 115 Yocto Projects, 16
shell example, 115–116 Memory management
LSB (Linux Standard Base), 12–13 cross-prelinking memory addresses, 27
LTSI (Long-Term Support Initiative), 13, kernel function, 8
250–251 Linux kernel, 136–137
LTTng (Linux Trace Toolkit—Next prelinking memory addresses, 27
Generation), 303 Memory management unit (MMU), 2
menuconfig command, 6
M Meta branch, kernel recipes, 240
Machine configuration, OpenEmbedded meta directory, 49
workf low, 42 meta metadata layer, 47
Machine configuration files, Yocto Project meta [-xxxx] variable, 112
BSPs, 280–281 Metadata. See also BitBake metadata.
MACHINE variable, 22, 112 analyzing, 119120
Machine-dependent packaging, 210 build, 191–193
MACHINE_ESSENTIAL_EXTRA_RDEPENDS caching, 52
variable, 256 core collection for OpenEmbedded build
MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS system, 27
variable, 256 definition, 32
MACHINE_EXTRA_RDEPENDS variable, 256 descriptive, 189
MACHINE_EXTRA_RRECOMMENDS variable, displaying, 67
256–257 executable, 42
MACHINE_FEATURES variable, 178–179 layer structure, 53–56
MACHINEOVERRIDES variable, 264 layers, creating, 50
Machines, metadata reference, 415–428 licensing, 190
Main subtab, 329 package manager, 189–190
444 Index

Metadata (continued) downloading BitBake source, 94–95

packaging, 193–194 postmirrors, 367
runtime, 194 source mirrors, 366–368
syntax, kernel recipes, 244–247 MIRRORS variable, 94–95, 174
Metadata application, kernel recipes, 250 MIT License, 377
Metadata files. See OpenEmbedded MKTEMPCMD variable, 106
workf low, metadata files. MKTEMPDIRCMD variable, 106
Metadata layers MMU (memory management unit), 2
BitBake, 31 Mobile phones
meta layer, 47 embedded distributions for, 4
meta-yocto layer, 47 tools and utilities, 7
meta-yocto-bsp layer, 47 Modularity, embedded Linux, 3
OE (OpenEmbedded) Core, 31 module parameter, 92
OpenEmbedded system architecture, 49 module_do_install task, 254
Metadata organization, kernel recipes, Monitors, 129
247–250 Monolithic kernels, 135
Metadata reference musl, C library, 143
layers, 404–414
machines, 415–428 N
meta-fsl-arm BSP layer, 276 -n parameter, 293
meta-fsl-ppc BSP layer, 276 Name (key) expansion, 86
meta-hob directory, 49 name parameter, 89–90
meta-intel BSP layer, 276 Naming conventions, BitBake variables, 72
meta-intel-galileo BSP layer, 276 Narcissus, 4–5
meta-intel-quark BSP layer, 276 NATIVELSBSTRING variable, 112
meta-minnow BSP layer, 276 --native-sysroot parameter, 293
meta-raspberrypi BSP layer, 276 Network stack, Linux kernel, 138–139
meta-renesas BSP layer, 276 Networking, embedded Linux, 3
meta-selftest directory, 49 Newlib, C library, 143
meta-skeleton directory, 49 NFS (Network File System), 332
meta-ti BSP layer, 276 nfs feature, 178
meta-xilinx BSP layer, 276 nfs-server feature, 154
meta-yocto directory, 49 NM variable, 309
meta-yocto metadata layer, 47 nocheckout parameter, 91
meta-yocto-bsp directory, 49 Non-stripped binary information, 311
meta-yocto-bsp metadata layer, 47 norecurse parameter, 92
meta-zynq BSP layer, 276 --no-setscene option, 65, 66
method parameter, 92 --no-table parameter, 296
Microkernels, 135 Note message severity, 114–115
migrate command, 354
Minicom, 270–271 O
MinnowBoard Max development board, 275 -o parameter, 284, 292–293
Mirror sites, 366 OBJCOPY variable, 309
Mirrors OBJDUMP variable, 309
configuring, 175 Object-oriented mapping (ORM), 345–346
creating, 95 Object-relational model category, Toaster,
definition, 43 350–351
 Index 445

ODROID-XU4 development board, 275 OpenEmbedded (OE) Core

OE (OpenEmbedded) Core definition, 32
definition, 32 description, 27
description, 27 metadata layer, 31, 53–56
metadata layer, 31, 53–56 OpenEmbedded system
OECORE_ACLOCAL_OPTS variable, 309 aligned development, 30
OECORE_DISTRO_VERSION variable, 309 build environment structure, 50–53
OECORE_TARGET_SYSROOT variable, 309 caching metadata, 52
oe-init-build-env script, 20, 46, 49 cooker process logging information, 52
oe-init-build-env-memres script, 49 core collection of metadata, 27
OELAYOUT_ABI variable, 175 deployment output, directory for, 52
OE_TERMINAL variable, 121, 227 history of Yocto Project, 29, 30–31
OGIT_MIRROR_DIR parameter, 371 launching Hob, 50
OGIT_TRASH_CRON_TIME parameter, 371 layer creation, 56
OGIT_TRASH_DIR parameter, 371 layer layout, 53–55
OGIT_TRASH_NICE_LEVEL parameter, 371 listing changed components, 50
--ondisk parameter, 296 metadata layer structure, 53–56
--ondrive parameter, 296 metadata layers, creating, 50
Online image assembly, 4–5 OE Core layer, 53–56
On-target execution, 310 overview, 7
Open firmware. See Device trees. QEMU emulator, launching, 50
Open Package Management (opkg), 162–163 recipes, creating, 50
Open Services Gateway Initiative (OSGi), 317 relationship to Yocto Project, 30–31
Open Source Initiative (OSI), 336 removing obsolete directories, 50
Open source licenses. See also Licensing and root filesystems, 52
compliance. shared software packages, directory for, 52
Apache License Version 2.0, 397–401 shared state manifest files, 52
BSD (Berkeley Software Distribution), 10 storing build statistics, 52
vs. commercial licenses, 10 task completion tags and signature data, 52
GNU GPL (General Public License), 10 tmp directory layout version number, 52
GNU GPL (General Public License) working subdirectories, 52
Version 2, 377–384 Yocto Project BSP layer, creating a, 50
GNU GPL (General Public License) Yocto project kernel recipes, configuring, 50
Version 3, 384–397 OpenEmbedded system architecture
MIT License, 377 base layers, 47. See also specific layers.
overview, 9–11 basic components, 45–46
permissive licenses, 10 build system structure, 47–50
self-perpetuating licenses, 10 integration and support scripts, 50
Open source software, packaging, 38–39 meta metadata layer, 47
Open source software packages, workf low metadata layers, 49
building, 38 meta-yocto metadata layer, 47
configuration, 37–38 meta-yocto-bsp metadata layer, 47
extracting source code, 36 OpenEmbedded workf low, diagram, 40
fetching source code, 36 OpenEmbedded workf low, metadata files
installation, 38 build environment configuration, 41
packaging, 38–39 build environment layer configuration, 41
patching, 37 configuration files, 40
446 Index

OpenEmbedded workf low, metadata files P

(continued) P variable, 106
distribution configuration, 42 Package groups
layer configuration, 40 core images, 155–159
machine configuration, 42 naming conventions, 159
recipes, 42–43 predefined, 155–158
OpenEmbedded workf low, process steps recipes, 158–159
compile, 44 Package management
configuration, 44 choosing, 162–163
fetching source code, 43–44 core image configuration, 162–163
image creating, 45 core image options, 162–163
installation, 44 dpkg (Debian Package Management),
output analysis, 44 162–163
packaging, 44 opkg (Open Package Management),
patching source code, 44 162–163
SDK generation, 45 RPM (Red Hat Package Manager),
unpacking source code, 44 162–163
opengl feature, 178 tar, 162
OpenMoko, 7 Package management systems. See also specific
OpenSIMpad, 7 systems.
OpenSUSE, setting up a build host, 19 definition, 33
OpenWrt distribution, 5 most common, 39
OpenZaurus project, 7, 28 shared software packages, directory for, 52
opkg (Open Package Management), 39, splitting files into multiple packages, 44
162–163 Package recipes, Toaster, 357
OProfile, 302 Package splitting, 207–209
OPTIMIZED_GIT_CLONE parameter, 371 PACKAGE_ARCH variable, 193
Optional inclusion, 77 PACKAGE_BEFORE_PN variable, 193
Organizations PACKAGE_CLASSES variable, 162
Apache Software Foundation, 11–12 PACKAGECONFIG variable, 192
CE (Consumer Electronics) Workgroup, PACKAGE_DEBUG_SPLIT_STYLE variable, 194
13 package-depends.dot file, 67, 121
CELF (Consumer Electronics Linux packagegroup class, 158–159
Forum), 13 packagegroup- predefined packages, 155–158
Eclipse Project, 12 package-management feature, 153
Linux Foundation, 11 Packages
LSB (Linux Standard Base), 12–13 architecture adjustment, 210
ORM (object-oriented mapping), 345–346 core images, 149–150
Orphan branches, kernel recipes, 240, 250 definition, 32
Orthogonality, 264 dependencies, graphing, 67–68
OSGi (Open Services Gateway Initiative), 317 deploying, 222
OSI (Open Source Initiative), 336 directives for building. See Recipes.
--outdir parameter, 284, 292–293 managing build package repositories, 29
Output analysis, OpenEmbedded workf low, omitting common packages, 68
44 QA, 209–210
--overhead-factor parameter, 296 removing, 222
OVERRIDES variable, 75, 106 PACKAGES variable, 193, 208
 Index 447

PACKAGESPLITFUNCS variable, 194 Plausibility checking, 209–210

Packaging Plus equal (+=), appending variables, 74
architecture-independent, 210 PN variable, 100, 106, 191
machine-dependent, 210 pn-buildlist file, 121
open source software, 38–39 pn-depends.dot file, 67, 121
OpenEmbedded workf low, 44 poky distribution configuration, 169
recipe build output, 207–210 Poky distribution policy, 170–176
Parallel build failure, 204 Poky Linux
Parallelism options, 22 architecture, 46
PARALLEL_MAKE variable, 22 build system. See Yocto Project Build
Parentheses (()), in license names, 201 Appliance.
partition directive, 295–296 definition, 33
--part-type parameter, 296 description, 28
Passwords history of Yocto Project, 29–30
Autobuilder, 369–370 installing, 19–20
shell and SSH logins, 161 licensing information, 48–49
user accounts, 166–167 obtaining, 17–18
Patch collection description, kernel recipes, poky-bleeding distribution configuration, 169
245–246 poky.conf file, 42, 170–176
patch command, 244, 285–286 poky-lsb distribution configuration, 169
patches subdirectory, 249 poky-tiny distribution configuration, 169
Patching populate_sdk_base_bbclass class, 154
BSP source code, 262 port parameter, 92
kernel recipes, 231–233, 237 Portage, 29
open source software, 37 Postmirrors, 43, 367
recipe source code, 201 Post-mortem debugging, 311
source code, OpenEmbedded workf low, 44 --postread option, 64, 68–69
PATH variable, 309 PowerTOP, 302
pci feature, 178 ppp feature, 178
pcmcia feature, 178 PR variable, 100, 106, 191
Percent sign (%), in BitBake version strings, 102 Prebuilt binaries, Yocto Project BSPs, 280
Perf, 303 PREFERRED_VERSION variable, 102
Performance information, Toaster, 357 Prelinking memory addresses, 27
Period. See Dot. PREMIRRORS variable, 94–95, 174
PERSISTENT_DIR variable, 106 _prepend operator, 75, 84–85
PF variable, 106 Prepending
Pipe symbol (|) BitBake variables, 74–75, 76
concatenating license names, 201, 337 functions, 84–85
separating kernel names, 237 Prepends, recipe layout, 194
PKG_CONFIG_PATH variable, 309 PRIORITY variable, 190
PKG_CONFIG_SYSROOT variable, 309 Privileged mode, 129
pkg_postinst_ script, 210 Process management, Linux kernel, 138
pkg_postrm_ script, 210 Processes
pkg_preinst_ script, 210 definition, 138
pkg_prerm_ script, 210 interprocess communication, 139
PKI (public key infrastructure), 360 vs. threads, 138
Plain message severity, 114–115 Project management, Toaster, 356
448 Index

Project-specific BitBake variables, 104 Question mark equal (?=), default value
protocol parameter assignment, 73
Git fetcher, 90 Question marks equal (??=), weak default
SVN (Subversion) fetcher, 92 assignment, 73
PROVIDES variable, 99–100, 106, 191
Provisioning R
BitBake dependency handling, 99–101 -r parameter, 64, 68–69, 293
explicit, 100 RANLIB variable, 309
implicit, 99–100 Raspberry Pi 2 B development board, 275
symbolic, 100–101 Raw mode, 292–293
Pseudo, description, 28 RCONFLICTS variable, 195
ptest-pkgs feature, 154 RDEPENDS variable, 101, 194
Public key infrastructure (PKI), 360 --read option, 64, 68–69
PUBLISH_BUILDS parameter, 371 README file, Yocto Project BSPs, 279
PUBLISH_SOURCE_MIRROR parameter, 371 README.sources file, Yocto Project BSPs, 280
PUBLISH_SSTATE parameter, 371 read-only-rootfs feature, 153
PV variable Real time operation, Linux, 2
build metadata, 191 Real-time systems, hard vs. soft, 2
building kernel recipes, 237 rebaseable parameter, 91
explicit provisioning, 100 Recipe files, 70–71, 281–282
runtime variable, 106 Recipes. See also Kernel recipes.
setting package version number, 243 appending files, listing, 123
PXELINUX bootloader, 133 building, 222
Python definition, 33
logging statements, example, 115 extending core images, 152–153
variable expansion, 74 filenames, 186
version verification, 19 formatting source code, 195
Python functions. See also Functions. listing, 123
accessing BitBake variables, 83 listing tasks, 116–117
anonymous, 80 metadata dependent, listing, 124
executable metadata, 79–80 OpenEmbedded workf low, 42–43
formatting guidelines, 196 package groups, 158–159
global, 80 tools and utilities, 7
python keyword, 79–80 updating, 223–224
Python virtual environment, Toaster, Recipes, creating
347–348 architecture-independent packaging, 210
PYTHONHOME variable, 309 common failures, 204
compiling source code, 203–204
Q configuring source code, 202–203
QEMU emulator custom installation scripts, 210–211
application development with, 331–333 establishing the recipe, 198–199
launching, 50 fetching source code, 199–200
launching applications, 333 host leakage, 204
purpose of, 302 installing the build output, 204–206
terminating, 24 licensing information, 201–202
qt4-pkgs feature, 154 machine-dependent packaging, 210
 Index 449

missing headers or libraries, 204 Red Hat Package Manager (RPM), 29, 39,
overview, 196–198 162–163
package architecture adjustment, 210 RedBoot bootloader, 131, 134
package QA, 209–210 Release schedule, Yocto Project, 17
package splitting, 207–209 Releases, code names, 277
packaging the build output, 207–210 Relevant bodies. See Organizations.
parallel build failure, 204 Remote on-target debugging, 311–315
patching source code, 201 _remove operator, 75
plausibility and error checking, 209–210 Removing. See also Deleting.
from a script, 50 obsolete directories, 50
setup system services, 206–207 packages, 222
skeleton recipe, 198 values from BitBake metadata, 75
source configuration systems, 203 required directive, 77
systemd, setting up, 207 Required inclusion, 77
SysVinit, setting up, 206–207 Restricted mode, 129
tools for. See Devtool. rev parameter, 92
unpacking source code, 200 Root filesystems
variants, 211 OpenEmbedded system, 52
workf low, 197 tweaking, 167–169
Recipes, examples types of, 164–166
Autotools-based package, 216–217 Root user accounts, 167
C file software, 212–213 --rootfs-dir parameter, 293
CMake-based package, 215–216 ROOTFS_POSTPROCESS_COMMAND, 167–169
externally built package, 217–218 Routing network traffic, distributions for, 5
makefile-based package, 213–215 Royalties, embedded Linux, 2
Recipes, layout RPM (Red Hat Package Manager), 29, 39,
appends, 194 162–163
build metadata, 191–193 RPROVIDES variable, 195
class extensions, 194 RRECOMMENDS variable, 194
code sample, 187–189 RREPLACES variable, 195
descriptive metadata, 189 rsh parameter, 92
includes, 190 RSUGGESTS variable, 194
inheritance directives, 190 run.do file, 118–119
licensing metadata, 190 runqemu script, 50
overview, 186 Runtime dependencies, 99
package manager metadata, 189–190
packaging metadata, 193–194 S
prepends, 194 -s parameter, 284, 292
runtime metadata, 194 S variable, 106, 191, 236
task overrides, 194 SANITY_TESTED_DISTROS variable, 176
variants, 194 saved_tmpdir file, 52
recipes-bsp directory, 281 Scalability, embedded Linux, 3
recipes-core directory, 281 Scaling to teams. See Autobuilder; Build
recipes-graphics directory, 281 history; Mirrors; Toaster.
recipes-kernel directory, 282 Scheduling, 135, 368
Red Hat bootloader. See RedBoot bootloader. SCI (system call interface), 139–140
450 Index

Scope, BitBake variables, 72 --skip-build-check parameter, 292

Scripts. See also specific scripts. -skip-git-check parameter, 284
BitBake, 27 Slab allocator, 137
integration and support, 50 smbfs feature, 178
SDK (software development kit). See also ADT Socket layer, 138–139
(Application Development Toolkit). Soft real-time systems, 2
generating, 45 Software development kit (SDK). See also
in OpenEmbedded workf low, 45 ADT (Application Development Toolkit).
SDKIMAGE_FEATURES variable, SDK generating, 45
information, 365 in OpenEmbedded workf low, 45
sdk-info.txt file, 365 Software Package Data Exchange (SPDX), 337
SDKMACHINE variable, SDK information, 365 Software requirements, Yocto Project, 17
SDK_NAME variable, 173, 365 Source code. See also Open source software.
SDKPATH variable, 173 configuring, tools and utilities for, 37–38
SDKSIZE variable, SDK information, 365 embedded Linux, 3
SDKTARGETSYSROOT variable, 309 extracting, 36
SDK_VENDOR variable, 173 fetching, 36, 43–44
SDK_VERSION variable, 173, 365 managing licensing and compliance,
SECTION variable, 189 341–343
Semicolon (;), command separator, 167 OpenEmbedded workf low, 43–44
Serial-to-USB cable, 270 patches, 262
set substitute-path command, 330 patching, 44
set sysroot command, 330 unpacking, 44
Set-scene, 64 Source mirrors, 366–368
setup.py script, 60–61 --source parameter, 295–296
setVar function, 83 Source tab, 330
sha256sum parameter, 89 SPDX (Software Package Data Exchange),
Shared Libraries subtab, 329 337
Shared software packages, directory for, 52 splash feature, 153
Shared state cache, specifying path to, 22 SquashFS compression, 165
Sharing SquashFS-xz compression, 165
metadata settings, 76–77 SRCDATE variable, 191
source packages. See Mirrors. SRCREV variable, 106, 237, 242
Sharp Zaurus SL-5000D, 28 SRC_URI variable
Shell functions build metadata, 191
accessing BitBake variables, 82–83 building kernel recipes, 236, 237, 242
executable metadata, 79 fetching source code, 199–200
formatting guidelines, 196 runtime variable, 106
Shell variables, setting, 20–22 SSH server configuration, 168
show-appends command, 123 ssh-server-dropbear feature, 154
show-cross-depends command, 124 ssh-server-openssh feature, 154
show-layers command, 123 sstate-control directory, 52
show-overlayed command, 123 SSTATE_DIR variable, 22
show-recipes command, 123 staging subdirectory, 249
Single quote ('), variable delimiter, 72 STAGING_KERNEL_DIR variable, 254
sites-config-* files, 307 Stallman, Richard, 10
--size parameter, 296 stamps directory, 52
 Index 451

Standard runtime BitBake variables, 104 Target Explorer, 324–325

Standards, LSB (Linux Standard Base), 12–13 TARGET_ARCH variable, 106
State manifest files, shared, 52 TARGET_FPU variable, 112
staticdev-pkgs feature, 154 TARGET_PREFIX, CROSS COMPILE variable, 309
String literals, BitBake variables, 72 TARGET_SYS variable, 112
STRIP variable, 309 TARGET_VENDOR variable, 173
Sudo configuration, 168 tar.gz compression, 164
Sudoer privileges, 167 tar.lz3 compression, 164
SUMMARY variable, 189 tar.xz compression, 164
SUSE distribution, 5, 19 Task execution
SVNDIR variable, 106 dependencies, 117–118
Swabber, description, 28 listing tasks, 116–117
syncdb command, 354 script files, 118–119
SYSLINUX bootloader, 131, 133 specific tasks, 118
sysroots directory, 52 troubleshooting, 116–119
System call interface (SCI), 139–140 Task overrides, recipe layout, 194
System call slot, 139 task-depends.dot file, 67, 121
System calls Tasks
kernel function, 8 BitBake metadata, 81–82, 107
tracing, 139–140 clean, 112
System manager completion tags and signature data, 52
core image configuration, 179 defining, 81–82
default, 179 definition, 33
System root, ADT applications, 302 executing specific, 66
System Tap, 303 obtaining and restoring output, 64
systemd, setting up, 207 TCF network protocol, 323
systemd feature, 178 TCLIBC variable, 174
systemd system manager, 178 TCLIBCAPPEND variable, 174
systemd-boot bootloader, 131, 134 TCMODE variable, 174
SYSTEMD_PACKAGES variable, 207 terminal class, 227
SYSTEMD_SERVICE variable, 207 Terminal emulation, 270–272
SysVinit, setting up, 206–207 Testing, core images with QEMU, 150–151
sysvinit feature, 178 Threads
SysVinit system manager, 179 definition, 138
vs. processes, 138
T Tilde (~), in variable names, 72
T variable, 106 --timeout parameter, 297
Tablet computers, embedded distributions Timing error, 2
for, 4 tmp directory layout version number, 52
tag parameter TMPBASE variable, 106
CVS (Current Versions System) fetcher, 92 TMPDIR variable, 106
Git fetcher, 90 TMP_DIR variable, 22
Tanenbaum, Andrew S., 135 Toaster
tar, package management, 162 administering the Django framework,
tar compression, 164 350–351
tar.bz2 compression, 164 Analysis mode, 346, 348
target directory, 365 authentication category, 350
452 Index

Toaster (continued) build history, 151–152

build configuration, 356 Buildroot, 6
build control category, 350 BusyBox, 6
build log, 357 for command line utility applications, 6
Build mode, 346–347, 348, 349 configuring source code, 37–38
build statistics, 357 creating bootable media images, 291
configuration, 349–351 creating Yocto Project BSPs, 282–289
description, 28, 345 cross-compilation toolchain, building, 6
image information, 357 crosstool.ng, 6
image targets, 357 embedded Linux systems, building, 6–7
installing requirements, 348 Linux distributions, building, 6
layer management, 357 Minicom, 270–271
local Toaster development, 348–349 for mobile phones, 7
object-relational model category, 350–351 OpenEmbedded, 7
operational modes, 346–347 recipes, 7
ORM (object-oriented mapping), 345–346 terminal emulation, 270–271
overview, 345–346 tools configuration data, 7
package recipes, 357 uClibc, 6
performance information, 357 user interface configuration, 6
project management, 356 verifying and comparing core images,
Python virtual environment, 347–348 151–152
setting the port, 349 wic, 291
setup, 347–348 yocto-bsp, 283–284
web user interface, 356–358 yocto-kernel, 284–286
Toaster, production deployment Tools configuration data, 7
installation and configuration, 352–354 tools-debug feature, 154
installing the build runner service, 355–356 tools-profile feature, 154
maintaining your production interface, 356 tools-sdk feature, 154
preparing the production host, 351–352 tools-testapps feature, 154
web server configuration, 354–355 Top-down approach to embedded Linux, 8–9
WSGI (Web Server Gateway Interface), Torvalds, Linus
354–355 creating Git, 236
Toolchains on Linux portability, 1
in ADT applications, 307–310 on microkernel architecture, 135
building a toolchain installer, 304 Tracing library functions, 330–331
configuring, 174–175 Tracing system calls, 139–140
cross-canadian toolchain binaries, 306 Tracking. See Build history.
cross-compilation, building, 6 Troubleshooting. See also Debugging; Log
cross-development, 32, 302 files; Logging statements.
installing, 305–307 analyzing metadata, 119120
Tooling, embedded Linux, 3 debugging layers, 122–124
Tools and utilities dependency graphs, 121–122
ADT profiling tools, 302–303 development shell, 120–121
Autotools, 37–38 task execution, 116–119
Baserock, 6 tracing system calls, 139–140
bitbake-layers, 122–124 TUNE_ARCH , 289
BSP development tools, 262 TUNE_ASARGS, 290
 Index 453

TUNE_CCARGS, 290 --use-uuid parameter, 296

tune-core2.inc file, 289 --uuid parameter, 296
tune-corei7.inc file, 289
TUNE_FEATURES, 289–290 V
TUNE_FEATURES variable, 112 Variables, listing, 120–121. See also BitBake
tune-i586.inc file, 289 metadata syntax, variables; specific
TUNE_LDARGS, 290 variables.
TUNE_PKGARCH , 290 Variants, 194, 211
Twisted Python networking engine, 368–369 Verifying core images, 151–152
version-* files, 307
U --version option, 64–65
ubi compression, 165 Version selection, BitBake, 102
ubifs compression, 165 Versions, displaying, 65
U-Boot bootloader, 131, 133 VFS (virtual filesystem), 137–138
Ubuntu distribution, 5, 19 Virtual addressing, 136–137
uClibc, C library, 6, 142 Virtual environments, 28
Underscore ( _ ) Virtual memory, 135
conditional variable setting, 76 virtualenv command, 347–348
in variable names, 72 Vmdk compression, 165
Unpacking
recipe source code, 200 W
source code, OpenEmbedded workf low, WandBoard development board, 275
44 Warn message severity, 114–115
Unrestricted mode, 129 WARN_QA variable, 176, 209
Upstream, definition, 33 wayland feature, 178
usbgadget feature, 178 Web user interface, Toaster, 356–358
usbhost feature, 178 wget command, 60
User accounts wic tool, 291
adding, 166–167 wifi feature, 178
deleting, 166–167 Window manager, 27
managing, 166–167 work directory, 52
modifying, 166–167 WORKDIR variable, 107
root, 167 Worker configuration file, 372–373
sudoer privileges, 167 Working subdirectories, OpenEmbedded
User groups system, 52
adding, 166–167 work-shared directory, 52
deleting, 167 workspace layers
modifying, 167 adding recipes, 220–221, 223
User interface configuration, tools and creating, 219–220
utilities, 6 displaying information about, 223
User mode, 129 WSGI (Web Server Gateway Interface),
User names, Autobuilder, 369–370 354–355
User space, 140
useradd command, 166–167 X
userdel command, 166–167 x11 feature, 154, 178
Userland. See User space. x11-base feature, 154
usermod command, 166–167 xconfig command, 6
454 Index

Y Yocto Project Application Developer’s Guide, 304

Yocto Project. See also BSPs (board support Yocto Project Autobuilder. See Autobuilder.
packages); Kernel recipes, building from Yocto Project BSPs
Yocto Project repositories. classes, 281
aligned development, 30 display support recipes, 281
BSP layer, creating, 50 layer configuration file, 280
building and installing software packages, 29 layer layout, 277–278
definition, 15 license files, 278
definition of common terms, 31–33. See Linux kernel recipes, 282
also specific terms. machine configuration files, 280–281
kernel recipes, configuring, 50 maintainers file, 279
layers, 276–278 prebuilt binaries, 280
overview, 7 README file, 279
reference distribution. See Poky Linux. README.sources file, 280
release schedule, 17 recipe files, 281–282
tools and utilities, 17–18 Yocto Project BSPs, creating
Yocto Project, getting started approaches to, 282
BitBake working directory, specifying, 22 kernel configuration options, 285
configuring a build environment, 20–23 kernel features, 285–286
disk space, 16 kernel patches, 285–286
hardware requirements, 16 tools for, 282–289
installing software packages, 19 workf low, 286–289
Internet connection, 16–17 Yocto Project BSPs, external
launching a build, 23 BSP layers, 276
location for downloads, specifying, 22 building with layers, 276–277
memory, 16 development boards, 272–276
obtaining tools, 17–18 overview, 272
parallelism options, 22 Yocto Project Build Appliance, 24–26
path to shared state cache, specifying, 22 Yocto Project Eclipse, 319–321. See also
prerequisites, 16–17 Eclipse IDE plugin.
setting shell variables, 20–22 Yocto Project family subprojects, 26–28. See
setting up the build host, 18–20 also specific subprojects.
software requirements, 17 Yocto Project Reference Manual, 209
target build machine type, selecting, 22 Yocto Projects, release code names, 277
verifying build results, 24 yocto-bsp create command, 284
without using a build host, 24–26 yocto-bsp list command, 283–284
Yocto Project, history of yocto-bsp script, 50
BitBake, 29 yocto-bsp tool, 283–284
ebuild, 29 yocto-controller/controller.cfg file, 372
emerge, 29 yocto-kernel config add command, 285
first Linux-based digital assistant, 28 yocto-kernel config list command, 285
OpenEmbedded project, 29, 30–31 yocto-kernel config rm command, 285
OpenZaurus project, 28 yocto-kernel feature add command, 286
Poky Linux, 29–30 yocto-kernel feature create command, 286
Portage, 29 yocto-kernel feature destroy command,
Sharp Zaurus SL-5000D, 28 286
 Index 455

yocto-kernel feature list command, 286 yocto-kernel patch rm command, 286

yocto-kernel feature rm command, 286 yocto-kernel script, 50
yocto-kernel features list command, 286 yocto-kernel tool, 284–286
yocto-kernel patch add command, 286 yocto-layer script, 50, 56
yocto-kernel patch list command, 285 yocto-worker/buildbot.tac file, 372–373