Crea la tua app dalla riga di comando

Puoi eseguire tutte le attività di build 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, usa uno dei seguenti comandi da una finestra Terminale (in Android Studio, seleziona Visualizza > Finestre degli strumenti > Terminale):

  • Su Windows:
    gradlew task-name
  • Su Mac o Linux:
    ./gradlew task-name

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

gradlew tasks

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

Se preferisci utilizzare gli strumenti di Android Studio anziché quelli della riga di comando, consulta l'articolo Creare ed eseguire un'app.

Informazioni sui tipi di build

Per impostazione predefinita, sono disponibili due tipi di build per ogni app Android: uno per il debug dell'app (la build di debug) e uno per il rilascio dell'app per gli utenti: la build di release. L'output risultante da ogni build 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 la pubblicazione su Google Play Store) e la build di release deve essere firmata con la tua chiave privata.

Se vuoi creare la tua app per la release, è importante anche firmare l'app con la chiave di firma appropriata. Tuttavia, se hai appena iniziato, puoi eseguire rapidamente le tue app su un emulatore o su un dispositivo connesso creando un APK di debug.

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

Creazione e deployment di un APK

Sebbene la creazione di un app bundle sia il modo migliore per pacchettizzare la tua app e caricarla su Play Console, la creazione di un APK è più adatta per testare rapidamente una build di debug o condividere la tua app come artefatto di cui è possibile eseguire il deployment con altri.

Creare un APK di debug

Per eseguire test e debug immediati, puoi creare un APK di debug. L'APK di debug viene firmato con una chiave di debug fornita dagli strumenti dell'SDK e consente di eseguire il debug tramite adb.

Per creare un APK di debug, apri una riga di comando e vai alla directory principale del progetto. Per avviare una build di debug, richiama 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 ed è in linea con zipalign, quindi puoi installarlo immediatamente su un dispositivo.

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

gradlew installDebug

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

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

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

Crea un APK o bundle di release

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

Esegui il deployment della tua app nell'emulatore

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

Dopo aver attivato la durata di visualizzazione media, avvia l'emulatore Android e installa la tua app nel seguente modo:

  1. In una riga di comando, vai a android_sdk/tools/ e avvia l'emulatore specificando la durata di visualizzazione media:

    emulator -avd avd_name

    Se hai dubbi sul nome della durata di visualizzazione media, esegui emulator -list-avds.

  2. Ora puoi installare la tua app utilizzando una delle attività di installazione di Gradle menzionate nella sezione su come creare un APK di debug oppure lo strumento adb.

    Se l'APK è stato creato utilizzando un SDK di anteprima per gli 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 Esecuzione di app sull'emulatore Android.

Eseguire il deployment dell'app su un dispositivo fisico

Per 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, le Opzioni sviluppatore sono nascoste per impostazione predefinita. Per renderlo disponibile, vai a Impostazioni > Informazioni sul telefono e tocca Numero build sette volte. Torna alla schermata precedente per trovare Opzioni sviluppatore.

Dopo aver configurato il dispositivo e collegato tramite USB, puoi installare l'app utilizzando le attività di installazione di Gradle menzionate nella sezione su come creare un APK di debug oppure 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 maggiori informazioni, vedi Esecuzione di 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 rimanda la generazione degli APK e la firma a Google Play. A differenza di un APK, non puoi eseguire il deployment di un app bundle direttamente su un dispositivo. Pertanto, se vuoi testare o condividere rapidamente un APK con qualcun altro, devi invece creare un APK.

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

Creare un app bundle con Gradle

Se preferisci generare un app bundle dalla riga di comando, esegui l'attività Gradle bundleVariant sul modulo di 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 della tua app. Per saperne di più, vai alla sezione su come configurare Gradle per firmare la tua app. Puoi quindi, ad esempio, creare la versione di release della tua app e Gradle genera automaticamente un app bundle e lo firma 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 app bundle è:

jarsigner -keystore pathToKeystore app-release.aab keyAlias

Crea un app bundle utilizzando bundletool

bundletool è uno strumento a riga di comando utilizzato da Android Studio, dal plug-in Android per Gradle e da Google Play per convertire il codice e le risorse compilati della tua 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 a livello locale il modo in cui Google Play genera gli APK, in genere non devi chiamare bundletool per creare l'app bundle stesso, ma devi invece utilizzare le attività Android Studio o Gradle, come descritto nelle sezioni precedenti.

Tuttavia, se non vuoi utilizzare le attività Android Studio o Gradle per creare bundle, ad esempio se utilizzi una Toolchain di creazione personalizzata, puoi utilizzare bundletool dalla riga di comando per creare un app bundle con 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 della tua 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 alcune informazioni sul progetto dell'app, ad esempio il file manifest e le risorse dell'app, siano nel formato Google Protocol Buffer, noto anche come "protobuf" e che utilizza l'estensione del file *.pb. I protobufs offrono un meccanismo estensibile e indipendente dal linguaggio e dalla piattaforma per la serializzazione dei dati strutturati. È simile al formato XML, ma più piccolo, più veloce e più semplice.

Scarica AAPT2

Puoi generare il file manifest e la tabella delle risorse dell'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 come segue:

  1. Vai a com.android.tools.build > aapt2 nell'indice del repository.
  2. Copia il nome dell'ultima versione di AAPT2.
  3. Inserisci il nome della versione 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-alpha448

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

  5. Apri il pacchetto del file JAR appena scaricato.

Utilizza AAPT2 per compilare le risorse della tua 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 all'AAPT2 di convertire il file manifest dell'app e le risorse compilate 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 i file AndroidManifest.xml, resources.pb e altri file di risorse della tua app, ora nel formato protobuf. Questi file sono necessari durante la preparazione dell'input richiesto da bundletool per la creazione dell'app bundle, come descritto nella sezione seguente.

Codice e risorse precompilati del pacchetto

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

File o directory Descrizione
manifest/AndroidManifest.xml Il file manifest del modulo in formato protobuf.
dex/... Una directory con uno o più file DEX compilati della tua app. Questi file devono essere denominati come segue: classes.dex, classes2.dex, classes3.dex e così via.
res/... Contiene le risorse del modulo in formato protobuf per tutte le configurazioni dispositivo. Le sottodirectory e i file devono essere organizzati in modo simile a quello di un tipico APK.
root/..., assets/... e lib/... Queste directory sono identiche a quelle descritte nella sezione relativa al formato Android App Bundle.
resources.pb Tabella delle risorse dell'app in formato protobuf.

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

Creare un app bundle utilizzando bundletool

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

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

La seguente tabella descrive in maggiore dettaglio i flag per il comando build-bundle:

Segnala Descrizione
--modules=path-to-base.zip, path-to-module2.zip,path-to-module3.zip Specifica l'elenco dei file ZIP dei moduli che bundletool deve utilizzare per creare il tuo app bundle.
--output=path-to-output.aab Specifica il percorso e il nome file per il file *.aab di output.
--config=path-to-BundleConfig.json Specifica il percorso di un file di configurazione facoltativo che puoi utilizzare per personalizzare il processo di compilazione. Per scoprire di più, consulta la sezione sulla personalizzazione della generazione di APK downstream.
--metadata-file=target-bundle-path:local-file-path Indica a bundletool di pacchettizzare un file di metadati facoltativo all'interno dell'app bundle. Puoi utilizzare questo file per includere dati, ad esempio mappature ProGuard o l'elenco completo dei file DEX della tua app, che potrebbero essere utili per altri passaggi nella Toolchain o in uno store.

target-bundle-path specifica un percorso relativo alla directory principale dell'app bundle in cui vuoi che venga pacchettizzato il file di metadati, mentre local-file-path specifica il percorso del file di metadati locale stesso.

Personalizza la generazione di APK downstream

Gli app bundle includono un file BundleConfig.pb che fornisce i metadati richiesti dagli store, ad esempio Google Play, per la generazione degli APK dal bundle. Anche se bundletool crea questo file per te, puoi configurare alcuni aspetti dei metadati in un file BundleConfig.json e passarli al comando bundletool build-bundle. In seguito, bundletool lo converte e unisce questo file alla versione protobuf inclusa in ogni app bundle.

Ad esempio, puoi controllare quali categorie di APK di configurazione abilitare o disabilitare. Nel seguente esempio di file BundleConfig.json vengono disattivati gli APK di configurazione, ognuno dei quali ha come target una lingua diversa (vale a dire, le risorse per tutte le lingue sono incluse nei rispettivi APK di base o funzionalità):

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

Nel file BundleConfig.json puoi anche specificare quali tipi di file non comprimere quando pacchettizzi APK utilizzando i pattern glob, come indicato di seguito:

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

Tieni presente che, per impostazione predefinita, bundletool non comprime le librerie native dell'app (su Android 6.0 o versioni successive) e la tabella delle risorse (resources.arsc). 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 APK e eseguirne il deployment su un dispositivo.

Firma 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 firmi la firma per te durante la build. 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 richiede le password per l'archivio chiavi e la chiave e per i campi "Nome distinto" per la chiave. Dopodiché genera l'archivio chiavi sotto forma di file denominato my-release-key.jks, salvandolo nella directory corrente (puoi spostarlo dove preferisci). L'archivio chiavi 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 di seguito.

Firmare l'app manualmente dalla riga di comando

Se vuoi firmare un app bundle dalla riga di comando, puoi utilizzare jarsigner. Se invece vuoi firmare un APK, devi usare 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 assicura che tutti i dati non compressi inizino con un particolare allineamento di byte rispetto all'inizio del file, il che potrebbe ridurre la quantità di RAM consumata da un'app.

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

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

    Questo esempio restituisce l'APK firmato all'indirizzo my-app-release.apk dopo averlo firmato con una chiave privata e un certificato archiviati in un singolo file dell'archivio chiavi: my-release-key.jks.

    Lo strumento apksigner supporta altre opzioni di firma, tra cui la firma di un file APK con file di certificati e una chiave privata separati e la firma di un APK utilizzando più firmatari. Per maggiori dettagli, consulta il riferimento apksigner.

    Nota: per utilizzare lo strumento apksigner, devi avere installato la revisione 24.0.3 o versioni successive degli strumenti di build dell'SDK Android. Puoi aggiornare questo pacchetto utilizzando SDK Manager.

  4. Verifica che l'APK sia firmato:

    apksigner verify my-app-release.apk
    

Configura Gradle per firmare la tua app

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

Kotlin


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")
            ...
        }
    }
}

Trendy

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 la tua app richiamando un'attività Gradle, Gradle firma l'app (e esegue zipalign) per te.

Inoltre, poiché hai configurato la build della release con la tua chiave di firma, l'attività di installazione è disponibile per quel tipo di build. Quindi puoi creare, allineare, firmare e installare l'APK della release su un emulatore o un dispositivo, il tutto con l'attività installRelease.

Un'app firmata con la tua chiave privata è pronta per la distribuzione, ma dovresti prima leggere ulteriori informazioni su come pubblicare l'app ed esaminare l'elenco di controllo per il lancio di Google Play.