Cordova: instal·lació

Aquí s'especifiquen detalls de la instal·lació.

Introducció i requisits

Per poder seguir aquest article se suposa que has de tenir coneixements de JavaScript, HTML i CSS.

Si tens coneixements molt bàsics també t'interessaria repassar els conceptes del DOM o Document Object Model.

Abans de començar a treballar amb Cordova caldrà que tinguem instal·lats els entorns de desenvolupament: llegeix Java i Android primerament.

Per instal·lar Cordova necessites un bon plegat d'eines. De forma general necessitaràs:

1. Android Studio que ens facilitarà les eines de l'Android SDK.
2. Java JDK té les llibreries de compilació de Java.
3. NodeJS que ens facilitarà el gestor de paquets NPM amb el què podrem instal·lar Cordova
4. Gradle en la darrera versió.

En cas de que puguis treballar en un Mac, hauràs d'instal·lar Xcode (des de la pròpia AppStore) i activar les CLI (Command Line Interface) Tools. En la versió Xcode 10 (High Sierra) seria:

XCode -> Preferences -> Locations -> Command Line Tools

MacOS: Instal·lació de Cordova per a MacOS.

Tens algun material per començar amb Cordova a Cacauet.org

Instal·lació en Ubuntu

1. Primer cal tenir instal·lat Anrdoid Studio:

   $ sudo snap install android-studio --classic

   1. Prova de crear un projecte dins d'Android Studio i llençar-lo sobre una VM Android (emulador) abans de seguir amb el tutorial.
2. Cal instal·lar Java JDK.
   1. Vigila que no tens cap altra versió instal·lada:

      $ javac -version

   2. Instal·la Java JDK:

      $ sudo apt update
      $ sudo apt install default-jdk

   3. Ajusta la variable d'entorn ANDROID_HOME:

      $ export ANDROID_HOME=~/Android/Sdk

   4. Millor que afegeixis aquest export a l'arxiu ~/.profile (afegiu-lo al final del fitxer). Si no, caldrà que facis l'export cada cop que obris una shell per treballar amb Cordova.
3. Necessitarem instal·lar NodeJS, no pel servidor web, sinó perquè necessitem el gestor de paquets npm. ULL! Ha de ser la versió LTS.
   1. Per a Ubuntu 22.04 (jammy) la versió dels repos és molt antiga i l'actualitzarem amb la utilitat n:

      $ sudo apt update
      $ sudo apt install nodejs npm
      $ sudo npm install -g n
      $ sudo n lts
      $ node --version

   2. Per a Ubuntu 24.04 (noble) la versió que ve per defecte (v18) ens és suficient:

      $ sudo apt update
      $ sudo apt install nodejs npm

4. Instal·lar Cordova:

   $ sudo npm install -g cordova

5. Instal·lar Gradle:
   1. En Ubuntu 22.04 (jammy): ajustem repos ppa per tal que s'instal·li la darrera versió

      $ sudo add-apt-repository ppa:cwchien/gradle
      $ sudo apt install gradle

   2. En Ubuntu 24.04 (noble): instal·lem via snap:

      $ sudo snap install gradle --classic

   3. Comprova que és una versió recent (7.x durant l'any 2022) amb:

      $ gradle -v

Quickstart

La seqüência típica per iniciar un projecte és com s'indica a continuació:

1. Crear projecte:

   $ cordova create proj1

2. Entrar al directori del projecte:

   $ cd proj1

3. Afegir plataformes (android/ios/browser):

   $ cordova platform add android

4. Compilar per Android:

   $ cordova build android

5. Arrencar el projecte a l'emulador:

   $ cordova run android

De vegades no arrenca bé l'emulador. Pots obrir-lo des del Android Studio, però llavors el IDE consumeix força recursos, i complica l'execució. Si tanques el projecte (File → Close Project a Android Studio) pots obrir el AVD Manager des de la pantalla d'inici d'Android Studio a Configure → AVD Manager.

També pots provar d'arrencar l'emulador des de la línia de comandes, com explica la doc oficial https://developer.android.com/studio/run/emulator-commandline

$ emulator -avd <el_meu_emulador>

Per exemple:

$ emulator -avd Pixel_2_API_28

Devices

Per córrer l'aplicació sobre un device real només cal que afegiu –device a la comanda:

$ cordova run android --device

Abans, però, caldrà que configureu el vostre dispositiu en mode developer buscant les dades del dispositiu i clicant 7 cops seguits al nº de compilació. Després activeu la Depuració USB.

Troubleshooting

Emulador KVM (Android Studio)

Si no et deixa crear una màquina virtual al Android Studio pq li falten permisos d'execució a KVM:

$ sudo chmod 777 /dev/kvm

Variables d'entorn GNU/Linux

Si al llançar el run ens dona errors en Ubuntu perquè no troba les llibreries (SDK, JDK), executa:

export ANDROID_HOME=~/Android/Sdk

El millor és que incloguis aquestes darreres instruccions a l'arxiu ~/.profile del teu home directory i així no caldrà picar-les cada cop que vulguis treballar amb Cordova. Si ho fas, per tal de no reiniciar la màquina, pots carregar l'script manualment:

$ source ~/.profile

Variables d'entorn Windows

Alguna comanda no et funciona, és perquè necessita estar al PATH per poder ser trobada.

Cerca «variables» amb el cercador de Windows i t'hauria de facilitar accedir a les variables d'entorn. Modifica la variable PATH per afegir el què et calgui, com per exemple Gradle o el Android SDK que sol estar a:

\Users\usuari\AppData\Local\Android\Sdk

Però cerca abans per assegurar-te d'on son exactament les eines.

Altres

Si es queixa de:

No usable Android build tools found. Highest 30.x installed version is 30.0.2; minimum version required is 30.0.3

aquest post explica com corregir-ho, simplement seleccionant la versió que necessitem del SDK Manager:

Android Studio -> Tools -> SDK Manager -> Android SDK -> SDK Tools

i activant Show package details.

Java version

Si tenim una versió de Java diferent de la 11 no ens funcionarà. Això ho pots saber amb:

$ java -version

Si en tenim una altra, podem instal·lar en paral·lel amb la 11 amb:

$ sudo apt install openjdk-11-jdk

I posar la 11 com a versió per defecte amb:

$ sudo update-alternatives --config java
$ sudo update-alternatives --config javac

Si es queixa de que no troba JAVA_HOME, l'haurem d'afegir a l'arxiu .profile:

export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64/

Si aquest no fos el path adequat de JAVA_HOME us donaria un error. Mireu quin és buscant on està la ruta del compilador java

$ ll `which javac`
$ ll /etc/alternatives/javac

Gradle

Si es queixa de que li falta gradle, l'instal·lem.

Instal·lar gradle per a GNU/Linux:

$ sudo add-apt-repository ppa:cwchien/gradle
$ sudo apt install gradle

Instal·lar gradle per a Windows:

1. Descarrega la darrera versió de Gradle
2. Descomprimeix Gradle a una carpeta tipus C:\Gradle
3. Ajusta la variable d'entorn PATH per tal que inclogui C:\Gradle\bin

Instal·lar gradle per a MacOS: …coming soon… probablement brew install gradle

I ja pots tornar a provar el cordova run android

Llicències

Si es queixa de que li falten llicències per acceptar, entra a Android Studio → SDK Manager i accepta les llicències pertinents. També ho pots fer per comandes:

$ ~/Android/Sdk/tools/bin/sdkmanager --licenses

Apple, ios, macos

Treballant amb Apple podem trobar alguns problemes una mica diferents.

Les variables d'entorn cal ajustar-les d'aquesta manera (en macos Monterey):

export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk1.8.0_311.jdk/Contents/Home/
export ANDROID_HOME=~/Library/Android/sdk

També hi ha un problema amb el nom dels executables del compilador DX. Cal renombrar o fer un symlink als arxiu d8 i lib/d8.jar (en la meva instal·lació estan a ~/Library/Android/sdk/build-tools/32.0.0-rc1).

A la versió Xcode 10 tenim una issue que ens fa afegir un paràmetre una mica incòmode a la línia de comandes:

$ cordova build ios --buildFlag='-UseModernBuildSystem=0'
$ cordova run ios --buildFlag='-UseModernBuildSystem=0'

Sembla que a partir de Xcode 11 ja no apareix aquest problema.

Si falla amb el missatge

xcode-select: error: tool 'xcodebuild' requires Xcode, but active developer directory '/Library/Developer/CommandLineTools' is a command line tools instance

Aquest post explica la solució:

$ sudo xcode-select -s /Applications/Xcode-Beta.app/Contents/Developer