Migrating to Android Studio

Migrating from Eclipse ADT to Android Studio requires adapting to a new project structure, build system, and IDE functionality. To simplify the migration process, Android Studio provides an import tool so you can quickly transition your Eclipse ADT workspaces and Ant build scripts to Android Studio projects and Gradle-based build files.

This document provides an overview of the migration process and walks you through a sample import procedure. For more information about Android Studio features and the Gradle-based build system, see Android Studio Overview and Configuring Gradle Builds.

Migration Overview

Migrating from Eclipse to Android Studio requires that you change the structure of your development projects, move to a new build system, and use a new user interface. Here are some of the key changes you should be aware of as you prepare to migrate to Android Studio:

• Project files

  Android Studio uses a different project structure. Each Eclipse ADT project is called a module in Android Studio. Each instance of Android Studio contains a project with one or more app modules. For more information see, Project Structure.

• Manifest settings

  Several elements in the AndroidManifest.xml file are now properties in the defaultConfig and productFlavors blocks in the build.gradle file. These elements are still valid manifest entries and may appear in manifests from older projects, imported projects, dependencies, and libraries. For more information see, Manifest Settings.

• Dependencies

  Library dependencies are handled differently in Android Studio, using Gradle dependency declarations and Maven dependencies for well-known local source and binary libraries with Maven coordinates. For more information see, Dependencies

• Test code

  With Eclipse ADT, test code is written in separate projects and integrated through the <instrumentation> element in your manifest file. Android Studio provides a AndroidTest folder within your project so you can easily add and maintain your test code within the same project view. JUnit tests can also be configured to run locally to reduce testing cycles.

• Gradle-based build system

  In place of XML-based Ant build files, Android Studio supports Gradle build files, which use the Gradle Domain Specific Language (DSL) for ease of extensibility and customization. The Android Studio build system also supports build variants, which are combinations of productFlavor and buildTypes, to customize your build outputs.

• User interface

  Android Studio provides an intuitive interface and menu options based on the IntelliJ IDEA IDE. To become familiar with the IDE basics, such as navigation, code completion, and keyboard shortcuts, see IntelliJ IDEA Quick Start Guide.

• Developer tools versioning

  Android Studio updates independently of the Gradle-based build system so different build settings can be applied across different versions of command line, Android Studio, and continuous integration builds. For more information, see Configuring Gradle Builds.

Migration Prerequisites

Before migrating your Eclipse ADT app to Android Studio, review the following steps to make sure your project is ready for conversion, and verify you have the tool configuration you need in Android Studio:

• In Eclipse ADT:
  • Make sure the Eclipse ADT root directory contains the AndroidManifest.xml file. Also, the root directory must contain either the .project and .classpath files from Eclipse or the res/ and src/ directories.
  • Build your project to ensure your latest workspace and project updates are saved and included in the import.
  • Comment out any references to Eclipse ADT workspace library files in the project.properties or .classpath files for import. You can add these references in the build.gradle file after the import. For more information, see Configuring Gradle Builds.
  • It may be useful to record your workspace directory, path variables, and any actual path maps that could be used to specify any unresolved relative paths, path variables, and linked resource references. Android Studio allows you to manually specify any unresolved paths during the import process.
• In Android Studio:
  • Make a note of any third-party Eclipse ADT plugins in use and check for equivalent features in Android Studio or search for a compatible plugin in the IntelliJ Android Studio Plugins repository. Use the File > Settings > Plugins menu option to manage plugins in Android Studio. Android Studio does not migrate any third-party Eclipse ADT plugins.
  • If you plan to run Android Studio behind a firewall, be sure to set the proxy settings for Android Studio and the SDK Manager. Android Studio requires an internet connection for Setup Wizard synchronization, 3rd-party library access, access to remote repositories, Gradle initialization and synchronization, and Android Studio version updates. For more information, see Proxy Settings.
  • Use the File > Settings > System Settings menu option to verify the current version and, if necessary, update Android Studio to the latest version from the stable channel. To install Android Studio, please visit the Android Studio download page.

Importing Projects to Android Studio

Android Studio provides a function for importing Eclipse ADT projects, which creates a new Android Studio project and app modules based on your current Eclipse ADT workspace and projects. No changes are made to your Eclipse project files. The Eclipse ADT workspace becomes a new Android Studio project, and each Eclipse ADT project within the workspace becomes a new Android Studio module. Each instance of Android Studio contains a project with one or more app modules.

After selecting an Eclipse ADT project to import, Android Studio creates the Android Studio project structure and app modules, generates the new Gradle-based build files and settings, and configures the required dependencies. The import options also allow you to enter your workspace directory and any actual path maps to handle any unresolved relative paths, path variables, and linked resource references.

Depending on the structure of your Eclipse ADT development project, you should select specific files for importing:

• For workspaces with multiple projects, select the project folder for each Eclipse ADT project individually to import the projects into the same Android Studio project. Android Studio combines the Eclipse ADT projects into a single Android Studio project with different app modules for each imported project.
• For Eclipse ADT projects with separate test projects, select the test project folder for import. Android Studio imports the test project and then follows the dependency chain to import the source project and any project dependencies.
• If Eclipse ADT projects share dependencies within the same workspace, import each project individually into Android Studio. Android Studio maintains the shared dependencies across the newly created modules as part of the import process.

To import a project to Android Studio:

1. Start Android Studio and close any open Android Studio projects.
2. From the Android Studio menu select File > New > Import Project.

   Alternatively, from the Welcome screen, select Import project (Eclipse ADT, Gradle, etc.).

3. Select the Eclipse ADT project folder with the AndroidManifest.xml file and click Ok.

   

4. Select the destination folder and click Next.

   

5. Select the import options and click Finish.

   The import process prompts to migrate any library and project dependencies to Android Studio, and add the dependency declarations to the build.gradle file. The import process also replaces any well-known source libraries, binary libraries, and JAR files that have known Maven coordinates with Maven dependencies, so you no longer need to maintain these dependencies manually. The import options also allow you to enter your workspace directory and any actual path maps to handle any unresolved relative paths, path variables, and linked resource references.

   

6. Android Studio imports the app and displays the project import summary. Review the summary for details about the project restructuring and the import process.

   

After importing the project from Eclipse ADT to the new Android Studio project and module structure, each app module folder in Android Studio contains the complete source set for that module, including the src/main and src/androidTest directories, resources, build file, and Android manifest. Before starting app development, you should resolve any issues shown in the project import summary to make sure the project re-structuring and import process completed properly.

Validating imported projects

After completing the import process, use the Android Studio Build and Run menu options to build your project and verify the output. If your project is not building properly, check the following settings:

• Use the Android SDK button in Android Studio to launch the SDK Manager and verify the installed versions of SDK tools, build tools, and platform match the settings for your Eclipse ADT project. Android Studio inherits the SDK Manager and JDK settings from your imported Eclipse project.
• Use the File > Project Structure menu option to verify additional Android Studio settings:
  • Under SDK Location verify Android Studio has access to the correct SDK and JDK locations and versions.
  • Under Project verify the Gradle version, Android Plugin version, and related repositories.
  • Under Modules verify the app and module settings, such as signing configuration and library dependencies.
• If your project depends on another project, make sure that dependency is defined properly in the build.gradle file in the app module folder.

If there still are unexpected issues when building and running your project in Android Studio after you have checked these settings, consider modifying the Eclipse ADT project and re-starting the import process. Importing an Eclipse ADT project to Android Studio creates a new Android Studio project and does not impact the existing Eclipse ADT project.

To get started using Android Studio, review the Android Studio features and Gradle-based build system to become familiar with the new project and module structure, flexible build settings, and other advanced Android development capabilities. For a comparison of Eclipse ADT and Android Studio features and usage, see Transitioning to Android Studio from Eclipse. For specific Android Studio how-to documentation, see the pages in the Workflow section.