Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 104 ยท Getting Started

Anatomy of an Android Project

Tour an Android Studio project: the app module, src/main, res folders, the manifest, build.gradle.kts, settings files and the generated R and BuildConfig classes.

The first time you open a generated Android project, it looks crowded. There are two build.gradle.kts files, a libs.versions.toml, a folder called res full of folders with odd names and a hidden build directory that grows to hundreds of megabytes. None of it is random. Android projects follow strong conventions, and once you know them you can open any app and find your way in minutes.

This lesson is a guided tour of the files and folders of an Empty Activity project. The real files are read-only listings: they need the Android build to mean anything. At the end a runnable stand-in models the most surprising part, the way res folders with qualifiers become a lookup table of numeric ids.

The top level of the project

Here is the root of a new project called "Notes". This is a read-only listing.

TEXT
Notes/
  settings.gradle.kts          which modules exist, plugin and repository setup
  build.gradle.kts             project-wide plugin declarations
  gradle.properties            Gradle and Android build flags
  local.properties             machine-specific paths (never commit it)
  gradle/
    libs.versions.toml         the version catalog: names and versions of dependencies
    wrapper/                   which Gradle version this project uses
  gradlew, gradlew.bat         wrapper scripts
  app/                         the app module
  build/                       generated output (never edit, never commit)

Two details are worth stating early. local.properties holds the location of the SDK on your machine, so it is ignored by version control. The build/ folders are outputs, always recreated from sources, and are also ignored.

Modules

A module is a unit of the build with its own build.gradle.kts. A new project has one module, named app. Larger apps split code into several modules, such as :feature:search or :core:data, to build faster and enforce boundaries. Modules are listed in settings.gradle.kts.

Kotlin
// read-only example: settings.gradle.kts
pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
    }
}

rootProject.name = "Notes"
include(":app")

include(":app") registers the module. The two repository blocks say where Gradle may download plugins and libraries from: google() hosts the Android and Jetpack artifacts, and mavenCentral() hosts most others.

The root build.gradle.kts usually just declares plugins with apply false, so each module can then apply the ones it needs at a consistent version:

Kotlin
// read-only example: build.gradle.kts (project root)
plugins {
    alias(libs.plugins.android.application) apply false
    alias(libs.plugins.kotlin.android) apply false
    alias(libs.plugins.kotlin.compose) apply false
}

The alias(...) calls refer to entries in the version catalog, which Gradle for Android explains.

Inside the app module

TEXT
app/
  build.gradle.kts             this module's plugins, SDK levels, dependencies
  proguard-rules.pro           keep rules for the code shrinker R8
  src/
    main/                      the code and resources that ship in every build
      AndroidManifest.xml
      java/com/example/notes/  Kotlin sources (the folder is named java by convention)
        MainActivity.kt
        ui/theme/...
      res/                     resources: strings, colors, images, layouts
    test/                      local unit tests, run on your computer's JVM
    androidTest/               instrumented tests, run on a device or emulator

Source sets deserve a short explanation. src/main is the code that is in every build of the app. Other folders such as src/debug, src/release or src/free can add or override files for one build type or flavor, which you will use in Signing and Release Builds. src/test and src/androidTest hold tests: the first run on a plain JVM (fast, no Android classes unless faked) and the second need a device.

The Kotlin sources live under java/ for historical reasons. Kotlin files may also sit in a kotlin/ folder, and Gradle accepts both. The package declaration at the top of a file should match its folder path.

The manifest

AndroidManifest.xml is the app's identity card for the system. It declares the components (activities, services, receivers, providers), the permissions the app requests and which Activity is the launcher entry point. The system reads it before it runs any of your code. You will study it in detail in The Manifest and Resources.

XML
<!-- read-only example: app/src/main/AndroidManifest.xml -->
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:theme="@style/Theme.Notes">
        <activity android:name=".MainActivity" android:exported="true">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
</manifest>

Note the @string/app_name style: those are resource references. The manifest does not contain the app's name as text. It points to an entry in res/values/strings.xml.

The res folder

All non-code assets live in res/, in folders named after their type:

Folder Holds
res/values/ strings, colors, dimensions, styles, as XML files
res/drawable/ images and vector drawables
res/mipmap-*/ launcher icons at several densities
res/layout/ XML layouts (legacy Views)
res/xml/ arbitrary XML config such as backup rules
res/raw/ raw files kept as they are

A folder name can carry a qualifier after a hyphen: values-night, values-es, drawable-xxhdpi, layout-sw600dp. The system picks the folder whose qualifiers best match the current device configuration. That mechanism is how one app supports dark mode, many languages and many screen densities with almost no code.

flowchart LR
    S["res/values/strings.xml<br/>app_name = Notes"] --> AAPT["Resource compiler (AAPT2)"]
    E["res/values-es/strings.xml<br/>app_name = Notas"] --> AAPT
    AAPT --> R["Generated R class<br/>R.string.app_name = 0x7f0f0001"]
    AAPT --> T["Compiled resource table<br/>in the APK"]

The build turns resource files into numeric ids in R and a table the app looks up at runtime.

Generated code: R and BuildConfig

Two classes appear in your project that you never write.

R is generated from res/. For every resource it holds an integer id: R.string.app_name, R.drawable.logo, R.color.purple_500. In code you refer to the id, and at runtime Android resolves it to the right file for the current configuration. In Compose you often wrap this in helper functions such as stringResource(R.string.app_name). Since a resource is looked up by id, a typo in a name is a compile error, not a runtime crash.

Kotlin
// read-only example: using generated ids from Kotlin
Text(text = stringResource(R.string.app_name))
Image(painter = painterResource(R.drawable.logo), contentDescription = null)

BuildConfig is optional in recent Android Gradle Plugin versions. When you enable it, the build generates constants such as BuildConfig.DEBUG and BuildConfig.VERSION_NAME, plus any custom fields you define. It is disabled by default in new projects, so you turn it on explicitly in the module file.

Kotlin
// read-only example: app/build.gradle.kts
android {
    buildFeatures {
        buildConfig = true
    }
}

Both classes live under app/build/generated/.... Never edit them, as the next build overwrites your changes.

A stand-in for resource lookup

The most unusual idea in the project layout is that resources are chosen at runtime, by id plus a set of qualifiers. This stand-in builds a small resource table. Each resource has a name, an integer id handed out in order, and values for several qualifier sets. It is a model, not the real AAPT2 format, and its matching is deliberately simple: an exact qualifier match wins, otherwise the default is used. The next lesson, The Manifest and Resources, refines this with a scoring rule.

Kotlin Resource ids and qualifier folders

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

The fallback line is the lesson inside the code: if a qualifier-specific variant is missing, the system uses the default one. That is why every resource needs a version in the unqualified values folder, and why a missing default is a common cause of build errors.

A stand-in for source sets

Source sets overlay each other: files in src/main are always present, and a variant's own folder, such as src/debug or src/free, adds files or replaces ones with the same path. This stand-in merges source sets for a variant. Real Gradle merges resources and the manifest with more rules, but the "later source set wins for the same path" idea is the heart of it.

Kotlin Merging source sets for a variant

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

The debug variant gets a local server address and an extra menu, while the release variant never contains the debug files at all. The same mechanism lets a free flavor change the app name.

Reading a project you did not write

When you open an unfamiliar app, follow this path:

  1. settings.gradle.kts to see which modules exist.
  2. The module's build.gradle.kts to see its applicationId, SDK levels and dependencies.
  3. AndroidManifest.xml to find the launcher Activity and declared components.
  4. The Activity named there and the first composable it passes to setContent.

In five minutes you know what the app is, what it depends on and where the screen starts.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which file lists the modules that belong to the build?

    settings.gradle.kts contains include(":app") and similar lines that register modules, plus repository setup.
  2. 2. What is the generated R class?

    The build generates R from res. Code refers to resources by these ids and the system picks the file that fits the current configuration.
  3. 3. What does a folder name such as values-night mean?

    The part after the hyphen is a qualifier. The system chooses the best-matching folder for the current device configuration.
  4. 4. Where do local unit tests that run on your computer's JVM belong?

    src/test holds local tests; src/androidTest holds instrumented tests that need a device or emulator.

Summary

  • A project has a root with settings and wrapper files, plus one or more modules; a new project has one module named app.
  • src/main holds the shipped sources, res and the manifest; src/test and src/androidTest hold tests; extra source sets customize build types and flavors.
  • The manifest declares components and entry points and refers to resources like @string/app_name.
  • res folders are named by type and may carry qualifiers such as -night, -es or -xxhdpi; the system picks the best match at runtime.
  • R and BuildConfig are generated; never edit them and never commit the build/ folders.

Next, see how the build is configured in Gradle for Android.