aosp_guide/aosp-source-tree.md

AOSP Source tree

Let’s take our first confident step into the world of Android’s internals.

Understanding the AOSP Source Tree Structure

Im going explain the things first and then put you hands on the source so slow down you curiosity and stabilize you brain to learn.

Once when you download the Android source code using Google’s repo tool, you’ll see a massive directory. But it’s not as overwhelming as it looks — most of it’s are precisely organized by its functions and some may not. Dont worry about it i will explain everything you need to know.

Here’s a list of the directories that you will see when you sucessfully pulled the source to your local machine or you remote machine.

Directory	Description
art/	Android Runtime (ART) source code
bionic/	Android’s custom C library (libc, libm, etc.)
bootable/	Bootloader and recovery-related code
build/	Build system files (Make, Soong, config scripts)
compatibility/	Compatibility Test Suite (CTS) and related tools
cts/	Compatibility Test Suite source code
dalvik/	Legacy Dalvik VM (mostly deprecated)
developers/	Developer tools and documentation
development/	Tools and sample code for platform development
device/	Device-specific configuration and files
external/	Third-party open-source libraries (e.g., OpenSSL, SQLite)
frameworks/	Android framework code (Java APIs, system services)
hardware/	HALs and hardware interface implementations
kernel/	Kernel source trees (if included; often managed separately)
libcore/	Core Java libraries (java.*, javax.*)
packages/	System apps like Settings, SystemUI, etc.
pdk/	Platform Development Kit
platform_testing/	Infrastructure for platform-level testing
prebuilts/	Precompiled binaries and tools used during build
sdk/	Android SDK components
system/	Core system components (init, sepolicy, etc.)
test/	Unit and integration tests
toolchain/	Toolchain sources (e.g., GCC, Clang)
tools/	Build tools and utilities
vendor/	Vendor-specific blobs and configuration

Depending on the branch or target (like Pixel or emulator), you might also see:

• product/ – Product partition overlays
• vndk/ – Vendor Native Development Kit
• common/ – Shared components across devices
• soong/ – Soong build system internals (sometimes under build/)
• Some more if you have you choose some specific branch but for 99% of the times you dont probably have more than this.

1. art/ – Android Runtime

• Purpose: Contains the source code for ART, which replaced the Dalvik VM.

• Key Components:

  • runtime/: Core of the ART virtual machine.
  • compiler/: ART’s optimizing compiler for converting DEX to native code.
  • oat/, dex2oat/: Tools and formats for ahead-of-time compilation.

• Why it matters: ART is what executes your Android apps. Just an runtime program to be simple.

2. bionic/ – C Runtime (libc)

• Purpose: Android’s custom implementation of the C standard library (libc, libm, libdl).

• Key Components:

  • libc/: The lightweight libc optimized for embedded use.
  • tests/: Unit tests ensuring standard behavior.

• Why it matters: Every native app and system service relies on this for basic memory, string, and math operations.

3. bootable/ – Bootloader & Recovery

• Purpose: Contains source for Android bootloader parts and the recovery mode.

• Key Components:

  • bootloader/: Minimal code to boot up the system on some devices.
  • recovery/: Source code for stock recovery image.

• Why it matters: The first line of code that runs after powering on, before the kernel.

4. build/ – Build System

• Purpose: Core build scripts using Make, Soong, and other tools.

• Key Components:

  • build/make/: Classic Makefiles and product configs.
  • build/soong/: The new build system in Go.

• Why it matters: You can’t compile Android without this—defines how everything is put together.

5. compatibility/ and cts/ – Compatibility Testing

• Purpose: Enforce Android ecosystem standards across OEMs.

• Key Components:

  • cts/: Compatibility Test Suite sources.
  • vts/, gts/: Vendor and Google test suites.

• Why it matters: Ensures your device behaves like any other Android-compliant one.

6. dalvik/ – Legacy Runtime

• Purpose: Original Android runtime, replaced by ART but still kept around for historical reasons or backward compatibility testing.

• Key Components:

  • vm/: Dalvik Virtual Machine internals.

• Why it matters: It was Android’s first runtime environment. Studying it can give you context for ART’s improvements.

7. development/ – Platform Dev Tools

• Purpose: Houses sample projects, SDK tools, and various utilities.

• Key Components:

  • apps/: Test apps like Dev Tools and spare launchers.
  • scripts/: Helper scripts for developers (e.g., systrace, profiling).

• Why it matters: Great for exploring how developers debug and experiment with Android features.

8. device/ – Device-Specific Configs

• Purpose: Contains configuration files for supported devices (like Pixel, emulator, etc.).

• Key Components:

  • device/google/: Pixel configuration examples.
  • BoardConfig.mk, device.mk: Setup how the build system understands the hardware.

• Why it matters: This is where you customize for new hardware — essential for custom ROMs. Also where you put those configurations of your motherborad, camera,... like devices info to make the AOSP to build for it.

9. external/ – Third-Party Libraries

• Purpose: Bundles open-source software Android depends on.

• Examples:

  • openssl/, zlib/, libpng/, clang/

• Why it matters: Keeps all upstream dependencies organized and versioned in sync with AOSP. Like the tolls used to dig a hole. here these are to build and streamline our experience while developing.

10. frameworks/ – The Android Framework

• Purpose: Java-based layer that provides high-level services used by apps.

• Key Components:

  • base/: Core framework — ActivityManager, WindowManager, ContentProviders, etc.
  • av/: Media framework.
  • native/: Native services and JNI bindings.

• Why it matters: If you want to modify system behavior, this is the place. You can optimize the performance by using your cutting edge skills by modifying things inside it.

11. hardware/ – Hardware Abstraction Layer (HAL)

• Purpose: Interface between Android and device hardware.

• Key Components:

  • Subfolders like interfaces/, libhardware/, google/
  • Contains HIDL/AIDL definitions and implementations.

• Why it matters: Lets Android talk to device-specific hardware without hardcoding vendor logic into the OS.

12. kernel/ – Linux Kernel (if present)

• Purpose: Kernel source trees for devices (optional — some are pulled externally).

• Key Components:

  • Typically named kernel/google/msm/ or similar.

• Why it matters: It’s the base of Android. You can modify schedulers, drivers, or build your own kernel.

13. libcore/ – Java Core Libraries

• Purpose: Provides foundational Java packages (java.util, java.io, etc.).

• Key Components:

  • luni/: Core libraries (java.lang, etc.)
  • ojluni/: Merged OpenJDK libraries.

• Why it matters: Every Java app on Android relies on this — it’s the bedrock of the language APIs.

14. packages/ – System Apps

• Purpose: Hosts the source code for system apps and UI components.

• Key Examples:

  • Settings/, SystemUI/, Launcher3/

• Why it matters: This is where things like the lock screen, Quick Settings, and launcher behavior live. You can add most required apps that you want to be preloaded.

15. platform_testing/ – Testing Infrastructure

• Purpose: Platform-wide test runners, benchmarking, and test coordination scripts.

• Why it matters: Ensures platform stability with continuous testing across modules.

16. prebuilts/ – Precompiled Tools

• Purpose: Tools and binaries that don’t need to be built from source (e.g., clang, aapt). You can also make or modify and use your it as you wish but its kinda hardcoding skills needed i recommend to stick with aosp ones as they are stable.

• Structure:

  • clang/, gcc/, sdk/, tools/

• Why it matters: These speed up builds and ensure consistent toolchains.

17. sdk/ – Android SDK

• Purpose: Contains parts of the Software Development Kit used by app developers.

• Key Components:

  • APIs, emulator images, tools like aapt, dx, and more.

• Why it matters: This is how Android app devs build, package, and test their apps using the platform you’re modifying.

18. system/ – Core Android System

• Purpose: One of the most important folders — includes Android’s init, core utilities, security policies, and daemon logic.

• Key Components:

  • core/: Native system components.
  • sepolicy/: SELinux rules for enforcing mandatory access control.
  • init/: The native init process implementation.

• Why it matters: Everything from system service spawning to filesystem mounting begins here.

19. test/ – Unit & Integration Testing

• Purpose: Used for testing Android components at the system level.

• Includes:

  • JUnit-based unit tests, integration frameworks, shell test runners.

• Why it matters: Ensures reliability when changes are made to core components.

20. toolchain/ – Compiler Infrastructure

• Purpose: Holds source and configs for GCC/Clang-based toolchains.

• Why it matters: You might not need to edit this often, but it defines the compilers used when building native code.

21. tools/ – Build Tools and Utilities

• Purpose: Miscellaneous tools used for code analysis, linting, SDK packaging, etc.

• Notable Subdirs:

  • repohooks/, lint/, apkzlib/

• Why it matters: Improves code quality and build consistency across the platform.

22. vendor/ – Proprietary Vendor Code

• Purpose: Non-open-source components and binaries provided by chipset vendors or OEMs.

• Why it matters: The bridge between AOSP and real hardware. If you want to port Android to a new device, you’ll need matching vendor blobs here.

(Optional, later will get to know) product/, vndk/, common/, soong/

• Seen in some branches or manifests.
• product/: Used for /product partition overlays.
• vndk/: Vendor Native Development Kit under Project Treble.
• common/: Shared code across multiple device platforms.
• soong/: Standalone directory for the Soong build system, in some branches.

---

Deeper Look Into Some Important Directories

---

Let’s roll on, This time zooming into some of the most important internal folders of the AOSP tree. Since we finished the top-level overview, I’ll now guide you into the internal structures of key folders, one at a time.

Let’s begin with:

frameworks/ – The Beating Heart of Android APIs

This directory is where the Android SDK APIs, system services, and many Java-side frameworks live. It’s vast, so here’s how it breaks down:

Subdirectory	Purpose
base/	Core of the Android framework — ActivityManager, SystemServer, ContextImpl, etc.
native/	Native system components (e.g., SurfaceFlinger, input system).
av/	Media framework: audio/video playback, camera services.
opt/	Optional modules, often experiments or new subsystems (like telephony).
ml/	Android ML interfaces and integration points for hardware acceleration.
support/	Legacy support libraries (mostly deprecated now).
rs/	RenderScript (deprecated, but still present in older branches).

Within frameworks/base/, you’ll find even more subdivisions:

• core/java/ → Public and hidden Java APIs.
• services/ → System services like ActivityManager, WindowManager.
• cmds/ → Entrypoints like app_process (where Zygote starts).
• startop/, telephony/, location/ → Domain-specific services.

You’ll basically live inside base/ if you're customizing Android behavior at the system level.

Next one of the most foundational areas of AOSP.

system/ – Core Android System Components

This folder is where much of Android’s native system infrastructure resides. It influences early boot, power management, process control, and security. Let’s break down its key subdirectories:

Subdirectory	Purpose
core/	Hosts libcutils, liblog, and native tools used system-wide. Also includes toolbox utilities (like ls, ps, etc.).
sepolicy/	SELinux policy source files (.te, .cil, .fc), defining what services can do at runtime.
init/	The init program implementation: parses init.rc, spawns daemons, mounts filesystems, applies permissions.
libvintf/	Verifies system/vendor interface compatibility (VINTF), part of Treble.
libfmq/, libhidl/	Fast message queues and legacy HIDL support libraries.
update_engine/	OTA update mechanism used by Android (especially in A/B partitions).
netd/	Manages Android’s networking stack — DNS, interfaces, tethering, etc.
logging/	Logging subsystem (logcat, buffer management, etc.).
security/	Key attestation, keystore, and related cryptography frameworks.
tools/	Misc utilities for packaging and system dev (like mksysimg).

---

Why system/ Matters:

• It's one of the earliest initialized parts of Android.
• Many of Android’s core daemons (like vold, servicemanager, lmkd, etc.) live or are launched from here.
• If you're working with init.rc, SELinux, or system binaries, this folder is your best friend.

Next we’ll venture into the next big one: packages/ — home to settings, UI, and the launcher you see on screen.

Let’s dive into a folder that paints what you see on screen and holds the apps Android users interact with every day.

packages/ – System Apps & UI Components

This folder contains the built-in Android applications, launchers, and essential UI layers. When you see Settings, SystemUI, or even the default Launcher — this is where the magic begins.

Subdirectory	Purpose
apps/	Official system apps like Contacts, Dialer, DeskClock, Messaging, etc.
Settings/	The Android Settings app — from toggles to hidden developer options.
SystemUI/	Status bar, notification panel, Quick Settings, lock screen, and more.
InputMethods/	Default input methods like LatinIME (keyboard apps).
Screensavers/	Built-in screen savers (aka “Daydreams” from older Androids).
Providers/	Content providers (e.g., MediaProvider, TelephonyProvider).
WallpaperPicker/	System wallpaper selector UI.
Launcher3/	Reference launcher used by AOSP — the “home screen” experience.

---

Why packages/ Matters:

• You’ll go here to customize or replace stock apps, like tweaking SystemUI for a custom ROM.
• It's where Java + XML combine: you get layouts, drawables, logic, and resource overlays all working together.
• If you're building a modular or minimalist ROM, this is the place to trim or enhance.

Most apps here use a mix of:

• Java/Kotlin for app logic
• XML for layouts and UI
• Gradle or Make/BP for build definitions

Next through vendor/ — where proprietary code lives, or external/, home of all the open-source third-party dependencies. Or if you're curious to enter the Android build pipeline soon, we can start looking at the build/ and prebuilts/ folders next.

vendor/ – Vendor-Specific Code & Proprietary Binaries

This directory is crucial for any device-specific AOSP build. It houses all the non-open-source blobs, configs, and binaries provided by SoC vendors (like Qualcomm, MediaTek) and OEMs (like Motorola, Samsung).

Subdirectory	Purpose
vendor/<oem>/	Top-level vendor folder, e.g., vendor/google/, vendor/motorola/.
proprietary/	Closed-source firmware blobs — camera libs, WiFi drivers, etc.
prebuilt/	Precompiled binaries needed during the build.
sepolicy/	Vendor-specific SELinux extensions to complement system policies.
init/	Vendor init RC scripts (like init.vendor.rc), executed by Android init.
lib64/, lib/	Vendor-shipped native shared libraries.
bin/	Daemons or executables (e.g., thermal_engine, imsd).
etc/	Config files for RIL, audio, graphics, etc.
modules/	Kernel modules (.ko files) required at runtime.

Why vendor/ Is Essential:

• Required for real hardware builds: Without this, AOSP runs only on generic emulators.
• Partition separation (Treble): It's split from /system and mounted as /vendor, isolating hardware code.
• For ROM devs like you, extracting vendor blobs is key for porting AOSP to new devices.

Next we continue with external/, which houses all third-party open-source libraries.

external/ – Third-Party Open Source Libraries

This directory is Android’s curated collection of open-source projects it depends on. These aren’t developed by Google but are vital for system functionality.

Subdirectory Examples	Purpose
openssl/, boringssl/	Cryptographic libraries.
libxml2/, jsoncpp/	XML and JSON parsing.
clang/, llvm-project/	Android’s compiler and tooling stack.
f2fs-tools/, e2fsprogs/	Filesystem utilities.
icu/	Unicode and internationalization support.
protobuf/	Google’s Protocol Buffers serialization.
libziparchive/, zlib/	Archiving and compression.

These folders are regularly updated to sync with upstream versions, but with patches to fit Android’s needs (like BoringSSL replacing OpenSSL).

build/ (revisited) – Android Build Logic

While we already mentioned it briefly, let’s look deeper.

Subdirectory	Role
make/	Legacy Make-based system. Includes envsetup.sh, lunch, product configs.
soong/	Modern Go-based build engine (Android.bp, blueprint) — much faster and more modular.
kati/, ninja/	Makefile-to-ninja converters for optimized builds.
tools/	Scripts for packaging OTAs, generating system.img, etc.

This folder orchestrates how the entire source tree gets transformed into flashable images.

prebuilts/ – Precompiled Tools and Artifacts

Subdirectory	Purpose
clang/, gcc/, ndk/	Prebuilt compilers and toolchains — used instead of building them from source.
sdk/, gradle-plugin/	Android SDK and build tools for app developers.
misc/, tools/	Helper binaries and scripts (e.g., aapt, adb, fastboot).

Why it matters: These binaries are version-locked and optimized — saving hours of build time. For example, building LLVM/Clang from scratch would be a nightmare without this.

toolchain/ – Compiler Source Trees

Subdirectory	Purpose
llvm/, riscv/, arm/	Source for platform-specific compilers and assembler/linker utilities.
binutils/, gcc/	Older toolchain components, still used on some branches.

Why it matters: If you're modifying native C/C++ build behavior, targeting exotic architectures, or tinkering with LLVM itself, this is the forge.

soong/ – Soong Build System Engine

• The brains behind the Android.bp system — written in Go.
• Interprets Blueprint files to produce Ninja build rules.
• Works side by side with Makefiles (especially during legacy-to-Soong transitions).

This is what powers modern AOSP builds — lightning-fast, modular, and dependency-aware.

vndk/ & product/ – Partitioned Modularity

Folder	Role
vndk/	Shared native libraries (Vendor Native Development Kit) for Treble compliance.
product/	Extra product-specific apps, overlays, or configs (goes into /product partition).

These ensure modularization between the system (/system), vendor (/vendor), and product (/product) partitions — giving manufacturers flexibility without breaking compatibility.

And that’s it — you’ve now mapped the entire AOSP source tree. Every folder, from the cryptic internals to the user-facing polish, the aosp source is now yours to explore.

Quick Recap: What You Now Know

• You understand the entire top-level AOSP directory tree.
• You’ve explored each key folder like frameworks/, system/, packages/, vendor/, external/, and more.
• You know when and why to explore subfolders — based on your goals (custom ROMs, HAL integration, boot mods, etc.).

Mostly this is much you learnt is enough for now but you might need to learn the much deep inside each folders when it comes to customizing, but no worries i will take care of it. I will also tell you how to customize of things and behaviours later on upcoming chapters. Stay Tuned!