This skill guides the initial setup of an Android Jetpack Compose project, providing a direct comparison to Xcode project creation. You Must use this skill when starting a new Android port of an existing iOS application or setting up a greenfield project intended to mirror an iOS app's structure.
Official Reference Links:
- Create an Android project
- Migrate your build to version catalogs | Android Developers
- Configure build variants | Android Developers
- Work with multiple manifest files | Android Developers
Prerequisites
Before initiating the project setup, you Must ensure the following prerequisites are met:
- Software Requirements: Android Gradle Plugin (AGP) 8.3+, Kotlin 1.9+,
and Jetpack Compose BOM 2023.08.00+ are Mandatory. You can use any
modern IDE (VS Code, Cursor, IntelliJ IDEA Community, Android Studio) or the
command line (
./gradlew). - JDK: Java Development Kit (JDK 17 or higher) must be configured.
- Source Context: Access to the iOS project structure (including the Xcode project file, Podfile, and Package.swift) is Mandatory to understand the source structure being mapped.
Limitations
This skill has the following limitations:
- Multi-Module Projects: This skill focuses on a single-module application
setup. Complex multi-module architecture setup is covered in
architecture-and-viewmodels.md. - CI/CD Pipelines: Setting up CI/CD pipelines (e.g., GitHub Actions, Bitrise) is outside the scope of this skill.
Glossary
| iOS Concept | Android Equivalent | Definition |
|---|---|---|
| Xcode Project (.xcodeproj) | Gradle Project | The container for source code, resources, and build configurations. |
| Bundle Identifier | Package Name / Application ID | The unique identifier for the application on the store. |
| Info.plist | AndroidManifest.xml | The file containing essential metadata about the application. |
| Build Phases | Gradle Tasks | The steps executed during the build process. |
| CocoaPods / SPM | Gradle Dependencies | The package management systems used to include external libraries. |
| Build Configurations (Debug/Release) | Build Types & Product Flavors | Mechanisms for creating different versions of the app (e.g., staging, production). |
Info.plist to AndroidManifest Mapping
You Must map common iOS Info.plist keys to the appropriate declarations in
the AndroidManifest.xml or build.gradle.kts.
| iOS Key | Android Equivalent | Location |
|---|---|---|
CFBundleIdentifier |
applicationId |
build.gradle.kts |
CFBundleShortVersionString |
versionName |
build.gradle.kts |
CFBundleVersion |
versionCode |
build.gradle.kts |
NSCameraUsageDescription |
android.permission.CAMERA |
AndroidManifest.xml |
NSLocationWhenInUseUsageDescription |
android.permission.ACCESS_COARSE_LOCATION |
AndroidManifest.xml |
NSPhotoLibraryUsageDescription |
android.permission.READ_MEDIA_IMAGES |
AndroidManifest.xml |
UISupportedInterfaceOrientations |
android:screenOrientation |
AndroidManifest.xml |
UIBackgroundModes |
ForegroundService / WorkManager |
AndroidManifest.xml |
LSApplicationQueriesSchemes |
<queries> |
AndroidManifest.xml |
UIRequiredDeviceCapabilities |
<uses-feature> |
AndroidManifest.xml |
Framework Mapping: iOS to Android
When setting up the project, you Must plan the replacement of core iOS frameworks with their Android equivalents.
| iOS Framework | Android Equivalent | Gradle Dependency | Notes |
|---|---|---|---|
| MapKit | Google Maps SDK | com.google.android.gms:play-services-maps |
Requires API key setup. |
| CoreData | Room | androidx.room:room-runtime |
SQLite-based ORM. |
| CoreLocation | Play Services Location | com.google.android.gms:play-services-location |
Use FusedLocationProviderClient. |
| Combine | Coroutines & Flow | org.jetbrains.kotlinx:kotlinx-coroutines-android |
Reactive model. |
| UIKit | Jetpack Compose | androidx.compose.ui:ui |
Declarative UI framework. |
Setup & Dependencies: Version Catalogs
Modern Android projects Must use Gradle Version Catalogs
(libs.versions.toml) for dependency management. This is equivalent to managing
dependencies in a centralized Podfile or Package.swift.
Example: libs.versions.toml ```toml [versions] agp = "8.3.0" kotlin = "1.9.22" coreKtx = "1.12.0" lifecycleRuntimeKtx = "2.8.0" activityCompose = "1.8.2" composeBom = "2024.02.00"
[libraries] androidx-core-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "coreKtx" } androidx-lifecycle-runtime-ktx = { group = "androidx.lifecycle", name = "lifecycle-runtime-ktx", version.ref = "lifecycleRuntimeKtx" } androidx-activity-compose = { group = "androidx.activity", name = "activity-compose", version.ref = "activityCompose" } androidx-compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "composeBom" } androidx-compose-ui = { group = "androidx.compose.ui", name = "ui" } androidx-compose-material3 = { group = "androidx.compose.material3", name = "material3" }
[plugins] android-application = { id = "com.android.application", version.ref = "agp" } kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" } ```
Instructions: Project Creation Workflow
Step 1: Structuring the Android Project & Boilerplate Architecture from iOS Source
When porting an existing iOS application, you Must structure the new Android
Gradle project and its baseline architecture directly from the patterns read out
of the iOS source tree (.xcodeproj, .xcworkspace, Info.plist, and source
directories).
1. Root & Build Layout (from iOS Project Metadata)
settings.gradle.kts: SetrootProject.namematching the iOS App Name and include:app(plus any modular feature targets read from Xcode sub-projects).gradle/libs.versions.toml: Define plugins and dependencies mapped fromPodfile/Package.swift.app/build.gradle.kts: ConfigureapplicationId(mapped from iOS Bundle ID),minSdk(mapped from iOS Deployment Target), and build types/flavors (mapped from Xcode build configurations).
2. Boilerplate Package & Architectural Structure (app/src/main/java/<package_name>/)
Read the iOS source directory organization and map it to standard Android Jetpack architecture:
ui/theme/(Theme.kt,Color.kt,Type.kt): Read iOS color catalogs (Asset Catalog) and typography rules, creating ComposeMaterialTheme,ColorScheme, andTypographydefinitions.ui/navigation/(AppNavigation.kt): Read iOS routing (NavigationStack,.storyboard, or coordinator flow) and generate the top-level ComposeNavHostand route hierarchy.ui/<feature>/: For each functional module in the iOS source (e.g.,Login/,Home/,Settings/), create a matching feature package containing composable screens (*Screen.kt) and their associated state holders (*ViewModel.kt).data/(repository/,model/,remote/): Map iOSCodablestructs, network clients (URLSession), and persistence layers (CoreData/UserDefaults) to Kotlin data classes, repository interfaces, and data source implementations.app/src/main/res/: Map.xcassetstores/drawable/andres/mipmap-anydpi-v26/, and.stringstores/values/strings.xml.
Step 2: Mapping Environments (Build Types & Flavors)
iOS apps often use different targets or configurations (Debug, Staging, Release)
for different environments. On Android, you Must use buildTypes and
productFlavors.
- iOS:
Debug,Staging,Releaseschemes. - Android:
debug,releasebuild types + custom flavors.
Example: Configuring Build Variants
- Input: Environment names from iOS.
- Output: Configured Gradle build variants.
- Side Effect: Generates different APKs for different environments.
// app/build.gradle.kts
android {
buildTypes {
getByName("debug") {
applicationIdSuffix = ".debug"
isDebuggable = true
}
getByName("release") {
isMinifyEnabled = true
proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro")
}
}
flavorDimensions.add("environment")
productFlavors {
create("staging") {
dimension = "environment"
applicationIdSuffix = ".staging"
versionNameSuffix = "-staging"
// Example: Different API URL for staging
buildConfigField("String", "API_URL", "\"https://staging.api.example.com\"")
}
create("production") {
dimension = "environment"
buildConfigField("String", "API_URL", "\"https://api.example.com\"")
}
}
}
Instructions: Mapping Xcode Build Phases to Gradle
You Must map custom build scripts or phases from Xcode to custom Gradle tasks.
- iOS: Xcode Build Phases -> New Run Script Phase.
- Android: Register a new Gradle task in
build.gradle.kts.
Example: Custom Task
- Input: Task name and action.
- Output: Executed action during build.
- Side Effect: Modifies files or generates resources.
tasks.register("generateBuildInfo") {
doLast {
val buildInfoFile = file("src/main/assets/build_info.txt")
buildInfoFile.writeText("Build Time: ${java.util.Date()}")
}
}
// Ensure it runs before the app is compiled
tasks.named("preBuild") {
dependsOn("generateBuildInfo")
}
Instructions: App Icon Setup
You Must map iOS app icons from Assets.xcassets to Android res/mipmap
directories. Android supports adaptive icons (introduced in API 26), which
consist of a background and a foreground layer.
- Input: A 1024x1024px source icon file (e.g.,
icon.png) or separate layers. - Output:
ic_launcher.xmlinres/mipmap-anydpi-v26/and multipleic_launcher.pngfiles in the correspondingres/mipmap-*directories. - Side Effect: Generates all density-specific bitmaps.
Logic:
- IF the iOS app has a vector or simple icon, THEN you Must define
an adaptive icon in
res/mipmap-anydpi-v26/ic_launcher.xmlreferencing vector drawables (@drawable/ic_launcher_foregroundand@color/ic_launcher_background). - ELSE (complex bitmap art), generate PNG fallbacks for all densities
(
mdpithroughxxxhdpi) using a CLI image processing utility (such as ImageMagick or an open-source Android asset generation CLI tool).
Example: Adaptive Icon XML (res/mipmap-anydpi-v26/ic_launcher.xml)
xml
<?xml version="1.0" encoding="utf-8"?>
<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
<background android:drawable="@color/ic_launcher_background"/>
<foreground android:drawable="@drawable/ic_launcher_foreground"/>
</adaptive-icon>
Legacy Mipmap Densities To support older devices, you Must provide legacy bitmaps in the following sizes:
| Density | Folder | Size (px) |
|---|---|---|
| mdpi | mipmap-mdpi |
48 x 48 |
| hdpi | mipmap-hdpi |
72 x 72 |
| xhdpi | mipmap-xhdpi |
96 x 96 |
| xxhdpi | mipmap-xxhdpi |
144 x 144 |
| xxxhdpi | mipmap-xxxhdpi |
192 x 192 |
Mapping Asset Catalogs to Resource Qualifiers
When mapping iOS assets from Assets.xcassets to Android, you Must use
Android's resource qualifier system to handle different device configurations
(e.g., dark mode, screen size).
| iOS Asset Trait | Android Qualifier | Example Directory |
|---|---|---|
| Light Mode | Default | res/drawable/ |
| Dark Mode | -night |
res/drawable-night/ |
| iPad (Tablet) | -sw600dp |
res/layout-sw600dp/ |
| Right-to-Left (RTL) | -ldrtl |
res/layout-ldrtl/ |
| High Resolution | -xxhdpi |
res/drawable-xxhdpi/ |
Instructions: Secrets Management
For API keys and secrets, iOS apps often use hardcoded values in code
(antipattern) or specialized build scripts to inject them. On Android, you
Must use the Secrets Gradle Plugin to read secrets from a
local.properties file.
Example: Secrets Setup
- Input: Secret key defined in
local.propertiesasAPI_KEY=value. - Output: Accessible string in code via
BuildConfig.API_KEY. - Side Effect: Keeps secrets out of version control and prevents accidental exposure.
Add the plugin to
libs.versions.toml:toml [plugins] secrets = { id = "com.google.android.libraries.mapsplatform.secrets-gradle-plugin", version = "2.0.1" }Apply the plugin in
app/build.gradle.kts:kotlin plugins { alias(libs.plugins.secrets) }Add secret to
local.properties:properties API_KEY=your_secret_keyAccess the secret in Kotlin code:
kotlin val apiKey = BuildConfig.API_KEY
Tooling Integration: Standard Actions
To enable automated assessment and migration tracking, this skill defines the following standard actions. Any automation tool built on this skill Must implement these actions with the specified parameters to ensure benchmark compliance.
Verification Commands & Agnostic Agent Instructions
To verify Version Catalog adoption and build flavor configuration without proprietary tool runners:
- Version Catalog Audit (CLI):
bash # Verify that gradle/libs.versions.toml exists and is referenced in build.gradle.kts ls -l gradle/libs.versions.toml grep -rn "libs\." app/build.gradle.kts - Build Flavors Verification (CLI):
bash # Verify configured build flavors and types via Gradle ./gradlew tasks --all | grep "assemble" - Agent Audit Instruction:
Read
gradle/libs.versions.tomlandapp/build.gradle.ktsto verify that all iOS dependencies and target environments have corresponding Version Catalog entries and product flavor definitions.
Antipatterns
DO
- DO use Version Catalogs for all dependencies.
- DO use
Empty Activityfor new Compose projects. - DO map iOS environments to Android Product Flavors.
- DO use
Secrets Gradle Pluginfor managing API keys.
DON'T
- DON'T hardcode dependency versions in
build.gradle.ktsfiles. - DON'T use a minimum SDK below API 24 (Android 7.0). You Must set the minimum SDK to API 24 or higher to support adaptive icons and modern resource handling while covering ~95% of active devices.
NEVER
- NEVER commit sensitive API keys or secrets directly into the
build.gradle.ktsorAndroidManifest.xml. - NEVER perform blocking network calls or heavy IO during the custom Gradle task execution.