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 (WSL 2)
  • 2.3 Locating Yocto Project Source Files
    • 2.3.1 Accessing Source Repositories
    • 2.3.2 Accessing Source Archives
    • 2.3.3 Using the Downloads Page
  • 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
  • 2.5 Initializing the Build Environment
• 3 Understanding and Creating Layers
  • 3.1 Creating Your Own Layer
  • 3.2 Following Best Practices When Creating Layers
  • 3.3 Making Sure Your Layer is Compatible With Yocto Project
    • 3.3.1 Yocto Project Compatible Program Application
    • 3.3.2 yocto-check-layer Script
  • 3.4 Enabling Your Layer
  • 3.5 Appending Other Layers Metadata With Your Layer
    • 3.5.1 Overlaying a File Using Your Layer
    • 3.5.2 Installing Additional Files Using Your Layer
  • 3.6 Prioritizing Your Layer
    • 3.6.1 Providing Global-level Configurations With Your Layer
      • 3.6.1.1 Conditionally Provide Global-level Configurations With Your Layer
  • 3.7 Managing Layers
  • 3.8 Creating a General Layer Using the bitbake-layers Script
  • 3.9 Adding a Layer Using the bitbake-layers Script
  • 3.10 Saving and restoring the layers setup
• 4 Customizing Images
  • 4.1 Customizing Images Using local.conf
  • 4.2 Customizing Images Using Custom IMAGE_FEATURES and EXTRA_IMAGE_FEATURES
  • 4.3 Customizing Images Using Custom .bb Files
  • 4.4 Customizing Images Using Custom Package Groups
  • 4.5 Customizing an Image Hostname
• 5 Writing a New Recipe
  • 5.1 Overview
  • 5.2 Locate or Automatically Create a Base Recipe
    • 5.2.1 Creating the Base Recipe Using devtool add
    • 5.2.2 Creating the Base Recipe Using recipetool create
    • 5.2.3 Locating and Using a Similar Recipe
  • 5.3 Storing and Naming the Recipe
  • 5.4 Running a Build on the Recipe
  • 5.5 Fetching Code
    • 5.5.1 Fetching Code Through Firewalls
    • 5.5.2 Limiting the Number of Parallel Connections
  • 5.6 Unpacking Code
  • 5.7 Patching Code
  • 5.8 Licensing
  • 5.9 Dependencies
  • 5.10 Configuring the Recipe
  • 5.11 Using Headers to Interface with Devices
  • 5.12 Compilation
  • 5.13 Installing
  • 5.14 Enabling System Services
  • 5.15 Packaging
  • 5.16 Sharing Files Between Recipes
  • 5.17 Using Virtual Providers
  • 5.18 Properly Versioning Pre-Release Recipes
  • 5.19 Post-Installation Scripts
  • 5.20 Testing
  • 5.21 Examples
    • 5.21.1 Building a Single .c File Package
    • 5.21.2 Building a Makefile-Based Package
    • 5.21.3 Building an Autotooled Package
    • 5.21.4 Building a Meson Package
    • 5.21.5 Splitting an Application into Multiple Packages
    • 5.21.6 Packaging Externally Produced Binaries
  • 5.22 Following Recipe Style Guidelines
  • 5.23 Recipe Syntax
• 6 Adding a New Machine
  • 6.1 Adding the Machine Configuration File
  • 6.2 Adding a Kernel for the Machine
  • 6.3 Adding a Formfactor Configuration File
• 7 Upgrading Recipes
  • 7.1 Using the Auto Upgrade Helper (AUH)
  • 7.2 Using devtool upgrade
  • 7.3 Manually Upgrading a Recipe
• 8 Finding Temporary Source Code
• 9 Using Quilt in Your Workflow
• 10 Using a Development Shell
• 11 Using a Python Development Shell
• 12 Building
  • 12.1 Building a Simple Image
  • 12.2 Building Images for Multiple Targets Using Multiple Configurations
    • 12.2.1 Setting Up and Running a Multiple Configuration Build
    • 12.2.2 Enabling Multiple Configuration Build Dependencies
  • 12.3 Building an Initial RAM Filesystem (Initramfs) Image
    • 12.3.1 Bundling an Initramfs Image From a Separate Multiconfig
  • 12.4 Building a Tiny System
    • 12.4.1 Tiny System Overview
    • 12.4.2 Goals and Guiding Principles
    • 12.4.3 Understand What Contributes to Your Image Size
    • 12.4.4 Trim the Root Filesystem
    • 12.4.5 Trim the Kernel
    • 12.4.6 Remove Package Management Requirements
    • 12.4.7 Look for Other Ways to Minimize Size
    • 12.4.8 Iterate on the Process
  • 12.5 Building Images for More than One Machine
  • 12.6 Building Software from an External Source
  • 12.7 Replicating a Build Offline
• 13 Speeding Up a Build
• 14 Working With Libraries
  • 14.1 Including Static Library Files
  • 14.2 Combining Multiple Versions of Library Files into One Image
    • 14.2.1 Preparing to Use Multilib
    • 14.2.2 Using Multilib
    • 14.2.3 Additional Implementation Details
  • 14.3 Installing Multiple Versions of the Same Library
• 15 Working with Pre-Built Libraries
  • 15.1 Introduction
  • 15.2 Versioned Libraries
  • 15.3 Non-Versioned Libraries
    • 15.3.1 Some Background
    • 15.3.2 Yocto Library Packaging Overview
    • 15.3.3 Example
• 16 Using x32 psABI
• 17 Enabling GObject Introspection Support
  • 17.1 Enabling the Generation of Introspection Data
  • 17.2 Disabling the Generation of Introspection Data
  • 17.3 Testing that Introspection Works in an Image
  • 17.4 Known Issues
• 18 Optionally Using an External Toolchain
• 19 Creating Partitioned Images Using Wic
  • 19.1 Background
  • 19.2 Requirements
  • 19.3 Getting Help
  • 19.4 Operational Modes
    • 19.4.1 Raw Mode
    • 19.4.2 Cooked Mode
  • 19.5 Using an Existing Kickstart File
  • 19.6 Using the Wic Plugin Interface
  • 19.7 Wic Examples
    • 19.7.1 Generate an Image using an Existing Kickstart File
    • 19.7.2 Using a Modified Kickstart File
    • 19.7.3 Using a Modified Kickstart File and Running in Raw Mode
    • 19.7.4 Using Wic to Manipulate an Image
• 20 Flashing Images Using bmaptool
• 21 Making Images More Secure
  • 21.1 General Considerations
  • 21.2 Security Flags
  • 21.3 Considerations Specific to the OpenEmbedded Build System
  • 21.4 Tools for Hardening Your Image
• 22 Creating Your Own Distribution
  • 22.1 Copying and modifying the Poky distribution
• 23 Creating a Custom Template Configuration Directory
• 24 Conserving Disk Space
  • 24.1 Conserving Disk Space During Builds
  • 24.2 Purging Obsolete Shared State Cache Files
• 25 Working with Packages
  • 25.1 Excluding Packages from an Image
  • 25.2 Incrementing a Package Version
    • 25.2.1 Working With a PR Service
    • 25.2.2 Manually Bumping PR
    • 25.2.3 Automatically Incrementing a Package Version Number
  • 25.3 Handling Optional Module Packaging
    • 25.3.1 Making Sure the Packaging is Done
    • 25.3.2 Satisfying Dependencies
  • 25.4 Using Runtime Package Management
    • 25.4.1 Build Considerations
    • 25.4.2 Host or Server Machine Setup
    • 25.4.3 Target Setup
      • 25.4.3.1 Using RPM
      • 25.4.3.2 Using IPK
      • 25.4.3.3 Using DEB
  • 25.5 Generating and Using Signed Packages
    • 25.5.1 Signing RPM Packages
    • 25.5.2 Processing Package Feeds
  • 25.6 Testing Packages With ptest
    • 25.6.1 Adding ptest to Your Build
    • 25.6.2 Running ptest
    • 25.6.3 Getting Your Package Ready
  • 25.7 Creating Node Package Manager (NPM) Packages
    • 25.7.1 Requirements and Caveats
    • 25.7.2 Using the Registry Modules Method
    • 25.7.3 Using the NPM Projects Code Method
  • 25.8 Adding custom metadata to packages
• 26 Efficiently Fetching Source Files During a Build
  • 26.1 Setting up Effective Mirrors
  • 26.2 Getting Source Files and Suppressing the Build
• 27 Selecting an Initialization Manager
  • 27.1 Using SysVinit with udev
  • 27.2 Using BusyBox init with BusyBox mdev
  • 27.3 Using systemd
    • 27.3.1 Controling systemd from the target command line
    • 27.3.2 Using systemd-journald without a traditional syslog daemon
    • 27.3.3 Summary
• 28 Selecting a Device Manager
  • 28.1 Using Persistent and Pre-Populated /dev
  • 28.2 Using devtmpfs and a Device Manager
• 29 Using an External SCM
• 30 Creating a Read-Only Root Filesystem
  • 30.1 Creating the Root Filesystem
  • 30.2 Post-Installation Scripts and Read-Only Root Filesystem
  • 30.3 Areas With Write Access
• 31 Maintaining Build Output Quality
  • 31.1 Enabling and Disabling Build History
  • 31.2 Understanding What the Build History Contains
    • 31.2.1 Build History Package Information
    • 31.2.2 Build History Image Information
    • 31.2.3 Using Build History to Gather Image Information Only
    • 31.2.4 Build History SDK Information
    • 31.2.5 Examining Build History Information
• 32 Performing Automated Runtime Testing
  • 32.1 Enabling Tests
    • 32.1.1 Enabling Runtime Tests on QEMU
    • 32.1.2 Enabling Runtime Tests on Hardware
    • 32.1.3 Selecting SystemdbootTarget
    • 32.1.4 Power Control
    • 32.1.5 Serial Console Connection
  • 32.2 Running Tests
  • 32.3 Exporting Tests
  • 32.4 Writing New Tests
    • 32.4.1 Class Methods
    • 32.4.2 Class Attributes
    • 32.4.3 Instance Attributes
  • 32.5 Installing Packages in the DUT Without the Package Manager
• 33 Debugging Tools and Techniques
  • 33.1 Viewing Logs from Failed Tasks
  • 33.2 Viewing Variable Values
  • 33.3 Viewing Package Information with oe-pkgdata-util
  • 33.4 Viewing Dependencies Between Recipes and Tasks
  • 33.5 Viewing Task Variable Dependencies
  • 33.6 Debugging signature construction and unexpected task executions
  • 33.7 Viewing Metadata Used to Create the Input Signature of a Shared State Task
  • 33.8 Invalidating Shared State to Force a Task to Run
  • 33.9 Running Specific Tasks
  • 33.10 General BitBake Problems
  • 33.11 Building with No Dependencies
  • 33.12 Recipe Logging Mechanisms
    • 33.12.1 Logging With Python
    • 33.12.2 Logging With Bash
  • 33.13 Debugging Parallel Make Races
    • 33.13.1 The Failure
    • 33.13.2 Reproducing the Error
    • 33.13.3 Creating a Patch for the Fix
    • 33.13.4 Testing the Build
  • 33.14 Debugging With the GNU Project Debugger (GDB) Remotely
    • 33.14.1 Using the debuginfod server method
    • 33.14.2 Using the gdbserver method
  • 33.15 Debugging with the GNU Project Debugger (GDB) on the Target
  • 33.16 Enabling Minidebuginfo
  • 33.17 Other Debugging Tips
• 34 Working With Licenses
  • 34.1 Tracking License Changes
    • 34.1.1 Specifying the LIC_FILES_CHKSUM Variable
    • 34.1.2 Explanation of Syntax
  • 34.2 Enabling Commercially Licensed Recipes
    • 34.2.1 License Flag Matching
    • 34.2.2 Other Variables Related to Commercial Licenses
  • 34.3 Maintaining Open Source License Compliance During Your Product’s Lifecycle
    • 34.3.1 Providing the Source Code
    • 34.3.2 Providing License Text
    • 34.3.3 Providing Compilation Scripts and Source Code Modifications
    • 34.3.4 Compliance Limitations with Executables Built from Static Libraries
  • 34.4 Copying Non Standard Licenses
• 35 Dealing with Vulnerability Reports
  • 35.1 How to report a potential security vulnerability?
    • 35.1.1 Branches maintained with security fixes
    • 35.1.2 Security-related discussions at the Yocto Project
    • 35.1.3 What you should do if you find a security vulnerability
  • 35.2 Security team
    • 35.2.1 Security team appointment
    • 35.2.2 Security Team Operations
    • 35.2.3 What Yocto Security Team does when it receives a security vulnerability
    • 35.2.4 If an upstream project does not respond quickly
    • 35.2.5 Current Security Team members
• 36 Checking for Vulnerabilities
  • 36.1 Vulnerabilities in Poky and OE-Core
  • 36.2 Vulnerability check at build time
  • 36.3 Fixing CVE product name and version mappings
  • 36.4 Fixing vulnerabilities in recipes
  • 36.5 Implementation details
• 37 Creating a Software Bill of Materials
• 38 Using the Error Reporting Tool
  • 38.1 Enabling and Using the Tool
  • 38.2 Disabling the Tool
  • 38.3 Setting Up Your Own Error Reporting Server
• 39 Using Wayland and Weston
  • 39.1 Enabling Wayland in an Image
    • 39.1.1 Building Wayland
    • 39.1.2 Installing Wayland and Weston
  • 39.2 Running Weston
• 40 Using the Quick EMUlator (QEMU)
  • 40.1 Overview
  • 40.2 Running QEMU
  • 40.3 Switching Between Consoles
  • 40.4 Removing the Splash Screen
  • 40.5 Disabling the Cursor Grab
  • 40.6 Running Under a Network File System (NFS) Server
  • 40.7 QEMU CPU Compatibility Under KVM
  • 40.8 QEMU Performance
  • 40.9 QEMU Command-Line Syntax
  • 40.10 runqemu Command-Line Options
• 41 Locking and Unlocking Recipes Using bblock
  • 41.1 Locking tasks and recipes
  • 41.2 Unlocking tasks and recipes
  • 41.3 Configuration file
  • 41.4 Locking mechanism
  • 41.5 Example

---

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 Libera Chat #yocto channel.