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 Index of Releases
    • 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
• 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
• 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
• 7 Adding the Machine Configuration File
• 8 Adding a Kernel for the Machine
• 9 Adding a Formfactor Configuration File
• 10 Upgrading Recipes
  • 10.1 Using the Auto Upgrade Helper (AUH)
  • 10.2 Using devtool upgrade
  • 10.3 Manually Upgrading a Recipe
• 11 Finding Temporary Source Code
• 12 Using Quilt in Your Workflow
• 13 Using a Development Shell
• 14 Using a Python Development Shell
• 15 Building
  • 15.1 Building a Simple Image
  • 15.2 Building Images for Multiple Targets Using Multiple Configurations
    • 15.2.1 Setting Up and Running a Multiple Configuration Build
    • 15.2.2 Enabling Multiple Configuration Build Dependencies
  • 15.3 Building an Initial RAM Filesystem (Initramfs) Image
    • 15.3.1 Bundling an Initramfs Image From a Separate Multiconfig
  • 15.4 Building a Tiny System
    • 15.4.1 Tiny System Overview
    • 15.4.2 Goals and Guiding Principles
    • 15.4.3 Understand What Contributes to Your Image Size
    • 15.4.4 Trim the Root Filesystem
    • 15.4.5 Trim the Kernel
    • 15.4.6 Remove Package Management Requirements
    • 15.4.7 Look for Other Ways to Minimize Size
    • 15.4.8 Iterate on the Process
  • 15.5 Building Images for More than One Machine
  • 15.6 Building Software from an External Source
  • 15.7 Replicating a Build Offline
• 16 Speeding Up a Build
• 17 Working With Libraries
  • 17.1 Including Static Library Files
  • 17.2 Combining Multiple Versions of Library Files into One Image
    • 17.2.1 Preparing to Use Multilib
    • 17.2.2 Using Multilib
    • 17.2.3 Additional Implementation Details
  • 17.3 Installing Multiple Versions of the Same Library
• 18 Working with Pre-Built Libraries
  • 18.1 Introduction
  • 18.2 Versioned Libraries
  • 18.3 Non-Versioned Libraries
    • 18.3.1 Some Background
    • 18.3.2 Yocto Library Packaging Overview
    • 18.3.3 Example
• 19 Using x32 psABI
• 20 Enabling GObject Introspection Support
  • 20.1 Enabling the Generation of Introspection Data
  • 20.2 Disabling the Generation of Introspection Data
  • 20.3 Testing that Introspection Works in an Image
  • 20.4 Known Issues
• 21 Optionally Using an External Toolchain
• 22 Creating Partitioned Images Using Wic
  • 22.1 Background
  • 22.2 Requirements
  • 22.3 Getting Help
  • 22.4 Operational Modes
    • 22.4.1 Raw Mode
    • 22.4.2 Cooked Mode
  • 22.5 Using an Existing Kickstart File
  • 22.6 Using the Wic Plugin Interface
  • 22.7 Wic Examples
    • 22.7.1 Generate an Image using an Existing Kickstart File
    • 22.7.2 Using a Modified Kickstart File
    • 22.7.3 Using a Modified Kickstart File and Running in Raw Mode
    • 22.7.4 Using Wic to Manipulate an Image
• 23 Flashing Images Using bmaptool
• 24 Making Images More Secure
  • 24.1 General Considerations
  • 24.2 Security Flags
  • 24.3 Considerations Specific to the OpenEmbedded Build System
  • 24.4 Tools for Hardening Your Image
• 25 Creating Your Own Distribution
  • 25.1 Copying and modifying the Poky distribution
• 26 Creating a Custom Template Configuration Directory
• 27 Conserving Disk Space
  • 27.1 Conserving Disk Space During Builds
  • 27.2 Purging Obsolete Shared State Cache Files
• 28 Working with Packages
  • 28.1 Excluding Packages from an Image
  • 28.2 Incrementing a Package Version
    • 28.2.1 Working With a PR Service
    • 28.2.2 Manually Bumping PR
    • 28.2.3 Automatically Incrementing a Package Version Number
  • 28.3 Handling Optional Module Packaging
    • 28.3.1 Making Sure the Packaging is Done
    • 28.3.2 Satisfying Dependencies
  • 28.4 Using Runtime Package Management
    • 28.4.1 Build Considerations
    • 28.4.2 Host or Server Machine Setup
    • 28.4.3 Target Setup
      • 28.4.3.1 Using RPM
      • 28.4.3.2 Using IPK
      • 28.4.3.3 Using DEB
  • 28.5 Generating and Using Signed Packages
    • 28.5.1 Signing RPM Packages
    • 28.5.2 Processing Package Feeds
  • 28.6 Testing Packages With ptest
    • 28.6.1 Adding ptest to Your Build
    • 28.6.2 Running ptest
    • 28.6.3 Getting Your Package Ready
  • 28.7 Creating Node Package Manager (NPM) Packages
    • 28.7.1 Requirements and Caveats
    • 28.7.2 Using the Registry Modules Method
    • 28.7.3 Using the NPM Projects Code Method
  • 28.8 Adding custom metadata to packages
• 29 Efficiently Fetching Source Files During a Build
  • 29.1 Setting up Effective Mirrors
  • 29.2 Getting Source Files and Suppressing the Build
• 30 Selecting an Initialization Manager
  • 30.1 Using SysVinit with udev
  • 30.2 Using BusyBox init with BusyBox mdev
  • 30.3 Using systemd
    • 30.3.1 Controling systemd from the target command line
    • 30.3.2 Using systemd-journald without a traditional syslog daemon
    • 30.3.3 Summary
• 31 Selecting a Device Manager
  • 31.1 Using Persistent and Pre-Populated /dev
  • 31.2 Using devtmpfs and a Device Manager
• 32 Using an External SCM
• 33 Creating a Read-Only Root Filesystem
  • 33.1 Creating the Root Filesystem
  • 33.2 Post-Installation Scripts and Read-Only Root Filesystem
  • 33.3 Areas With Write Access
• 34 Maintaining Build Output Quality
  • 34.1 Enabling and Disabling Build History
  • 34.2 Understanding What the Build History Contains
    • 34.2.1 Build History Package Information
    • 34.2.2 Build History Image Information
    • 34.2.3 Using Build History to Gather Image Information Only
    • 34.2.4 Build History SDK Information
    • 34.2.5 Examining Build History Information
• 35 Performing Automated Runtime Testing
  • 35.1 Enabling Tests
    • 35.1.1 Enabling Runtime Tests on QEMU
    • 35.1.2 Enabling Runtime Tests on Hardware
    • 35.1.3 Selecting SystemdbootTarget
    • 35.1.4 Power Control
    • 35.1.5 Serial Console Connection
  • 35.2 Running Tests
  • 35.3 Exporting Tests
  • 35.4 Writing New Tests
    • 35.4.1 Class Methods
    • 35.4.2 Class Attributes
    • 35.4.3 Instance Attributes
  • 35.5 Installing Packages in the DUT Without the Package Manager
• 36 Debugging Tools and Techniques
  • 36.1 Viewing Logs from Failed Tasks
  • 36.2 Viewing Variable Values
  • 36.3 Viewing Package Information with oe-pkgdata-util
  • 36.4 Viewing Dependencies Between Recipes and Tasks
  • 36.5 Viewing Task Variable Dependencies
  • 36.6 Debugging signature construction and unexpected task executions
  • 36.7 Viewing Metadata Used to Create the Input Signature of a Shared State Task
  • 36.8 Invalidating Shared State to Force a Task to Run
  • 36.9 Running Specific Tasks
  • 36.10 General BitBake Problems
  • 36.11 Building with No Dependencies
  • 36.12 Recipe Logging Mechanisms
    • 36.12.1 Logging With Python
    • 36.12.2 Logging With Bash
  • 36.13 Debugging Parallel Make Races
    • 36.13.1 The Failure
    • 36.13.2 Reproducing the Error
    • 36.13.3 Creating a Patch for the Fix
    • 36.13.4 Testing the Build
  • 36.14 Debugging With the GNU Project Debugger (GDB) Remotely
    • 36.14.1 Using the debuginfod server method
    • 36.14.2 Using the gdbserver method
  • 36.15 Debugging with the GNU Project Debugger (GDB) on the Target
  • 36.16 Other Debugging Tips
• 37 Working With Licenses
  • 37.1 Tracking License Changes
    • 37.1.1 Specifying the LIC_FILES_CHKSUM Variable
    • 37.1.2 Explanation of Syntax
  • 37.2 Enabling Commercially Licensed Recipes
    • 37.2.1 License Flag Matching
    • 37.2.2 Other Variables Related to Commercial Licenses
  • 37.3 Maintaining Open Source License Compliance During Your Product’s Lifecycle
    • 37.3.1 Providing the Source Code
      • 37.3.1.1 Providing License Text
    • 37.3.2 Providing Compilation Scripts and Source Code Modifications
    • 37.3.3 Compliance Limitations with Executables Built from Static Libraries
  • 37.4 Copying Non Standard Licenses
• 38 Dealing with Vulnerability Reports
  • 38.1 How to report a potential security vulnerability?
    • 38.1.1 Branches maintained with security fixes
    • 38.1.2 Security-related discussions at the Yocto Project
    • 38.1.3 What you should do if you find a security vulnerability
  • 38.2 Security team
    • 38.2.1 Security team appointment
    • 38.2.2 Security Team Operations
    • 38.2.3 What Yocto Security Team does when it receives a security vulnerability
    • 38.2.4 If an upstream project does not respond quickly
    • 38.2.5 Current Security Team members
• 39 Checking for Vulnerabilities
  • 39.1 Vulnerabilities in Poky and OE-Core
  • 39.2 Vulnerability check at build time
  • 39.3 Fixing CVE product name and version mappings
  • 39.4 Fixing vulnerabilities in recipes
  • 39.5 Implementation details
• 40 Creating a Software Bill of Materials
• 41 Using the Error Reporting Tool
  • 41.1 Enabling and Using the Tool
  • 41.2 Disabling the Tool
  • 41.3 Setting Up Your Own Error Reporting Server
• 42 Using Wayland and Weston
  • 42.1 Enabling Wayland in an Image
    • 42.1.1 Building Wayland
    • 42.1.2 Installing Wayland and Weston
  • 42.2 Running Weston
• 43 Using the Quick EMUlator (QEMU)
  • 43.1 Overview
  • 43.2 Running QEMU
  • 43.3 Switching Between Consoles
  • 43.4 Removing the Splash Screen
  • 43.5 Disabling the Cursor Grab
  • 43.6 Running Under a Network File System (NFS) Server
  • 43.7 QEMU CPU Compatibility Under KVM
  • 43.8 QEMU Performance
  • 43.9 QEMU Command-Line Syntax
  • 43.10 runqemu Command-Line Options

---

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.