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.



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

- **Structure:**
  - `clang/`, `gcc/`, `sdk/`, `tools/`

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