====== Cordova: instal·lació ======
<WRAP info>
Ve de l'article general [[Cordova]].
</WRAP>

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

{{ cordova.png?400 }}

{{tag> #Dam #DamMp08 #DamMpDual #DawMpDual Android iOS Cordova HTML JavaScript }}


===== 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 [[https://www.w3schools.com/js/js_htmldom.asp|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:
  - **Android Studio** que ens facilitarà les eines de l'Android SDK.
  - **Java JDK** té les llibreries de compilació de Java.
  - **NodeJS** que ens facilitarà el gestor de paquets NPM amb el què podrem instal·lar Cordova
  - **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: [[https://evothings.com/doc/build/cordova-install-osx.html|Instal·lació de Cordova per a MacOS]].

Tens algun material per [[https://cacauet.org/wiki/index.php/Android|començar amb Cordova a Cacauet.org]]

\\

===== Instal·lació en Ubuntu =====

  - Primer cal tenir instal·lat **Anrdoid Studio**:<code>$ sudo snap install android-studio --classic</code>
    - Prova de crear un projecte dins d'Android Studio i llençar-lo sobre una VM Android (emulador) abans de seguir amb el tutorial.
  - Cal **instal·lar Java JDK**.
    - Vigila que no tens cap altra versió instal·lada:<code>$ javac -version</code>
    - Instal·la Java JDK:<code>$ sudo apt update
$ sudo apt install default-jdk</code>
    - Ajusta la variable d'entorn ''ANDROID_HOME'':<code>$ export ANDROID_HOME=~/Android/Sdk</code>
    - 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.
  - Necessitarem **instal·lar NodeJS**, no pel servidor web, sinó perquè necessitem el gestor de paquets ''npm''. ULL! Ha de ser la versió LTS.
    - Per a Ubuntu 22.04 (jammy) la versió dels repos és molt antiga i l'actualitzarem amb la utilitat ''n'':<code>
$ sudo apt update
$ sudo apt install nodejs npm
$ sudo npm install -g n
$ sudo n lts
$ node --version</code>
    - Per a Ubuntu 24.04 (noble) la versió que ve per defecte (v18) ens és suficient:<code>
$ sudo apt update
$ sudo apt install nodejs npm
</code>
  - Instal·lar **Cordova**: <code>$ sudo npm install -g cordova</code>
  - Instal·lar **Gradle**:
    - En Ubuntu 22.04 (jammy): ajustem [[https://launchpad.net/~cwchien/+archive/ubuntu/gradle|repos ppa]] per tal que s'instal·li la darrera versió<code>$ sudo add-apt-repository ppa:cwchien/gradle
$ sudo apt install gradle</code>
    - En Ubuntu 24.04 (noble): instal·lem via ''snap'':<code>$ sudo snap install gradle --classic</code>
    - Comprova que és una versió recent (7.x durant l'any 2022) amb:<code>$ gradle -v</code>

\\

===== Quickstart ======
La seqüência típica per iniciar un projecte és com s'indica a continuació:
  - Crear projecte: <code>$ cordova create proj1</code>
  - Entrar al directori del projecte: <code>$ cd proj1</code>
  - Afegir plataformes (android/ios/browser): <code>$ cordova platform add android</code>
  - Compilar per Android: <code>$ cordova build android</code>
  - Arrencar el projecte a l'emulador: <code>$ cordova run android</code>

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
[[https://stackoverflow.com/questions/70002327/ionic-cordova-android-no-usable-android-build-tools-found-highest-30-x-install|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:
  - Descarrega [[https://gradle.org/releases/|la darrera versió de Gradle]]
  - Descomprimeix Gradle a una carpeta tipus C:\Gradle
  - 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 [[https://stackoverflow.com/questions/68387270/android-studio-error-installed-build-tools-revision-31-0-0-is-corrupted|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'').

[[https://github.com/apache/cordova-ios/issues/407|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 <code>xcode-select: error: tool 'xcodebuild' requires Xcode, but active developer directory '/Library/Developer/CommandLineTools' is a command line tools instance</code>

[[https://github.com/nodejs/node-gyp/issues/569|Aquest post explica la solució]]:
  $ sudo xcode-select -s /Applications/Xcode-Beta.app/Contents/Developer

\\