BUILD_PACKAGE and Other Build Rules

The Missing Trigger: Why Variables Do Not Build Code

You just wrote an Android.mk file with perfect syntax. After defining your source files and naming your module, you typed out the module build command. The build finishes instantly, but your output directory remains completely empty. Make reads your file, parses every variable, and then quietly exits without compiling a single line of code.

This happens because LOCAL_ variables only hold configuration state. They are entirely inert on their own. Think of them like gathering ingredients on a kitchen counter. Without turning on the blender, you just have a messy counter. The build system needs a specific command to act on the state you just defined.

That command is the build rule. By adding an include $(BUILD_*) statement at the bottom of your module, you trigger the execution engine. This rule consumes all the LOCAL_ variables defined above it and fires off the actual compiler commands.

LOCAL_PATH := $(call my-dir)
include $(CLEAR_VARS)

LOCAL_MODULE := useless_module
LOCAL_SRC_FILES := main.cpp

# Without a rule here, nothing happens

Warning: Always include $(CLEAR_VARS) at the top of a new module definition. If you forget this, variables from the previously evaluated module will pollute your current module state before your build rule fires.

When you add include $(BUILD_EXECUTABLE) to that file, Make finally calls the C++ compiler. Build rules act as the engine for AOSP compilation. Once we understand that rules are the engine, we can look at the engine used to build apps.

Replacing Gradle: Building Apps with BUILD_PACKAGE

Android developers are used to relying on Gradle to handle the heavy lifting of building an application. Inside the AOSP source tree, Gradle does not exist. You have to compile Java code and resources directly into a system APK using Make. The platform build system replaces the massive Gradle infrastructure with a single target.

The BUILD_PACKAGE rule handles everything required to generate a complete .apk file. First, it compiles your Java or Kotlin sources. Next, the tool packages your XML resources. Finally, it signs the output with a platform cryptographic key.

LOCAL_PATH := $(call my-dir)
include $(CLEAR_VARS)

LOCAL_SRC_FILES := $(call all-java-files-under, src)
LOCAL_RESOURCE_DIR := $(LOCAL_PATH)/res
LOCAL_PACKAGE_NAME := MySystemApp
LOCAL_CERTIFICATE := platform

include $(BUILD_PACKAGE)

Processing this file places the resulting application into /system/app/MySystemApp/. The LOCAL_CERTIFICATE variable tells the system to sign this APK with the core platform key, granting it elevated permissions. This single rule orchestrates the entire compilation pipeline.

Common Mistake: Do not use LOCAL_MODULE when building an app. Apps require LOCAL_PACKAGE_NAME to compile correctly, whereas native and Java libraries require LOCAL_MODULE.

Applications run in a managed Java environment, but they only represent one layer of the operating system. The platform requires native daemons running beneath that framework to function.

Dropping to the Shell: Native Binaries with BUILD_EXECUTABLE

Sometimes you need to write a command-line tool that runs directly in the Linux layer of Android. You cannot package a raw C++ file inside an APK to run as a shell command. The operating system needs a compiled executable binary sitting in a bin directory. A dedicated rule exists for this exact requirement.

The BUILD_EXECUTABLE target compiles C and C++ source files into a standalone binary. You define your source files, and the build system handles the cross-compilation for the target device architecture. Running the module build command generates the executable, which you then push to the device for testing.

mm
adb push $OUT/system/bin/hello_aosp /system/bin/
adb shell hello_aosp

A common error engineers make is attempting to push and run a freshly compiled binary on a read-only partition without remounting first. Always ensure your device has a writable file system and the binary has execute permissions. Standalone tools work perfectly for isolated tasks. However, multiple daemons often need to share the same underlying native code.

Sharing Native Code: Shared vs. Static Libraries

Copying the same utility functions into ten different command-line tools wastes physical storage on the device. When building native libraries in AOSP, you must decide how that code gets distributed. You have to choose between embedding the code directly or linking it at runtime. The build system offers two different rules for these two approaches.

The BUILD_SHARED_LIBRARY rule creates a .so file that the dynamic linker loads into memory on the physical device. In contrast, the BUILD_STATIC_LIBRARY rule creates an .a archive that the compiler embeds into another binary during the build process. We can understand this deployment model by tracking the files across three distinct steps:

1. The host machine compiles the static library.
2. Compile-time linking embeds that static library directly into both daemons on the host.
3. Target devices dynamically load the separate shared library into those same daemons at runtime.

Visualizing this process demonstrates that a static library never actually transfers to the physical device. Your build machine injects the static library code directly into Daemon 1 and Daemon 2. The shared library moves to the target device, where both daemons reference the single file in memory.

If you have a core graphics library required by both SurfaceFlinger and a custom daemon, you build it as a shared library. Alternatively, if you have a tiny math utility used by only one custom executable, you build it as a static library to avoid dynamic linking overhead.

Interview Note: Static libraries exist strictly on the Ubuntu build host. You will never find a .a file on a running Android device.

Choosing the right library type keeps the OS image lean and efficient. While we usually compile code from source, sometimes we have to include proprietary libraries without source code.

Handling Vendor Blobs: The BUILD_PREBUILT Escape Hatch

Hardware manufacturers frequently provide drivers as closed-source proprietary binaries. You cannot use the standard build rules because you have no C++ files to compile. The build system needs a way to bypass the compiler and place an existing file into the final image.

The BUILD_PREBUILT target acts as an escape hatch for these situations. It tells Make to take a pre-compiled file from your source tree and copy it directly to a specific partition. You are essentially plating prepared food instead of cooking raw ingredients.

LOCAL_PATH := $(call my-dir)
include $(CLEAR_VARS)

LOCAL_MODULE := libcamera_vendor
LOCAL_SRC_FILES := libcamera_vendor.so
LOCAL_MODULE_CLASS := SHARED_LIBRARIES
LOCAL_MODULE_SUFFIX := .so

include $(BUILD_PREBUILT)

Because there is no source code to infer from, you must explicitly declare the LOCAL_MODULE_CLASS. This variable tells the build system what kind of file it is handling so it knows where to place it. Setting it to SHARED_LIBRARIES ensures the prebuilt binary lands in a library directory rather than an app directory.

Common Mistake: Forgetting to declare LOCAL_MODULE_CLASS causes the build system to fail because it does not know where to install the prebuilt file.

These fundamental rules work together to assemble every piece of the Android OS.

The Foundation of the OS Image

Make acts as an execution engine for your module configuration. The BUILD_PACKAGE rule replaces Gradle for system applications, while BUILD_EXECUTABLE generates native command-line tools. You use shared libraries to conserve space on the device and static libraries for compile-time embedding. Finally, BUILD_PREBUILT provides a path for integrating proprietary vendor blobs directly into the system image.

We just learned the fundamental Make rules, but a major problem exists with this approach. Make is slow, error-prone, and Google is actively deprecating it within AOSP. If Make is disappearing, how exactly does the modern platform compile all this code today?