Yocto Project Development Manual

Scott Rifenbark

Intel Corporation

Permission is granted to copy, distribute and/or modify this document under the terms of the Creative Commons Attribution-Share Alike 2.0 UK: England & Wales as published by Creative Commons.

Manual Notes

  • This version of the Yocto Project Development Manual is for the 2.2.4 release of the Yocto Project. To be sure you have the latest version of the manual for this release, go to the Yocto Project documentation page and select the manual from that site. Manuals from the site are more up-to-date than manuals derived from the Yocto Project released TAR files.

  • If you located this manual through a web search, the version of the manual might not be the one you want (e.g. the search might have returned a manual much older than the Yocto Project version with which you are working). You can see all Yocto Project major releases by visiting the Releases page. If you need a version of this manual for a different Yocto Project release, visit the Yocto Project documentation page and select the manual set by using the "ACTIVE RELEASES DOCUMENTATION" or "DOCUMENTS ARCHIVE" pull-down menus.

  • To report any inaccuracies or problems with this manual, send an email to the Yocto Project discussion group at yocto@yoctoproject.com or log into the freenode #yocto channel.

Revision History
Revision 1.1 6 October 2011
The initial document released with the Yocto Project 1.1 Release.
Revision 1.2 April 2012
Released with the Yocto Project 1.2 Release.
Revision 1.3 October 2012
Released with the Yocto Project 1.3 Release.
Revision 1.4 April 2013
Released with the Yocto Project 1.4 Release.
Revision 1.5 October 2013
Released with the Yocto Project 1.5 Release.
Revision 1.5.1 January 2014
Released with the Yocto Project 1.5.1 Release.
Revision 1.6 April 2014
Released with the Yocto Project 1.6 Release.
Revision 1.7 October 2014
Released with the Yocto Project 1.7 Release.
Revision 1.8 April 2015
Released with the Yocto Project 1.8 Release.
Revision 2.0 October 2015
Released with the Yocto Project 2.0 Release.
Revision 2.1 April 2016
Released with the Yocto Project 2.1 Release.
Revision 2.2 October 2016
Released with the Yocto Project 2.2 Release.
Revision 2.2.1 January 2017
Released with the Yocto Project 2.2.1 Release.
Revision 2.2.2 June 2017
Released with the Yocto Project 2.2.2 Release.
Revision 2.2.3 December 2017
Released with the Yocto Project 2.2.3 Release.
Revision 2.2.4 April 2018
Released with the Yocto Project 2.2.4 Release.

Table of Contents

1. The Yocto Project Development Manual
1.1. Introduction
1.2. What This Manual Provides
1.3. What this Manual Does Not Provide
1.4. Other Information
2. Getting Started with the Yocto Project
2.1. Introducing the Yocto Project
2.2. Getting Set Up
2.3. Building Images
2.4. Using Pre-Built Binaries and QEMU
3. The Yocto Project Open Source Development Environment
3.1. Open Source Philosophy
3.2. Using the Yocto Project in a Team Environment
3.2.1. System Configurations
3.2.2. Source Control Management (SCM)
3.2.3. Autobuilders
3.2.4. Policies and Change Flow
3.2.5. Summary
3.3. Yocto Project Source Repositories
3.4. Yocto Project Terms
3.5. Licensing
3.6. Git
3.6.1. Repositories, Tags, and Branches
3.6.2. Basic Commands
3.7. Workflows
3.8. Tracking Bugs
3.9. How to Submit a Change
3.9.1. Using Scripts to Push a Change Upstream and Request a Pull
3.9.2. Using Email to Submit a Patch
4. Common Development Models
4.1. System Development Workflow
4.1.1. Developing a Board Support Package (BSP)
4.1.2. Modifying the Kernel
4.2. Application Development Workflow Using an SDK
4.3. Modifying Source Code
4.3.1. Using devtool in Your Workflow
4.3.2. Using Quilt in Your Workflow
4.3.3. Finding Temporary Source Code
4.4. Image Development Using Toaster
4.5. Using a Development Shell
4.6. Using a Development Python Shell
5. Common Tasks
5.1. Understanding and Creating Layers
5.1.1. Layers
5.1.2. Creating Your Own Layer
5.1.3. Best Practices to Follow When Creating Layers
5.1.4. Enabling Your Layer
5.1.5. Using .bbappend Files
5.1.6. Prioritizing Your Layer
5.1.7. Managing Layers
5.1.8. Creating a General Layer Using the yocto-layer Script
5.2. Customizing Images
5.2.1. Customizing Images Using local.conf
5.2.2. Customizing Images Using Custom IMAGE_FEATURES and EXTRA_IMAGE_FEATURES
5.2.3. Customizing Images Using Custom .bb Files
5.2.4. Customizing Images Using Custom Package Groups
5.2.5. Customizing an Image Hostname
5.3. Writing a New Recipe
5.3.1. Overview
5.3.2. Locate or Automatically Create a Base Recipe
5.3.3. Storing and Naming the Recipe
5.3.4. Understanding Recipe Syntax
5.3.5. Running a Build on the Recipe
5.3.6. Fetching Code
5.3.7. Unpacking Code
5.3.8. Patching Code
5.3.9. Licensing
5.3.10. Dependencies
5.3.11. Configuring the Recipe
5.3.12. Compilation
5.3.13. Installing
5.3.14. Enabling System Services
5.3.15. Packaging
5.3.16. Sharing Files Between Recipes
5.3.17. Properly Versioning Pre-Release Recipes
5.3.18. Post-Installation Scripts
5.3.19. Testing
5.3.20. Examples
5.3.21. Following Recipe Style Guidelines
5.4. Adding a New Machine
5.4.1. Adding the Machine Configuration File
5.4.2. Adding a Kernel for the Machine
5.4.3. Adding a Formfactor Configuration File
5.5. Building Targets with Multiple Configurations
5.6. Working With Libraries
5.6.1. Including Static Library Files
5.6.2. Combining Multiple Versions of Library Files into One Image
5.6.3. Installing Multiple Versions of the Same Library
5.7. Enabling GObject Introspection Support
5.7.1. Enabling the Generation of Introspection Data
5.7.2. Disabling the Generation of Introspection Data
5.7.3. Testing that Introspection Works in an Image
5.7.4. Known Issues
5.8. Optionally Using an External Toolchain
5.9. Creating Partitioned Images
5.9.1. Creating Partitioned Images
5.9.2. Using OpenEmbedded Image Creator Wic to Generate Partitioned Images
5.10. Building an Initial RAM Filesystem (initramfs) Image
5.11. Configuring the Kernel
5.11.1. Using  menuconfig
5.11.2. Creating a  defconfig File
5.11.3. Creating Configuration Fragments
5.11.4. Fine-Tuning the Kernel Configuration File
5.11.5. Determining Hardware and Non-Hardware Features for the Kernel Configuration Audit Phase
5.12. Patching the Kernel
5.12.1. Create a Layer for your Changes
5.12.2. Finding the Kernel Source Code
5.12.3. Creating the Patch
5.12.4. Set Up Your Layer for the Build
5.12.5. Set Up for the Build
5.12.6. Build the Modified QEMU Kernel Image
5.12.7. Boot the Image and Verify Your Changes
5.13. Making Images More Secure
5.13.1. General Considerations
5.13.2. Security Flags
5.13.3. Considerations Specific to the OpenEmbedded Build System
5.13.4. Tools for Hardening Your Image
5.14. Creating Your Own Distribution
5.15. Creating a Custom Template Configuration Directory
5.16. Building a Tiny System
5.16.1. Overview
5.16.2. Goals and Guiding Principles
5.16.3. Understand What Contributes to Your Image Size
5.16.4. Trim the Root Filesystem
5.16.5. Trim the Kernel
5.16.6. Remove Package Management Requirements
5.16.7. Look for Other Ways to Minimize Size
5.16.8. Iterate on the Process
5.17. Building Images for More than One Machine
5.18. Working with Packages
5.18.1. Excluding Packages from an Image
5.18.2. Incrementing a Package Revision Number
5.18.3. Handling Optional Module Packaging
5.18.4. Using Runtime Package Management
5.18.5. Testing Packages With ptest
5.19. Working with Source Files
5.19.1. Setting up Effective Mirrors
5.19.2. Getting Source Files and Suppressing the Build
5.20. Building Software from an External Source
5.21. Selecting an Initialization Manager
5.21.1. Using systemd Exclusively
5.21.2. Using systemd for the Main Image and Using SysVinit for the Rescue Image
5.22. Selecting a Device Manager
5.22.1. Using Persistent and Pre-Populated/dev
5.22.2. Using devtmpfs and a Device Manager
5.23. Using an External SCM
5.24. Creating a Read-Only Root Filesystem
5.24.1. Creating the Root Filesystem
5.24.2. Post-Installation Scripts
5.24.3. Areas With Write Access
5.25. Performing Automated Runtime Testing
5.25.1. Enabling Tests
5.25.2. Running Tests
5.25.3. Exporting Tests
5.25.4. Writing New Tests
5.25.5. Installing Packages in the DUT Without the Package Manager
5.26. Debugging With the GNU Project Debugger (GDB) Remotely
5.27. Debugging with the GNU Project Debugger (GDB) on the Target
5.28. Debugging Parallel Make Races
5.28.1. The Failure
5.28.2. Reproducing the Error
5.28.3. Creating a Patch for the Fix
5.28.4. Testing the Build
5.29. Maintaining Open Source License Compliance During Your Product's Lifecycle
5.29.1. Providing the Source Code
5.29.2. Providing License Text
5.29.3. Providing Compilation Scripts and Source Code Modifications
5.30. Using the Error Reporting Tool
5.30.1. Enabling and Using the Tool
5.30.2. Disabling the Tool
5.30.3. Setting Up Your Own Error Reporting Server
6. Using the Quick EMUlator (QEMU)
6.1. Overview
6.2. Running QEMU
6.2.1. Setting Up the Environment
6.2.2. Using the runqemu Command
6.3. Running Under a Network File System (NFS) Server
6.3.1. Setting Up to Use NFS
6.3.2. Starting and Stopping NFS
6.4. Tips and Tricks