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) 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.

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!