Chapter 5. Common Tasks

Table of Contents

5.1. Understanding and Creating Layers
5.1.1. Layers
5.1.2. Creating Your Own Layer
5.1.3. Best Practices to Follow When Creating Layers
5.1.4. Enabling Your Layer
5.1.5. Using .bbappend Files
5.1.6. Prioritizing Your Layer
5.1.7. Managing Layers
5.1.8. Creating a General Layer Using the yocto-layer Script
5.2. Customizing Images
5.2.1. Customizing Images Using local.conf
5.2.2. Customizing Images Using Custom IMAGE_FEATURES and EXTRA_IMAGE_FEATURES
5.2.3. Customizing Images Using Custom .bb Files
5.2.4. Customizing Images Using Custom Package Groups
5.3. Writing a New Recipe
5.3.1. Overview
5.3.2. Locate a Base Recipe
5.3.3. Storing and Naming the Recipe
5.3.4. Understanding Recipe Syntax
5.3.5. Running a Build on the Recipe
5.3.6. Fetching Code
5.3.7. Unpacking Code
5.3.8. Patching Code
5.3.9. Licensing
5.3.10. Configuring the Recipe
5.3.11. Compilation
5.3.12. Installing
5.3.13. Enabling System Services
5.3.14. Packaging
5.3.15. Properly Versioning Pre-Release Recipes
5.3.16. Post-Installation Scripts
5.3.17. Testing
5.3.18. Examples
5.4. Adding a New Machine
5.4.1. Adding the Machine Configuration File
5.4.2. Adding a Kernel for the Machine
5.4.3. Adding a Formfactor Configuration File
5.5. Working With Libraries
5.5.1. Including Static Library Files
5.5.2. Combining Multiple Versions of Library Files into One Image
5.5.3. Installing Multiple Versions of the Same Library
5.6. Configuring the Kernel
5.6.1. Using  menuconfig
5.6.2. Creating Configuration Fragments
5.6.3. Fine-Tuning the Kernel Configuration File
5.7. Patching the Kernel
5.7.1. Create a Layer for your Changes
5.7.2. Finding the Kernel Source Code
5.7.3. Creating the Patch
5.7.4. Set Up Your Layer for the Build
5.7.5. Set Up for the Build
5.7.6. Build the Modified QEMU Kernel Image
5.7.7. Boot the Image and Verify Your Changes
5.8. Making Images More Secure
5.8.1. General Considerations
5.8.2. Security Flags
5.8.3. Considerations Specific to the OpenEmbedded Build System
5.8.4. Tools for Hardening Your Image
5.9. Creating Your Own Distribution
5.10. Creating a Custom Template Configuration Directory
5.11. Building a Tiny System
5.11.1. Overview
5.11.2. Goals and Guiding Principles
5.11.3. Understand What Contributes to Your Image Size
5.11.4. Trim the Root Filesystem
5.11.5. Trim the Kernel
5.11.6. Remove Package Management Requirements
5.11.7. Look for Other Ways to Minimize Size
5.11.8. Iterate on the Process
5.12. Working with Packages
5.12.1. Excluding Packages from an Image
5.12.2. Incrementing a Package Revision Number
5.12.3. Handling a Package Name Alias
5.12.4. Handling Optional Module Packaging
5.12.5. Using Runtime Package Management
5.12.6. Testing Packages With ptest
5.13. Working with Source Files
5.13.1. Setting up Effective Mirrors
5.13.2. Getting Source Files and Suppressing the Build
5.14. Building Software from an External Source
5.15. Selecting an Initialization Manager
5.15.1. Using systemd Exclusively
5.15.2. Using systemd for the Main Image and Using SysVinit for the Rescue Image
5.16. Using an External SCM
5.17. Creating a Read-Only Root Filesystem
5.17.1. Creating the Root Filesystem
5.17.2. Post-Installation Scripts
5.17.3. Areas With Write Access
5.18. Performing Automated Runtime Testing
5.18.1. Enabling Tests
5.18.2. Running Tests
5.18.3. Exporting Tests
5.18.4. Writing New Tests
5.19. Debugging With the GNU Project Debugger (GDB) Remotely
5.19.1. Set Up the Cross-Development Debugging Environment
5.19.2. Launch Gdbserver on the Target
5.19.3. Launch GDB on the Host Computer
5.19.4. Connect to the Remote GDB Server
5.19.5. Use the Debugger
5.20. Debugging Parallel Make Races
5.20.1. The Failure
5.20.2. Reproducing the Error
5.20.3. Creating a Patch for the Fix
5.20.4. Testing the Build
5.21. Examining Builds Using the Toaster API
5.21.1. Starting Toaster
5.21.2. Using Toaster
5.21.3. Examining Toaster Data
5.21.4. Stopping Toaster
5.22. Profiling with OProfile
5.22.1. Profiling on the Target
5.22.2. Using OProfileUI
5.23. Maintaining Open Source License Compliance During Your Product's Lifecycle
5.23.1. Providing the Source Code
5.23.2. Providing License Text
5.23.3. Providing Compilation Scripts and Source Code Modifications
5.24. Using the Error Reporting Tool
5.24.1. Enabling and Using the Tool
5.24.2. Disabling the Tool
5.24.3. Setting Up Your Own Error Reporting Server

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.