Crea la tua app dalla riga di comando

Puoi eseguire tutte le attività di compilazione disponibili per il tuo progetto Android utilizzando lo strumento a riga di comando Gradle wrapper. È disponibile come file batch per Windows (gradlew.bat) e come script shell per Linux e Mac (gradlew.sh) ed è accessibile dalla directory principale di ogni progetto creato con Android Studio.

Per eseguire un'attività con il wrapper, utilizza uno dei seguenti comandi da una finestra del terminale (in Android Studio, seleziona Visualizza > Finestre degli strumenti > Terminale):

• Nella shell di comando di Windows:

  gradlew task-name

• Su Mac, Linux o Windows PowerShell:

  ./gradlew task-name

Per visualizzare un elenco di tutte le attività di compilazione disponibili per il tuo progetto, esegui tasks:

gradlew tasks

Il resto di questa pagina descrive le nozioni di base per compilare ed eseguire l'app con il wrapper Gradle. Per ulteriori informazioni su come configurare la build Android, consulta Configurare la build.

Se preferisci utilizzare gli strumenti di Android Studio anziché gli strumenti a riga di comando, consulta Compilare ed eseguire l'app.

Informazioni sui tipi di build

Per impostazione predefinita, sono disponibili due tipi di build per ogni app per Android: una per il debug dell'app (la build di debug) e una per la release dell'app agli utenti (la build di release). L'output risultante di ogni compilazione deve essere firmato con un certificato prima di poter eseguire il deployment dell'app su un dispositivo. La build di debug viene firmata automaticamente con una chiave di debug fornita dagli strumenti SDK (non è sicura e non puoi utilizzarla per pubblicare sul Google Play Store) e la build di release deve essere firmata con la tua chiave privata.

Se vuoi compilare l'app per la release, è importante anche firmarla con la chiave di firma appropriata. Tuttavia, se sei agli inizi, puoi eseguire rapidamente le tue app su un emulatore o un dispositivo connesso creando un APK di debug.

Puoi anche definire un tipo di compilazione personalizzato nel file build.gradle.kts e configurarlo in modo che venga firmato come compilazione di debug includendo debuggable true. Per ulteriori informazioni, consulta Configurare le varianti di build.

Creare e implementare un APK

Sebbene la creazione di un app bundle sia il modo migliore per impacchettare l'app e caricarla su Play Console, la creazione di un APK è più adatta quando vuoi testare rapidamente una build di debug o condividere la tua app come elemento di deployment con altri.

Creare un APK di debug

Per testare e eseguire il debug immediato dell'app, puoi creare un APK di debug. L'APK di debug è firmato con una chiave di debug fornita dagli strumenti SDK e consente il debug tramite adb.

Per compilare un APK di debug, apri una riga di comando e vai alla directory principale del progetto. Per avviare una compilazione di debug, invoca l'attività assembleDebug:

gradlew assembleDebug

Viene creato un APK denominato module_name-debug.apk in project_name/module_name/build/outputs/apk/. Il file è già firmato con la chiave di debug e allineato con zipalign, quindi puoi installarlo immediatamente su un dispositivo.

In alternativa, per compilare l'APK e installarlo immediatamente su un emulatore o un dispositivo connesso in esecuzione, invoca installDebug:

gradlew installDebug

La parte "Debug" nei nomi delle attività precedenti è solo una versione in lettere maiuscole e minuscole del nome della variante di build, pertanto può essere sostituita con il tipo o la variante di build che vuoi assemblare o installare. Ad esempio, se hai un "demo" impostazione del prodotto, puoi creare la versione di debug con l'attività assembleDemoDebug.

Per visualizzare tutte le attività di compilazione e installazione disponibili per ogni variante (incluse le attività di disinstallazione), esegui l'attività tasks.

Consulta anche la sezione su come eseguire l'app sull'emulatore e eseguire l'app su un dispositivo.

Crea un app bundle o un APK di release

Quando è tutto pronto per rilasciare e distribuire l'app, devi creare un app bundle o un APK firmato con la tua chiave privata. Per ulteriori informazioni, consulta la sezione su come firmare l'app dalla riga di comando.

Esegui il deployment dell'app nell'emulatore

Per utilizzare l'emulatore Android, devi creare un dispositivo virtuale Android (AVD) utilizzando Android Studio.

Dopo aver creato un AVD, avvia l'emulatore Android e installa la tua app come segue:

1. In una riga di comando, vai a android_sdk/tools/ e avvia l'emulatore specificando il tuo AVD:

   emulator -avd avd_name

   Se hai dubbi sul nome dell'AVD, esegui emulator -list-avds.

2. Ora puoi installare l'app utilizzando una delle attività di installazione di Gradle riportate nella sezione su come creare un APK di debug o lo strumento adb.

   Se l'APK viene creato utilizzando un SDK di anteprima per sviluppatori (se targetSdkVersion è una lettera anziché un numero), devi includere l'opzione -t con il comando install per installare un APK di test.

   adb install path/to/your_app.apk
   

   Tutti gli APK che crei vengono salvati in project_name/module_name/build/outputs/apk/.

Per ulteriori informazioni, vedi Eseguire app nell'emulatore Android.

Esegui il deployment dell'app su un dispositivo fisico

Prima di poter eseguire l'app su un dispositivo, devi attivare il debug USB sul dispositivo. Puoi trovare l'opzione in Impostazioni > Opzioni sviluppatore.

Nota:su Android 4.2 e versioni successive, Opzioni sviluppatore è nascosta per impostazione predefinita. Per renderlo disponibile, vai a Impostazioni > Informazioni sullo smartphone e tocca Numero build sette volte. Torna alla schermata precedente per trovare Opzioni sviluppatore.

Una volta configurato e collegato il dispositivo tramite USB, puoi installare l'app utilizzando le attività di installazione di Gradle menzionate nella sezione su come creare un APK di debug o lo strumento adb:

adb -d install path/to/your_app.apk

Tutti gli APK che crei vengono salvati in project_name/module_name/build/outputs/apk/.

Per ulteriori informazioni, consulta Eseguire app su un dispositivo hardware.

Creare un app bundle

Gli Android App Bundle includono tutto il codice e le risorse compilati della tua app, ma richiedono la generazione e la firma dell'APK a Google Play. A differenza di un APK, non puoi implementare un app bundle direttamente su un dispositivo. Pertanto, se vuoi testare o condividere rapidamente un APK con qualcun altro, devi crearlo.

Il modo più semplice per creare un app bundle è utilizzare Android Studio. Tuttavia, se devi compilare un bundle di app dalla riga di comando, puoi utilizzare Gradle o bundletool, come descritto nelle sezioni seguenti.

Creare un app bundle con Gradle

Se preferisci generare un app bundle dalla riga di comando, esegui l'bundleVariantattività Gradle sul modulo base della tua app. Ad esempio, il seguente comando crea un app bundle per la versione di debug del modulo di base:

./gradlew :base:bundleDebug

Se vuoi creare un bundle firmato da caricare su Play Console, devi prima configurare il file build.gradle.kts del modulo di base con le informazioni di firma dell'app. Per scoprire di più, vai alla sezione su come configurare Gradle per firmare l'app. Puoi quindi, ad esempio, compilare la versione release dell'app e Gradle genererà automaticamente un app bundle e lo firmerà con le informazioni di firma fornite nel file build.gradle.kts.

Se invece vuoi firmare un app bundle come passaggio separato, puoi utilizzare jarsigner per firmare l'app bundle dalla riga di comando. Il comando per creare un bundle di app è:

jarsigner -keystore pathToKeystore app-release.aab keyAlias

Creare un app bundle utilizzando bundletool

bundletool è uno strumento a riga di comando utilizzato da Android Studio, dal plug-in Gradle per Android e da Google Play per convertire il codice e le risorse compilati dell'app in app bundle e generare APK di cui è possibile eseguire il deployment da questi bundle.

Pertanto, anche se è utile testare gli app bundle con bundletool e ricreare localmente come Google Play genera gli APK, in genere non è necessario invocare bundletool per compilare l'app bundle stesso. È invece consigliabile utilizzare le attività di Android Studio o Gradle, come descritto nelle sezioni precedenti.

Tuttavia, se non vuoi utilizzare Android Studio o le attività Gradle per creare i bundle, ad esempio se utilizzi una toolchain di compilazione personalizzata, puoi utilizzare bundletool dalla riga di comando per creare un app bundle da codice e risorse precompilati. Se non l'hai ancora fatto, scarica bundletool dal repository GitHub.

Questa sezione descrive come pacchettizzare il codice e le risorse compilati dell'app e come utilizzare bundletool dalla riga di comando per convertirli in un Android App Bundle.

Genera il manifest e le risorse in formato proto

bundletool richiede che determinate informazioni sul progetto dell'app, ad esempio il manifest e le risorse dell'app, siano nel formato Protocol Buffer di Google, noto anche come "protobuf" e che utilizzi l'estensione file *.pb. I protobufs forniscono un meccanismo estensibile, indipendente dal linguaggio e dalla piattaforma per la serializzazione dei dati strutturati. Sono simili a XML, ma più piccoli, più veloci e più semplici.

Scarica AAPT2

Puoi generare il file manifest e la tabella delle risorse della tua app in formato protobuf utilizzando la versione più recente di AAPT2 dal repository Maven di Google.

Per scaricare AAPT2 dal repository Maven di Google, procedi nel seguente modo:

1. Vai a com.android.tools.build > aapt2 nell'indice del repository.
2. Copia il nome della versione più recente di AAPT2.

3. Inserisci il nome della versione che hai copiato nel seguente URL e specifica il sistema operativo di destinazione: https://dl.google.com/dl/android/maven2/com/android/tools/build/aapt2/aapt2-version/aapt2-aapt2-version-[windows | linux | osx].jar

   Ad esempio, per scaricare la versione 3.2.0-alpha18-4804415 per Windows, devi utilizzare: https://dl.google.com/dl/android/maven2/com/android/tools/build/aapt2/3.2.0-alpha18-4804415/aapt2-3.2.0-alpha18-4804415-windows.jar

4. Vai all'URL in un browser. Il download di AAPT2 dovrebbe iniziare a breve.

5. Estrai il file JAR che hai appena scaricato.

Compila e collega le risorse dell'app

Utilizza AAPT2 per compilare le risorse dell'app con il seguente comando:

aapt2 compile \
project_root/module_root/src/main/res/drawable/Image1.png \
project_root/module_root/src/main/res/drawable/Image2.png \
-o compiled_resources/

Durante la fase di collegamento, in cui AAPT2 collega le varie risorse compilate in un singolo APK, chiedi ad AAPT2 di convertire il file manifest e le risorse compilate dell'app nel formato protobuf includendo il flag --proto-format, come mostrato di seguito:

aapt2 link --proto-format -o output.apk \
-I android_sdk/platforms/android_version/android.jar \
--manifest project_root/module_root/src/main/AndroidManifest.xml \
-R compiled_resources/*.flat \
--auto-add-overlay

Puoi quindi estrarre i contenuti dall'APK di output, ad esempio AndroidManifest.xml, resources.pb e altri file di risorse della tua app, ora nel formato protobuf. Questi file sono necessari per preparare gli input richiesti da bundletool per compilare il tuo app bundle, come descritto nella sezione seguente.

Impacchettare codice e risorse precompilate

Prima di utilizzare bundletool per generare un app bundle per la tua app, devi fornire innanzitutto file ZIP contenenti ciascuno il codice e le risorse compilati per un determinato modulo dell'app. I contenuti e l'organizzazione del file ZIP di ogni modulo sono molto simili a quelli del formato del bundle di app per Android. Ad esempio, devi creare un file base.zip per il modulo di base dell'app e organizzare i relativi contenuti come segue:

Dopo aver preparato il file ZIP per ogni modulo dell'app, puoi trasmetterli a bundletool per creare il tuo app bundle, come descritto nella sezione seguente.

Creare l'app bundle utilizzando bundletool

Per creare il bundle dell'app, utilizza il comando bundletool build-bundle, come mostrato di seguito:

bundletool build-bundle --modules=base.zip --output=mybundle.aab

La tabella seguente descrive più dettagliatamente i flag per il comando build-bundle:

Personalizzare la generazione di APK a valle

Gli app bundle includono un file BundleConfig.pb che fornisce i metadati richiesti dagli store, come Google Play, per la generazione di APK dal bundle. Sebbene bundletool crei questo file per te, puoi configurare alcuni aspetti degli metadati in un file BundleConfig.json e passarlo al comando bundletool build-bundle. bundletool in seguito converte e unisce questo file con la versione protobuf inclusa in ogni app bundle.

Ad esempio, puoi controllare quali categorie di APK di configurazione attivare o disattivare. Il seguente esempio di file BundleConfig.json disattiva gli APK di configurazione ciascuno dei quali ha come target una lingua diversa (ovvero le risorse per tutte le lingue sono incluse nei rispettivi APK di base o di funzionalità):

{
  "optimizations": {
    "splitsConfig": {
      "splitDimension": [{
        "value": "LANGUAGE",
        "negate": true
      }]
    }
  }
}

Nel file BundleConfig.json puoi anche specificare i tipi di file da non comprimere durante il packaging degli APK utilizzando i pattern di glob, come segue:

{
  "compression": {
    "uncompressedGlob": ["res/raw/**", "assets/**.uncompressed"]
  }
}

Tieni presente che, per impostazione predefinita, bundletool non comprime le librerie native (su Android 6.0 o versioni successive) e la tabella delle risorse (resources.arsc) dell'app. Per una descrizione completa di ciò che puoi configurare in BundleConfig.json, controlla il file bundletool config.proto, scritto utilizzando la sintassi Proto3.

Eseguire il deployment dell'app da un app bundle

Se hai creato e firmato un app bundle, utilizza bundletool per generare gli APK e eseguirne il deployment su un dispositivo.

Firmare l'app dalla riga di comando

Non è necessario Android Studio per firmare l'app. Puoi firmare l'app dalla riga di comando utilizzando apksigner per gli APK o jarsigner per gli app bundle oppure configurare Gradle in modo che la firmi per te durante la compilazione. In ogni caso, devi prima generare una chiave privata utilizzando keytool, come mostrato di seguito:

keytool -genkey -v -keystore my-release-key.jks -keyalg RSA -keysize 2048 -validity 10000 -alias my-alias

L'esempio riportato sopra ti chiede le password per il keystore e la chiave, nonché per i campi "Nome distinto" della chiave. Quindi genera il file del keystore denominato my-release-key.jks e lo salva nella directory corrente (puoi spostarlo dove preferisci). Il keystore contiene una singola chiave valida per 10.000 giorni.

Ora puoi firmare manualmente l'APK o l'app bundle oppure configurare Gradle per firmare la tua app durante il processo di compilazione, come descritto nelle sezioni seguenti.

Firmare manualmente l'app dalla riga di comando

Se vuoi firmare un app bundle dalla riga di comando, puoi utilizzare jarsigner. Se invece vuoi firmare un APK, devi utilizzare zipalign e apksigner come descritto di seguito.

1. Apri una riga di comando: in Android Studio, seleziona Visualizza > Finestre degli strumenti > Terminale e vai alla directory in cui si trova l'APK non firmato.

2. Allinea l'APK non firmato utilizzando zipalign:

   zipalign -v -p 4 my-app-unsigned.apk my-app-unsigned-aligned.apk
   

   zipalign garantisce che tutti i dati non compressi inizino con un particolare allineamento dei byte rispetto all'inizio del file, il che può ridurre la quantità di RAM consumata da un'app.

3. Firma l'APK con la tua chiave privata utilizzando apksigner:

   apksigner sign --ks my-release-key.jks --out my-app-release.apk my-app-unsigned-aligned.apk
   

   Questo esempio genera l'APK firmato in my-app-release.apk dopo averlo firmato con una chiave privata e un certificato memorizzati in un singolo file KeyStore: my-release-key.jks.

   Lo strumento apksigner supporta altre opzioni di firma, tra cui la firma di un file APK utilizzando file di chiavi private e certificati separati e la firma di un APK utilizzando più firmatari. Per ulteriori dettagli, consulta la documentazione di riferimento apksigner.

   Nota: per utilizzare lo strumento apksigner, devi avere installato la revisione 24.0.3 o successive di Android SDK Build Tools. Puoi aggiornare questo pacchetto utilizzando SDK Manager.

4. Verifica che l'APK sia firmato:

   apksigner verify my-app-release.apk
   

Configurare Gradle per firmare l'app

Apri il file build.gradle.kts a livello di modulo e aggiungi il blocco signingConfigs {} con le voci per storeFile, storePassword, keyAlias e keyPassword, quindi passa l'oggetto alla proprietà signingConfig nel tipo di build. Ad esempio:

android {
    ...
    defaultConfig { ... }
    signingConfigs {
        create("release") {
            // You need to specify either an absolute path or include the
            // keystore file in the same directory as the build.gradle file.
            storeFile = file("my-release-key.jks")
            storePassword = "password"
            keyAlias = "my-alias"
            keyPassword = "password"
        }
    }
    buildTypes {
        getByName("release") {
            signingConfig = signingConfigs.getByName("release")
            ...
        }
    }
}

android {
    ...
    defaultConfig { ... }
    signingConfigs {
        release {
            // You need to specify either an absolute path or include the
            // keystore file in the same directory as the build.gradle file.
            storeFile file("my-release-key.jks")
            storePassword "password"
            keyAlias "my-alias"
            keyPassword "password"
        }
    }
    buildTypes {
        release {
            signingConfig signingConfigs.release
            ...
        }
    }
}

Ora, quando crei l'app richiamando un'attività Gradle, Gradle firma l'app (ed esegue zipalign) per te.

Inoltre, poiché hai configurato la build di release con la tua chiave di firma, l'attività "install" è disponibile per quel tipo di build. In questo modo, puoi compilare, allineare, firmare e installare l'APK release su un emulatore o un dispositivo con l'attività installRelease.

Un'app firmata con la tua chiave privata è pronta per la distribuzione, ma devi prima approfondire come pubblicare la tua app e consultare l'elenco di controllo per il lancio su Google Play.