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.3 Building an Initial RAM Filesystem (Initramfs) Image
    • 12.3.1 Customizing an Initramfs using initramfs-framework
    • 12.3.2 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 Building Images for Multiple Targets With Multiconfig
  • 13.1 Setting Up and Running a Multiple Configuration Build
  • 13.2 Enabling Multiple Configuration Build Dependencies
  • 13.3 Suggested best practices
  • 13.4 Common use case: building baremetal firmware alongside a Linux build
    • 13.4.1 Adding a multiconfig configuration file and recipe for a baremetal firmware
    • 13.4.2 Building the firmware
    • 13.4.3 Using the output of my-firmware
• 14 Speeding Up a Build
• 15 Working With Libraries
  • 15.1 Including Static Library Files
  • 15.2 Combining Multiple Versions of Library Files into One Image
    • 15.2.1 Preparing to Use Multilib
    • 15.2.2 Using Multilib
    • 15.2.3 Additional Implementation Details
  • 15.3 Installing Multiple Versions of the Same Library
• 16 Working with Pre-Built Libraries
  • 16.1 Introduction
  • 16.2 Versioned Libraries
  • 16.3 Non-Versioned Libraries
    • 16.3.1 Some Background
    • 16.3.2 Yocto Library Packaging Overview
    • 16.3.3 Example
• 17 Using the devtool command-line tool
  • 17.1 Use devtool add to Add an Application
  • 17.2 Use devtool modify to Modify the Source of an Existing Component
  • 17.3 devtool ide-sdk configures IDEs and bootstraps SDKs
  • 17.4 Use devtool upgrade to Create a Version of the Recipe that Supports a Newer Version of the Software
  • 17.5 A Closer Look at devtool add
    • 17.5.1 Name and Version
    • 17.5.2 Dependency Detection and Mapping
    • 17.5.3 License Detection
    • 17.5.4 Adding Makefile-Only Software
    • 17.5.5 Adding Native Tools
    • 17.5.6 Adding Node.js Modules
  • 17.6 Working With Recipes
    • 17.6.1 Finding Logs and Work Files
    • 17.6.2 Setting Configure Arguments
    • 17.6.3 Sharing Files Between Recipes
    • 17.6.4 Packaging
  • 17.7 Restoring the Target Device to its Original State
• 18 Using x32 psABI
• 19 Enabling GObject Introspection Support
  • 19.1 Enabling the Generation of Introspection Data
  • 19.2 Disabling the Generation of Introspection Data
  • 19.3 Testing that Introspection Works in an Image
  • 19.4 Known Issues
• 20 Optionally Using an External Toolchain
• 21 Creating Partitioned Images Using Wic
  • 21.1 Background
  • 21.2 Requirements
  • 21.3 Getting Help
  • 21.4 Operational Modes
    • 21.4.1 Raw Mode
    • 21.4.2 Cooked Mode
  • 21.5 Using an Existing Kickstart File
  • 21.6 Using the Wic Plugin Interface
  • 21.7 Wic Examples
    • 21.7.1 Generate an Image using an Existing Kickstart File
    • 21.7.2 Using a Modified Kickstart File
    • 21.7.3 Using a Modified Kickstart File and Running in Raw Mode
    • 21.7.4 Using Wic to Manipulate an Image
• 22 Flashing Images Using bmaptool
• 23 Making Images More Secure
  • 23.1 General Considerations
  • 23.2 Security Flags
  • 23.3 Considerations Specific to the OpenEmbedded Build System
  • 23.4 Tools for Hardening Your Image
• 24 Creating Your Own Distribution
  • 24.1 Copying and modifying the Poky distribution
• 25 Creating a Custom Template Configuration Directory
• 26 Conserving Disk Space
  • 26.1 Conserving Disk Space During Builds
  • 26.2 Purging Obsolete Shared State Cache Files
• 27 Working with Packages
  • 27.1 Excluding Packages from an Image
  • 27.2 Incrementing a Package Version
    • 27.2.1 Working With a PR Service
    • 27.2.2 Manually Bumping PR
    • 27.2.3 Automatically Incrementing a Package Version Number
  • 27.3 Handling Optional Module Packaging
    • 27.3.1 Making Sure the Packaging is Done
    • 27.3.2 Satisfying Dependencies
  • 27.4 Using Runtime Package Management
    • 27.4.1 Build Considerations
    • 27.4.2 Host or Server Machine Setup
    • 27.4.3 Target Setup
      • 27.4.3.1 Using RPM
      • 27.4.3.2 Using IPK
      • 27.4.3.3 Using DEB
  • 27.5 Generating and Using Signed Packages
    • 27.5.1 Signing RPM Packages
    • 27.5.2 Processing Package Feeds
  • 27.6 Testing Packages With ptest
  • 27.7 Creating Node Package Manager (NPM) Packages
    • 27.7.1 Requirements and Caveats
    • 27.7.2 Using the Registry Modules Method
    • 27.7.3 Using the NPM Projects Code Method
  • 27.8 Adding custom metadata to packages
• 28 Efficiently Fetching Source Files During a Build
  • 28.1 Setting up Effective Mirrors
  • 28.2 Getting Source Files and Suppressing the Build
• 29 Selecting an Initialization Manager
  • 29.1 Using SysVinit with udev
  • 29.2 Using BusyBox init with BusyBox mdev
  • 29.3 Using systemd
    • 29.3.1 Controling systemd from the target command line
    • 29.3.2 Using systemd-journald without a traditional syslog daemon
    • 29.3.3 Summary
• 30 Selecting a Device Manager
  • 30.1 Using Persistent and Pre-Populated /dev
  • 30.2 Using devtmpfs and a Device Manager
• 31 Using an External SCM
• 32 Creating a Read-Only Root Filesystem
  • 32.1 Creating the Root Filesystem
  • 32.2 Post-Installation Scripts and Read-Only Root Filesystem
  • 32.3 Areas With Write Access
• 33 Maintaining Build Output Quality
  • 33.1 Enabling and Disabling Build History
  • 33.2 Understanding What the Build History Contains
    • 33.2.1 Build History Package Information
    • 33.2.2 Build History Image Information
    • 33.2.3 Using Build History to Gather Image Information Only
    • 33.2.4 Build History SDK Information
    • 33.2.5 Examining Build History Information
• 34 Debugging Tools and Techniques
  • 34.1 Viewing Logs from Failed Tasks
  • 34.2 Viewing Variable Values
  • 34.3 Viewing Package Information with oe-pkgdata-util
  • 34.4 Viewing Dependencies Between Recipes and Tasks
  • 34.5 Viewing Task Variable Dependencies
  • 34.6 Debugging signature construction and unexpected task executions
  • 34.7 Viewing Metadata Used to Create the Input Signature of a Shared State Task
  • 34.8 Invalidating Shared State to Force a Task to Run
  • 34.9 Running Specific Tasks
  • 34.10 General BitBake Problems
  • 34.11 Building with No Dependencies
  • 34.12 Recipe Logging Mechanisms
    • 34.12.1 Logging With Python
    • 34.12.2 Logging With Bash
  • 34.13 Debugging Parallel Make Races
    • 34.13.1 The Failure
    • 34.13.2 Reproducing the Error
    • 34.13.3 Creating a Patch for the Fix
    • 34.13.4 Testing the Build
  • 34.14 Debugging With the GNU Project Debugger (GDB) Remotely
    • 34.14.1 Using the debuginfod server method
    • 34.14.2 Using the gdbserver method
  • 34.15 Debugging with the GNU Project Debugger (GDB) on the Target
  • 34.16 Enabling Minidebuginfo
  • 34.17 Other Debugging Tips
• 35 Working With Licenses
  • 35.1 Tracking License Changes
    • 35.1.1 Specifying the LIC_FILES_CHKSUM Variable
    • 35.1.2 Explanation of Syntax
  • 35.2 Enabling Commercially Licensed Recipes
    • 35.2.1 License Flag Matching
    • 35.2.2 Other Variables Related to Commercial Licenses
  • 35.3 Maintaining Open Source License Compliance During Your Product’s Lifecycle
    • 35.3.1 Providing the Source Code
    • 35.3.2 Providing License Text
    • 35.3.3 Providing Compilation Scripts and Source Code Modifications
    • 35.3.4 Compliance Limitations with Executables Built from Static Libraries
  • 35.4 Copying Non Standard Licenses
• 36 Dealing with Vulnerability Reports
  • 36.1 How to report a potential security vulnerability?
    • 36.1.1 Branches maintained with security fixes
    • 36.1.2 Security-related discussions at the Yocto Project
    • 36.1.3 What you should do if you find a security vulnerability
  • 36.2 Security team
    • 36.2.1 Security team appointment
    • 36.2.2 Security Team Operations
    • 36.2.3 What Yocto Security Team does when it receives a security vulnerability
    • 36.2.4 If an upstream project does not respond quickly
    • 36.2.5 Current Security Team members
• 37 Checking for Vulnerabilities
  • 37.1 Vulnerabilities in Poky and OE-Core
  • 37.2 Vulnerability check at build time
  • 37.3 Fixing CVE product name and version mappings
  • 37.4 Fixing vulnerabilities in recipes
  • 37.5 Implementation details
• 38 Creating a Software Bill of Materials
• 39 Using the Error Reporting Tool
  • 39.1 Enabling and Using the Tool
  • 39.2 Disabling the Tool
  • 39.3 Setting Up Your Own Error Reporting Server
• 40 Using Wayland and Weston
  • 40.1 Enabling Wayland in an Image
    • 40.1.1 Building Wayland
    • 40.1.2 Installing Wayland and Weston
  • 40.2 Running Weston
• 41 Using the Quick EMUlator (QEMU)
  • 41.1 Overview
  • 41.2 Running QEMU
  • 41.3 Switching Between Consoles
  • 41.4 Removing the Splash Screen
  • 41.5 Disabling the Cursor Grab
  • 41.6 Running Under a Network File System (NFS) Server
  • 41.7 QEMU CPU Compatibility Under KVM
  • 41.8 QEMU Performance
  • 41.9 QEMU Command-Line Syntax
  • 41.10 runqemu Command-Line Options
• 42 Locking and Unlocking Recipes Using bblock
  • 42.1 Locking tasks and recipes
  • 42.2 Unlocking tasks and recipes
  • 42.3 Configuration file
  • 42.4 Locking mechanism
  • 42.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.