Application Designer Prerequisites

You must install the following software on your computer in order to use Application Designer:

Java - Java is required by the Android SDK

Chrome - Google's Chrome browser.

NodeJS - a framework for easily building fast, scalable applications. Download Version 6.2.2 or higher and install it from NodeJS

Grunt - a task-based scripting environment (installation is described below).

Android SDK - the software development kit for Android devices (installation is described below).

Warning

It is tricky to foresee all the issues that can crop up on many different machines and setups. If something in this process does not go as expected, please check the ODK-X Forum.

Warning

Android Studio is not supported on the Windows Linux subsystem, so you will not be able to run Application Designer if you are using it.

Java

Make sure Java 8 or higher is installed on the computer you plan to use. If it is not, download and install it. If you are using MacOSX, it may require special care and attention. See MacOSX Java install and MacOSX Java FAQ.

NodeJS

You must use Version 12 or higher. To avoid directory path problems on Windows, we require npm version 6.9 or higher (generally npm will be bundled with NodeJS installer). Follow the instructions to install NodeJS.

For Windows

When installing on Windows you can use an automated NodeJS installer that uses Chocolatey. If you chose not to let the installer use Chocolatey to install a bunch of packages after installing NodeJS, you will need to ensure the location of the npm folder is added to the PATH variable of your system. If it is not, subsequent calls to access grunt will fail. For example: C:\Users\[username]\AppData\Roaming\npm. For instructions on modifying PATH, see the section at the bottom of this page called Add adb to your PATH For Windows. Instead of navigating to the location of Android SDK, navigate to the location of the npm folder. You can check if npm has been installed properly by executing the following command in cmd or PowerShell.

$ npm --version

For Mac/Unix

After installing NodeJS, open a terminal (which you can do by clicking the spotlight in the top right corner of the screen, typing terminal, and clicking the program named Terminal) and type:

$ npm --version

Warning

If a number is not displayed, but you instead receive a message that the command npm cannot be found, you will have to perform some additional configuration.

As of this writing, by default NodeJS installs its commands into /usr/local/bin/. In the terminal, type:

$ ls /usr/local/bin/npm

If this command outputs something like /usr/local/bin/npm, but you are still unable to run:

$ npm --version

try running:

$ /usr/local/bin/npm --version

If this is successful, then npm is successfully installed, and you will just have to add /usr/local/bin/ to your system PATH variable (see below).

If the command:

$ ls /usr/local/bin/npm

outputs a message telling you permission is denied, then you will have to change the ownership of the /usr/local/ and /usr/local/bin/ directories. On Mac, follow the instructions to take ownership of these directories, or to at least give yourself read permission. On other Unix systems, use the chown command or the user-interface appropriate to your distribution to do so.

Grunt

After installing NodeJS, install grunt by doing the following:

Note

These installation steps are copied from the Grunt Getting Started guide.

On Windows, open a cmd window (go to Start Menu, search for cmd and open it); on MacOSX, open a terminal window. Within this window, type:

$ npm install -g grunt-cli

If the above command is unsuccessful, some machines may need to append sudo at the beginning of the command. If grunt is successfully installed, the following command:

$ grunt --version

Should display the installed version of grunt. For example the version might be grunt-cli v1.2.0

Warning

If grunt is not found, you may need to add it to the PATH variable of your system.

Android SDK

To install the Android SDK:

Browse to the Android SDK download page.

Scroll down on this page to the section labeled: Get just the command line tools.

Note

There no longer exists graphical tool for package management when using only the command line tools. You should install the full Android Studio, in which case you should follow Google's instructions. Open the SDK Manager from Android Studio, click Tools > SDK Manager or click SDK Manager in the toolbar.

Within that section, download the appropriate zipped file(s) based on your operating system.

Accept the Command Line Tools terms and conditions.

After the download completes, create a folder called Android and extract the contents of the zipped folder to the \Android folder you created.

Navigate to the cmdline-tools folder. It should contain a \bin folder and a \lib folder and two other files NOTICE.txt and sources.properties.

In the cmdline-tools folder, create a new folder called latest and move the contents of cmdline-tools into the latest folder. At this point, the cmdline-tools has just one folder latest which should contain the \bin and \lib folder and two other files NOTICE.txt and sources.properties.

Note

Important for steps 8 and 9: On Windows, the bin directory mentioned above will contain a file named sdkmanager.bat, but on Unix (Mac, Linux), it will contain a file named sdkmanager. Steps 8 and 9 involve commands using sdkmanager. If you are on Windows, these commands should start with sdkmanager.bat, and on Unix, they should start with sdkmanager

Also, if you are using Terminal or Powershell to run commands, you could need to prefix the commands with a ./ depending on if . is added to your PATH variable. For example, consider the command sdkmanager --list. On Windows, you might have to do ./sdkmanager.bat --list, and on a Mac ./sdkmanager --list. You can try the commands first without the ./, and if they fail, try the commands with it.

Run sdkmanager.bat --list, this shows a list of all packages with the versions that are available be installed.
On Windows open a PowerShell or cmd window, whichever one you decide to go with (open the Start menu, type cmd or PowerShell in the search box, select and open it). Get to the \bin directory

On Mac/Unix, open a terminal window.
$ /Android/cmdline-tools/latest/bin>
$ /Android/cmdline-tools/latest/bin>sdkmanager.bat --list
Select the latest versions of the following packages by typing sdkmanager followed by the package path wrapped in quotes and separated by a space:
Android Platform-tools

Android Build-tools
$ /Android/cmdline-tools/latest/bin>sdkmanager "platform-tools" "build-tools;30.0.3"
If there are extra packages you wish to install, you may add them by passing the package path wrapped in quotes, separated with a space.
$ /Android/cmdline-tools/latest/bin>sdkmanager "platform-tools" "build-tools;30.0.3" "extra-package-path"
Accept the license agreement(s) by entering y to the Accept? (y/N): prompt.

Among many other things, this will install the Android Debug Bridge software on your computer. This tool enables the scripted pushing of files and APKs down to your Android device. See adb (Android Debug Bridge) for a listing of its capabilities.

Next, on Windows open a PowerShell or cmd window and on Mac/Unix open a terminal window. Type:

$ adb version

If this displays a version string, then your installation is complete; you are done with this section and can move on to Installing Application Designer.

Warning

If there is an error complaining about Java not being installed, you will need to close this cmd/PowerShell or terminal window and download and install Java. After installing Java, open a new cmd/PowerShell or terminal window and type this command again.

Warning

If adb is not found, then you need to add it to the PATH variable of your system.

Add adb to your PATH

For Windows

Open a Windows File Explorer and navigate to the location of your Android folder. This will typically be at one of: C:\Users\your_username\Android or C:\Program Files\Android or C:\Program Files (x86)\Android.

Navigate into the platform-tools folder.

Click in the file path at the top of the File Explorer window. The path will become a selected text string. Copy it into your copy-and-paste buffer.

In the File Explorer, right-click on This PC.

Choose Properties. The About screen in Settings opens.

Scroll down and click on Advanced system setting under Related settings. The System Properties dialog opens.

Click on the Environment Variables… button at the bottom of the screen. The Environment Variables dialog opens.

Select the Path variable in the bottom System variables scroll window.

Click Edit…. The Edit environment variable dialog opens.

Click New. A text box appears.

Paste the platform-tools directory path into the text box.

Click on OK and exit all of the windows.

Verify that you have made the change by closing all PowerShell or cmd windows and open a new one (so it picks up the change), and type

$ adb version

You should now see the version of the adb tool. For example: Android Debug Bridge version 1.0.31. You can now move on to Installing Application Designer.

For Mac/Unix

The PATH variable is nothing more than a default list of places the system looks for commands. Open a terminal. Type:

$ echo $PATH

You will see a colon-separated list of folders on your computer. (echo means just print whatever comes next, and the ${ } means that the system will treat PATH as a variable, not a program. You don't need to know this to follow these instructions, but knowledge is power.) For example, you might see something like this:

$ echo $PATH
  /usr/local/bin:/usr/local/sbin:/usr/bin:/bin

This means that when you type:

$ adb --version

the system will look for the command called adb in the directories /usr/local/bin/, /usr/local/sbin/, /usr/bin/, and /bin/.

Note the location where you saved the Android folder. It should contain a folder called platform-tools, which itself contains the program adb. If this was in the folder /Users/someuser/Desktop/Android/ you should be able to run:

$ /Users/someuser/Desktop/Android/platform-tools/adb --version

This works because we're telling the computer exactly where the program adb exists. By putting the platform-tools directory on the system's PATH variable, we will be able to just type adb and have the system find it in the /Users/someuser/Desktop/Android/platform-tools/ directory.

This process is more involved on Mac/Unix than on Windows. Use a text editor (not Word, but something like TextEdit), select the option to open a file, and browse to your home directory. You can find your home directory by typing:

$ echo ~

in a terminal. ('~' is a shortcut for the home directory.) Macs use a hidden file called .bash_profile in the home directory to set variables like PATH. Other Unix systems use files like .bashrc. You might have to check the specifics for your distribution to know which you should use. Open the appropriate file. If the file does not already exist, create a new file that will be saved with the appropriate name in your home directory.

We want to add the location of the adb tool to your PATH while preserving the existing PATH information. Assuming that your adb program is in the /Users/someuser/Desktop/android-sdk/platform-tools/ directory, you would add the following command to the end of the .bash_profile file:

$ export PATH=${PATH}:/Users/someuser/Desktop/Android/platform-tools

Save the file, close the terminal window, open a new terminal window, and type:

$ echo $PATH

You should see your old path with the new directory you added above, and you should now be able to run:

$ adb --version

Tip

If you are going to be heavily customizing the look-and-feel of the application with a lot of external JavaScript libraries, you might also choose to install bower.

You can now move on to Installing Application Designer.