Yocto Project Development Tasks Manual

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 Tiny System 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 Wic 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 and Read-Only Root Filesystem
    • 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.13.1 Using the debuginfod server method
      • 3.30.13.2 Using the gdbserver method
    • 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 Preparing Changes for Submission
      • 3.31.2.2 Using Email to Submit a Patch
      • 3.31.2.3 Using Scripts to Push a Change Upstream and Request a Pull
      • 3.31.2.4 Responding to Patch Review
      • 3.31.2.5 Submitting Changes to Stable Release Branches
  • 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.3.4 Providing spdx files
    • 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 Wayland
      • 3.34.1.2 Installing Wayland and Weston
    • 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
• 5 Manual Revision History

---

The Yocto Project ®

<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.

To report any inaccuracies or problems with this (or any other Yocto Project) manual, or to send additions or changes, please send email/patches to the Yocto Project documentation mailing list at docs@lists.yoctoproject.org or log into the Freenode #yocto channel.