Setting Up the Android Development Environment for Android Studio

Setting up the Android Development Environment

Supported development platforms
  • The Vuforia SDK officially supports Android OS 4.1 and above, and OpenGL ES 2 and 3.
  • The recommended development environment is Microsoft Windows 7 or 8 32/64-bit.
  • The components to build the actual code (JDK, Android Studio, Android SDK / NDK) are available across multiple platforms. While building on Linux Ubuntu and Mac OS X environments is possible, we are unable to support those platforms with detailed documentation. However, we have included hints and notes to platform-specific issues that will help you set up your development environment on Linux Ubuntu 10.10 or Mac OS X 10.7 (Lion). This setup guide has been written for the Win7 32/64-bit platform with special notes for other operating systems.
NOTE: If you have already set up the Android SDK and NDK, go directly to Installing the Vuforia Android SDK

The Vuforia SDK requires the Android SDK and the NDK. The Android NDK is an extension of the Android SDK that lets Android developers build performance-critical parts of their applications in native code. The SDK and NDK communicate over the Java Native Interface (JNI).
To set up the development environment, install these components in the following order, using the latest versions of the tools with the Vuforia SDK:
  • JDK (Java SE)
  • Android Studio IDE
  • Android SDK packages
  • Cygwin environment
  • Android NDK

JDK

Mac OSX: The JDK is already integrated into the Mac OS X operation system.
  1. Download the Java SE Development Kit (JDK) from this site: http://www.oracle.com/technetwork/java/javase/downloads/
  2. Click ‘Download’ from the JDK section of the 'Java Platform, Standard Edition' table.
  3. Install the JDK environment with default settings.
Detailed installation instructions and system requirements can be found at: http://www.oracle.com/technetwork/java/javase/index-137561.html

Android Studio

Android Studio provides everything you need to start developing apps for Android, including the Android Studio IDE and the Android SDK tools.
  1. Download the Android Studio installer from: http://developer.android.com/sdk/index.html
  2. Once the download has completed, run the installer executable and follow the installation instructions to install the IDE in the destination directory of your choice (e.g. ‘C:\Program Files\Android\Android Studio’); in particular, pay attention to the following steps:
    • In the ‘Select components to install’ page, make sure that ‘Android SDK’ option is selected;
    • In the ‘Configuration Settings – Install Locations’ page of the install wizard, specify the location where you want to install the Android SDK; we suggest to set it to a location like ‘C:\Development\Android\android-sdk’, where ‘C:\Development\Android’ represents the base directory of your Android development environment; this is also the directory where you will want to install the Android NDK, as discussed later in this guide (note: we will refer to such base directory as <DEVELOPMENT_ROOT> in the remainder of this guide)

Android SDK Packages

By installing Android Studio, you also installed the most recent version of the Android SDK and the relevant SDK tools. However, the SDK Manager allows you to install additional / optional SDK components and to update your Android SDK and SDK tools to the latest revisions available; therefore you may want to periodically run the SDK Manager to check for the latest SDK revisions, and update to them if necessary.
We also recommend to run the SDK Manager at least once after the installation of Android Studio, to download the necessary components for developing with Vuforia:
  1. Launch Android Studio
  2. In Android Studio, click on the SDK Manager icon in the Toolbar.
  3. In the dialog window that opens up, click on the ‘Launch Standalone SDK Manager’
  4. In the SDK Manager standalone window, select the following packages to install:
    • Tools:
      • Android SDK Tools (latest rev.)
      • Android SDK Build Tools (latest rev.)
      • Android SDK Platform-Tools (latest rev.)
    • Android 6.0 (API 23):
      • SDK Platform
      • Documentation for Android SDK
        • NOTE: These items should have been already installed during the Android Studio installation (if not, simply select them for installation)
    • Android 5.1.1 (API 22):
      • SDK Platform
        • NOTE: Vuforia 5.0.x does not fully support Android 6.0 (akas Android ‘Marshmallow’ or Android ‘M’); therefore we recommend installing the Android 5.1.1 (API 22)
    • Extras:
      • Google USB Driver (Windows only)


Once you've selected all the desired packages, continue to install:
  1. Click 'Install X packages'
  2. In the next window, double-click each package name on the left to accept the license agreement for each.
  3. Click Install.
The download progress is shown at the bottom of the SDK Manager window. Do not exit the SDK Manager or it will cancel the download.

Setting the System Environment Variables

Add the Android SDK ‘tools’ and ‘platform-tools’ directories to your Windows Path:
  1. Right-click My Computer on the desktop and select ‘Properties’.
  2. Click the ‘Advanced System settings’ button ab to open the System properties window
  3. Under the ‘Advanced’ tab, select ‘Environment Variables’ and look for the Variable ‘Path’ in the System variables window.
  4. After pressing Edit, scroll to the end of ‘Variable value:’ and add the full path to the directory to the end of the path, separated by a semicolon from the previous path. In the above example, you would add:
;C:\Development\Android\android-sdk\tools\;C:\Development\Android\android-sdk\platform-tools\
NOTE: The last "\" at the end of the Path variable has to be included.

Mac OSX: Update the PATH variable to point to the Android SDK Platform-tools directory in the /etc/rc.common file or ~/.bash_profile:
 PATH=/bin:/sbin:/usr/bin:/usr/sbin:/usr/libexec:/System/Library/CoreServices:/Developer/usr/bin:~/Development/Android/android-sdk/tools:~/Development/Android/android-sdk/platform-tools:export PATH

Linux: Update your PATH to point to the Android SDK Platform-tools directory. If you use bash shell, add the following to ~/.bashrc :
export PATH=/opt/android-sdk/tools/:/opt/android-sdk/platform-tools/:

Cygwin environment

Linux: This section is not relevant for Linux users who have GNU make installed and in their path.
Mac OSX: This section is not relevant for Mac users who have Apple Developer Tools (XCode) installed. Install XCode if necessary from http://developer.apple.com/xcode/.

The Vuforia SDK for the Android platform includes both a Java API and a C++ API. The Java API enables the full suite of Vuforia features and functionalities and allows developers to build Android applications without having to write native C++ code.

The C++ API is meant to be used by developers with very advanced / specific requirements, such as the ability to integrate C++-based third party libraries or custom C++ software components. When this is not required, it is generally recommended to use the Java API.
If you expect to need the C++ native API, you will need a C++ GNU compiler, as explained in the following paragraph; otherwise, for pure Java based development, you can skip this section.

A GNU compiler is required to compile dynamic applications as shared libraries for the Android NDK. Android makefiles are designed to run with gcc4. On Windows, a convenient way to have the complete environment prepared for this is to install Cygwin.

Cygwin uses an installer helper to manage the installation process.
  1. Go to http://www.cygwin.com, download and run the installer (setup.exe)
  2. Select "Install from the Internet!" when prompted at "Choose a Download Source" in the installer. We recommend not changing the Root Directory in the next window, and leaving it at "C:\cygwin." The "Local Package Directory" holds the downloaded packages. You may want to keep them with the downloaded Setup.exe file in the same directory to have a Cygwin installer directory. Choose a download site with a known fast connection near you.
When the package information is downloaded you will see a hierarchical browser to select packages.
  1. Select the following package from the hierarchy for download: All -> Devel -> "make: The GNU version of the 'make' utility"
  2. Select the word ‘skip’ to change it to the actual version number that will be installed
  3. Finish the installation by clicking Next.
Your Cygwin environment is fully set up to work with the Vuforia SDK. If you have other similar environments installed, make sure to set your Windows path variable to point to "C:\cygwin\bin" so that bash uses this version of GNU's make.exe.

Android NDK

The Android NDK is an extension of the Android SDK that lets Android developers build performance-critical parts of their applications in native code.
If you need to use the C++ API of the Vuforia SDK, you will also need to install the Android NDK which enables native C++ programming on Android. If you plan to only use the Java API, you may skip this section.
  1. Download the NDK package from http://developer.android.com/sdk/ndk/index.html
  2. Unzip the archive, and copy the contents into a directory. To be consistent with our previous setup, we recommend putting the contents in "C:\Development\Android\android-ndk-rxy\". Thus, Android SDK and Android NDK share the same parent directory. Later, we will add the Vuforia SDK and your project files. NDK requires the above directory to be added to the Windows path.
  3. Right-click My Computer on the desktop and select ‘Properties’.
  4. Click the ‘Advanced System settings’ button to open the System properties window
  5. Under the ‘Advanced’ tab, select ‘Environment Variables’ and look for the Variable ‘Path’ in the System variables window.
  6. After pressing Edit, scroll to the end of ‘Variable value:’ and add the full path to the directory to the end of the path, separated by a semicolon from the previous path. In the above example, you would add:
;C:\Development\Android\android-ndk-rxy\

NOTE: Path has a semicolon at the beginning. Do not use pathnames with spaces. Alternatively, you can set a User variable with the name Path, but this is valid only for the current user. The last "\" at the end of the Path variable has to be included.

To test your installation, compile any of the NDK sample applications. Using a Cygwin bash shell, navigate to the root directory of any demo application (e.g., for the 'san-angeles' sample app without the installation path above):
cd /cygdrive/c/Development/Android/android-ndk-rxy/samples/san-angeles
ndk-build 

The compiler should produce a dynamically linked library libsanangeles.so and write it to ‘/libs/armeabi’ within the application directory. NDK includes support for different architectures so you might find different subdirectories in /libs.
Now your development environment is ready to host Vuforia SDK-related content.

Mac OSX: Update the PATH variable to point to the Android NDK directory in the /etc/rc.common file or the ~/.bash_profile:
PATH=/bin:/sbin:/usr/bin:/usr/sbin:/usr/libexec:/System/Library/CoreServices:/Developer/usr/bin:~/Development/Android/android-sdk-macosx/tools:~/Development/Android/android-sdk-macosx/platform-tools:~/Development/Android/android-ndk-rxy:export PATH

Linux: Update your PATH to point to the Android NDK Platform directory. If you use bash shell, add the following to the ~/.bashrc file:
export PATH=~/bin:/opt/android-sdk-linux_x86/tools/:/opt/android-ndk-rxy: