= Android Initial Setup
:page-aliases: android_initial_setup.adoc
// Default, if not set via antora.yml
:android-cmdline-tools-version: 19.0

This page provides an overview of the initial setup required for building Android applications using Mill.

== 1. Install Mill
Don't have Mill installed yet?
You can follow the steps as described in xref:cli/installation-ide.adoc[]

== 2. SDK cmdline-tools

Mill requires the Android SDK `cmdline-tools` to build Android applications.

Ensure the `$ANDROID_HOME` environment variable is set (typically to `~/Android/Sdk`).

Mill will automatically install and use the `{android-cmdline-tools-version}` version.
To use a different version, override `cmdlineToolsVersion` in your `build.mill`.

[NOTE]
====
The SDK package licenses must be accepted before installing new packages.
If not accepted, Mill will throw an error with instructions.
You can also configure Mill to automatically accept the licenses by overriding `autoAcceptLicenses`.
====

.Override `AndroidSdkModule.cmdlineToolsVersion` to specify a different version.
[source,scala]
----
object androidSdkModule0 extends AndroidSdkModule {
  override def cmdlineToolsVersion = "17.0"
  // Or
  override def cmdlineToolsVersion = "latest"

  // Automatically accept licenses
  override def autoAcceptLicenses = true
}
----

[NOTE]
====
This feature is still experimental.
If any issues occur with the automatic installation, you can manually install the `cmdline-tools` package via the Android Studio SDK Manager tab, or download it directly from the https://developer.android.com/studio#command-line-tools-only[official Android website].
====



== 3. Create a new Mill project
// The structure of a Mill project can be found in the next android pages like:
The structure of a Mill project and the relative Android commands can be found in the following pages:

- xref:android/java.adoc[]
- xref:android/kotlin.adoc[]
- xref:android/compose-samples.adoc[]
- xref:android/hilt-sample.adoc[]

If you want to start with an example project, you can use the `init` command as shown in xref:cli/builtin-commands.adoc[this] page.

== 4. Use Android Studio
You can use Android Studio to open and work with your Mill project.

image::android/AndroidStudio.png[AndroidStudio.png]

== 5. Run your application on an Android Virtual Device (AVD)


=== Create the AVD
[source,console]
----
> ./mill app.createAndroidVirtualDevice
----

=== Start the Android Emulator

You can provide additional arguments to the emulator command found in the https://developer.android.com/studio/run/emulator-commandline[official documentation], by adding them after the command.
If you want to exclude the default arguments provided by Mill, you can set the `--excludeDefaultArgs` flag.
[source,console]
----
# Run with default arguments
> ./mill app.startAndroidEmulator

# Run with additional arguments
> ./mill app.startAndroidEmulator -noaudio

# Exclude default arguments
> ./mill app.startAndroidEmulator --excludeDefaultArgs -avd test_avd
----

[CAUTION]
====
If setting the `--excludeDefaultArgs` flag, make sure to provide it first before any additional arguments.
====

=== Install your application on the running emulator
This will install apk built by the `app.androidApk` command.
[source,console]
----
> ./mill app.androidInstall
----

=== Stop the emulator
[source,console]
----
> ./mill app.stopAndroidEmulator
----

=== Delete the AVD
When you no longer need the AVD, you can delete it using the following command:
[source,console]
----
> ./mill app.deleteAndroidVirtualDevice
---- 