Einrichten des NetBeans-Cordova-Plugins (PhoneGap)

NetBeans ist eine hervorragende IDE, um hybride Web-Apps zu entwicklen. Was hybride Web-Apps sind, wurde in diesem Beitrag dargestellt.

Hier wird nun beschrieben, welche Installationsvoraussetzungen erfüllt sein müssen und wie man einen Basis-Workflow mit NetBeans einrichtet, um eine einfache Hello-World-App in Betrieb zu nehmen.

In weiteren Artikeln wird gezeigt, wie man diesen Workflow so optimiert, dass man fast die gleiche Performance erreicht, wie bei der Eintwicklung einer statischen Webseite.

Welche Tools werden benötigt und sind wie zu installieren?

Zunächst einmal, wie so häufig, müssen wir prüfen, ob wir die Vorraussetzungen für den Einsatz von Cordova mit NetBeans erfüllen. Es gibt eine sehr gute Anleitung für die Installation des Cordova-Plugins in der Netbeans-Dokumentation. Die folgende Anleitung deckt sich im wesentlichen damit, ergänzt die Dokumentation aber und betont bestimmte Aspekte etwas anders.

Android-SDK installieren

Ihr benötigt unbedingt das Android-SDK, dessen Installation ich in diesem Beitrag beschrieben habe. Einige Pfade in den Einstellungen der NetBeans-IDE sind auf dieses SDK zu setzen (dazu später mehr).

Ich stelle hier nur den Workflow für Android vor. iOS und mit Einschränkung andere Betriebssysteme sind natürlich auch möglich, sollen aber nicht Gegenstand dieser Einsteiger-Reihe sein.

Node.js installieren

Ich hatte die Installation von Node.js schon im ersten Beitrag der kleinen Grunt-Artikel-Serie beschrieben. Hier deshalb nochmal in Kurzform.

Verwendet einfach den Windows-Installer. Danach kann man Node.js und npm ausführen über Tasks / Alle Programme / Node.js. Wer Node.js unbedingt zu Fuß installieren möchte, dem sei diese Anleitung hier empfohlen.

Ant installieren ? Nicht mehr notwendig.

Die Cordova-Plugins früherer NetBeans-Versionen (< 8.0.2) verwendeten Ant für die Erstellung eines Build. Ant unterstützt in dem Zusammenhang verschiedene Funktionen für das Compilieren, Zusammenfügen, Testen und Launchen von Java-Applikationen. Die aktuelle Version des Cordova-Plugins verwendet dazu Git. Eine Installation von Ant ist demnach nicht mehr erforderlich obwohl das Ding in den Status-Meldungen manchmal noch auftaucht. Ich habe bei mir Ant sicherheitshalber unter C:\ant installiert. Einen Windows-Installer bekommt man hier.

Update: NetBeans 8.0.2 enthält eigene Ant-Tools und zwar im Ordner C:\Program Files\NetBeans 8.0.2\extide\ant (s. Netbeans: Options / Java / Ant Home). Dieser Pfad sollte unbedingt auch in der Windows PATH-Umgebungsvariable gesetzt werden. Dort vorhande Verweise auf andere Ant-Installationen sind zu entfernen. Die Benutzer-Variable ANT_HOME ist dort ebenfalls zu löschen, falls sie existiert. Nach dem Neustart von NetBeans und einer Windows-Console kann man mit where ant überprüfen, ob der Pfad für ant auf dem Netbeans-Verzeichnis steht.

Git installieren

Wir installieren Git - übrigens wie in der NetBeans-Anleitung empfohlen - mittels dieses Windows-Installers und nur über diesen. Die Gründe dafür hatte ich in diesem Beitrag zur Installation von Grunt unter Windows dargestellt. Wenn wir ein Git aus einer anderen Quelle verwenden, kann es sein, dass unser Grunt-Workflow nicht mehr funktioniert.

Damit Git aus jeder Windows-Konsole heraus funktioniert, müssen wir den Pfad zu den Binaries in die Path-Variable von Windows eintragen.

Node.js-Plugin für Cordova installieren

Wir kennen das schon. Das Installieren von Node.js-Programmen mit npm gehört für Grunt-Anwender zum täglichen Geschäft. Wir installieren und updaten das Cordova-Framework als globale Node.js-Anwendung mit folgendem Installationskommandos in einer Windows-Console:

npm install -g cordova
npm update -g cordova

NetBeans-Android-Plugin unter Netbeans installieren

Interessant war, dass bei einer kompletten Neu-Installation von NetBeans 8.0.2 im Gegensatz zu vorherigen Versionen auch nach Löschung sämtlicher Anwender-Daten das NetBeans-Android-Plugin (Name: Cordova Support) fertig installiert war. Ich brauchte nur noch unter

• Tools / Options / Miscellaneous / Mobile Platforms

den Pfad auf das SKD zu setzen (vgl. Abb. 1):

• C:\Users\<user>\AppData\Local\Android\android-sdk\

Abb. 1: NetBeans / Options / Miscellaneous / Mobile Platforms

Wenn ich dann mit New Project ein neues Projekt anlegen will, kann ich die Scaffolding-Möglichkeit von NetBeans für Hybride Apps ausnutzen, indem ich in der Auswahlmaske unter Html5 Cordova Application auswähle (Abb. 2).

Abb. 2: Netbeans / New Project / Html5 / Cordova Application

Es folgen noch einige weitere Masken, in denen man ein Template für seine Anwendung auswählt. Folgt einfach dem Begriff "Cordova Hello World" und stellt ansonsten am besten nichts Spezielles mehr ein.

Wer also ein frisches NetBeans installiert hat, nachdem die vorhergehenden Installationsschritte durchgeführt wurden, ist so sehr schnell am Ziel und kann  jetzt eine einfache PhoneGap-Anwendung generieren.

Aber halt, ein Build and Run wird wahrscheinlich nicht sofort funktionieren (dazu später mehr) und dazu wird euch auch nicht die oben verlinkte Original-Anleitung von NetBeans weiterhelfen.

An dieser Stelle zunächst einmal ein paar Instruktionen für diejenigen, die keinen Cordova Support finden (vgl. Abb. 3) unter

• Tools / Plugins / Installed / Cordova Support

Abb. 3: Tools / Plugins / Installed / Cordova Support

Diesen Absatz können alle überspringen, die auf die neueste NetBeans-Version upgedatet haben: Für ältere NetBeans-Versionen musste das sogenannten NBAndroid-Plugin installiert werden. Unter Settings wurde dazu diese Url im Update Center hinzugefügt: http://nbandroid.org/updates/updates.xml. Wenn man jetzt unter Available Plugins den Check für Newest-Plugins machte und dann nach NBAndroid suchte, erschienen drei Plugins, die alle aktiviert werden mussten. Aber wie gesagt, dies ist mit der aktuellen NetBeans-Version (mindestens > 8.0.2) nicht mehr notwendig.

Allerdings scheint es mit der neuen Version auch ein paar neue Hakeleien zu geben, bei denen man sich zu helfen wissen muss (s. Absatz Problembehandlung unten).

Build and Run einer einfachen hybriden Web-App

Ich habe schon darauf hingewiesen, dass ein Build and Run nach erfolgreicher Installation wahrscheinlich zu einem Build-Error führen wird. Dies hat damit zu tun, dass wir die Parameter für unsere Cordova-App noch nicht mit den Einstellungen des Android-SDK synchronisiert haben.

Der wichtigste Punkt ist, dass ich mich für eine minimale Betriebssystem-Version entscheiden muss, die ich noch mit meiner App unterstützen möchte.

Im Artikel zur Installaktion des SDK wurde schon darauf hingewiesen, dass ich entsprechende Pakete auswählen und installieren muss, z.B. für Android 2.2 (Froyo) die API Level 8 (s. Artikel: Abb. 3). Die Installation nimmte einige Minuten in Anspruch.

Nehmen wir außerdem an, dass ich Versionen bis hin zu Android 4.2.2 (API 17) unterstützen möchte. Auch diese Packages (und später die dazwischen) muss ich installieren.

Jetzt kommt der entscheidende Punkt, der euch viel Zeit für die Ursachenforschung erspart und auf den in kaum einem anderen Artikel hingewiesen wird. Es gibt in eurem Cordova-Projekt eine Datei AndroidManifest.xml:

• C:\xampp\htdocs\PhonegapTest\platforms\android\AndroidManifest.xml

Dort wird die Bandbreite der Android-Versionen, für die compiliert wird, eingetragen. Für die hier angezielten Plattformen muss die Zeile <uses-sdk ...> dort so angepasst werden:

<uses-sdk android:maxSdkVersion="17" android:minSdkVersion="8" android:targetSdkVersion="17" />

Man erkennt, dass eine minimale und eine maximale Android-Version eingetragen wird sowie eine Target-Version.

Es gibt im gleichen Ordner noch eine zweite Datei project.properties:

• C:\xampp\htdocs\PhonegapTest\platforms\android\project.properties

Dort müssen wir das Target ebenfalls auf den gleichen Level (17) einstellen, wie im Android-Manifest:

target=android-17
android.library.reference.1=CordovaLib

Ein solcher Emulator sollte vorher im SDK eingerichtet worden sein mit dem Android Virtual Device Manager (erreichbar im Android Device Monitor unter Window). Dort (s. Abb. 4) findet man dann hoffentlich die Bandbreite der API-Levels wieder (hier 8 ... 17).

Abb. 4: Mit dem Virtual Device Manager eingerichtete Emulatoren

Man erkennt in Abb. 4, dass ich zwei Emulatoren eingerichtet habe, einen für Android 2.2 (Froyo) und einen für Android 4.2.2. Ein Beispiel für die Einstellungen für Android 4.2.2 kann man Abb. 5 entnehmen.

Abb. 5: Einstellungen des Emulators für Android 4.2.2

Wenn ich also jetzt geeignete Emulatoren eingerichtet habe und die Datei AndroidManifest.xml entsprechend angepasst habe, müsste ein Build & Run (Projekt-Ordner in NetBeans anklicken, rechte Maustaste, Menu Run) ohne Build-Fehler durchlaufen.

Vorher muss ich aber in NetBeans die Ziel-Plattform auswählen (Click auf das Icon mit dem grünen Handy-Symbol, vgl. Abb. 6). Falls wir ein Test-Handy richtig an unseren PC angeschlossen haben, können wir auch dieses auswählen (Android Device).

Abb. 6: Auswahl der Ziel-Plattform

Um unsere App endlich erfolgreich zu compilieren, starten wir zunächst mit dem Android Virtual Device Manager unseren Emulator und betätigen dann mit der rechten Maustaste über dem Projekt-Ordner in NetBeans den Menu-Punkt Run.

Nach einem ordentlichen Build & Run wird automatisch unsere App im Emulator gestartet (Abb. 7).

Abb. 7: Simple hybride Hello-World-App im Android-Emulator

Beim ersten Mal wird dieses Build & Run mehr Zeit in Anspruch nehmen. Das hat damit zu tun, dass sich NetBeans für diese Build gleichzeitig noch Ressourcen aus dem Netz herunterlädt (über Git). Deswegen sollte man nicht zu schnell abbrechen, wenn einem die Länge der Compilierung komisch vorkommt. Lieber einen Kaffee trinken und dann wiederkommen.

Problembehandlung

Im Protokoll wird normalerweise angezeigt, welche Ressourcen gerade heruntergeladen werden. Bei mir war es so, dass sich über einen sehr langen Zeitraum gar nichts mehr tat ohne Fehlermeldung. Ich habe dann einfach den Build-Prozess abgebrochen und es noch einmal versucht und hatte dann den Erfolg, dass die App relativ schnell im Emulator gestartet wurde (s. Abb. 7).

Das 'xxxx' in Abb. 7 habe ich übrigens in index.html meines Projektes hinzugefügt. Das ist nicht Bestandteil des Hello-World-Examples. Bitte auch nicht wundern, wenn nirgends ein Hello-World zu sehen ist. Das Template des Cordova-Projekts, das ich ausgewählt habe im Beispiel, heißt nur so.

Mögliche Fehlerquellen

Falls das Build oder auch ein Hochladen des apk-Files auf den Emulator (oder das mobile Endgerät) nicht funktioniert, sollte man folgendes prüfen:

• Startet den Build nochmal, falls es beim ersten Mal nicht klappt. Das hilft manchmal.
• Target-Levels (minimal, maximal und Ziel) richtig eingestellt in AndroidManifest.xml,
• Ziel-Target-Level richtig eingestellt in project.properties,
• Existiert unter C:\Users\Admin\AppData\Local\Temp\ der Ordner plugman\git, den Cordova für das Herunterladen von Git-Ressourcen für das erste Build benötigt. Dieser Ordner wurde bei mir nicht automatisch angelegt (NetBeans-Bug?) und führte dann zu einem Build-Abbruch, falls man ein Android-Plugin benötigt, das per Git erst noch geladen werden muss. Die Fehlermeldung weist allerdings auf dieses Problem hin.
• Arbeitet NetBeans mit dem richtigen Node.js-Cordova-Plugin zusammen? Die Cordova-Plugin-Liste von NetBeans findet man unter: nbproject \ plugins.properties. Dort sollten die Listeneinträge für Cordova 4.2 folgende Form haben: org.apache.cordova.device=....
• Falls man die Cordova-Version wechselt, sollte man immer die Ordner platforms und plugins im Projektordner komplett leeren und ein neues Build starten. Falls man dort neue Icon-Ressourcen und ähnliches erstellt hat, die nicht von der NetBeans-Konfigurations verwaltet werden (was leider manchmal notwendig ist), sollte man sich diese vorher sichern.
• Falls Build und Run nicht durchlaufen in NetBeans, kann man diese aus dem Ordner platforms \ android \ cordova heraus manuell ohne NetBeans starten mit z.B. run --device bzw. run --emulator. Damit bekommt man auch ausführlichere Fehlermeldungen.
• Vor einem Build sollte mindestens ein Android-Emulator gestartet sein, da sich das Build vom SDK Ressourcen holt. Checkliste: Emu starten, Manifest überprüfen (z.B. Level 8 bis 17), Datei project.properties überprüfen (Level 17), Target in NetBeans auf Cordova (Android Emulator) einstellen, Build.
• Hier findet man Release Notes, die einem bei sonstigen Problemen weiterhelfen können: https://netbeans.org/community/releases/80/relnotes.html.

Zu diesem Punkt eine Anmerkung. Überprüft die Version eures Cordova-Plugins mit:

cordova --version

Falls ihr undefinierbare Probleme habt, liegt das vielleicht daran, dass NetBeans nur mit einer älteren Version zusammenarbeitet. Zu empfehlen ist in diesem Fall die Version 3.4.0-0.1.0.

Update: Die spezielle Version 3.1.0-0.1.0 wird nicht mehr benötigt für NetBeans 8.0.2. Bei mir funktioniert im Moment die 'Latest'-Version 4.2.0 am besten.

Die letzte Cordova-Version kann man folgendermaßen installieren:

npm uninstall -g cordova
npm install -g cordova           ;depricated: npm install -g cordova@3.1.0-0.1.0  

Eine weitere Möglichkeit, Problemen auf den Grund zu kommen, besteht darin, das Build & Run nicht über NetBeans, sondern über eine Windows-Console zu starten. In diesem Fall bekommt man ausführlichere Fehlermeldungen (vgl. Abb. 8)!

Mehr Hinweise auf Fehler: Run --emulator ohne NetBeans starten

Dazu geht man in den folgenden Unterordner des Projekt-Ordners ...

• C:\xampp\htdocs\CordovaMapsSample\platforms\android\cordova

... und startet ein Run in einer Windows-Console mit:

run --emulator

bzw.

run --device (falls gerootetes Endgerät im Debug-Modus angeschlossen ist)

Abb. 8: NetBeans Run manuell per Windows-Console

Update: Mir ist es im Moment nicht möglich, aus NetBeans 8.0.2 heraus ein Run auszuführen (Cordova 4.2). Das Kommando bleibt ohne Fehlermeldung stecken zwischen dem Build und der Installation des apk-Files auf dem Emulator. Mir bleibt im Moment also nichts anderes übrig, als das Run wie oben beschrieben manuell außerhalb von NetBeans auszuführen.

Verwendung des Android-Monitors

Weitere Hinweise auf Fehlermöglichkeiten liefert der Andorid-SDK-Monitor, mit dem aktuelle Aktivitäten eines Emulators oder Device überwacht werden können. Gestartet wird er hier:

• C:\Users\Admin\AppData\Local\Android\android-sdk\tools\monitor.bat

Ausblick

Nach dem ersten erfolgreichen Launchen des Projekts werden die Compilierungen schneller, weil alle wichtigen Ressourcen schon im Projekt existieren. Allerdings ist diese Art des Entwickelns ausschließlich mit den Android-SDK-Emulatoren noch sehr unproduktiv.

Deshalb wird in einem folgenden Beitrag der Ripple-Emulator von Chrome vorgestellt, der den Workflow für die Entwicklung von hybriden Apps genial verbessert.

Außerdem wird ein Grunt-Skript vorgestellt, welches per Live-Kopieren, den Entwicklungsprozess noch einmal beschleunigt, so dass man am Ende die gleiche Performance erreicht, wie für eine normale Html-Webseite.

Fazit

In diesem Beitrag wurde der Workflow für die Entwicklung einer hybriden Web-App mit Netbeans, Cordova (PhoneGap) und dem Android-SDK vorgestellt.

Das Ergebnis ist eine einfache Hello-World-App noch ohne Mobile-Sensorik und Web-Server.

In weiteren Artikeln wird der Workflow dahingehend erweitert, dass der Entwicklungsprozess effizienter wird (Ripple-Emulator, Grunt-Watch-Skript) sowie gezeigt, wie man die Handy-Sensorik und Web-Server-Funktionalität integrieren kann.