Using a Custom Set of Java Libraries In Your RAD Studio Android Apps

From RAD Studio
Jump to: navigation, search

Go Up to Using Java Libraries in Your RAD Studio Android Apps

RAD Studio allows you to use your own or third-party Java libraries in RAD Studio applications.

To use a custom set of libraries in your RAD Studio Android applications:

  1. Ensure that your Java libraries meet the RAD Studio requirements for Java libraries.
  2. Create a native bridge file that your Delphi or C++ applications can use to access the APIs of your Java libraries.
  3. Create a classes.dex file from both your custom libraries and the RAD Studio built-in Java libraries that your applications need.
  4. Deploy your custom classes.dex file along with your Android applications, replacing the default classes.dex file that provides the RAD Studio built-in Java libraries.

RAD Studio Requirements for Java Libraries

RAD Studio only supports the Android API level 10 (Android 2.3.3) and later. If your Java libraries use the Android API, they must be compiled using a supported Android API.

If your Java library depends on other Java libraries, you must have the JAR files of both your Java library and the libraries that your library depends on. You need the JAR files of all those Java libraries to generate a valid classes.dex file later.

See in the table under Generating a classes.dex File which JAR file belongs to each library.

Creating a Native Bridge File for a Java Library

Once you have your Java library, you need to create one or more native bridge files, files in Delphi or C++ that you can include in your native RAD Studio applications to access the API of your Java libraries.

To learn how to create a bridge file, check the existing bridge files (prefixed with Androidapi.JNI) in the following paths within the RAD Studio installation folder (C:\Program Files (x86)\Embarcadero\Studio\14.0):

  • source\rtl\android (Delphi)
  • include\android\rtl (C++)

Creating a classes.dex File

The classes.dex file is a Dalvik Executable file that all Android applications must have. This file contains the Java libraries that the application uses.

When you deploy an application for Android, RAD Studio includes a classes.dex file that contains the RAD Studio built-in Java libraries. To use your own Java libraries in your RAD Studio applications, you must create a new classes.dex file that includes both those RAD Studio built-in Java libraries that your application needs and your own Java libraries.

Determining Which JAR Files to Include in Your classes.dex File

To create your new classes.dex file, you need the JAR files of every Java library that your applications use, as well as the JAR files of the libraries on which those libraries depend.

This affects the RAD Studio built-in Java libraries as well. For example, if your applications need the Google Play Services Java library, your classes.dex file must also contain the JAR file of the Google Play Application Licensing Java library, because Google Play Application Licensing is a dependency of Google Play Services. If Google Play Application Licensing had its own dependencies, you would have to include those as well.

The following table lists the dependencies of the RAD Studio built-in Java libraries:

Library JAR File Dependencies Required by RAD Studio

Android Support





  • Android Support


Google Mobile Ads



Google Analytics



Google Play Application Licensing



Google Play In-app Billing


  • Google Play Application Licensing


Google Play Services


  • Google Play Application Licensing


APK Expansion


  • FireMonkey
  • Google Play Application Licensing


Cloud Messaging


  • FireMonkey
  • Google Play Application Licensing


You can find these JAR files in the following folders within the RAD Studio installation folder (C:\Program Files (x86)\Embarcadero\Studio\14.0):

  • lib\android\debug
  • lib\android\release

You can either include all the RAD Studio built-in Java libraries in your classes.dex file or determine, based on the information on the table above, which RAD Studio built-in Java libraries your applications need.

Warning: You must always include the Java libraries that are Required by RAD Studio in your custom classes.dex file.

Generating a classes.dex File from JAR Files

Once you have determined which JAR files your Android applications need, you can create a classes.dex file from them.

To create a classes.dex file, you need to use the command-line tool dx. You can find this command-line tool at C:\Users\Public\Documents\Embarcadero\Studio\14.0\PlatformSDKs\adt-bundle-windows-x86-20131030\sdk.

Run dx with the --dex parameter, the --output parameter with the output path of the classes.dex file as its argument, and a space-separated list of paths to the JAR files that you want to include in the generated classes.dex file. For example:

dx --dex --output="classes.dex" "C:\Path\To\Library1.jar" "C:\Path\To\Library2.jar"
Note: You should create both a debug and a release version of your classes.dex file. The RAD Studio debugging features are only available if the deployed classes.dex file contains the debug versions of the included RAD Studio built-in Java libraries.

Deploying the classes.dex File

Warning: Follow these steps carefully. Android applications must always include a valid classes.dex file. For more information, see Invalid or Missing classes.dex File below.

To configure your Android application to be deployed with your custom classes.dex file:

  1. Select Project > Deployment to open the Deployment Manager.
  2. Uncheck the checkbox of the default classes.dex file.
  3. Click the Add Files button and add your custom classes.dex file to the list of deployment files.
  4. Change the Remote Path of your new entry to classes\.
  5. Change the Platforms of your new entry to Android only.



Invalid or Missing classes.dex File

This is the error message that you see when you run an application on an Android device using RAD Studio and your application does not have a valid classes.dex file:

Unable to create process: Unable to install '<APK file>'. Failure [INSTALL_FAILED_DEXOPT]

An Android application package (APK file) must always contain a valid classes.dex file. That is:

  • There must be a classes.dex file in the APK file.
  • The classes.dex file must be located at classes/classes.dex within the APK file.
  • The classes.dex must be a valid Dalvik executable.

When you use a custom classes.dex file, you must be careful. After you unckeck the default classes.dex file on the Deployment Manager and you add an entry for your custom classes.dex file:

  • Make sure that the entry of your custom file is checked.
  • Make sure that the Remote Path of your new entry is classes\.
  • Make sure that your new entry is your classes.dex file, and not a different file that may not be a valid Dalvik executable.

If your Android application is not configured to be deployed with a valid classes.dex file, and you run your application on an Android device from RAD Studio or install on your device an APK file of your application generated with RAD Studio, the installation will fail, but it will leave data in your Android device preventing you from installing applications with the same package name (see [[|]]) as your application.

After you attempt to install an APK file without a valid classes.dex file, the only know solution is to perform a factory reset of your Android device.

Warning: A factory reset removed all date from your device (personal data, custom settings, and more). Carefully consider whether fixing the issue is worth losing your data. If you decide to go forward, remember to back up your data before you perform the factory reset.

See Also