docs/html/tools/building/building-studio.jd

page.title=Building and Running from Android Studio
parent.title=Building and Running
parent.link=index.html
@jd:body

<div id="qv-wrapper">
  <div id="qv">
    <h2>In this document</h2>
      <ol>
        <li>
          <a href="#run-configuration">Changing the run configuration</a>
        </li>

        <li>
          <a href="#changing-variant">Changing build variants</a>
        </li>

        <li>
          <a href="#gradle-console">Monitoring the build process</a>
        </li>

        <li>
          <a href="#generating-apks">Generating APKs</a>
        </li>

        <li>
          <a href="#instant-run">About Instant Run</a>
          <ol>
            <li>
              <a href="#set-up-ir">Configuring and optimizing your project for Instant Run</a>
            </li>

            <li>
              <a href="#ir-limitations">Limitations of Instant Run</a>
            </li>
          </ol>
        </li>
      </ol>

    <h2>See also</h2>
      <ol>
        <li><a href="{@docRoot}sdk/installing/studio-build.html">
          Build System</a></li>
        <li><a href="{@docRoot}tools/devices/managing-avds.html">
          Managing AVDs with AVD Manager</a></li>
        <li><a href="{@docRoot}tools/devices/emulator.html">
          Using the Android Emulator</a></li>
        <li><a href="{@docRoot}tools/device.html">
          Using Hardware Devices</a></li>
        <li><a href="{@docRoot}tools/publishing/app-signing.html">
          Signing Your Applications</a></li>
      </ol>
  </div>
</div>

<p>
  By default, Android Studio sets up new projects to deploy to the Emulator or
  a physical device with just a few clicks. With Instant Run, you can push
  changes to methods and existing app resources to a running app without
  building a new APK, so code changes are visible almost instantly.
</p>

<p>
  To build and run your app, click <strong>Run 'app'</strong> <img src=
  "{@docRoot}images/tools/as-run.png" alt="" style=
  "vertical-align:bottom;margin:0;">. Android Studio builds your app with
  Gradle, asks you to select a deployment target (an emulator or a connected
  device), and then deploys your app to it. You can customize some of this
  default behavior, such as selecting an automatic deployment target, by
  <a href="#run-configuration">changing the run configuration</a>.
</p>

<p>
  If you want to <a href="{@docRoot}tools/devices/emulator.html">use the Android
  Emulator</a> to run your app, you need to have an Android Virtual Device
  (AVD) ready. If you haven't already created one, then after you click
  <strong>Run 'app'</strong>, click <strong>Create New Emulator</strong> in the
  <strong>Select Deployment Target</strong> dialog. Follow the Virtual Device
  Configuration wizard to define the type of device you want to emulate. For
  more information, see <a href=
  "{@docRoot}tools/devices/managing-avds.html">Managing AVDs with the AVD
  Manager</a>.
</p>

<p>
  If you're using a physical Android device, you need to enable USB debugging
  on the device. For more information, see <a href=
  "{@docRoot}tools/device.html">Using Hardware Devices</a>.
</p>

<p class="note">
  <strong>Note:</strong> You can also deploy your app in debug mode by clicking
  <strong>Debug 'app'</strong> <img src=
  "{@docRoot}images/tools/as-debugbutton.png" alt="" style=
  "vertical-align:bottom;margin:0;">. Running your app in debug mode
  allows you to set breakpoints in your code, examine variables and evaluate
  expressions at run time, and run debugging tools. To learn more, read about
  <a href="{@docRoot}tools/debugging/debugging-studio.html">Debugging with
  Android Studio</a>.
</p>

<h3 id="run-configuration">
  Changing the run configuration
</h3>

<p>
  The run configuration specifies the module to run, package to deploy,
  activity to start, target device, emulator settings, and Logcat options. The
  default run configuration launches the default project activity and uses the
  <strong>Device Chooser</strong> for target device selection. If the default
  settings don't suit your project or module, you can customize the run
  configuration, or even create a new one, at the project, default, and module
  levels. To edit a run configuration:
</p>

<ol>
  <li>Select <strong>Run</strong> &gt; <strong>Edit Configurations</strong>.
  </li>

  <li>Expand the <strong>Android Application</strong> item and select an
  existing run configuration.
    <ul>
      <li>To create a new run configuration, click the '<strong>+</strong>'
      button in the top left corner of the dialog box and select
      <strong>Android Application</strong>.
      </li>
    </ul>
  </li>

  <li>With a run configuration selected, adjust your desired settings. For
  example, in the <strong>General</strong> tab, you can specify the APK
  installation settings, launch options, and deployment target options.
  </li>
</ol>

<h3 id="changing-variant">
  Changing the build variant
</h3>

<p>
  By default, Android Studio builds the debug version of your app, which is
  intended only for testing, when you click <strong>Run 'app'</strong>. You
  need to build the release version when <a href=
  "{@docRoot}tools/publishing/preparing.html">preparing your app for public
  release</a>.
</p>
<p>
  To change the build variant Android Studio uses, go to <strong>Build</strong>
  &gt; <strong>Select Build Variant</strong> and select a different one from
  the drop-down menu. By default, new projects are set up with a debug and
  release build variant.
</p>

<p>
  Using <em>product flavors</em>, you can create additional build variants for
  different versions of your app, each having different features or device
  requirements. To learn more about build variants and product flavors, read
  <a href="{@docRoot}tools/building/configuring-gradle.html">Configuring Gradle
  Builds</a>.
</p>

<h3 id="gradle-console">
  Monitoring the build process
</h3>

<p>
  You can view details about the build process by clicking <strong>Gradle
  Console</strong> <img src="{@docRoot}images/tools/as-gradlebutton.png" alt=""
  style="vertical-align:bottom;margin:0;">. The console displays each
  task that Gradle executes in order to build your app, as shown in figure 1.
</p>

<img src="{@docRoot}images/tools/studio-gradle-console.png" alt="">
<p class="img-caption">
  <strong>Figure 1.</strong> The Gradle Console in Android Studio.
</p>

<p>
  If your build variants use product flavors, Gradle also invokes tasks to
  build those product flavors. To view the list of all available build tasks,
  click <strong>Gradle</strong> <img src=
  "{@docRoot}images/tools/as-gradle.png" alt="" style=
  "vertical-align:bottom;margin:0;"> on the right side of the IDE
  window.
</p>

<p>
  If an error occurs during the build process, the <em>Messages</em> window
  appears to describe the issue. Gradle may recommend some command-line
  options to help you resolve the issue, such as <code>--stacktrace</code> or
  <code>--debug</code>. To use command-line options with your build process:
</p>

<ol>
  <li>Open the <strong>Settings</strong> or <strong>Preferences</strong>
  dialog:
    <ul>
      <li>On Windows or Linux, select <strong>File</strong> &gt;
      <strong>Settings</strong> from the main menu.
      </li>

      <li>On Mac OSX, select <strong>Android Studio</strong> &gt;
      <strong>Preferences</strong> from the main menu.
      </li>
    </ul>
  </li>

  <li>Navigate to <strong>Build, Execution, Deployment</strong> &gt;
  <strong>Compiler</strong>.
  </li>

  <li>In the text field next to <em>Command-line Options</em>, enter your
  command-line options.
  </li>

  <li>Click <strong>OK</strong> to save and exit.
  </li>
</ol>

<p>
  Gradle will apply these command-line options the next time you try building
  your app.
</p>

<h3 id="generating-apks">
  Generating APKs
</h3>

<p>
  When you click <strong>Run 'app'</strong>, Android Studio generates a debug
  APK and deploys it to your target device. Before you can generate a release
  version of your app for public distribution, however, you must first learn
  how to <a href="{@docRoot}tools/publishing/app-signing.html#studio">sign your
  app</a>. You can then generate multiple signed APKs of your debug or release
  build variants. To locate the generated APK files, click the link in the
  pop-up dialog, as shown in figure 2.
</p>

<p>
  <img src="{@docRoot}images/tools/as-find-apk.png" alt="">
</p>

<p class="img-caption">
  <strong>Figure 2.</strong> Click the link to locate the generated APK
  files.
</p>

<h2 id="instant-run">About Instant Run</h3>

<p>
  Introduced in Android Studio 2.0, Instant Run is a behavior for the
  <strong>Run</strong> <img src="{@docRoot}images/tools/as-run.png" alt=""
  style="vertical-align:bottom;margin:0;"> and <strong>Debug</strong> <img src=
  "{@docRoot}images/tools/as-debugbutton.png" alt="" style=
  "vertical-align:bottom;margin:0;"> commands that significantly reduces the
  time between updates to your app. Although your first build may take longer
  to complete, Instant Run pushes subsequent updates to your app without
  building a new APK, so changes are visible much more quickly.
</p>

<p>
  Instant Run is supported only when you deploy the debug build variant, use
  Android Plugin for Gradle version 2.0.0 or higher, and set
  <code>minSdkVersion</code> to 15 or higher in your app's module-level
  <code>build.gradle</code> file. For the best performance, set
  <code>minSdkVersion</code> to 21 or higher.
</p>

<p>
  After deploying an app, a small, yellow thunderbolt icon appears within the
  <strong>Run</strong> <img src=
  "{@docRoot}images/tools/instant-run/as-irrun.png" alt="" style=
  "vertical-align:bottom;margin:0;"> button (or <strong>Debug</strong>
  <img src="{@docRoot}images/tools/instant-run/as-irdebug.png" alt="" style=
  "vertical-align:bottom;margin:0;"> button), indicating that Instant Run is
  ready to push updates the next time you click the button. Instead of building
  a new APK, it pushes just those new changes and, in some cases, the app
  doesn't even need to restart but immediately shows the effect of those code
  changes.
</p>

<p>
  Instant Run pushes updated code and resources to your connected device or
  emulator by performing a <em>hot swap</em>, <em>warm swap</em>, or <em>cold
  swap</em>. It automatically determines the type of swap to perform based on
  the type of change you made. The following table describes how Instant Run
  behaves when you push certain code changes to a target device.
</p>

<table id="ir-table">
  <col width="40%">
  <tr>
    <th scope="col">
      Code Change
    </th>
    <th scope="col">
      Instant Run Behavior
    </th>
  </tr>

  <tr id="hot-swap">
    <td>
      <ul>
        <li>Change implementation code of an existing method
        </li>
      </ul>
    </td>
    <td>
      <p>
        Supported with <strong>hot swap</strong>: This is the
        fastest type of swap and makes changes visible much more quickly. Your
        application keeps running and a stub method with the new implementation is used
        the next time the method is called.
      </p>

      <p>
        Hot swaps do not re-initialize objects in your running app. You may need to
        restart the current activity, or <a href="#rerun">restart the app</a>, before
        you see certain updates. By default, Android Studio automatically restarts the
        current activity after performing a hot swap. If you do not want this behavior,
        you can <a href="#activity-restart">disable automatic activity restarts</a>.
      </p>
    </td>
  </tr>

  <tr id="warm-swap">
    <td>
      <ul>
        <li>Change or remove an existing resource
        </li>
      </ul>
    </td>
    <td>
      Supported with <strong>warm swap</strong>: This swap
      is still very fast, but Instant Run must restart the current activity when it
      pushes the changed resources to your app. Your app keeps running, but a small
      flicker may appear on the screen as the activity restarts—this is normal.
    </td>
  </tr>

  <tr id="cold-swap">
    <td>
      Structural code changes, such as:
      <ul>
        <li>Add, remove, or change:
          <ul>
            <li>an annotation
            </li>

            <li>an instance field
            </li>

            <li>a static field
            </li>

            <li>a static method signature
            </li>

            <li>an instance method signature
            </li>
          </ul>
        </li>

        <li>Change which parent class the current class inherits from
        </li>

        <li>Change the list of implemented interfaces
        </li>

        <li>Change a class's static initializer
        </li>

        <li>Reorder layout elements that use dynamic resource IDs
        </li>
      </ul>
    </td>
    <td>
      <p>
        Supported with <strong>cold swap</strong> (API level 21 or higher): This swap
        is a bit slower because, although a new APK is not required, Instant Run must
        restart the whole app when it pushes structural code changes.
      </p>

      <p>
        For target devices running API level 20 or lower, Android Studio
        deploys a full APK.
      </p>
    </td>
  </tr>

  <tr>
    <td>
      <ul>
        <li>Change the app manifest
        </li>

        <li>Change resources reference by the app manifest
        </li>

        <li>Change an Android widget UI element (requires a <a href="#rerun">
          Clean and Rerun</a>)
        </li>
      </ul>
    </td>
    <td>
      <p>
        When making changes to the app's manifest or resources referenced by the
        manifest, Android Studio automatically <strong>deploys a new build</strong>
        in order to apply these changes. This is because certain information about
        the app, such as its name, app icon resources, and intent filters, are
        determined from the manifest when the APK is installed on the device.
      </p>

      <p>
        If your build process automatically updates any part of the app manifest,
        such as automatically iterating <code>versionCode</code> or
        <code>versionName</code>, you will not be able to benefit from the full
        performance of Instant Run. We recommend that you disable automatic updates
        to any part in the app manifest in your debug build variants.
      </p>
    </td>
  </tr>
</table>

<p class="note">
  <strong>Note:</strong> If you need to restart your app after a crash, do not
  launch it from your target device. Restarting your app from your target
  device does not apply any of your code changes since the last cold swap or
  <em>incremental build</em>. To launch your app with all your recent changes,
  click <strong>Run</strong> <img src="{@docRoot}images/tools/as-run.png" alt=
  "" style="vertical-align:bottom;margin:0;"> (or <strong>Debug</strong>
  <img src="{@docRoot}images/tools/as-debugbutton.png" alt="" style=
  "vertical-align:bottom;margin:0;">) from Android Studio.
</p>

<h4 id="rerun">
  Using Rerun
</h4>

<p>
  When pushing code changes that affect certain initializers, such as changes
  to an app's {@link android.app.Application#onCreate onCreate()} method, you
  need to restart your app for the changes to take effect. To perform an
  <em>incremental build</em> and restart the app, click <strong>Rerun</strong>
  <img src="{@docRoot}images/tools/as-restart.png" alt="" style=
  "vertical-align:bottom;margin:0;">.
</p>

<p>
  If you need to deploy a <em>clean build</em>, select <strong>Run</strong>
  &gt; <strong>Clean and Rerun 'app'</strong> <img src=
  "{@docRoot}images/tools/as-cleanrerun.png" alt="" style=
  "vertical-align:bottom;margin:0;"> from the main menu, or hold down the
  <strong>Shift</strong> key while clicking <strong>Rerun</strong> <img src=
  "{@docRoot}images/tools/as-restart.png" alt="" style=
  "vertical-align:bottom;margin:0;">. This action stops the running app,
  performs a full clean build, and deploys the new APK to your target device.
</p>

<h4 id="activity-restart">
  Disabling automatic activity restart
</h4>

<p>
  When performing a hot swap, your app keeps running but Android Studio
  automatically restarts the current activity. To disable this default setting:
</p>

<ol>
  <li>Open the <strong>Settings</strong> or <strong>Preferences</strong>
  dialog:
    <ul>
      <li>On Windows or Linux, select <strong>File</strong> &gt;
      <strong>Settings</strong> from the main menu.
      </li>

      <li>On Mac OSX, select <strong>Android Studio</strong> &gt;
      <strong>Preferences</strong> from the main menu.
      </li>
    </ul>
  </li>

  <li>Navigate to <strong>Build, Execution, Deployment</strong> &gt;
  <strong>Instant Run</strong>.
  </li>

  <li>Uncheck the box next to <strong>Restart activity on code
  changes</strong>.
  </li>
</ol>

<p>
  If automatic activity restart is disabled, you can manually restart the current
  activity from the menu bar by selecting <strong>Run</strong> &gt; <strong>Restart
  Activity</strong>.
</p>

<h3 id="set-up-ir">
  Configuring and optimizing your project for Instant Run
</h3>

<p>
  Android Studio enables Instant Run by default for projects built using
  Android Plugin for Gradle 2.0.0 and higher.
</p>

<p>
  To update an existing project with the latest version of the plugin:
</p>

<ol>
  <li>Open the <strong>Settings</strong> or <strong>Preferences</strong>
  dialog.
  </li>

  <li>
    <p>
      Navigate to <strong>Build, Execution, Deployment</strong> &gt;
      <strong>Instant Run</strong> and click <strong>Update Project</strong>,
      as shown in figure 3.
    </p>

    <p>
      If the option to update the project does not appear, it’s already
      up-to-date with the latest Android Plugin for Gradle.
    </p>

    <img src="{@docRoot}images/tools/instant-run/update-project-dialog.png"
    alt="" height="51">

    <p class="img-caption">
      <strong>Figure 3.</strong> Updating the Android Plugin for Gradle for an
      existing project.
    </p>
  </li>
</ol>

<p>
  You also need to <a href="#changing-variant">change the build variant</a> to
  a debug version of your app to start using Instant Run.
</p>

<h4 id="configure-dexoptions">
  Improve build times by configuring DEX resources
</h4>

<p>
  When you deploy a clean build, Android Studio instruments your app to allow
  Instant Run to push code and resource updates. Although updating the running
  app happens much more quickly, the first build may take longer to complete.
  You can improve the build process by configuring a few DEX options, such as
  <code>maxProcessCount</code> and <code>javaMaxHeapSize</code>.
</p>

<dl>
  <dt>
    <code>maxProcessCount</code>
  </dt>

  <dd>
    Sets the maximum number of DEX processes that can be started
    concurrently. If the Gradle daemon is already running, you need to
    stop the process before initializing it with a new maximum process count.
    You can terminate the Gradle daemon by calling one of the following from
    the <em>Terminal</em> window:
    <ul>
      <li>On Windows, call <code>gradlew --stop</code>
      </li>

      <li>On Linux/Mac OSX, call <code>./gradlew --stop</code>
      </li>
    </ul>
  </dd>

  <dt>
    <code>javaMaxHeapSize</code>
  </dt>

  <dd>
    Sets the maximum memory allocation pool size for the dex operation. When
    passing a value, you can append the letter 'k' to indicate kilobytes, 'm'
    to indicate megabytes, or 'g' to indicate gigabytes.
  </dd>
</dl>

<p>
  The following example sets <code>maxProcessCount</code> to 4 and
  <code>javaMaxHeapSize</code> to "2g" in the module-level
  <code>build.gradle</code> file:
</p>

<pre>
android {
  ...
  dexOptions {
    maxProcessCount 8
    javaMaxHeapSize "2g"
  }
}
</pre>

<p>
  You should experiment with these settings by incrementing their values and
  observing the effect on your build times. You could experience a negative
  impact to performance if you allocate too many resources to the DEX'ing process.
</p>

<h4 id="windows-defender">
  Excluding your project from Windows Defender
</h4>

<p>
  On Windows systems, Windows Defender may cause slowdowns while using Instant
  Run. If you are using Windows Defender, you should <a class="external-link"
  href=
  "http://answers.microsoft.com/en-us/protect/wiki/protect_defender-protect_scanning/how-to-exclude-a-filefolder-from-windows-defender/f32ee18f-a012-4f02-8611-0737570e8eee">
  exclude your Android Studio project folder from Windows Defender malware
  scans</a>.
</p>

<h4 id="crashlytics">
  Disabling Crashlytics for your debug build variant
</h4>

<p>
  Using Crashlytics is known to cause slower build times. To improve build
  performance while developing your app, you can <a class="external-link" href=
  "https://docs.fabric.io/android/crashlytics/build-tools.html#disabling-crashlytics-for-debug-builds">
  disable Crashlytics for your debug build variant</a>.
</p>

<h3 id="ir-limitations">
  Limitations of Instant Run
</h3>

<p>
  Instant Run is designed to speed up the build and deploy process in most
  situations. However, there are some aspects to using Instant Run that might
  affect its behavior and compatibility with your app. If you experience any
  other issues while using Instant Run, please <a class="external-link" href=
  "http://tools.android.com/filing-bugs">file a bug</a>.
</p>

<h4 id="multiple-devices">
  Deploying to multiple devices
</h4>

<p>
  Instant Run uses different techniques to perform hot, warm, and cold swaps
  that are specific to the API level of the target device. For this reason,
  while deploying an app to multiple devices at once, Android Studio
  temporarily turns off Instant Run.
</p>

<h4 id="ir-multidex">
  Multidexing your app
</h4>

<p>
  If your project is configured for <a href=
  "{@docRoot}tools/building/multidex.html#mdex-pre-l">Legacy Multidex</a>—that
  is, when <code>build.gradle</code> is configured with <code>multiDexEnabled
  true</code> and <code>minSdkVersion 20</code> or lower—and you deploy to
  target devices running Android 4.4 (API level 20) or lower, Android Studio
  disables Instant Run.
</p>

<p>
  If <code>minSdkVersion</code> is set to 21 or higher, Instant Run
  automatically configures your app for multidex. Because Instant Run only
  works with the debug version of your app, you may need to <a href=
  "{@docRoot}tools/building/multidex.html#mdex-gradle">configure your app for
  multidex</a> when deploying your release build variant.
</p>

<h4 id="instrumented-tests">
  Running instrumented tests and performance profilers
</h4>

<p>
  Instrumented tests load both the debug APK and a test APK into the same
  process on a test device, allowing control methods to override the normal
  lifecycle of the app and perform tests. While running or debugging
  instrumented tests, Android Studio does not inject the additional methods
  required for Instant Run and turns the feature off.
</p>

<p>
  While profiling an app, you should disable Instant Run. There is a small
  performance impact when using Instant Run and a slightly larger impact when
  overriding methods with a hot swap. This performance impact could interfere
  with information provided by performance profiling tools. Additionally, the
  stub methods generated with each hot swap can complicate stack traces.
</p>

<h4 id="plugins">
  Using third-party plugins
</h4>

<p>
  Android Studio temporarily disables the Java Code Coverage Library (JaCoCo)
  and ProGuard while using Instant Run. Because Instant Run only works with
  debug builds, this does not affect your release build.
</p>

<p>
  Certain third-party plugins that perform bytecode enhancement may cause
  issues with how Instant Run instruments your app. If you experience these
  issues, but want to continue using Instant Run, you should disable those
  plugins for your debug build variant. You can also help improve compatibility
  with third-party plugins by <a class="external-link" href=
  "http://tools.android.com/filing-bugs">filing a bug</a>.
</p>

<h4 id="multi-process-apps">
  Pushing changes to multi-process apps
</h4>

<p>
  Instant Run only instruments your app's main process in order to perform hot
  swaps and warm swaps. When pushing code changes to other app processes, such
  as changes to a method implementation or an existing resource, Instant Run
  performs a <a href="#cold-swap">cold swap</a>.
</p>

<h4 id="disable-ir">
  Disabling Instant Run
</h4>

<p>
  To disable Instant Run:
</p>

<ol>
  <li>Open the <strong>Settings</strong> or <strong>Preferences</strong>
  dialog.
  </li>

  <li>Navigate to <strong>Build, Execution, Deployment</strong> &gt;
  <strong>Instant Run</strong>.
  </li>

  <li>Uncheck the box next to <strong>Enable Instant Run</strong>.
  </li>
</ol>