Yocto Project Development Tasks Manual

The Yocto Project

Copyright © 2010-2020, The Linux Foundation

<docs@lists.yoctoproject.org>

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.

Note

• This version of this manual is for the 3.1 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 (or any other Yocto Project) manual, send an email to the Yocto Project documentation mailing list at docs@lists.yoctoproject.org or log into the freenode #yocto channel.

Revision	Date	Note
1.1	October 2011	The initial document released with the Yocto Project 1.1 Release
1.2	April 2012	Released with the Yocto Project 1.2 Release.
1.3	October 2012	Released with the Yocto Project 1.3 Release.
1.4	April 2013	Released with the Yocto Project 1.4 Release.
1.5	October 2013	Released with the Yocto Project 1.5 Release.
1.6	April 2014	Released with the Yocto Project 1.6 Release.
1.7	October 2014	Released with the Yocto Project 1.7 Release.
1.8	April 2015	Released with the Yocto Project 1.8 Release.
2.0	October 2015	Released with the Yocto Project 2.0 Release.
2.1	April 2016	Released with the Yocto Project 2.1 Release.
2.2	October 2016	Released with the Yocto Project 2.2 Release.
2.3	May 2017	Released with the Yocto Project 2.3 Release.
2.4	October 2017	Released with the Yocto Project 2.4 Release.
2.5	May 2018	Released with the Yocto Project 2.5 Release.
2.6	November 2018	Released with the Yocto Project 2.6 Release.
2.7	May 2019	Released with the Yocto Project 2.7 Release.
3.0	October 2019	Released with the Yocto Project 3.0 Release.
3.1	April 2020	Released with the Yocto Project 3.1 Release.

Table of Contents

• 1. The Yocto Project Development Tasks Manual
  • 1.1. Welcome
  • 1.2. Other Information
• 2. Setting Up to Use the Yocto Project
  • 2.1. Creating a Team Development Environment
  • 2.2. Preparing the Build Host
    • 2.2.1. Setting Up a Native Linux Host
    • 2.2.2. Setting Up to Use CROss PlatformS (CROPS)
    • 2.2.3. Setting Up to Use Windows Subsystem For Linux (WSLv2)
  • 2.3. Locating Yocto Project Source Files
    • 2.3.1. Accessing Source Repositories
    • 2.3.2. Accessing Index of Releases
    • 2.3.3. Using the Downloads Page
    • 2.3.4. Accessing Nightly Builds
  • 2.4. Cloning and Checking Out Branches
    • 2.4.1. Cloning the poky Repository
    • 2.4.2. Checking Out by Branch in Poky
    • 2.4.3. Checking Out by Tag in Poky
• 3. Common Tasks
  • 3.1. Understanding and Creating Layers
    • 3.1.1. Creating Your Own Layer
    • 3.1.2. Following Best Practices When Creating Layers
    • 3.1.3. Making Sure Your Layer is Compatible With Yocto Project
      • 3.1.3.1. Yocto Project Compatible Program Application
      • 3.1.3.2. yocto-check-layer Script
    • 3.1.4. Enabling Your Layer
    • 3.1.5. Using .bbappend Files in Your Layer
    • 3.1.6. Prioritizing Your Layer
    • 3.1.7. Managing Layers
    • 3.1.8. Creating a General Layer Using the bitbake-layers Script
    • 3.1.9. Adding a Layer Using the bitbake-layers Script
  • 3.2. Customizing Images
    • 3.2.1. Customizing Images Using local.conf
    • 3.2.2. Customizing Images Using Custom IMAGE_FEATURES and EXTRA_IMAGE_FEATURES
    • 3.2.3. Customizing Images Using Custom .bb Files
    • 3.2.4. Customizing Images Using Custom Package Groups
    • 3.2.5. Customizing an Image Hostname
  • 3.3. Writing a New Recipe
    • 3.3.1. Overview
    • 3.3.2. Locate or Automatically Create a Base Recipe
      • 3.3.2.1. Creating the Base Recipe Using devtool add
      • 3.3.2.2. Creating the Base Recipe Using recipetool create
      • 3.3.2.3. Locating and Using a Similar Recipe
    • 3.3.3. Storing and Naming the Recipe
    • 3.3.4. Running a Build on the Recipe
    • 3.3.5. Fetching Code
    • 3.3.6. Unpacking Code
    • 3.3.7. Patching Code
    • 3.3.8. Licensing
    • 3.3.9. Dependencies
    • 3.3.10. Configuring the Recipe
    • 3.3.11. Using Headers to Interface with Devices
    • 3.3.12. Compilation
    • 3.3.13. Installing
    • 3.3.14. Enabling System Services
    • 3.3.15. Packaging
    • 3.3.16. Sharing Files Between Recipes
    • 3.3.17. Using Virtual Providers
    • 3.3.18. Properly Versioning Pre-Release Recipes
    • 3.3.19. Post-Installation Scripts
    • 3.3.20. Testing
    • 3.3.21. Examples
      • 3.3.21.1. Single .c File Package (Hello World!)
      • 3.3.21.2. Autotooled Package
      • 3.3.21.3. Makefile-Based Package
      • 3.3.21.4. Splitting an Application into Multiple Packages
      • 3.3.21.5. Packaging Externally Produced Binaries
    • 3.3.22. Following Recipe Style Guidelines
    • 3.3.23. Recipe Syntax
  • 3.4. Adding a New Machine
    • 3.4.1. Adding the Machine Configuration File
    • 3.4.2. Adding a Kernel for the Machine
    • 3.4.3. Adding a Formfactor Configuration File
  • 3.5. Upgrading Recipes
    • 3.5.1. Using the Auto Upgrade Helper (AUH)
    • 3.5.2. Using devtool upgrade
    • 3.5.3. Manually Upgrading a Recipe
  • 3.6. Finding Temporary Source Code
  • 3.7. Using Quilt in Your Workflow
  • 3.8. Using a Development Shell
  • 3.9. Using a Development Python Shell
  • 3.10. Building
    • 3.10.1. Building a Simple Image
    • 3.10.2. Building Images for Multiple Targets Using Multiple Configurations
      • 3.10.2.1. Setting Up and Running a Multiple Configuration Build
      • 3.10.2.2. Enabling Multiple Configuration Build Dependencies
    • 3.10.3. Building an Initial RAM Filesystem (initramfs) Image
    • 3.10.4. Building a Tiny System
      • 3.10.4.1. Overview
      • 3.10.4.2. Goals and Guiding Principles
      • 3.10.4.3. Understand What Contributes to Your Image Size
      • 3.10.4.4. Trim the Root Filesystem
      • 3.10.4.5. Trim the Kernel
      • 3.10.4.6. Remove Package Management Requirements
      • 3.10.4.7. Look for Other Ways to Minimize Size
      • 3.10.4.8. Iterate on the Process
    • 3.10.5. Building Images for More than One Machine
    • 3.10.6. Building Software from an External Source
    • 3.10.7. Replicating a Build Offline
  • 3.11. Speeding Up a Build
  • 3.12. Working With Libraries
    • 3.12.1. Including Static Library Files
    • 3.12.2. Combining Multiple Versions of Library Files into One Image
      • 3.12.2.1. Preparing to Use Multilib
      • 3.12.2.2. Using Multilib
      • 3.12.2.3. Additional Implementation Details
    • 3.12.3. Installing Multiple Versions of the Same Library
  • 3.13. Using x32 psABI
  • 3.14. Enabling GObject Introspection Support
    • 3.14.1. Enabling the Generation of Introspection Data
    • 3.14.2. Disabling the Generation of Introspection Data
    • 3.14.3. Testing that Introspection Works in an Image
    • 3.14.4. Known Issues
  • 3.15. Optionally Using an External Toolchain
  • 3.16. Creating Partitioned Images Using Wic
    • 3.16.1. Background
    • 3.16.2. Requirements
    • 3.16.3. Getting Help
    • 3.16.4. Operational Modes
      • 3.16.4.1. Raw Mode
      • 3.16.4.2. Cooked Mode
    • 3.16.5. Using an Existing Kickstart File
    • 3.16.6. Using the Wic Plugin Interface
    • 3.16.7. Examples
      • 3.16.7.1. Generate an Image using an Existing Kickstart File
      • 3.16.7.2. Using a Modified Kickstart File
      • 3.16.7.3. Using a Modified Kickstart File and Running in Raw Mode
      • 3.16.7.4. Using Wic to Manipulate an Image
  • 3.17. Flashing Images Using bmaptool
  • 3.18. Making Images More Secure
    • 3.18.1. General Considerations
    • 3.18.2. Security Flags
    • 3.18.3. Considerations Specific to the OpenEmbedded Build System
    • 3.18.4. Tools for Hardening Your Image
  • 3.19. Creating Your Own Distribution
  • 3.20. Creating a Custom Template Configuration Directory
  • 3.21. Conserving Disk Space During Builds
  • 3.22. Working with Packages
    • 3.22.1. Excluding Packages from an Image
    • 3.22.2. Incrementing a Package Version
      • 3.22.2.1. Working With a PR Service
      • 3.22.2.2. Manually Bumping PR
      • 3.22.2.3. Automatically Incrementing a Package Version Number
    • 3.22.3. Handling Optional Module Packaging
      • 3.22.3.1. Making Sure the Packaging is Done
      • 3.22.3.2. Satisfying Dependencies
    • 3.22.4. Using Runtime Package Management
      • 3.22.4.1. Build Considerations
      • 3.22.4.2. Host or Server Machine Setup
      • 3.22.4.3. Target Setup
        • 3.22.4.3.1. Using RPM
        • 3.22.4.3.2. Using IPK
        • 3.22.4.3.3. Using DEB
    • 3.22.5. Generating and Using Signed Packages
      • 3.22.5.1. Signing RPM Packages
      • 3.22.5.2. Processing Package Feeds
    • 3.22.6. Testing Packages With ptest
      • 3.22.6.1. Adding ptest to Your Build
      • 3.22.6.2. Running ptest
      • 3.22.6.3. Getting Your Package Ready
    • 3.22.7. Creating Node Package Manager (NPM) Packages
      • 3.22.7.1. Requirements and Caveats
      • 3.22.7.2. Using the Registry Modules Method
      • 3.22.7.3. Using the NPM Projects Code Method
    • 3.22.8. Adding custom metadata to packages
  • 3.23. Efficiently Fetching Source Files During a Build
    • 3.23.1. Setting up Effective Mirrors
    • 3.23.2. Getting Source Files and Suppressing the Build
  • 3.24. Selecting an Initialization Manager
    • 3.24.1. Using systemd Exclusively
    • 3.24.2. Using systemd for the Main Image and Using SysVinit for the Rescue Image
  • 3.25. Selecting a Device Manager
    • 3.25.1. Using Persistent and Pre-Populated/dev
    • 3.25.2. Using devtmpfs and a Device Manager
  • 3.26. Using an External SCM
  • 3.27. Creating a Read-Only Root Filesystem
    • 3.27.1. Creating the Root Filesystem
    • 3.27.2. Post-Installation Scripts
    • 3.27.3. Areas With Write Access
  • 3.28. Maintaining Build Output Quality
    • 3.28.1. Enabling and Disabling Build History
    • 3.28.2. Understanding What the Build History Contains
      • 3.28.2.1. Build History Package Information
      • 3.28.2.2. Build History Image Information
      • 3.28.2.3. Using Build History to Gather Image Information Only
      • 3.28.2.4. Build History SDK Information
      • 3.28.2.5. Examining Build History Information
  • 3.29. Performing Automated Runtime Testing
    • 3.29.1. Enabling Tests
      • 3.29.1.1. Enabling Runtime Tests on QEMU
      • 3.29.1.2. Enabling Runtime Tests on Hardware
      • 3.29.1.3. Selecting SystemdbootTarget
      • 3.29.1.4. Power Control
      • 3.29.1.5. Serial Console Connection
    • 3.29.2. Running Tests
    • 3.29.3. Exporting Tests
    • 3.29.4. Writing New Tests
      • 3.29.4.1. Class Methods
      • 3.29.4.2. Class Attributes
      • 3.29.4.3. Instance Attributes
    • 3.29.5. Installing Packages in the DUT Without the Package Manager
  • 3.30. Debugging Tools and Techniques
    • 3.30.1. Viewing Logs from Failed Tasks
    • 3.30.2. Viewing Variable Values
    • 3.30.3. Viewing Package Information with oe-pkgdata-util
    • 3.30.4. Viewing Dependencies Between Recipes and Tasks
    • 3.30.5. Viewing Task Variable Dependencies
    • 3.30.6. Viewing Metadata Used to Create the Input Signature of a Shared State Task
    • 3.30.7. Invalidating Shared State to Force a Task to Run
    • 3.30.8. Running Specific Tasks
    • 3.30.9. General BitBake Problems
    • 3.30.10. Building with No Dependencies
    • 3.30.11. Recipe Logging Mechanisms
      • 3.30.11.1. Logging With Python
      • 3.30.11.2. Logging With Bash
    • 3.30.12. Debugging Parallel Make Races
      • 3.30.12.1. The Failure
      • 3.30.12.2. Reproducing the Error
      • 3.30.12.3. Creating a Patch for the Fix
      • 3.30.12.4. Testing the Build
    • 3.30.13. Debugging With the GNU Project Debugger (GDB) Remotely
    • 3.30.14. Debugging with the GNU Project Debugger (GDB) on the Target
    • 3.30.15. Other Debugging Tips
  • 3.31. Making Changes to the Yocto Project
    • 3.31.1. Submitting a Defect Against the Yocto Project
    • 3.31.2. Submitting a Change to the Yocto Project
      • 3.31.2.1. Using Scripts to Push a Change Upstream and Request a Pull
      • 3.31.2.2. Using Email to Submit a Patch
  • 3.32. Working With Licenses
    • 3.32.1. Tracking License Changes
      • 3.32.1.1. Specifying the LIC_FILES_CHKSUM Variable
      • 3.32.1.2. Explanation of Syntax
    • 3.32.2. Enabling Commercially Licensed Recipes
      • 3.32.2.1. License Flag Matching
      • 3.32.2.2. Other Variables Related to Commercial Licenses
    • 3.32.3. Maintaining Open Source License Compliance During Your Product’s Lifecycle
      • 3.32.3.1. Providing the Source Code
      • 3.32.3.2. Providing License Text
      • 3.32.3.3. Providing Compilation Scripts and Source Code Modifications
    • 3.32.4. Copying Licenses that Do Not Exist
  • 3.33. Using the Error Reporting Tool
    • 3.33.1. Enabling and Using the Tool
    • 3.33.2. Disabling the Tool
    • 3.33.3. Setting Up Your Own Error Reporting Server
  • 3.34. Using Wayland and Weston
    • 3.34.1. Enabling Wayland in an Image
      • 3.34.1.1. Building
      • 3.34.1.2. Installing
    • 3.34.2. Running Weston
• 4. Using the Quick EMUlator (QEMU)
  • 4.1. Overview
  • 4.2. Running QEMU
  • 4.3. Switching Between Consoles
  • 4.4. Removing the Splash Screen
  • 4.5. Disabling the Cursor Grab
  • 4.6. Running Under a Network File System (NFS) Server
  • 4.7. QEMU CPU Compatibility Under KVM
  • 4.8. QEMU Performance
  • 4.9. QEMU Command-Line Syntax
  • 4.10. runqemu Command-Line Options