Creating and Deploying a classes.dex File Manually

From RAD Studio
Jump to: navigation, search

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

Creating and deploying a classes.dex file manually allows you not only to add libraries to your application, but also to modify the built-in RAD Studio Java libraries for Android, or remove those that you do not need. If you just need to add a custom Java library to your application for Android, see Adding A Java Library to Your Application Using the Project Manager.

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\23.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 in 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\23.0\CatalogRepository\AndroidSDK-<Version>.

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 as your application (see Android Version Info).

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