Ionic and Cordova on Win 10 - AliceDigitalLabs/SupportingLiveProjects_2018 GitHub Wiki

In this example, we're setting up an Ionic / Cordova development system on a fresh Windows 10 'Express' install, on Oracle Virtual Box, running on a MacPro, High Sierra. We've installed the Oracle VirtualBox Guest Additions Image. Plus an automatic update. Meh.

You can the same installation order as we have below, but take a look at some of the differences you're likely to encounter here

• We've installed Chrome Browser, and made it the default browser.

• We've installed GitHub Desktop for access to GitHub repos

The goal of this example is to be able to install LittleList on an Android device.

First, have a look at Ionic Framework, what it's for and where it fits.

OK? Now we'll start on the installation. We're using the documentation for installing Ionic Framework V1 Since we're installing on Windows, take a look at the 'Windows note on Java, And and Android'. You don't need to do anything yet, but have it in the back of your mind as we're doing things.

Install the most recent Java 8 JDK (NOT just the JRE), JDK 9 is NOT currently (2017.12) supported by Cordova.

We like to install to path which DON'T have spaces in their folder names. The installation likes to put things in C:\Program Files\ We don't like that, because it messes up command-line stuff - you have to remember to put all paths in quotes. Ugh.

Install the Java Development Kit (JDK) to:

C:\java\jdk1.8.0_202

and the Java Runtime Environment (JRE) to:

C:\java\jre1.8.0_202

Use the Windows 10 utility to set environment variables:

1. go to the start bar, and search for 'environment'.
2. choose to set environment variable for your user account.
3. create the environment variable JAVA_HOME:
4. set the value to the root folder where the Java JDK was installed.
   • in this case: C:\java\jdk1.8.0_202
5. change the environment variable PATH:
   • in this case, add %JAVA_HOME%\bin

Use the Windows Command Prompt utility to check.

Go to the start bar, and search for cmd.
Choose 'Command Prompt'.
In the Command Prompt, type

echo %PATH%

and

echo %JAVA_HOME%

Check the values are as you expect. Type

java -version

You should get something like:

java version "1.8.0_202"
Java(TM) SE Runtime Environment (build 1.8.0_202-b08)
Java HotSpot(TM) 64-Bit Server VM (build 25.202-b08, mixed mode)

1. Download the .zip from here.
   • you can install the 1.10.x, because we just installed Java8
2. Extract the .zip
3. Move the top folder in the zip to c:\
4. Update your PATH to include the bin folder in that folder.
   • For example

     C:\apache-ant-1.10.5\bin

5. Add the environment variable ANT_HOME, to be the root folder of the installation
   • For example

     C:\apache-ant-1.10.5

Type the following into a command prompt:

ant -version

You should get something like:

Apache Ant(TM) version 1.10.5 compiled on July 10 2018

If you don't:

1. Check that you don't have a space between entries in in your PATH variable. Each entry should begin directly after the ';'
2. Close the CMD window, and use a new one. CMD loads its environment variables at the start, and does not update them when you change them.

Google used to distribute its SDK tools independently of the IDE. But now it doesn't. Now you have to have all of it.

1. Download from here
2. Run the downloaded .exe
3. When prompted, install to:

   C:\android\android_studio
   

   ... it avoids having spaces in the path.
4. Once installed, allow Android Studio to run, and let it install its default set of tools and SDKs.

Our target SDK for Little List is Lollipop (5.1)

1. Fire-up Android Studio
2. On the front page, you'll see a 'gear' icon, with the label 'configure'. Press this, and choose 'SDK Manager from the drop-down'
3. In the SDK Manager, you can see a list of all the SDKs available.
4. DESELECT the default SDK
5. SELECT 5.1 Lollipop
6. Choose to Apply these changes.
7. You will be presented with a choice to ACCEPT the licenses. Accept the licenses.
8. Allow the SDK to install (takes a while!)

1. Download the LTS version of Node.JS, from here
2. Run the installer
3. Install to

   c:\nodejs

   ... it avoids having spaces in the path
4. installation of node, npm and setting environment variables should be sorted for you by the installer

1. In a new command prompt, type the following:

   npm --version

   you should get:

   6.4.1

2. and then type:

   node --version

   You should get:

   v10.15.0

3. if you've installed a version of NodeJS >= 10 then type:

    npm install natives
   

You'll need to install Python 2.7, so that npm can build some dependencies of your project.

1. In a browser, go to: https://www.python.org/downloads/. Find the latest 2.7 release. Ours is 2.7.15. Download it.
2. The python MSI should take care of the installation for you, and will install to:

   C:\Python27

3. Once downloaded, add this to your PATH environment variable.

In a new Command Prompt, type:

python --version

you should get something like:

Python 2.7.15

Some NodeJS dependencies require a native build of components from C source code. MSBuild tools need to be installed to do this. If you have MS Visual Studio installed, you may this step. However, there is a dependency on version 2.0 of the MS Build tools, which will produce errors when building sass. If this happens, return to this step and give it a try.

1. In the Windows 10 search bar, type cmd
2. On the suggestion 'Command Prompt', right click, and choose 'As Administrator'
3. In the new Command Prompt, run the following command

   npm install --global --production windows-build-tools
   

4. The result will spawn several MS Visual Studio installers (check the task manager), which will install all necessary build tools.
5. It takes about 10 minutes to complete, and the output is a bit ambiguous, but it will finish with the following:

---------- Visual Studio Build Tools ----------
2019-01-22T15:23:00 : Verbose : Calling SetupEngine.Installer.EvaluateInstallParameters. [channelId: VisualStudio.15.Release, productId: Microsoft.VisualStudio.Product.BuildTools, installationPath: 'C:\Program Files (x86)\Microsoft Visual Studio\2017\BuildTools', languages: 'en-US' selectedPackageReferences.length: 13]
---------- Visual Studio Build Tools ----------
Successfully installed Visual Studio Build Tools.
------------------- Python --------------------
Python 2.7.15 is already installed, not installing again.

Now configuring the Visual Studio Build Tools..

All done!
 
+ [email protected]
added 145 packages from 98 contributors in 1031.859s

More information here.

We're nearly there - Cordova is the part of the tool-chain which creates native mobile apps to hold a webview. This houses the cross-platform javascript. Cordova is also responsible for managing and building platform-specific plugins, which add functionality and make it available via browser extensions.

1. In a new Command Prompt, type the following

   npm install -g cordova

2. Now type:

   npm install -g ionic

3. you will need to add the ionic v1 toolkit package to the ionic CLI: (little_list is an ionic v1 project (yes, we're still using ionic v1 and angularjs. BECAUSE.)) At the Command Prompt, type:

   npm i -D @ionic/v1-toolkit
   

1. In the command prompt, type the following:

   ionic --version
   

   you should get a response like:

   4.8.0
   

2. In the command prompt, type the following:

   cordova --version
   

   you should get a response like:

   ? May Cordova anonymously report usage statistics to improve the tool over time? No
   
   You have been opted out of telemetry. To change this, run: cordova telemetry on.
   8.1.2 (cordova-lib@8.1.1)

Now we'll clone the projects we want to use.

1. Run GitHub Desktop. Check you are signed-in.
2. In the Chrome browser, go to:

   https://github.com/aliceliveprojects/little_list

3. On this page, you'll see the 'code' tab. Click on it.
4. Now you'll see the 'Clone or Download' button. Click on it.
5. Choose the option to add the URL to the clip-board.
6. In Github Desktop, choose 'Clone a repository from the internet'.
7. In the dialog which pops up, make SURE you are in the URL tab.
8. Paste the URL from the clipboard, and allow Github Desktop to set the correct download directory for you. We get:

   C:\Users\DigitalLabs\Documents\GitHub\little_list

9. Click 'Clone'.
10. GitHub Desktop will download the repo for you.
11. GitHub Desktop will offer to 'Show in Explorer`. Select this option, and bring up an explorer window.
12. In Explorer, select the path from the address bar, and copy it.
13. Bring up a command window. Type the following: cd
    note the space!
14. Now paste the clipboard. We get:

    cd C:\Users\DigitalLabs\Documents\GitHub\little_list
    

    ... hit return to go to the root of your project.
15. Now go to the root of the little_list code. Type:

    cd .\little_list\code\little_list
    

Like all projects in GitHub, little_list has a .gitignore file, which tells the Git client not to check in the binary files of the project, generated as part of the build process. This is a pretty standard file, which we got from here use it in your next project. Because of the .gitignore file, the source code comes to us in a pretty basic state; it needs to be prepared.

The javascript part of our cross-platform application needs a whole load of dependencies, which are stored in the project's package.json file. This is read, and the dependencies installed into ./node_modules.

1. In the command prompt (at the root of the source code) type:

   npm install

   ... you'll find the node package manager goes away and gets all the dependencies. ... it will attempt to do a native build of some of them, and this is where you WILL need the ntive build tools we installed earlier.

1. Time to add native capability to the project.
2. At the Command Prompt, type:

   ionic cordova platform add android

3. This will attempt to generate the underlying project code.
4. At this point, all should be OK, and the command should complete with a few warnings.

1. Now we're going to go for a build.
2. At the Command Prompt, type:

   ionic cordova build android

3. The build process should run, and complete:

BUILD SUCCESSFUL in 2m 29s
46 actionable tasks: 46 executed
Built the following apk(s):
        C:\Users\DigitalLabs\Documents\GitHub\little_list\little_list\code\little_list\platforms\android\app\build\outputs\apk\debug\app-debug.apk

When you have a build, Ionic and Cordova have the tools to deploy to a device. Doing this is preferable to running in emulator.
Device connection is handled by the native build tools, so in this case it's the Android tool-chain. Google provides USB drivers for windows, and a tool called the ADB (Android Debug Bridge) to make the necessary software connections between your application and a debugger.
You'll need to activate debug functionality on your device.

Most device manufacturers have buried this functionality in their user interfaces, so it's wise to simply google for what you need to do. Which is:

1. Allow installation of non-Play store apps (side loading)
2. Activate debugging
3. Trust the computer which you are making the connection from

This is handled by Android Studio:

1. Install the Google USB Drivers:
   1. Start Android Studio
   2. On the main front page, find the gear 'config' button, press it, and choose 'SDK Manager' from the drop-down list.
   3. In the SDK Manager, go to the 'SDK Tools'.
   4. You'll find a big list of components. Find the one called 'Google USB Driver'. Check its select box.
   5. Find the 'Apply' button, to apply this change.
   6. The SDK Manager will download and install the driver.
2. Put the ADB in your PATH
   1. In the SDK Manager, the box at the top is labelled 'Android SDK Location'.
   2. Copy the path in this box to the clipboard
   3. Use the Windows Start Bar's search box to bring up 'Environment Variables' for your account
   4. Find the Environment Variable, PATH.
   5. Add a ';' delimiter to the last entry, and then paste in the path from the clipboard. Add the subdirectory 'platform-tools'. For example
      • C:\some-other\path;C:\Users\DigitalLabs\AppData\Local\Android\Sdk\platform-tools
   6. Bring up a NEW command prompt, and type

   adb version
   

   You should see something like

   Android Debug Bridge version 1.0.40
   Version 4986621
   Installed as C:\Users\DigitalLabs\AppData\Local\Android\Sdk\platform-tools\adb.exe
   

Now you can connect your device via USB.

1. Windows should recognise you have device connected, and ask what you want to do with this device.
   • Choose 'Take no action'
2. On the device, you may have a notification that you are connected for debugging
   • you may be asked if you trust this computer - confirm this.

1. in the command prompt, type:

adb devices

you should get a response like:

List of devices attached
04d38ef7003c09c9        device

You're ready to deploy to device!

In the command prompt, type:

ionic cordova run android

the build process will be run again. If all goes well, the process should complete like this:

BUILD SUCCESSFUL in 4s
46 actionable tasks: 1 executed, 45 up-to-date
Built the following apk(s):
        C:\Users\DigitalLabs\Documents\GitHub\little_list\little_list\code\little_list\platforms\android\app\build\outputs\apk\debug\app-debug.apk
ANDROID_HOME=C:\Users\DigitalLabs\AppData\Local\Android\Sdk
JAVA_HOME=C:\java\jdk1.8.0_202
No target specified, deploying to device '04d38ef7003c09c9'.
none
Skipping build...
Built the following apk(s):
        C:\Users\DigitalLabs\Documents\GitHub\little_list\little_list\code\little_list\platforms\android\app\build\outputs\apk\debug\app-debug.apk
Using apk: C:\Users\DigitalLabs\Documents\GitHub\little_list\little_list\code\little_list\platforms\android\app\build\outputs\apk\debug\app-debug.apk
Package name: io.ionic.starter
LAUNCH SUCCESS

There are lots of ways of debugging applications written with the Cordova toolchain:

1. Use the browser
2. Use Visual Studio Code
3. Use Visual Studio

Debugging with the browser is very convenient, but you need to use Chrome for Android devices, and Safari for iOS devices. The downside is that it doesn't integrate very well with your coding environment. Visual Studio has many tools for helping with Cordova development, but it tends to wrap everything in its own project format. We've found Visual Studio Code gives us the right combination:

1. Run a new instance of Visual Studio Code
2. Install the VS Code Extension 'Cordova Tools'
3. You'll need to re-load VS Code for the changes to take effect.

1. Use VS Code to open the root directory of the little_list Cordova project
   • that's the directory which has the package.json file
2. Click on the 'Explorer' icon in VSCode's toolbar. You can see:
   • little_list - file tree, nicely colour coded according to file type
3. Use the file tree to open the following file
   • <root>\www\js\app_specific\events\events.service.js

1. In the 'Explorer' pane, you can see
   • 'Outline' - this is a symbolic view of all the items in that file; functions, variables, etc. Useful!
2. Use the Outline view to find the function createDummyEvents

1. In the editor pane, you'll find you can click on the left-hand side, to create a break-point in the function createDummyEvents

1. Click on the 'Debug' icon in VS Code's toolbar.
   • You get the 'Debug' Pane being displayed.
   • You can see a Green 'play' arrow at the top, with a drop-down, next to it. The default is 'Run Android on device'.
   • You can see a 'gear' settings button next to that
   • You can see a button marked 'debug console` next that
2. Press the 'debug console' button, to get a debug window
3. Press the play button to start a debug session
4. You'll get a build process output appearing, followed by:

App successfully launched
Attaching to android
Forwarding debug port
Attaching to app.

1. On the device, you'll see your app has launched.
2. On the device, press the 'Update' button, in the little_list app.
3. The app moves into the 'Updating' state.
4. After a few moments, you should see the breakpoint hit in VSCode.

We've gone right through the set-up process for a cross-platform development on Windows 10, using Android as the target. Along the way, we've seen all the technologies on which this depends, and finally, we've topped it off with a really lightweight, elegant IDE, which we can use to debug cross-platform applications, live, on-device.