Chapter 3. Common Tasks

Table of Contents

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.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.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.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 Targets with Multiple Configurations
3.10.3. Building an Initial RAM Filesystem (initramfs) Image
3.10.4. Building a Tiny System
3.10.5. Building Images for More than One Machine
3.10.6. Building Software from an External Source
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.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.5. Using an Existing Kickstart File
3.16.6. Using the Wic Plug-Ins Interface
3.16.7. Examples
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.3. Handling Optional Module Packaging
3.22.4. Using Runtime Package Management
3.22.5. Generating and Using Signed Packages
3.22.6. Testing Packages With ptest
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
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.29. Performing Automated Runtime Testing
3.29.1. Enabling Tests
3.29.2. Running Tests
3.29.3. Exporting Tests
3.29.4. Writing New Tests
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.12. Debugging Parallel Make Races
3.30.13. Debugging With the GNU Project Debugger (GDB) Remotely
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.32. Working With Licenses
3.32.1. Tracking License Changes
3.32.2. Enabling Commercially Licensed Recipes
3.32.3. Maintaining Open Source License Compliance During Your Product's Lifecycle
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.2. Running Weston

This chapter describes fundamental procedures such as creating layers, adding new software packages, extending or customizing images, porting work to new hardware (adding a new machine), and so forth. You will find that the procedures documented here occur often in the development cycle using the Yocto Project.