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 Creating New Configuration Fragments In Your Build
  • 9.1 Creating A Standard Configuration Fragment
  • 9.2 Creating A Built-in Fragment
• 10 Using Quilt in Your Workflow
• 11 Using a Development Shell
• 12 Using a Python Development Shell
• 13 Building
  • 13.1 Building a Simple Image
  • 13.2 Building Images for Multiple Targets Using Multiple Configurations
  • 13.3 Building an Initial RAM Filesystem (Initramfs) Image
    • 13.3.1 Customizing an Initramfs using initramfs-framework
    • 13.3.2 Bundling an Initramfs Image From a Separate Multiconfig
  • 13.4 Building a Tiny System
    • 13.4.1 Tiny System Overview
    • 13.4.2 Goals and Guiding Principles
    • 13.4.3 Understand What Contributes to Your Image Size
    • 13.4.4 Trim the Root Filesystem
    • 13.4.5 Trim the Kernel
    • 13.4.6 Remove Package Management Requirements
    • 13.4.7 Look for Other Ways to Minimize Size
    • 13.4.8 Iterate on the Process
  • 13.5 Building Images for More than One Machine
  • 13.6 Building Software from an External Source
  • 13.7 Replicating a Build Offline
• 14 Building Images for Multiple Targets With Multiconfig
  • 14.1 Setting Up and Running a Multiple Configuration Build
  • 14.2 Enabling Multiple Configuration Build Dependencies
  • 14.3 Suggested best practices
  • 14.4 Common use case: building baremetal firmware alongside a Linux build
    • 14.4.1 Adding a multiconfig configuration file and recipe for a baremetal firmware
    • 14.4.2 Building the firmware
    • 14.4.3 Using the output of my-firmware
• 15 Speeding Up a Build
• 16 Limiting the Host Resources Usage
• 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 the devtool command-line tool
  • 19.1 Use devtool add to Add an Application
  • 19.2 Use devtool modify to Modify the Source of an Existing Component
  • 19.3 devtool ide-sdk configures IDEs and bootstraps SDKs
  • 19.4 Use devtool upgrade to Create a Version of the Recipe that Supports a Newer Version of the Software
  • 19.5 A Closer Look at devtool add
    • 19.5.1 Name and Version
    • 19.5.2 Dependency Detection and Mapping
    • 19.5.3 License Detection
    • 19.5.4 Adding Makefile-Only Software
    • 19.5.5 Adding Native Tools
    • 19.5.6 Adding Node.js Modules
  • 19.6 Working With Recipes
    • 19.6.1 Finding Logs and Work Files
    • 19.6.2 Setting Configure Arguments
    • 19.6.3 Sharing Files Between Recipes
    • 19.6.4 Packaging
  • 19.7 Restoring the Target Device to its Original State
• 20 Using x32 psABI
• 21 Enabling GObject Introspection Support
  • 21.1 Enabling the Generation of Introspection Data
  • 21.2 Disabling the Generation of Introspection Data
  • 21.3 Testing that Introspection Works in an Image
  • 21.4 Known Issues
• 22 Optionally Using an External Toolchain
• 23 Creating Partitioned Images Using Wic
  • 23.1 Background
  • 23.2 Requirements
  • 23.3 Getting Help
  • 23.4 Operational Modes
    • 23.4.1 Raw Mode
    • 23.4.2 Cooked Mode
  • 23.5 Using an Existing Kickstart File
  • 23.6 Using the Wic Plugin Interface
  • 23.7 Wic Examples
    • 23.7.1 Generate an Image using an Existing Kickstart File
    • 23.7.2 Using a Modified Kickstart File
    • 23.7.3 Using a Modified Kickstart File and Running in Raw Mode
    • 23.7.4 Using Wic to Manipulate an Image
• 24 Flashing Images Using bmaptool
• 25 Making Images More Secure
  • 25.1 General Considerations
  • 25.2 Security Flags
  • 25.3 Considerations Specific to the OpenEmbedded Build System
  • 25.4 Tools for Hardening Your Image
• 26 Creating Your Own Distribution
  • 26.1 Copying and modifying the Poky distribution
• 27 Creating a Custom Template Configuration Directory
• 28 Conserving Disk Space
  • 28.1 Conserving Disk Space During Builds
  • 28.2 Purging Obsolete Shared State Cache Files
• 29 Working with Packages
  • 29.1 Excluding Packages from an Image
  • 29.2 Incrementing a Package Version
    • 29.2.1 Working With a PR Service
    • 29.2.2 Manually Bumping PR
    • 29.2.3 Automatically Incrementing a Package Version Number
  • 29.3 Handling Optional Module Packaging
    • 29.3.1 Making Sure the Packaging is Done
    • 29.3.2 Satisfying Dependencies
  • 29.4 Using Runtime Package Management
    • 29.4.1 Build Considerations
    • 29.4.2 Host or Server Machine Setup
    • 29.4.3 Target Setup
      • 29.4.3.1 Using RPM
      • 29.4.3.2 Using IPK
      • 29.4.3.3 Using DEB
  • 29.5 Generating and Using Signed Packages
    • 29.5.1 Signing RPM Packages
    • 29.5.2 Processing Package Feeds
  • 29.6 Testing Packages With ptest
  • 29.7 Creating Node Package Manager (NPM) Packages
    • 29.7.1 Requirements and Caveats
    • 29.7.2 Using the Registry Modules Method
    • 29.7.3 Using the NPM Projects Code Method
  • 29.8 Adding custom metadata to packages
• 30 Efficiently Fetching Source Files During a Build
  • 30.1 Setting up Effective Mirrors
  • 30.2 Getting Source Files and Suppressing the Build
• 31 Selecting an Initialization Manager
  • 31.1 Using SysVinit with udev
  • 31.2 Using BusyBox init with BusyBox mdev
  • 31.3 Using systemd
    • 31.3.1 Controling systemd from the target command line
    • 31.3.2 Using systemd-journald without a traditional syslog daemon
    • 31.3.3 Summary
• 32 Selecting a Device Manager
  • 32.1 Using Persistent and Pre-Populated /dev
  • 32.2 Using devtmpfs and a Device Manager
• 33 Using an External SCM
• 34 Creating a Read-Only Root Filesystem
  • 34.1 Creating the Root Filesystem
  • 34.2 Post-Installation Scripts and Read-Only Root Filesystem
  • 34.3 Areas With Write Access
• 35 Maintaining Build Output Quality
  • 35.1 Enabling and Disabling Build History
  • 35.2 Understanding What the Build History Contains
    • 35.2.1 Build History Package Information
    • 35.2.2 Build History Image Information
    • 35.2.3 Using Build History to Gather Image Information Only
    • 35.2.4 Build History SDK Information
    • 35.2.5 Examining Build History Information
• 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 Enabling Minidebuginfo
  • 36.17 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.2 Providing License Text
    • 37.3.3 Providing Compilation Scripts and Source Code Modifications
    • 37.3.4 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
• 44 Locking and Unlocking Recipes Using bblock
  • 44.1 Locking tasks and recipes
  • 44.2 Unlocking tasks and recipes
  • 44.3 Configuration file
  • 44.4 Locking mechanism
  • 44.5 Example
• 45 Setting up a Hash Equivalence Server
  • 45.1 Hash Equivalence Server Setup
  • 45.2 Yocto Project Build Setup

---

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.