A Comprehensive Guide to the Android.bp Build System

type

status

date

slug

summary

Introduction

As Android projects have grown in complexity and size, the traditional Make-based build system has become increasingly challenging to maintain and extend. To improve build efficiency and modularity, Android introduced a new build system called Soong starting from Nougat (Android 7.0). Soong uses Blueprint as its configuration language and is implemented in Go, aiming to replace the old Make build system.

Evolution of the Build System

From Make to Soong

GNU Make: The early Android build system was based on GNU Make, utilizing Android.mk files to define build rules. As projects grew, the complexity and maintenance cost of Makefiles increased.

Kati: To address performance issues with GNU Make, Android introduced Kati, a tool for parsing Makefiles, which improved build speeds.

Soong: To fundamentally solve the maintainability and scalability challenges, Android began using Soong, leveraging a modern language and architectural design.

Overview of the Soong Build System

Soong and Blueprint

Soong: A new build system for Android, written in Go, designed to enhance build speed and maintainability.

Blueprint: A meta-build system implemented in Go, providing the configuration language for Soong. Blueprint files have the .bp extension, known as Android.bp files.

Soong uses Blueprint as a front-end parser to read Android.bp files, generates Ninja build files, and then uses Ninja to execute the actual build process.

Structure of Android.bp Files

Basic Syntax

Module Definitions: Each module is defined by a function call, where the function name represents the module type, and the parameters are property dictionaries.

Comments: Use // for single-line comments.

Module Definitions

Module Types: Specify the type of module to build, such as cc_library, cc_binary, java_library, android_app, etc.

Properties: Key-value pairs within modules defining various attributes like name, source files, dependencies, and more.

Common Module Types

cc_library

Used to build C/C++ static or shared libraries.

cc_binary

Used to build C/C++ executables.

java_library

Used to build Java libraries.

android_app

Used to build Android applications (APKs).

Detailed Explanation of Attributes

name

Description: The unique name of the module.

Type: String.

Example:

srcs

Description: Specifies the list of source files, can include wildcards.

Type: List of strings.

Example:

deps

Description: Dependencies of the module, commonly used in Java modules.

Type: List of strings.

Example:

shared_libs and static_libs

Description: Shared and static library dependencies for C/C++ modules.

Type: List of strings.

Example:

Compilation Options

cflags: Flags passed to the C compiler.

cppflags: Flags passed to the C++ compiler.

ldflags: Flags passed to the linker.

Example:

Conditional Compilation and Variants

Product Variables

Adjust module properties based on product variables.

Config Variables

Set properties based on build configurations.

Example Analysis

Below is a complete Android.bp example with explanations:

name: The module is named libexample.

srcs: Source file src/example.cpp.

shared_libs: Depends on the shared library libdependency.

cflags: Adds the compiler flag DEXAMPLE_FEATURE.

product_variables: Adds DDEBUG_MODE when building a debuggable variant.

target: Adds specific source files based on the target platform.

Debugging and Common Issues

How to View Build Logs

Add Verbose Logging:

Inspect Ninja Files:

Common Errors and Solutions

Duplicate Module Names: Ensure that the name attribute is unique across all modules.

Incorrect Paths: Verify that srcs, include_dirs, and other paths are correct.

Missing Dependencies: Check that dependency module names are correct and that they are included in the build.

Advanced Topics

Custom Module Types

While Soong provides a rich set of built-in module types, you might need to define custom module types to meet specific build requirements.

Defining Custom Modules

Creating a custom module type involves writing Go code within Soong:

Create a New Soong Module: Add new Go source files under the build/soong directory.

Register the Custom Module: Register the new module type during Soong's initialization.

Implement Module Logic: Define module properties and behavior, handling source files, dependencies, and output generation.

Example: Custom Script Module

Here's how you might create a module type to execute custom scripts:

Note: Defining custom modules requires in-depth knowledge of Soong internals and is recommended only when necessary.

Common Functions and Operators

In Android.bp files, you can use functions and operators to manipulate strings and lists, enhancing configuration flexibility.

String Operations

replace: Replace substrings within strings.

prefix: Add a prefix to each string in a list.

suffix: Add a suffix to each string in a list.

List Operations

append: Combine two lists.

filter: Filter a list based on patterns.

Multi-Architecture and Multi-Platform Support

Device and Host Builds

Configure modules for different targets:

Device Target: For modules running on Android devices.

Host Target: For tools or modules running on the build host.

Handling Different CPU Architectures

Architecture-Specific Configurations: Customize configurations for different CPU architectures.

Specifying Architectures: Use the arch property to specify architecture-specific source files.

Build Variants

Soong supports generating different module versions based on build variants.

Feature Variants

Defining Variants: Create different module versions based on feature sets.

Language Variants

Supporting Multiple Languages: Include different language source files within the same module.

Resource Management

Localization Resources

Resource Directories: Specify application resource files.

Localization Support: Use directories like values-xx for different languages.

Resource Merging and Optimization

AAPT Options: Configure resource packaging options.

Resource Optimization: Optimize resources by setting options like compressible and png_optimization.

Interoperability with Legacy Android.mk

Include Mechanism

Including Legacy Makefiles: You can include old Makefiles in Android.bp files.

Converting Existing Android.mk Files

Using bpfix Tool: Android provides the bpfix tool to convert some Android.mk files to Android.bp.

Manual Conversion: Since automatic conversion may be incomplete, it's advisable to manually review and adjust the converted files.

Best Practices

Module Naming Conventions

Uniqueness: Ensure module names are globally unique to prevent conflicts.

Clarity: Use names that clearly describe the module's purpose or content.

Code Organization and Directory Structure

Functional Organization: Organize code by functionality for easier maintenance.

Modular Design: Break code into small, independent modules to enhance reusability.

Performance Optimization

Minimize Dependencies: Depend only on necessary modules to avoid redundant builds.

Parallel Builds: Use the j option and tools like ccache to speed up builds.

Frequently Asked Questions

Q1: Why isn't my module being built?

Solution: Ensure the module is correctly included in the build:

Check that the module's directory contains an Android.bp file.

Verify the module name is correct.

Build the module individually using m <module_name> to check for errors.

Q2: How do I use environment variables in Soong?

Solution: Soong doesn't directly support environment variables. Use soong_config or product_variables to pass configurations.

Q3: Where is my module's build output located?

Solution: Build outputs are typically under out/soong/<module_type>/<module_name>/. Search for the module name in build.ninja to find the exact path.

Summary

The Android.bp build system is a key component of Android's build architecture, offering a modern, modular, and efficient build process. By understanding Soong's principles and Android.bp's syntax, developers can better manage builds and improve development efficiency.

In practice, leverage Soong's features and follow best practices to ensure your project's maintainability and scalability.