Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit f895942d authored by smain@google.com's avatar smain@google.com Committed by Android (Google) Code Review
Browse files

Merge "docs: setup-virtual-device"

parents 690047f5 c56cd34d

docs/html/images/tools/as-avd-start.png

0 → 100644
+4.39 KiB
Loading image diff...

docs/html/images/ui/studio-avdmgr-icon.png

deleted100644 → 0
−546 B
Loading image diff...

docs/html/tools/devices/emulator.jd

+35 −35
Original line number Diff line number Diff line
@@ -160,7 +160,7 @@ href="{@docRoot}tools/devices/index.html">Managing Virtual Devices</a>.</p> 


<p>During development and testing of your application, you install and run your

application in the Android emulator. You can launch the emulator as a standalone

application from a command line, or you can run it from within your Eclipse

application from a command line, or you can run it from within your Android Studio

development environment. In either case, you specify the AVD configuration to

load and any startup options you want to use, as described in this document.

</p>
@@ -188,13 +188,13 @@ window. For more information about command line options for the emulator, see th 
instances of the emulator concurrently, each with its own AVD configuration and

storage area for user data, SD card, and so on.</p>



<p>If you are working in Eclipse, the ADT plugin for Eclipse installs your

application and starts the emulator automatically, when you run or debug

the application. You can specify emulator startup options in the Run/Debug

<p>When you run your app from Android Studio, it installs and launches the

app on your connected device or emulator (launching the emulator, if necessary).

You can specify emulator startup options in the Run/Debug

dialog, in the Target tab. When the emulator is running, you can issue

console commands as described later in this document.</p>



<p>If you are not working in Eclipse, see <a href="#apps">Installing Applications

<p>If you are not working in Android Studio, see <a href="#apps">Installing Applications

on the Emulator</a> for information about how to install your application.</p>



<p>To stop an emulator instance, just close the emulator's window.</p>
@@ -206,7 +206,7 @@ reference.</p> 


<h2 id="apps">Installing Applications on the Emulator</h2>



<p>If you don't have access to Eclipse or the ADT Plugin, you can install your application on the

<p>If you don't have access to Android Studio, you can install your application on the

emulator using the <a href="{@docRoot}tools/help/adb.html#move">adb</a> utility. Before

installing the application, you need to build and package it into an <code>.apk</code> as described

in <a href="{@docRoot}tools/building/index.html">Building and
@@ -287,16 +287,16 @@ option: 
Android 4.0.3 (API Level 15, revision 3) or higher system image target. Graphics acceleration is not

available for earlier system images.</p>

  </li>

  <li>If you are running the emulator from Eclipse, run your Android application using an AVD with

the {@code -gpu on} option enabled:

  <li>If you are running the emulator from Android Studio, run your Android application using an AVD

with the {@code -gpu on} option enabled:

    <ol>

      <li>In Eclipse, click your Android project folder and then select <strong>Run > Run

Configurations...</strong></li>

      <li>In the left panel of the <strong>Run Configurations</strong> dialog, select your Android

project run configuration or create a new configuration.</li>

      <li>Click the <strong>Target</strong> tab.</li>

      <li>Select the AVD you created in the previous procedure.</li>

      <li>In the <strong>Additional Emulator Command Line Options</strong> field, enter:<br>

      <li>In Android Studio, click your Android application module folder and then select

      <strong>Run > Edit Configurations...</strong></li>

      <li>In the left panel of the <strong>Run/Debug Configurations</strong> dialog, select your Android

      run configuration or create a new configuration.</li>

      <li>Under the <strong>Device Target</strong> options,

      select the AVD you created in the previous procedure.</li>

      <li>In the <strong>Additional Command Line Options</strong> field, enter:<br>

        {@code -gpu on}</li>

      <li>Run your Android project using this run configuration.</li>

    </ol>
@@ -414,15 +414,15 @@ SERVICE_NAME: intelhaxm 
    <p class="note"><strong>Note:</strong> You must provide an x86-based AVD configuration

name, otherwise VM acceleration will not be enabled.</p>

  </li>

  <li>If you are running the emulator from Eclipse, run your Android application with an x86-based

  <li>If you are running the emulator from Android Studio, run your Android application with an x86-based

AVD:

    <ol>

      <li>In Eclipse, click your Android project folder and then select <strong>Run > Run

      <li>In Android Studio, click your Android project folder and then select <strong>Run > Edit

Configurations...</strong></li>

      <li>In the left panel of the <strong>Run Configurations</strong> dialog, select your Android

project run configuration or create a new configuration.</li>

      <li>Click the <strong>Target</strong> tab.</li>

      <li>Select the x86-based AVD you created previously.</li>

      <li>In the left panel of the <strong>Run/Debug Configurations</strong> dialog, select your Android

run configuration or create a new configuration.</li>

      <li>Under the <strong>Device Target</strong> options, select the x86-based AVD you created

previously.</li>

      <li>Run your Android project using this run configuration.</li>

    </ol>

  </li>
@@ -467,15 +467,15 @@ opening a terminal window and running the following command: 
    <p class="note"><strong>Note:</strong> You must provide an x86-based AVD configuration

name, otherwise VM acceleration will not be enabled.</p>

  </li>

  <li>If you are running the emulator from Eclipse, run your Android application with an x86-based

  <li>If you are running the emulator from Andriod Studio, run your Android application with an x86-based

AVD:

    <ol>

      <li>In Eclipse, click your Android project folder and then select <strong>Run > Run

      <li>In Android Studio, click your Android module folder and then select <strong>Run > Edit

Configurations...</strong></li>

      <li>In the left panel of the <strong>Run Configurations</strong> dialog, select your Android

project run configuration or create a new configuration.</li>

      <li>Click the <strong>Target</strong> tab.</li>

      <li>Select the x86-based AVD you created previously.</li>

      <li>In the left panel of the <strong>Run/Debug Configurations</strong> dialog, select your Android

run configuration or create a new configuration.</li>

      <li>Under the <strong>Device Target</strong> options,

      select the x86-based AVD you created previously.</li>

      <li>Run your Android project using this run configuration.</li>

    </ol>

  </li>
@@ -513,16 +513,16 @@ AVD and include the KVM options: 
    <p class="note"><strong>Note:</strong> You must provide an x86-based AVD configuration

name, otherwise VM acceleration will not be enabled.</p>

  </li>

  <li>If you are running the emulator from Eclipse, run your Android application with an x86-based

  <li>If you are running the emulator from Android Studio, run your Android application with an x86-based

AVD and include the KVM options:

    <ol>

      <li>In Eclipse, click your Android project folder and then select <strong>Run > Run

      <li>In Android Studio, click your Android module folder and then select <strong>Run > Edit

Configurations...</strong></li>

      <li>In the left panel of the <strong>Run Configurations</strong> dialog, select your Android

project run configuration or create a new configuration.</li>

      <li>Click the <strong>Target</strong> tab.</li>

      <li>Select the x86-based AVD you created previously.</li>

      <li>In the <strong>Additional Emulator Command Line Options</strong> field, enter:

      <li>In the left panel of the <strong>Run/Debug Configurations</strong> dialog, select your Android

run configuration or create a new configuration.</li>

      <li>Under the <strong>Device Target</strong> options, select the x86-based AVD you created

previously.</li>

      <li>In the <strong>Additional Command Line Options</strong> field, enter:

        <pre>-qemu -m 512 -enable-kvm</pre>

      </li>

      <li>Run your Android project using this run configuration.</li>
@@ -721,7 +721,7 @@ in the AVD directory, or in a custom location (if you specified a path with the 
  <td>Override using <code>-data &lt;filepath&gt;</code>, where <code>&lt;filepath&gt;</code> is the

path the image, relative to the current working directory. If you supply a filename only,

the emulator looks for the file in the current working directory. If the file at <code>&lt;filepath&gt;</code> does

not exist, the emulator creates an image from the default userdata.img, stores it under the name you

not exist, the emulator creates an image from the default <code>userdata.img</code>, stores it under the name you

specified, and persists user data to it at shutdown. </td>

</tr>

docs/html/tools/devices/managing-avds.jd

+102 −96
Original line number Diff line number Diff line
@@ -10,100 +10,110 @@ parent.link=index.html 
      <ol>

        <li><a href="#createavd">Creating an AVD</a>

          <ol>

            <li><a href="#CreateDefinition">Creating a device definition</a></li>

            <li><a href="#hardwareopts">Hardware options</a></li>

          </ol>

        </li>

        <li><a href="#skins">Creating Emulator Skins</a></li>

      </ol>

    </div>

  </div>



  <p>The AVD Manager is an easy to use user interface to manage your AVD (Android Virtual Device)

  configurations. An AVD is a device configuration for the Android emulator that allows you to

  model different configurations of Android-powered devices. When you start the AVD Manager in Android

  Studio or navigate to your SDK's {@code tools/} directory and execute

  <code>android avd</code>, you will see the AVD Manager main screen with your current virtual

  devices. You can right-click an existing AVD to perform actions on the AVD, such as delete,

  duplicate, wipe data, show on disk, and display details. </p>

  <p>The AVD Manager is a tool you can use

  to create and manage Android virtual devices (AVDs), which define device configurations

  for the <a href="{@docRoot}tools/devices/emulator.html"

  >Android Emulator</a>.</p>



   <img src="{@docRoot}images/studio-avdmgr-firstscreen.png" alt="">

   <p class="img-caption"><strong>Figure 1.</strong> AVD Manager.</p>

<p>To launch the AVD Manager:</p>

<ul>

  <li>In Android Studio, select <strong>Tools &gt; Android &gt; AVD Manager</strong>, or click

  the AVD Manager icon <img src="{@docRoot}images/tools/avd-manager-studio.png"

  style="vertical-align:bottom;margin:0;height:19px"> in the toolbar.</li>



  <li>Or, use the command line to navigate to your SDK's <code>tools/</code> directory and execute:

  <pre class="no-prettyprint classic">$ android avd</pre>

  </li>

</ul>



  <h2 id="createavd">Creating an AVD</h2>

  <p>The AVD Manager main screen shows your current virtual devices, as shown in figure 1.</p>



  <p>You can create as many AVDs as you would like to test on. It is recommended that you test your

  applications on all API levels higher than the target API level for your application.</p>



  <p>To create an AVD:</p>

   <img src="{@docRoot}images/studio-avdmgr-firstscreen.png" alt="">

   <p class="img-caption"><strong>Figure 1.</strong> The AVD Manager main screen shows your current

   virtual devices.</p>



  <ol>

    <li>Start the AVD Manager:



      <ul>

        <li>In Android Studio: select <strong>Tools &gt; Android &gt; AVD Manager</strong>, or click

        the AVD Manager icon <img src="{@docRoot}images/ui/studio-avdmgr-icon.png"style="vertical-align:bottom;margin:0;height:19px"> in the Android Studio toolbar.</li>

<p class="note"><strong>Note:</strong> If you launch the AVD Manager from the command line, the UI

is different than how it appears in Android Studio, as documented here. Most of the same

functionality is available, but the command-line version of the AVD Manager

is currently not documented.</p>





        <li>In other IDEs: Navigate to your SDK's <code>tools/</code> directory and execute the

        <code>android</code> tool with no arguments.</li>

      </ul>

    </li>

  <h2 id="createavd">Creating an AVD</h2>



    <li><p>Click <strong>Create Virtual Device</strong> to create an AVD. The

    <strong>Select Hardware</strong> dialog appears.</p>

  <p>You can create as many AVDs as you would like to use with the Android Emulator.

  To effectively test your app, you should create an AVD that models each device type for which

  you have designed your app to support. For instance, you should create an AVD for each

  API level equal to and higher than the minimum version you've specified in your manifest

  <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html" style="white-space: nowrap;"

  >{@code &lt;uses-sdk>}</a> tag.</p>



      <img src="{@docRoot}images/studio-avdmgr-selecthdwr.png">

      <p class="img-caption"><strong>Figure 2.</strong> Select Hardware window.</p>

    </li>

  <p>To create an AVD based on an existing device definition:</p>



    <li><p>Select the device category and form factor. Click <strong>Edit Device</strong> to modify

    an existing AVD, or click <strong>New Hardware Profile</strong> to create a new hardware profile.

    Click <strong>Next</strong> to continue. </p>

    <p>The hardware profile includes settings for screen size, camera, memory options,input type,

    and sensors. For a list of hardware features, see <a href="#hardwareopts">Hardware options</a>.</p>

  <ol>

    <li>From the main screen (figure 1), click <strong>Create Virtual Device</strong>.</li>



      <img src="{@docRoot}images/studio-avdmgr-confighardwareprof.png" alt="">

      <p class="img-caption"><strong>Figure 3.</strong> Configure Hardware window.</p>

    </li>

    <li><p>In the Select Hardware window, select a device configuration, such as Nexus 6,

    then click <strong>Next</strong>.</p>



    <li>Select the desired system image.  Click <strong>Install Latest Version</strong> to download

    a new system image. Click <strong>Next</strong> to continue.

      <img src="{@docRoot}images/studio-avdmgr-selecthdwr.png" alt="">

      <p class="img-caption"><strong>Figure 2.</strong> The Select Hardware window.</p>

    </li>

    <li>Select the desired system version for the AVD and click <strong>Next</strong>.

    </li>

    <li>Verify the configuration settings, then click <strong>Finish</strong>.

    <p>If necessary, click <strong>Show Advanced Settings</strong> to select a custom skin

      for the hardware profile and adjust other hardware settings.</p>

    </li>

  </ol>



    <li>Fill in the details for the AVD.

  <p>To launch the AVD in the Android Emulator, click the launch button

  <img src="{@docRoot}images/tools/as-avd-start.png"

  style="vertical-align:bottom;margin:0;height:19px">

   in the list of AVDs.</p>



      <p>Give it a name, device type, platform target, image size, orientation, and emulator

      performance. Click <strong>Show Advanced Settings</strong> to assign a custom skin to the

      hardware profile and other advanced settings for the device type.

      </p>



      <p class="note"><strong>Tip:</strong>Store custom skins in an easily accessible directory,

      such as <em>~/skins</em>. From information about custom skins, see

      <a href="#skins">Skins</a>. </p>

<h3 id="CreateDefinition">Creating a device definition</h3>



<p>In case the available device definitions do not match the device type you'd like to emulate,

you can create a custom device definition for your AVD:</p>

<ol>

  <li>From the main screen (figure 1), click <strong>Create Virtual Device</strong>.</li>

  <li>To begin you custom device by using an existing device profile as a template, select

  a device profile then click <strong>Clone Device</strong>.

  <p>Or, to start from scratch, click <strong>New Hardware Profile</strong>.</p>

  </li>

  <li>

<p>The following Configure Hardware Profile window (figure 3) allows you to specify various

configurations such as the screen size, memory options, input type, and sensors.</p>



      <img src="{@docRoot}images/studio-avdmgr-configavd.png" alt="">

      <p class="img-caption"><strong>Figure 4.</strong> Configure AVD window.</p>

    <p>When you're done configuring the device, click <strong>Finish</strong>.</p>



      <p class="note"><strong>Tip:</strong> Be sure to define a target for your AVD that satisfies

      your application's Build Target (the AVD platform target must have an API Level equal to or

      greater than the API Level that your application compiles against).</p>

      <img src="{@docRoot}images/studio-avdmgr-confighardwareprof.png" alt="">

      <p class="img-caption"><strong>Figure 3.</strong> The Configure Hardware window when

      creating a custom device configuration.</p>

    </li>

  <li>Your custom device configuration is now available in the list of device definitions

  (shown after you click <strong>Create Virtual Device</strong>). To continue preparing an AVD

  with your custom device configuration, select the new configuration and follow the instructions

  above to create an AVD with an existing device definition (and select your new definition).</li>



    <li>Click <strong>Finish</strong>.</li>

  </ol>



  <p>Your AVD is now ready and you can either close the AVD Manager, create more AVDs, or

  manage an emulator with the AVD by clicking an icon in the <strong>Actions</strong> column:

  </p>



  <ul>

    <li>Start an AVD <img src="{@docRoot}images/tools/studio-avdmgr-action-icon.png" alt=""></li>

    <li>Edit an AVD <img src="{@docRoot}images/tools/studio-avdmgr-actions-edit-icon.png" alt=""></li>

    <li>Perform management actions <img src="{@docRoot}images/tools/studio-avdmgr-actions-dropdown-icon.png" alt=""></li>

  </ul>





<h3 id="hardwareopts">Hardware options</h3>



<p>If you are creating a new AVD, you can specify the following hardware options for the AVD

to emulate:</p>
@@ -264,28 +274,31 @@ to emulate:</p> 
  </table>





<h3 id="skins">Using Custom Emulator Skins</h3>

<p>A custom Android emulator skin is a collection of files that enable you to customize the visual

and control elements of an emulator display. Custom emulator skins enable you to define variations

of emulation properties, such as the use of a trackball or touchscreen, to match your device

customizations. Each custom emulator skin contains:</p>

<h2 id="skins">Creating Emulator Skins</h2>



<p>An Android emulator skin is a collection of files that define the visual and control elements of

an emulator display. If the skin definitions available in the AVD settings don't meet your needs,

you can create your own custom skin definition, then apply it to your AVD from the

advanced settings on the Verify Configuration screen.</p>



<p>Each emulator skin contains:</p>

   <ul>

      <li>A <code>hardware.ini file</code> for initialization settings</li>

      <li>A <code>hardware.ini</code> file</li>

      <li>Layout files for supported orientations (landscape, portrait) and physical configuration</li>

      <li>Image files for display elements, such as background, keys and buttons</li>

    </ul>

<p>To create and use a custom skin:</p>

 <ol>

      <li>Create a skin folder in an easily accessible location, such as  <em>~/skins</em>. </li>

      <li>Define the skin orientation and configuration settings in a file called <code>layout</code>

      in the skin folder.

<pre>

    <li>Create a new directory where you will save your skin configuration files. </li>

    <li>Define the visual appearance of the skin in a text file named

    <code>layout</code>. This file defines many characteristics of the skin, such as the

    size and image assets for specific buttons. For example:

<pre class="no-prettyprint">

parts {



    device {

        display {

            width   1080

            height  1920

            width   320

            height  480

            x       0

            y       0

        }
@@ -306,25 +319,18 @@ parts { 
    }

    ...

}



</pre></li>



      <li>Creates a <code>hardware.ini</code> file for the skin-specific properties that determine

      emulator specifications and behavior. For a complete list of emulator properties, see

      <a href="{@docRoot}tools/devices/managing-avds-cmdline.html">Managing AVDs from the Command

      Line</a>. For example:</li>

<pre>

# skin-specific hardware values

hw.lcd.density=213

vm.heapSize=48

hw.ramSize=1024

hw.keyboard.lid=no

hw.mainKeys=no

</pre>

      <li>Add the bitmap files of the device images to the skin folder. </li>

      <li>Archive the files in the skin folder. </li>

      <li>Create a new AVD and select the archive file as a custom skin. </li>

  <li>Add the bitmap files of the device images in the same directory.</li>

  <li>Specify additional hardware-specific device configurations an <code>hardware.ini</code>

  file for the device settings, such as <code>hw.keyboard</code> and

  <code>hw.lcd.density</code>.</li>

  <li>Archive the files in the skin folder and select the archive file as a custom skin. </li>

</ol>



<p>You can now run the AVD with a custom skin for testing and viewing your app. </p>

<p>For more detailed information about creating emulator skins, see the

<a href="https://android.googlesource.com/platform/external/qemu.git/+/master/docs/ANDROID-SKIN-FILES.TXT"

>Android Emulator Skin File Specification</a> in the tools source code.</p>

docs/html/tools/devices/index.jd

+1 −1

File changed.

Contains only whitespace changes.