tobi/M7350
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

M7350v1_en_gpl

Browse Source
This commit is contained in:
T
2024-09-09 08:52:07 +00:00
commit f9cc65cfda
65988 changed files with 26357421 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
base/docs/html/guide/developing/tools/MonkeyDevice.jd
+1353
View File
File diff suppressed because it is too large Load Diff
base/docs/html/guide/developing/tools/MonkeyImage.jd
+435
View File
@@ -0,0 +1,435 @@
page.title=MonkeyImage
@jd:body
<style>
h4.jd-details-title {background-color: #DEE8F1;}
</style>
<p>
A monkeyrunner class to hold an image of the device or emulator's screen. The image is
copied from the screen buffer during a screenshot. This object's methods allow you to
convert the image into various storage formats, write the image to a file, copy parts of
the image, and compare this object to other <code>MonkeyImage</code> objects.
</p>
<p>
You do not need to create new instances of <code>MonkeyImage</code>. Instead, use
<code><a href="{@docRoot}guide/developing/tools/MonkeyDevice.html#takeSnapshot">
MonkeyDevice.takeSnapshot()</a></code> to create a new instance from a screenshot. For example, use:
</p>
<pre>
newimage = MonkeyDevice.takeSnapshot()
</pre>
<h2>Summary</h2>
<table id="pubmethods" class="jd-sumtable">
<tr>
<th colspan="12" style="background-color: #E2E2E2">Methods</th>
</tr>
<tr class="api" >
<td class="jd-typecol">
<nobr>
<em>string</em>
</nobr>
</td>
<td class="jd-linkcol" width="100%">
<nobr>
<span class="sympad">
<a href="#convertToBytes">convertToBytes</a>
</span>
(<em>string</em> format)
</nobr>
<div class="jd-descrdiv">
Converts the current image to a particular format and returns it as a
<em>string</em> that you can then access as an <em>iterable</em> of binary bytes.
</div>
</td>
</tr>
<tr class="api" >
<td class="jd-typecol">
<nobr>
<em>tuple</em>
</nobr>
</td>
<td class="jd-linkcol" width="100%">
<nobr>
<span class="sympad">
<a href="#getRawPixel">getRawPixel</a>
</span>
(<em>integer</em> x,
<em>integer</em> y)
</nobr>
<div class="jd-descrdiv">
Returns the single pixel at the image location (x,y), as an
a <em>tuple</em> of <em>integer</em>, in the form (a,r,g,b).
</div>
</td>
</tr>
<tr class="api" >
<td class="jd-typecol">
<nobr>
<em>integer</em>
</nobr>
</td>
<td class="jd-linkcol" width="100%">
<nobr>
<span class="sympad">
<a href="#getRawPixelInt">getRawPixelInt</a>
</span>
(<em>integer</em> x,
<em>integer</em> y)
</nobr>
<div class="jd-descrdiv">
Returns the single pixel at the image location (x,y), as
a 32-bit <em>integer</em>.
</div>
</td>
</tr>
<tr class="api" >
<td class="jd-typecol">
<nobr>
<code>
<a href="{@docRoot}guide/developing/tools/MonkeyImage.html">MonkeyImage</a>
</code>
</nobr>
</td>
<td class="jd-linkcol" width="100%">
<nobr>
<span class="sympad">
<a href="#getSubImage">getSubImage</a>
</span>
(<em>tuple</em> rect)
</nobr>
<div class="jd-descrdiv">
Creates a new <code>MonkeyImage</code> object from a rectangular selection of the
current image.
</div>
</td>
</tr>
<tr class="api" >
<td class="jd-typecol">
<nobr>
<em>boolean</em>
</nobr>
</td>
<td class="jd-linkcol" width="100%">
<nobr>
<span class="sympad">
<a href="#sameAs">sameAs</a>
</span>
(<code><a href="{@docRoot}guide/developing/tools/MonkeyImage.html">MonkeyImage</a></code>
other,
<em>float</em> percent)
</nobr>
<div class="jd-descrdiv">
Compares this <code>MonkeyImage</code> object to another and returns the result of
the comparison. The <code>percent</code> argument specifies the percentage
difference that is allowed for the two images to be "equal".
</div>
</td>
</tr>
<tr class="api" >
<td class="jd-typecol">
<nobr>
<em>void</em>
</nobr>
</td>
<td class="jd-linkcol" width="100%">
<nobr>
<span class="sympad">
<a href="#writeToFile">writeToFile</a>
</span>
(<em>string</em> path,
<em>string</em> format)
</nobr>
<div class="jd-descrdiv">
Writes the current image to the file specified by <code>filename</code>, in the
format specified by <code>format</code>.
</div>
</td>
</tr>
</table>
<!-- ========= METHOD DETAIL ======== -->
<!-- Public methods -->
<h2>Public Methods</h2>
<A NAME="convertToBytes"></A>
<div class="jd-details api ">
<h4 class="jd-details-title">
<span class="normal">
<em>string</em>
</span>
<span class="sympad">convertToBytes</span>
<span class="normal">
(
<em>string</em> format)
</span>
</h4>
<div class="jd-details-descr">
<div class="jd-tagdata jd-tagdescr">
<p>
Converts the current image to a particular format and returns it as a <em>string</em>
that you can then access as an <em>iterable</em> of binary bytes.
</p>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Arguments</h5>
<table class="jd-tagtable">
<tr>
<th>format</th>
<td>
The desired output format. All of the common raster output formats are supported.
The default value is "png" (Portable Network Graphics).
</td>
</tr>
</table>
</div>
</div>
</div>
<A NAME="getRawPixel"></A>
<div class="jd-details api ">
<h4 class="jd-details-title">
<span class="normal">
<em>tuple</em>
</span>
<span class="sympad">getRawPixel</span>
<span class="normal">
(<em>integer</em> x,
<em>integer</em> y)
</span>
</h4>
<div class="jd-details-descr">
<div class="jd-tagdata jd-tagdescr">
<p>
Returns the single pixel at the image location (x,y), as an
a <em>tuple</em> of <em>integer</em>, in the form (a,r,g,b).
</p>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Arguments</h5>
<table class="jd-tagtable">
<tr>
<th>x</th>
<td>
The horizontal position of the pixel, starting with 0 at the left of the screen in the
orientation it had when the screenshot was taken.
</td>
</tr>
<tr>
<th>y</th>
<td>
The vertical position of the pixel, starting with 0 at the top of the screen in the
orientation it had when the screenshot was taken.
</td>
</tr>
</table>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Returns</h5>
<ul class="nolist">
<li>
A tuple of integers representing the pixel, in the form (a,r,g,b) where
a is the alpha channel value, and r, g, and b are the red, green, and blue values,
respectively.
</li>
</ul>
</div>
</div>
</div>
<A NAME="getRawPixelInt"></A>
<div class="jd-details api ">
<h4 class="jd-details-title">
<span class="normal">
<em>tuple</em>
</span>
<span class="sympad">getRawPixelInt</span>
<span class="normal">
(<em>integer</em> x,
<em>integer</em> y)
</span>
</h4>
<div class="jd-details-descr">
<div class="jd-tagdata jd-tagdescr">
<p>
Returns the single pixel at the image location (x,y), as an
an <em>integer</em>. Use this method to economize on memory.
</p>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Arguments</h5>
<table class="jd-tagtable">
<tr>
<th>x</th>
<td>
The horizontal position of the pixel, starting with 0 at the left of the screen in the
orientation it had when the screenshot was taken.
</td>
</tr>
<tr>
<th>y</th>
<td>
The vertical position of the pixel, starting with 0 at the top of the screen in the
orientation it had when the screenshot was taken.
</td>
</tr>
</table>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Returns</h5>
<ul class="nolist">
<li>
The a,r,g, and b values of the pixel as 8-bit values combined into a 32-bit
integer, with a as the leftmost 8 bits, r the next rightmost, and so forth.
</li>
</ul>
</div>
</div>
</div>
<A NAME="getSubImage"></A>
<div class="jd-details api ">
<h4 class="jd-details-title">
<span class="normal">
<code>
<a href="{@docRoot}guide/developing/tools/MonkeyImage.html">MonkeyImage</a>
</code>
</span>
<span class="sympad">getSubImage</span>
<span class="normal">
(<em>tuple</em> rect)
</span>
</h4>
<div class="jd-details-descr">
<div class="jd-tagdata jd-tagdescr">
<p>
Creates a new <code>MonkeyImage</code> object from a rectangular selection of the
current image.
</p>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Arguments</h5>
<table class="jd-tagtable">
<tr>
<th>rect</th>
<td>
A tuple (x, y, w, h) specifying the selection. x and y specify the 0-based pixel
position of the upper left-hand corner of the selection. w specifies the width of the
region, and h specifies its height, both in units of pixels.
<p>
The image's orientation is the same as the screen orientation at the time the
screenshot was made.
</p>
</td>
</tr>
</table>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Returns</h5>
<ul class="nolist">
<li>
A new <code>MonkeyImage</code> object containing the selection.
</li>
</ul>
</div>
</div>
</div>
<A NAME="sameAs"></A>
<div class="jd-details api ">
<h4 class="jd-details-title">
<span class="normal">
<em>boolean</em>
</span>
<span class="sympad">sameAs</span>
<span class="normal">
(
<code>
<a href="{@docRoot}guide/developing/tools/MonkeyImage.html">MonkeyImage</a>
</code> otherImage,
<em>float</em> percent
)
</span>
</h4>
<div class="jd-details-descr">
<div class="jd-tagdata jd-tagdescr">
<p>
Compares this <code>MonkeyImage</code> object to another and returns the result of
the comparison. The <code>percent</code> argument specifies the percentage
difference that is allowed for the two images to be "equal".
</p>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Arguments</h5>
<table class="jd-tagtable">
<tr>
<th>other</th>
<td>
Another <code>MonkeyImage</code> object to compare to this one.
</td>
</tr>
<tr>
<th>
percent
</th>
<td>
A float in the range 0.0 to 1.0, inclusive, indicating
the percentage of pixels that need to be the same for the method to return
<code>true</code>. The default is 1.0, indicating that all the pixels
must match.
</td>
</tr>
</table>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Returns</h5>
<ul class="nolist">
<li>
Boolean <code>true</code> if the images match, or boolean <code>false</code> otherwise.
</li>
</ul>
</div>
</div>
</div>
<A NAME="writeToFile"></A>
<div class="jd-details api ">
<h4 class="jd-details-title">
<span class="normal">
void
</span>
<span class="sympad">writeToFile</span>
<span class="normal">
(<em>string</em> filename,
<em>string</em> format)
</span>
</h4>
<div class="jd-details-descr">
<div class="jd-tagdata jd-tagdescr">
<p>
Writes the current image to the file specified by <code>filename</code>, in the
format specified by <code>format</code>.
</p>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Arguments</h5>
<table class="jd-tagtable">
<tr>
<th>path</th>
<td>
The fully-qualified filename and extension of the output file.
</td>
</tr>
<tr>
<th>
format
</th>
<td>
The output format to use for the file. If no format is provided, then the
method tries to guess the format from the filename's extension. If no
extension is provided and no format is specified, then the default format of
"png" (Portable Network Graphics) is used.
</td>
</tr>
</table>
</div>
</div>
</div>
base/docs/html/guide/developing/tools/MonkeyRunner.jd
+445
View File
@@ -0,0 +1,445 @@
page.title=MonkeyRunner
@jd:body
<style>
h4.jd-details-title {background-color: #DEE8F1;}
</style>
<p>
A monkeyrunner class that contains static utility methods.
</p>
<h2>Summary</h2>
<table id="pubmethods" class="jd-sumtable">
<tr>
<th colspan="12" style="background-color: #E2E2E2">Methods</th>
</tr>
<tr class="api" >
<td class="jd-typecol">
<nobr>
void
</nobr>
</td>
<td class="jd-linkcol" width="100%">
<nobr>
<span class="sympad">
<a href="#alert">alert</a>
</span>
(<em>string</em> message,
<em>string</em> title,
<em>string</em> okTitle)
</nobr>
<div class="jd-descrdiv">
Displays an alert dialog to the process running the current
program.
</div>
</td>
</tr>
<tr class="api" >
<td class="jd-typecol">
<nobr>
<em>integer</em>
</nobr>
</td>
<td class="jd-linkcol" width="100%">
<nobr>
<span class="sympad">
<a href="#choice">choice</a>
</span>
(<em>string</em> message,
<em>iterable</em> choices,
<em>string</em> title)
</nobr>
<div class="jd-descrdiv">
Displays a dialog with a list of choices to the process running the current program.
</div>
</td>
</tr>
<tr class="api" >
<td class="jd-typecol">
<nobr>
void
</nobr>
</td>
<td class="jd-linkcol" width="100%">
<nobr>
<span class="sympad">
<a href="#help">help</a>
</span>
(<em>string</em> format)
</nobr>
<div class="jd-descrdiv">
Displays the monkeyrunner API reference in a style similar to that of Python's
<code>pydoc</code> tool, using the specified format.
</div>
</td>
</tr>
<tr class="api" >
<td class="jd-typecol">
<nobr>
<em>string</em>
</nobr>
</td>
<td class="jd-linkcol" width="100%">
<nobr>
<span class="sympad">
<a href="#input">input</a>
</span>
(<em>string</em> message,
<em>string</em> initialValue,
<em>string</em> title,
<em>string</em> okTitle,
<em>string</em> cancelTitle)
</nobr>
<div class="jd-descrdiv">
Displays a dialog that accepts input.
</div>
</td>
</tr>
<tr class="api" >
<td class="jd-typecol">
<nobr>
void
</nobr>
</td>
<td class="jd-linkcol" width="100%">
<nobr>
<span class="sympad">
<a href="#sleep">sleep</a>
</span>
(<em>float</em> seconds)
</nobr>
<div class="jd-descrdiv">
Pauses the current program for the specified number of seconds.
</div>
</td>
</tr>
<tr class="api" >
<td class="jd-typecol">
<nobr>
<code>
<a href="{@docRoot}guide/developing/tools/MonkeyDevice.html">MonkeyDevice</a>
</code>
</nobr>
</td>
<td class="jd-linkcol" width="100%">
<nobr>
<span class="sympad">
<a href="#waitForConnection">waitForConnection</a>
</span>
(<em>float</em> timeout,
<em>string</em> deviceId)
</nobr>
<div class="jd-descrdiv">
Tries to make a connection between the <code>monkeyrunner</code> backend and the
specified device or emulator.
</div>
</td>
</tr>
</table>
<!-- ========= METHOD DETAIL ======== -->
<!-- Public methods -->
<h2>Public Methods</h2>
<A NAME="alert"></A>
<div class="jd-details api ">
<h4 class="jd-details-title">
<span class="normal">
<em>string</em>
</span>
<span class="sympad">alert</span>
<span class="normal">
(
<em>string</em> message,
<em>string</em> title,
<em>string</em> okTitle)
</span>
</h4>
<div class="jd-details-descr">
<div class="jd-tagdata jd-tagdescr">
<p>
Displays an alert dialog to the process running the current
program. The dialog is modal, so the program pauses until the user clicks the dialog's
button.
</p>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Arguments</h5>
<table class="jd-tagtable">
<tr>
<th>message</th>
<td>
The message to display in the dialog.
</td>
</tr>
<tr>
<th>title</th>
<td>
The dialog's title. The default value is "Alert".
</td>
</tr>
<tr>
<th>okTitle</th>
<td>
The text displayed in the dialog button. The default value is "OK".
</td>
</tr>
</table>
</div>
</div>
</div>
<A NAME="choice"></A>
<div class="jd-details api ">
<h4 class="jd-details-title">
<span class="normal">
<em>integer</em>
</span>
<span class="sympad">choice</span>
<span class="normal">
(<em>string</em> message,
<em>iterable</em> choices,
<em>string</em> title)
</span>
</h4>
<div class="jd-details-descr">
<div class="jd-tagdata jd-tagdescr">
<p>
Displays a dialog with a list of choices to the process running the current program. The
dialog is modal, so the program pauses until the user clicks one of the dialog's
buttons.
</p>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Arguments</h5>
<table class="jd-tagtable">
<tr>
<th>message</th>
<td>
The prompt message displayed in the dialog.
</td>
</tr>
<tr>
<th>choices</th>
<td>
A Python iterable containing one or more objects that are displayed as strings. The
recommended form is an array of strings.
</td>
</tr>
<tr>
<th>
title
</th>
<td>
The dialog's title. The default is "Input".
</td>
</tr>
</table>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Returns</h5>
<ul class="nolist">
<li>
If the user makes a selection and clicks the "OK" button, the method returns
the 0-based index of the selection within the iterable.
If the user clicks the "Cancel" button, the method returns -1.
</li>
</ul>
</div>
</div>
</div>
<A NAME="help"></A>
<div class="jd-details api ">
<h4 class="jd-details-title">
<span class="normal">
void
</span>
<span class="sympad">help</span>
<span class="normal">
(<em>string</em> format)
</span>
</h4>
<div class="jd-details-descr">
<div class="jd-tagdata jd-tagdescr">
<p>
Displays the monkeyrunner API reference in a style similar to that of Python's
<code>pydoc</code> tool, using the specified format.
</p>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Arguments</h5>
<table class="jd-tagtable">
<tr>
<th>format</th>
<td>
The markup format to use in the output. The possible values are "text" for plain text
or "html" for HTML.
</td>
</tr>
</table>
</div>
</div>
</div>
<A NAME="input"></A>
<div class="jd-details api ">
<h4 class="jd-details-title">
<span class="normal">
<em>string</em>
</span>
<span class="sympad">input</span>
<span class="normal">
(<em>string</em> message
<em>string</em> initialValue,
<em>string</em> title,
<em>string</em> okTitle,
<em>string</em> cancelTitle)
</span>
</h4>
<div class="jd-details-descr">
<div class="jd-tagdata jd-tagdescr">
<p>
Displays a dialog that accepts input and returns it to the program. The dialog is
modal, so the program pauses until the user clicks one of the dialog's buttons.
</p>
<p>
The dialog contains two buttons, one of which displays the okTitle value
and the other the cancelTitle value. If the user clicks the okTitle button,
the current value of the input box is returned. If the user clicks the cancelTitle
button, an empty string is returned.
</p>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Arguments</h5>
<table class="jd-tagtable">
<tr>
<th>message</th>
<td>
The prompt message displayed in the dialog.
</td>
</tr>
<tr>
<th>initialValue</th>
<td>
The initial value to display in the dialog. The default is an empty string.
</td>
</tr>
<tr>
<th>title</th>
<td>
The dialog's title. The default is "Input".
</td>
</tr>
<tr>
<th>okTitle</th>
<td>
The text displayed in the okTitle button. The default is "OK".
</td>
</tr>
<tr>
<th>cancelTitle</th>
<td>
The text displayed in the cancelTitle button. The default is "Cancel".
</td>
</tr>
</table>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Returns</h5>
<ul class="nolist">
<li>
If the user clicks the okTitle button, then the method returns the current value of
the dialog's input box. If the user clicks the cancelTitle button, the method returns
an empty string.
</li>
</ul>
</div>
</div>
</div>
<A NAME="sleep"></A>
<div class="jd-details api ">
<h4 class="jd-details-title">
<span class="normal">
void
</span>
<span class="sympad">sleep</span>
<span class="normal">
(
<em>float</em> seconds
)
</span>
</h4>
<div class="jd-details-descr">
<div class="jd-tagdata jd-tagdescr">
<p>
Pauses the current program for the specified number of seconds.
</p>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Arguments</h5>
<table class="jd-tagtable">
<tr>
<th>seconds</th>
<td>
The number of seconds to pause.
</td>
</tr>
</table>
</div>
</div>
</div>
<A NAME="waitForConnection"></A>
<div class="jd-details api ">
<h4 class="jd-details-title">
<span class="normal">
<code>
<a href="{@docRoot}guide/developing/tools/MonkeyDevice.html">MonkeyDevice</a>
</code>
</span>
<span class="sympad">waitForConnection</span>
<span class="normal">
(<em>float</em> timeout,
<em>string</em> deviceId)
</span>
</h4>
<div class="jd-details-descr">
<div class="jd-tagdata jd-tagdescr">
<p>
Tries to make a connection between the <code>monkeyrunner</code> backend and the
specified device or emulator.
</p>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Arguments</h5>
<table class="jd-tagtable">
<tr>
<th>timeout</th>
<td>
The number of seconds to wait for a connection. The default is to wait forever.
</td>
</tr>
<tr>
<th>
deviceId
</th>
<td>
A regular expression that specifies the serial number of the device or emulator. See
the topic
<a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a>
for a description of device and emulator serial numbers.
</td>
</tr>
</table>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Returns</h5>
<ul class="nolist">
<li>
A <code><a href="{@docRoot}guide/developing/tools/MonkeyDevice.html">MonkeyDevice</a></code>
instance for the device or emulator. Use this object to control and communicate with the
device or emulator.
</li>
</ul>
</div>
</div>
</div>
base/docs/html/guide/developing/tools/aapt.jd
+20
View File
@@ -0,0 +1,20 @@
page.title=Using aapt
@jd:body
<p><strong>aapt</strong> stands for Android Asset Packaging Tool and is included in the <code>tools/</code> directory of the SDK. This tool allows you to view, create, and update Zip-compatible archives (zip, jar, apk). It can also compile resources into binary assets.
</p>
<p>
Though you probably won't often use <strong>aapt</strong> directly, build scripts and IDE plugins can utilize this tool to package the apk file that constitutes an Android application.
</p>
<p>
For more usage details, open a terminal, go to the <code>tools/</code> directory, and run the command:
</p>
<ul>
<li><p>Linux or Mac OS X:</p>
<pre>./aapt</pre>
</li>
<li><p>Windows:</p>
<pre>aapt.exe</pre>
</li>
</ul>
base/docs/html/guide/developing/tools/adb.jd
+701
View File
@@ -0,0 +1,701 @@
page.title=Android Debug Bridge
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>ADB quickview</h2>
<ul>
<li>Manage the state of an emulator or device</li>
<li>Run shell commands on a device</li>
<li>Manage port forwarding on an emulator or device</li>
<li>Copy files to/from an emulator or device</li>
</ul>
<h2>In this document</h2>
<ol>
<li><a href="#issuingcommands">Issuing ADB Commands</a></li>
<li><a href="#devicestatus">Querying for Emulator/Device Instances</a></li>
<li><a href="#directingcommands">Directing Commands to a Specific Emulator/Device Instance</a></li>
<li><a href="#move">Installing an Application</a></li>
<li><a href="#forwardports">Forwarding Ports</a></li>
<li><a href="#copyfiles">Copying Files to or from an Emulator/Device Instance</a></li>
<li><a href="#commandsummary">Listing of adb Commands </a></li>
<li><a href="#shellcommands">Issuing Shell Commands</a></li>
<li><a href="#logcat">Enabling logcat Logging</a></li>
<li><a href="#stopping">Stopping the adb Server</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="emulator.html">Emulator</a></li>
</ol>
</div>
</div>
<!--
<p>Android Debug Bridge (adb) is a versatile tool that </a>. </p>
<p>Some of ways you can use adb include:</p>
<ul>
</ul>
<p>The sections below introduce adb and describe many of its common uses. </p>
<h2>Contents</h2>
<dl>
<dt><a href="#overview">Overview</a></dt>
<dt><a href="#issuingcommands">Issuing adb Commands</a></dt>
<dt><a href="#devicestatus">Querying for Emulator/Device Instances</a></dt>
<dt><a href="#directingcommands">Directing Commands to a Specific Emulator/Device Instance</a></dt>
<dt><a href="#move">Installing an Application</a></dt>
<dt><a href="#forwardports">Forwarding Ports</a></dt>
<dt><a href="#copyfiles">Copying Files to or from an Emulator/Device Instance</a></dt>
<dt><a href="#commandsummary">Listing of adb Commands </a></dt>
<dt><a href="#shellcommands">Issuing Shell Commands</a></dt>
<dd><a href="#sqlite">Examining sqlite3 Databases from a Remote Shell</a></dd>
<dd><a href="#monkey">UI/Application Exerciser Monkey</a></dd>
<dd><a href="#othershellcommands">Other Shell Commands</a></dd>
<dt><a href="#logcat">Enabling logcat Logging</a> </dt>
<dd><a href="#usinglogcat">Using logcat Commands</a></dd>
<dd><a href="#filteringoutput">Filtering Log Output</a></dd>
<dd><a href="#outputformat">Controlling Log Output Format</a></dd>
<dd><a href="#alternativebuffers">Viewing Alternative Log Buffers</a></dd>
<dd><a href="#stdout">Viewing stdout and stderr</a></dd>
<dd><a href="#logcatoptions">Listing of logcat Command Options</a></dd>
<dt><a href="#stopping">Stopping the adb Server</a> </dt>
</dl>
<a name="overview"></a>
<h2>Overview</h2>
-->
<p>Android Debug Bridge (adb) is a versatile tool lets you manage the state of an emulator instance or Android-powered device. It is a client-server program that includes three components: </p>
<ul>
<li>A client, which runs on your development machine. You can invoke a client from a shell by issuing an adb command. Other Android tools such as the ADT plugin and DDMS also create adb clients. </li>
<li>A server, which runs as a background process on your development machine. The server manages communication between the client and the adb daemon running on an emulator or device. </li>
<li>A daemon, which runs as a background process on each emulator or device instance. </li>
</ul>
<p>You can find the {@code adb} tool in {@code &lt;sdk&gt;/platform-tools/}.</p>
<p>When you start an adb client, the client first checks whether there is an adb server process already running. If there isn't, it starts the server process. When the server starts, it binds to local TCP port 5037 and listens for commands sent from adb clients&mdash;all adb clients use port 5037 to communicate with the adb server. </p>
<p>The server then sets up connections to all running emulator/device instances. It locates emulator/device instances by scanning odd-numbered ports in the range 5555 to 5585, the range used by emulators/devices. Where the server finds an adb daemon, it sets up a connection to that port. Note that each emulator/device instance acquires a pair of sequential ports &mdash; an even-numbered port for console connections and an odd-numbered port for adb connections. For example: </p>
<p style="margin-left:2em">
Emulator 1, console: 5554<br/>
Emulator 1, adb: 5555<br>
Emulator 2, console: 5556<br>
Emulator 2, adb: 5557 ...
</p>
<p>As shown, the emulator instance connected to adb on port 5555 is the same as the instance whose console listens on port 5554. </p>
<p>Once the server has set up connections to all emulator instances, you can use adb commands to control and access those instances. Because the server manages connections to emulator/device instances and handles commands from multiple adb clients, you can control any emulator/device instance from any client (or from a script).</p>
<p>The sections below describe the commands that you can use to access adb capabilities and manage the state of an emulator/device. Note that if you are developing Android applications in Eclipse and have installed the ADT plugin, you do not need to access adb from the command line. The ADT plugin provides a transparent integration of adb into the Eclipse IDE. However, you can still use adb directly as necessary, such as for debugging.</p>
<a name="issuingcommands"></a>
<h2>Issuing adb Commands</h2>
<p>You can issue adb commands from a command line on your development machine or from a script. The usage is: </p>
<pre>adb [-d|-e|-s &lt;serialNumber&gt;] &lt;command&gt; </pre>
<p>When you issue a command, the program invokes an adb client. The client is not specifically associated with any emulator instance, so if multiple emulators/devices are running, you need to use the <code>-d</code> option to specify the target instance to which the command should be directed. For more information about using this option, see <a href="#directingcommands">Directing Commands to a Specific Emulator/Device Instance</a>. </p>
<a name="devicestatus"></a>
<h2>Querying for Emulator/Device Instances</h2>
<p>Before issuing adb commands, it is helpful to know what emulator/device instances are connected to the adb server. You can generate a list of attached emulators/devices using the <code>devices</code> command: </p>
<pre>adb devices</pre>
<p>In response, adb prints this status information for each instance:</p>
<ul>
<li>Serial number &mdash; A string created by adb to uniquely identify an emulator/device instance by its
console port number. The format of the serial number is <code>&lt;type&gt;-&lt;consolePort&gt;</code>.
Here's an example serial number: <code>emulator-5554</code></li>
<li>State &mdash; The connection state of the instance. Three states are supported:
<ul>
<li><code>offline</code> &mdash; the instance is not connected to adb or is not responding.</li>
<li><code>device</code> &mdash; the instance is now connected to the adb server. Note that this state does not
imply that the Android system is fully booted and operational, since the instance connects to adb
while the system is still booting. However, after boot-up, this is the normal operational state of
an emulator/device instance.</li>
</ul>
</li>
</ul>
<p>The output for each instance is formatted like this: </p>
<pre>[serialNumber] [state]</pre>
<p>Here's an example showing the <code>devices</code> command and its output:</p>
<pre>$ adb devices
List of devices attached
emulator-5554&nbsp;&nbsp;device
emulator-5556&nbsp;&nbsp;device
emulator-5558&nbsp;&nbsp;device</pre>
<p>If there is no emulator/device running, adb returns <code>no device</code>.</p>
<a name="directingcommands"></a>
<h2>Directing Commands to a Specific Emulator/Device Instance</h2>
<p>If multiple emulator/device instances are running, you need to specify a target instance when issuing adb commands. To so so, use the <code>-s</code> option in the commands. The usage for the <code>-s</code> option is:</p>
<pre>adb -s &lt;serialNumber&gt; &lt;command&gt; </pre>
<p>As shown, you specify the target instance for a command using its adb-assigned serial number. You can use the <code>devices</code> command to obtain the serial numbers of running emulator/device instances. </p>
<p>Here is an example: </p>
<pre>adb -s emulator-5556 install helloWorld.apk</pre>
<p>Note that, if you issue a command without specifying a target emulator/device instance using <code>-s</code>, adb generates an error.
<a name="move"></a>
<h2>Installing an Application</h2>
<p>You can use adb to copy an application from your development computer and install it on an emulator/device instance. To do so, use the <code>install</code> command. With the command, you must specify the path to the .apk file that you want to install:</p>
<pre>adb install &lt;path_to_apk&gt;</pre>
<p>For more information about how to create an .apk file that you can install on an emulator/device instance, see <a href="{@docRoot}guide/developing/tools/aapt.html">Android Asset Packaging Tool</a> (aapt). </p>
<p>Note that, if you are using the Eclipse IDE and have the ADT plugin installed, you do not need to use adb (or aapt) directly to install your application on the emulator/device. Instead, the ADT plugin handles the packaging and installation of the application for you. </p>
<a name="forwardports"></a>
<h2>Forwarding Ports</h2>
<p>You can use the <code>forward</code> command to set up arbitrary port forwarding &mdash; forwarding of requests on a specific host port to a different port on an emulator/device instance. Here's how you would set up forwarding of host port 6100 to emulator/device port 7100:</p>
<pre>adb forward tcp:6100 tcp:7100</pre>
<p>You can also use adb to set up forwarding to named abstract UNIX domain sockets, as illustrated here:</p>
<pre>adb forward tcp:6100 local:logd </pre>
<a name="copyfiles"></a>
<h2>Copying Files to or from an Emulator/Device Instance</h2>
<p>You can use the adb commands <code>pull</code> and <code>push</code> to copy files to and from an emulator/device instance's data file. Unlike the <code>install</code> command, which only copies an .apk file to a specific location, the <code>pull</code> and <code>push</code> commands let you copy arbitrary directories and files to any location in an emulator/device instance. </p>
<p>To copy a file or directory (recursively) <em>from</em> the emulator or device, use</p>
<pre>adb pull &lt;remote&gt; &lt;local&gt;</pre>
<p>To copy a file or directory (recursively) <em>to</em> the emulator or device, use</p>
<pre>adb push &lt;local&gt; &lt;remote&gt;</pre>
<p>In the commands, <code>&lt;local&gt;</code> and <code>&lt;remote&gt;</code> refer to the paths to the target files/directory on your development machine (local) and on the emulator/device instance (remote).</p>
<p>Here's an example: </p>
<pre>adb push foo.txt /sdcard/foo.txt</pre>
<a name="commandsummary"></a>
<h2>Listing of adb Commands</h2>
<p>The table below lists all of the supported adb commands and explains their meaning and usage. </p>
<table>
<tr>
<th>Category</th>
<th>Command</th>
<th>Description</th>
<th>Comments</th>
</tr>
<tr>
<td rowspan="3">Options</td>
<td><code>-d</code></td>
<td>Direct an adb command to the only attached USB device.</td>
<td>Returns an error if more than one USB device is attached.</td>
</tr>
<tr>
<td><code>-e</code></td>
<td>Direct an adb command to the only running emulator instance.</td>
<td>Returns an error if more than one emulator instance is running. </td>
</tr>
<tr>
<td><code>-s&nbsp;&lt;serialNumber&gt;</code></td>
<td>Direct an adb command a specific emulator/device instance, referred to by its adb-assigned serial number (such as "emulator-5556").</td>
<td>If not specified, adb generates an error.</td>
</tr>
<tr>
<td rowspan="3">General</td>
<td><code>devices</code></td>
<td>Prints a list of all attached emulator/device instances.</td>
<td>See <a href="#devicestatus">Querying for Emulator/Device Instances</a> for more information.</td>
</tr>
<tr>
<td><code>help</code></td>
<td>Prints a list of supported adb commands.</td>
<td>&nbsp;</td>
</tr>
<tr>
<td><code>version</code></td>
<td>Prints the adb version number. </td>
<td>&nbsp;</td>
</tr>
<tr>
<td rowspan="3">Debug</td>
<td ><code>logcat&nbsp;[&lt;option&gt;] [&lt;filter-specs&gt;]</code></td>
<td>Prints log data to the screen. </td>
<td>&nbsp;</td>
</tr>
<tr>
<td><code>bugreport</code></td>
<td>Prints <code>dumpsys</code>, <code>dumpstate</code>, and <code>logcat</code> data to the screen, for the purposes of bug reporting. </td>
<td>&nbsp;</td>
</tr>
<tr>
<td><code>jdwp</code></td>
<td>Prints a list of available JDWP processes on a given device. </td>
<td>You can use the <code>forward jdwp:&lt;pid&gt;</code> port-forwarding specification to connect to a specific JDWP process. For example: <br>
<code>adb forward tcp:8000 jdwp:472</code><br>
<code>jdb -attach localhost:8000</code></p>
</td>
</tr>
<tr>
<td rowspan=3">Data</td>
<td><code>install&nbsp;&lt;path-to-apk&gt;</code></td>
<td>Pushes an Android application (specified as a full path to an .apk file) to the data file of an emulator/device. </td>
<td>&nbsp;</td>
</tr>
<tr>
<td><code>pull&nbsp;&lt;remote&gt;&nbsp;&lt;local&gt;</code></td>
<td>Copies a specified file from an emulator/device instance to your development computer. </td>
<td>&nbsp;</td>
</tr>
<tr>
<td><code>push&nbsp;&lt;local&gt;&nbsp;&lt;remote&gt;</code></td>
<td>Copies a specified file from your development computer to an emulator/device instance. </td>
<td>&nbsp;</td>
</tr>
<tr>
<td rowspan="2">Ports and Networking</td>
<td><code>forward&nbsp;&lt;local&gt;&nbsp;&lt;remote&gt;</code></td>
<td>Forwards socket connections from a specified local port to a specified remote port on the emulator/device instance. </td>
<td>Port specifications can use these schemes:
<ul><li><code>tcp:&lt;portnum&gt;</code></li>
<li><code>local:&lt;UNIX domain socket name&gt;</code></li>
<li><code>dev:&lt;character device name&gt;</code></li>
<li><code>jdwp:&lt;pid&gt;</code></li></ul>
</td>
</tr>
<tr>
<td><code>ppp&nbsp;&lt;tty&gt;&nbsp;[parm]...</code></td>
<td>Run PPP over USB.
<ul>
<li><code>&lt;tty&gt;</code> &mdash; the tty for PPP stream. For example <code>dev:/dev/omap_csmi_ttyl</code>. </li>
<li><code>[parm]... </code> &mdash zero or more PPP/PPPD options, such as <code>defaultroute</code>, <code>local</code>, <code>notty</code>, etc.</li></ul>
<p>Note that you should not automatically start a PPP connection. </p></td>
<td></td>
</tr>
<tr>
<td rowspan="3">Scripting</td>
<td><code>get-serialno</code></td>
<td>Prints the adb instance serial number string.</td>
<td rowspan="2">See <a href="#devicestatus">Querying for Emulator/Device Instances</a> for more information. </td>
</tr>
<tr>
<td><code>get-state</code></td>
<td>Prints the adb state of an emulator/device instance.</td>
</td>
</tr>
<tr>
<td><code>wait-for-device</code></td>
<td>Blocks execution until the device is online &mdash; that is, until the instance state is <code>device</code>.</td>
<td>You can prepend this command to other adb commands, in which case adb will wait until the emulator/device instance is connected before issuing the other commands. Here's an example:
<pre>adb wait-for-device shell getprop</pre>
Note that this command does <em>not</em> cause adb to wait until the entire system is fully booted. For that reason, you should not prepend it to other commands that require a fully booted system. As an example, the <code>install</code> requires the Android package manager, which is available only after the system is fully booted. A command such as
<pre>adb wait-for-device install &lt;app&gt;.apk</pre>
would issue the <code>install</code> command as soon as the emulator or device instance connected to the adb server, but before the Android system was fully booted, so it would result in an error. </td>
</tr>
<tr>
<td rowspan="2">Server</td>
<td><code>start-server</code></td>
<td>Checks whether the adb server process is running and starts it, if not.</td>
<td>&nbsp;</td>
</tr>
<tr>
<td><code>kill-server</code></td>
<td>Terminates the adb server process.</td>
<td>&nbsp;</td>
</tr>
<tr>
<td rowspan="2">Shell</td>
<td><code>shell</code></td>
<td>Starts a remote shell in the target emulator/device instance.</td>
<td rowspan="2">See <a href="#shellcommands">Issuing Shell Commands</a> for more information. </td>
</tr>
<tr>
<td><code>shell&nbsp;[&lt;shellCommand&gt;]</code></td>
<td>Issues a shell command in the target emulator/device instance and then exits the remote shell.</td>
</tr>
</table>
<a name="shellcommands"></a>
<h2>Issuing Shell Commands</h2>
<p>Adb provides an ash shell that you can use to run a variety of commands on an emulator
or device. The command binaries are stored in the file system of the emulator or device,
in this location: </p>
<pre>/system/bin/...</pre>
<p>You can use the <code>shell</code> command to issue commands, with or without entering the adb remote shell on the emulator/device. </p>
<p>To issue a single command without entering a remote shell, use the <code>shell</code> command like this: </p>
<pre>adb [-d|-e|-s {&lt;serialNumber&gt;}] shell &lt;shellCommand&gt;</pre>
<p>To drop into a remote shell on a emulator/device instance, use the <code>shell</code> command like this:</p>
<pre>adb [-d|-e|-s {&lt;serialNumber&gt;}] shell</pre>
<p>When you are ready to exit the remote shell, use <code>CTRL+D</code> or <code>exit</code> to end the shell session. </p>
<p>The sections below provide more information about shell commands that you can use.</p>
<a name="sqlite" id="sqlite"></a>
<h3>Examining sqlite3 Databases from a Remote Shell</h3>
<p>From an adb remote shell, you can use the
<a href="http://www.sqlite.org/sqlite.html">sqlite3</a> command-line program to
manage SQLite databases created by Android applications. The
<code>sqlite3</code> tool includes many useful commands, such as
<code>.dump</code> to print out the contents of a table and
<code>.schema</code> to print the SQL CREATE statement for an existing table.
The tool also gives you the ability to execute SQLite commands on the fly.</p>
<p>To use <code>sqlite3</code>, enter a remote shell on the emulator instance, as described above, then invoke the tool using the <code>sqlite3</code> command. Optionally, when invoking <code>sqlite3</code> you can specify the full path to the database you want to explore. Emulator/device instances store SQLite3 databases in the folder <code><span chatdir="1"><span chatindex="259474B4B070F261">/data/data/<em>&lt;package_name&gt;</em>/databases</span></span>/</code>. </p>
<p>Here's an example: </p>
<pre>$ adb -s emulator-5554 shell
# sqlite3 /data/data/com.example.google.rss.rssexample/databases/rssitems.db
SQLite version 3.3.12
Enter &quot;.help&quot; for instructions
<em>.... enter commands, then quit...</em>
sqlite&gt; .exit </pre>
<p>Once you've invoked <code>sqlite3</code>, you can issue <code>sqlite3</code> commands in the shell. To exit and return to the adb remote shell, use <code>exit</code> or <code>CTRL+D</code>.
<a name="monkey"></a>
<h3>UI/Application Exerciser Monkey</h3>
<p>The Monkey is a program that runs on your emulator or device and generates pseudo-random
streams of user events such as clicks, touches, or gestures, as well as a number of system-level
events. You can use the Monkey to stress-test applications that you are developing,
in a random yet repeatable manner.</p>
<p>The simplest way to use the monkey is with the following command, which will launch your
application and send 500 pseudo-random events to it.</p>
<pre>$ adb shell monkey -v -p your.package.name 500</pre>
<p>For more information about command options for Monkey, see the complete
<a href="{@docRoot}guide/developing/tools/monkey.html" title="monkey">UI/Application Exerciser Monkey</a> documentation page.</p>
<a name="othershellcommands"></a>
<h3>Other Shell Commands</h3>
<p>The table below lists several of the adb shell commands available. For a complete list of commands and programs, start an emulator instance and use the <code>adb -help</code> command. </p>
<pre>adb shell ls /system/bin</pre>
<p>Help is available for most of the commands. </p>
<table>
<tr>
<th>Shell Command</th>
<th>Description</th>
<th>Comments</th>
</tr>
<tr>
<td><code>dumpsys</code></td>
<td>Dumps system data to the screen.</td>
<td rowspan=4">The <a href="{@docRoot}guide/developing/tools/ddms.html">Dalvik Debug Monitor Service</a> (DDMS) tool offers integrated debug environment that you may find easier to use.</td>
</tr>
<tr>
<td><code>dumpstate</code></td>
<td>Dumps state to a file.</td>
</tr>
<tr>
<td><code>logcat&nbsp;[&lt;option&gt;]...&nbsp;[&lt;filter-spec&gt;]...</code></td>
<td>Enables radio logging and prints output to the screen. </td>
</tr>
<tr>
<td><code>dmesg</code></td>
<td>Prints kernel debugging messages to the screen. </td>
</tr>
<tr>
<td><code>start</code></td>
<td>Starts (restarts) an emulator/device instance.</td>
<td>&nbsp;</td>
</tr>
<tr>
<td><code>stop</code></td>
<td>Stops execution of an emulator/device instance.</td>
<td>&nbsp;</td>
</tr>
</table>
<a name="logcat"></a>
<h2>Enabling logcat Logging</h2>
<p>The Android logging system provides a mechanism for collecting and viewing system debug output. Logs from various applications and portions of the system are collected in a series of circular buffers, which then can be viewed and filtered by the <code>logcat</code> command.</p>
<a name="usinglogcat"></a>
<h3>Using logcat Commands</h3>
<p>You can use the <code>logcat</code> command to view and follow the contents of the system's log buffers. The general usage is:</p>
<pre>[adb] logcat [&lt;option&gt;] ... [&lt;filter-spec&gt;] ...</pre>
<p>The sections below explain filter specifications and the command options. See <a href="#logcatoptions">Listing of logcat Command Options</a> for a summary of options. </p>
<p>You can use the <code>logcat</code> command from your development computer or from a remote adb shell in an emulator/device instance. To view log output in your development computer, you use</p>
<pre>$ adb logcat</pre>
<p>and from a remote adb shell you use</p>
<pre># logcat</pre>
<a name="filteringoutput"></a>
<h3>Filtering Log Output</h3>
<p>Every Android log message has a <em>tag</em> and a <em>priority</em> associated with it. </p>
<ul>
<li>The tag of a log message is a short string indicating the system component from which the message originates (for example, "View" for the view system). </li>
<li>The priority is one of the following character values, ordered from lowest to highest priority:</li>
<ul>
<li><code>V</code> &mdash; Verbose (lowest priority)</li>
<li><code>D</code> &mdash; Debug</li>
<li><code>I</code> &mdash; Info</li>
<li><code>W</code> &mdash; Warning</li>
<li><code>E</code> &mdash; Error</li>
<li><code>F</code> &mdash; Fatal</li>
<li><code>S</code> &mdash; Silent (highest priority, on which nothing is ever printed)</li>
</ul>
</ul>
<p>You can obtain a list of tags used in the system, together with priorities, by running <code>logcat</code> and observing the first two columns
of each message, given as <code>&lt;priority&gt;/&lt;tag&gt;</code>. </p>
<p>Here's an example of logcat output that shows that the message relates to priority level "I" and tag "ActivityManager":</p>
<pre>I/ActivityManager( 585): Starting activity: Intent { action=android.intent.action...}</pre>
<p>To reduce the log output to a manageable level, you can restrict log output using <em>filter expressions</em>. Filter expressions let you indicate to the system the tags-priority combinations that you are interested in &mdash; the system suppresses other messages for the specified tags. </p>
<p>A filter expression follows this format <code>tag:priority ...</code>, where <code>tag</code> indicates the tag of interest and <code>priority</code> indicates the <em>minimum</em> level of priority to report for that tag. Messages for that tag at or above the specified priority are written to the log. You can supply any number of <code>tag:priority</code> specifications in a single filter expression. The series of specifications is whitespace-delimited. </p>
<p>Here's an example of a filter expression that suppresses all log messages except those with the tag "ActivityManager", at priority "Info" or above, and all log messages with tag "MyApp", with priority "Debug" or above:</p>
<pre>adb logcat ActivityManager:I MyApp:D *:S</pre>
<p>The final element in the above expression, <code>*:S</code>, sets the priority level for all tags to "silent", thus ensuring only log messages with "View" and "MyApp" are displayed. Using <code>*:S</code> is an excellent way to ensure that log output is restricted to the filters that you have explicitly specified &mdash; it lets your filters serve as a "whitelist" for log output.</p>
<p>The following filter expression displays all log messages with priority level "warning" and higher, on all tags:</p>
<pre>adb logcat *:W</pre>
<p>If you're running <code>logcat</code> from your development computer (versus running it on a remote adb shell), you can also set a default filter expression by exporting a value for the environment variable <code>ANDROID_LOG_TAGS</code>:</p>
<pre>export ANDROID_LOG_TAGS="ActivityManager:I MyApp:D *:S"</pre>
<p>Note that <code>ANDROID_LOG_TAGS</code> filter is not exported to the emulator/device instance, if you are running <code>logcat</code> from a remote shell or using <code>adb shell logcat</code>.</p>
<a name="outputformat"></a>
<h3>Controlling Log Output Format</h3>
<p>Log messages contain a number of metadata fields, in addition to the tag and priority. You can modify the output format for messages so that they display a specific metadata field. To do so, you use the <code>-v</code> option and specify one of the supported output formats listed below. </p>
<ul>
<li><code>brief</code> &mdash; Display priority/tag and PID of originating process (the default format).</li>
<li><code>process</code> &mdash; Display PID only.</li>
<li><code>tag</code> &mdash; Display the priority/tag only. </li>
<li><code>thread</code> &mdash; Display process:thread and priority/tag only. </li>
<li><code>raw</code> &mdash; Display the raw log message, with no other metadata fields.</li>
<li><code>time</code> &mdash; Display the date, invocation time, priority/tag, and PID of the originating process.</li>
<li><code>long</code> &mdash; Display all metadata fields and separate messages with a blank lines.</li>
</ul>
<p>When starting <code>logcat</code>, you can specify the output format you want by using the <code>-v</code> option:</p>
<pre>[adb] logcat [-v &lt;format&gt;]</pre>
<p>Here's an example that shows how to generate messages in <code>thread</code> output format: </p>
<pre>adb logcat -v thread</pre>
<p>Note that you can only specify one output format with the <code>-v</code> option. </p>
<a name="alternativebuffers"></a>
<h3>Viewing Alternative Log Buffers </h3>
<p>The Android logging system keeps multiple circular buffers for log messages, and not all of the log messages are sent to the default circular buffer. To see additional log messages, you can start <code>logcat</code> with the <code>-b</code> option, to request viewing of an alternate circular buffer. You can view any of these alternate buffers: </p>
<ul>
<li><code>radio</code> &mdash; View the buffer that contains radio/telephony related messages.</li>
<li><code>events</code> &mdash; View the buffer containing events-related messages.</li>
<li><code>main</code> &mdash; View the main log buffer (default)</li>
</ul>
<p>The usage of the <code>-b</code> option is:</p>
<pre>[adb] logcat [-b &lt;buffer&gt;]</pre>
<p>Here's an example of how to view a log buffer containing radio and telephony messages: </p>
<pre>adb logcat -b radio</b></pre>
<a name="stdout"></a>
<h3>Viewing stdout and stderr</h3>
<p>By default, the Android system sends <code>stdout</code> and <code>stderr</code> (<code>System.out</code> and <code>System.err</code>) output to <code>/dev/null</code>. In
processes that run the Dalvik VM, you can have the system write a copy of the output to the log file. In this case, the system writes the messages to the log using the log tags <code>stdout</code> and <code>stderr</code>, both with priority <code>I</code>. </p>
<p>To route the output in this way, you stop a running emulator/device instance and then use the shell command <code>setprop</code> to enable the redirection of output. Here's how you do it: </p>
<pre>$ adb shell stop
$ adb shell setprop log.redirect-stdio true
$ adb shell start</pre>
<p>The system retains this setting until you terminate the emulator/device instance. To use the setting as a default on the emulator/device instance, you can add an entry to <code>/data/local.prop</code>
on the device.</p>
<a name="logcatoptions"></a>
<h3>Listing of logcat Command Options</h3>
<table>
<tr>
<th>Option</th>
<th>Description</th>
</tr>
<tr>
<td><code>-b&nbsp;&lt;buffer&gt;</code></td>
<td>Loads an alternate log buffer for viewing, such as <code>event</code> or <code>radio</code>. The <code>main</code> buffer is used by default. See <a href="#alternativebuffers">Viewing Alternative Log Buffers</a>.</td>
</tr>
<tr>
<td><code>-c</code></td>
<td>Clears (flushes) the entire log and exits. </td>
</tr>
<tr>
<td><code>-d</code></td>
<td>Dumps the log to the screen and exits.</td>
</tr>
<tr>
<td><code>-f&nbsp;&lt;filename&gt;</code></td>
<td>Writes log message output to <code>&lt;filename&gt;</code>. The default is <code>stdout</code>.</td>
</tr>
<tr>
<td><code>-g</code></td>
<td>Prints the size of the specified log buffer and exits. </td>
</tr>
<tr>
<td><code>-n&nbsp;&lt;count&gt;</code></td>
<td>Sets the maximum number of rotated logs to <code>&lt;count&gt;</code>. The default value is 4. Requires the <code>-r</code> option. </td>
</tr>
<tr>
<td><code>-r&nbsp;&lt;kbytes&gt;</code></td>
<td>Rotates the log file every <code>&lt;kbytes&gt;</code> of output. The default value is 16. Requires the <code>-f</code> option. </td>
</tr>
<tr>
<td><code>-s</code></td>
<td>Sets the default filter spec to silent. </td>
</tr>
<tr>
<td><code>-v&nbsp;&lt;format&gt;</code></td>
<td>Sets the output format for log messages. The default is <code>brief</code> format. For a list of supported formats, see <a href="#outputformat">Controlling Log Output Format</a>.</td>
</tr>
</table>
<a name="stopping"></a>
<h2>Stopping the adb Server</h2>
<p>In some cases, you might need to terminate the adb server process and then restart it. For example, if adb does not respond to a command, you can terminate the server and restart it and that may resolve the problem. </p>
<p>To stop the adb server, use the <code>kill-server</code>. You can then restart the server by issuing any adb command. </p>
base/docs/html/guide/developing/tools/adt.html
+10
View File
@@ -0,0 +1,10 @@
<html>
<head>
<meta http-equiv="refresh" content="0;url=http://developer.android.com/sdk/eclipse-adt.html">
<title>Redirecting...</title>
</head>
<body>
<p>You should be redirected. Please <a
href="http://developer.android.com/sdk/eclipse-adt.html">click here</a>.</p>
</body>
</html>
base/docs/html/guide/developing/tools/aidl.jd
+305
View File
@@ -0,0 +1,305 @@
page.title=Designing a Remote Interface Using AIDL
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#implementing">Implementing IPC Using AIDL</a>
<ol>
<li><a href="#aidlsyntax">Create an .aidl File</a></li>
<li><a href="#implementtheinterface">Implementing the Interface</a></li>
<li><a href="#exposingtheinterface">Exposing Your Interface to Clients</a></li>
<li><a href="#parcelable">Pass by value Parameters using Parcelables</a></li>
</ol>
</li>
<li><a href="#calling">Calling an IPC Method</a></li>
</ol>
</div>
</div>
<p>Since each application runs in its own process, and you can write a service that
runs in a different process from your Application's UI, sometimes you need to pass objects
between processes. On the Android platform, one process can not normally access the memory
of another process. So to talk, they need to decompose their objects into primitives that
the operating system can understand, and "marshall" the object across that boundary for you.</p>
<p>The code to do that marshalling is tedious to write, so we provide the AIDL tool to do it
for you.</p>
<p>AIDL (Android Interface Definition Language) is an <a
href="http://en.wikipedia.org/wiki/Interface_description_language">IDL</a>
language used to generate code that enables two processes on an Android-powered device
to talk using interprocess communication (IPC). If you have code
in one process (for example, in an Activity) that needs to call methods on an
object in another process (for example, a Service), you would use AIDL to
generate code to marshall the parameters.</p>
<p>The AIDL IPC mechanism
is interface-based, similar to COM or Corba, but lighter weight. It uses a proxy
class to pass values between the client and the implementation. </p>
<h2 id="implementing">Implementing IPC Using AIDL</h2>
<p>Follow these steps to implement an IPC service using AIDL.</p>
<ol>
<li><strong><a href="#aidlsyntax">Create your .aidl file</a> </strong>- This
file defines an interface (<em>YourInterface</em>.aidl) that defines the
methods and fields available to a client. </li>
<li><strong>Add the .aidl file to your makefile</strong> - (the ADT Plugin for Eclipse
manages this for you). Android includes the compiler, called
AIDL, in the <code>tools/</code> directory. </li>
<li><strong><a href="#implementtheinterface">Implement your interface methods</a></strong> -
The AIDL compiler creates an interface in the Java programming language from your AIDL interface.
This interface has an inner abstract class named Stub that inherits the
interface (and implements a few additional methods necessary for the IPC
call). You must create a class that extends <em>YourInterface</em>.Stub
and implements the methods you declared in your .aidl file. </li>
<li><strong><a href="#exposingtheinterface">Expose your interface to clients</a></strong> -
If you're writing a service, you should extend {@link
android.app.Service Service} and override {@link android.app.Service#onBind
Service.onBind(Intent)} to return an instance of your class that implements your
interface. </li>
</ol>
<h3 id="aidlsyntax">Create an .aidl File</h3>
<p>AIDL is a simple syntax that lets you declare an interface with one or more
methods, that can take parameters and return values. These parameters and return
values can be of any type, even other AIDL-generated interfaces. <em>However, it
is important to note</em> that you <em>must</em> import all non-built-in types,
<em>even if they are defined in the same package as your interface</em>.
Here are the data types that AIDL can support: </p>
<ul>
<li>Primitive Java programming language types (int, boolean, etc)
&mdash; No <code>import</code> statement is needed. </li>
<li>One of the following classes (no <code>import</code> statements needed):
<ul>
<li><strong>String</strong></li>
<li><strong>List</strong> - All elements in the List must be one of the types
in this list, including other AIDL-generated interfaces and
parcelables. List may optionally be used as a "generic" class (e.g.
List&lt;String&gt;).
The actual concrete class that the other side will receive
will always be an ArrayList, although the method will be generated
to use the List interface. </li>
<li><strong>Map</strong> - All elements in the Map must be of one of the
types in this list, including other AIDL-generated interfaces and
parcelables. Generic maps, (e.g. of the form Map&lt;String,Integer&gt;
are not supported.
The actual concrete class that the other side will receive
will always be a HashMap, although the method will be generated
to use the Map interface.</li>
<li><strong>CharSequence</strong> - This is useful for the CharSequence
types used by {@link android.widget.TextView TextView} and other
widget objects. </li>
</ul>
</li>
<li>Other AIDL-generated interfaces, which are always passed by reference.
An <code>import</code> statement is always needed for these.</li>
<li>Custom classes that implement the <a href="#parcelable">Parcelable
protocol</a> and are passed by value.
An <code>import</code> statement is always needed for these.</li>
</ul>
<p>Here is the basic AIDL syntax:</p>
<pre>// My AIDL file, named <em>SomeClass</em>.aidl
// Note that standard comment syntax is respected.
// Comments before the import or package statements are not bubbled up
// to the generated interface, but comments above interface/method/field
// declarations are added to the generated interface.
// Include your fully-qualified package statement.
package com.android.sample;
// See the list above for which classes need
// import statements (hint--most of them)
import com.android.sample.IAtmService;
// Declare the interface.
interface IBankAccountService {
// Methods can take 0 or more parameters, and
// return a value or void.
int getAccountBalance();
void setOwnerNames(in List&lt;String&gt; names);
// Methods can even take other AIDL-defined parameters.
BankAccount createAccount(in String name, int startingDeposit, in IAtmService atmService);
// All non-Java primitive parameters (e.g., int, bool, etc) require
// a directional tag indicating which way the data will go. Available
// values are in, out, inout. (Primitives are in by default, and cannot be otherwise).
// Limit the direction to what is truly needed, because marshalling parameters
// is expensive.
int getCustomerList(in String branch, out String[] customerList);
}</pre>
<h3 id="implementtheinterface">Implementing the Interface</h3>
<p>AIDL generates an interface file for you with the same name as your .aidl
file. If you are using the Eclipse plugin, AIDL will automatically be run as part of
the build process (you don't need to run AIDL first and then build your project).
If you are not using the plugin, you should run AIDL first. </p>
<p>The generated interface
includes an abstract inner class named Stub that declares all the methods
that you declared in your .aidl file. Stub also defines a few helper methods,
most notably asInterface(), which takes an IBinder (passed to a client's onServiceConnected()
implementation when applicationContext.bindService() succeeds), and returns an
instance of the interface used to call the IPC methods. See the section
<a href="#calling">Calling an IPC Method</a> for more details on how to make this cast.</p>
<p>To implement your interface, extend <em>YourInterface</em>.Stub,
and implement the methods. (You can create the .aidl file and implement the stub
methods without building between--the Android build process will process .aidl
files before .java files.) </p>
<p>Here is an example of implementing an interface called IRemoteService, which exposes
a single method, getPid(), using an anonymous instance:</p>
<pre>// No need to import IRemoteService if it's in the same project.
private final IRemoteService.Stub mBinder = new IRemoteService.Stub(){
public int getPid(){
return Process.myPid();
}
}</pre>
<p>A few rules about implementing your interface: </p>
<ul>
<li>No exceptions that you throw will be sent back to the caller.</li>
<li>By default, IPC calls are synchronous. If you know that an IPC service takes more than
a few milliseconds to complete, you should not call it in the Activity/View thread,
because it might hang the application (Android might display an &quot;Application
is Not Responding&quot; dialog).
Try to call them in a separate thread. </li>
<li>Only methods are supported; you cannot declare static fields in an AIDL interface.</li>
</ul>
<h3 id="exposingtheinterface">Exposing Your Interface to Clients</h3>
<p>Now that you've got your interface implementation, you need to expose it to clients.
This is known as &quot;publishing your service.&quot; To publish a service,
inherit {@link android.app.Service Service} and implement {@link android.app.Service#onBind
Service.onBind(Intent)} to return an instance of the class that implements your interface.
Here's a code snippet of a service that exposes the IRemoteService
interface to clients. </p>
<pre>public class RemoteService extends Service {
...
{@include development/samples/ApiDemos/src/com/example/android/apis/app/RemoteService.java
exposing_a_service}
}</pre>
<h3 id="parcelable">Pass by value Parameters using Parcelables</h3>
<p>If you have a class that you would like to send from one process to another through
an AIDL interface, you can do that. You must ensure that the code for your class is available
to the other side of the IPC. Generally, that means that you're talking to a service that you
started.</p>
<p>There are five parts to making a class support the Parcelable protocol:</b>
<ol>
<li>Make your class implement the {@link android.os.Parcelable} interface.</li>
<li>Implement the method <code>public void writeToParcel(Parcel out)</code> that takes the
current state of the object and writes it to a parcel.</li>
value in a parcel into your object.</li>
<li>Add a static field called <code>CREATOR</code> to your class which is an object implementing
the {@link android.os.Parcelable.Creator Parcelable.Creator} interface.</li>
<li>Last but not least, create an aidl file
that declares your parcelable class (as shown below). If you are using a custom build process,
do not add the aidl file to your build. Similar to a header file in C, the aidl file isn't
compiled.</li>
</ol>
<p>AIDL will use these methods and fields in the code it generates to marshall and unmarshall
your objects.</p>
<p>Here is an example of how the {@link android.graphics.Rect} class implements the
Parcelable protocol.</p>
<pre class="prettyprint">
import android.os.Parcel;
import android.os.Parcelable;
public final class Rect implements Parcelable {
public int left;
public int top;
public int right;
public int bottom;
public static final Parcelable.Creator&lt;Rect&gt; CREATOR = new Parcelable.Creator&lt;Rect&gt;() {
public Rect createFromParcel(Parcel in) {
return new Rect(in);
}
public Rect[] newArray(int size) {
return new Rect[size];
}
};
public Rect() {
}
private Rect(Parcel in) {
readFromParcel(in);
}
public void writeToParcel(Parcel out) {
out.writeInt(left);
out.writeInt(top);
out.writeInt(right);
out.writeInt(bottom);
}
public void readFromParcel(Parcel in) {
left = in.readInt();
top = in.readInt();
right = in.readInt();
bottom = in.readInt();
}
}
</pre>
<p>Here is Rect.aidl for this example</p>
<pre class="prettyprint">
package android.graphics;
// Declare Rect so AIDL can find it and knows that it implements
// the parcelable protocol.
parcelable Rect;
</pre>
<p>The marshalling in the Rect class is pretty simple. Take a look at the other
methods on {@link android.os.Parcel} to see the other kinds of values you can write
to a Parcel.</p>
<p class="warning"><b>Warning:</b> Don't forget the security implications of receiving data from
other processes. In this case, the rect will read four numbers from the parcel,
but it is up to you to ensure that these are within the acceptable range of
values for whatever the caller is trying to do. See
<a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a> for more
on how to keep your application secure from malware.</p>
<h2 id="calling">Calling an IPC Method</h2>
<p>Here are the steps a calling class should make to call your remote interface: </p>
<ol>
<li>Declare a variable of the interface type that your .aidl file defined. </li>
<li>Implement {@link android.content.ServiceConnection ServiceConnection}. </li>
<li>Call {@link android.content.Context#bindService(android.content.Intent,android.content.ServiceConnection,int)
Context.bindService()}, passing in your ServiceConnection implementation. </li>
<li>In your implementation of {@link android.content.ServiceConnection#onServiceConnected(android.content.ComponentName,android.os.IBinder)
ServiceConnection.onServiceConnected()}, you will receive an {@link android.os.IBinder
IBinder} instance (called <em>service</em>). Call <code><em>YourInterfaceName</em>.Stub.asInterface((IBinder)<em>service</em>)</code> to
cast the returned parameter to <em>YourInterface</em> type.</li>
<li>Call the methods that you defined on your interface. You should always trap
{@link android.os.DeadObjectException} exceptions, which are thrown when
the connection has broken; this will be the only exception thrown by remote
methods.</li>
<li>To disconnect, call {@link android.content.Context#unbindService(android.content.ServiceConnection)
Context.unbindService()} with the instance of your interface. </li>
</ol>
<p>A few comments on calling an IPC service:</p>
<ul>
<li>Objects are reference counted across processes. </li>
<li>You can send anonymous objects
as method arguments. </li>
</ul>
<p>Here is some sample code demonstrating calling an AIDL-created service, taken
from the Remote Service sample in the ApiDemos project.</p>
<p>{@sample development/samples/ApiDemos/src/com/example/android/apis/app/RemoteService.java
calling_a_service}</p>
base/docs/html/guide/developing/tools/avd.jd
+447
View File
@@ -0,0 +1,447 @@
page.title=Android Virtual Devices
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>AVD quickview</h2>
<ul>
<li>You need to create an AVD to run any app in the Android emulator</li>
<li>Each AVD is a completely independent virtual device, with its own
hardware options, system image, and data storage.
<li>You create AVD configurations to model different device environments
in the Android emulator.</li>
<li>You can launch a graphical Android AVD Manager either through Eclipse or
through the <code>android</code> tool. The <code>android</code> tool also offers
a command-line interface for creating and managing AVDs.</li> </ul>
<h2>In this document</h2>
<ol>
<li><a href="#creating">Creating an AVD</a>
<ol>
<li><a href="#hardwareopts">Setting hardware emulation options</a></li>
<li><a href="#location">Default location of the AVD files</a></li>
</ol>
</li>
<li><a href="#managing">Managing AVDs</a>
<ol>
<li><a href="#moving">Moving an AVD</a></li>
<li><a href="#updating">Updating an AVD</a></li>
<li><a href="#deleting">Deleting an AVD</a></li>
</ol>
</li>
<li><a href="#options">Command-line options</a></li>
</ol>
<h2>See Also</h2>
<ol>
<li><a href="{@docRoot}guide/developing/tools/emulator.html">Android
Emulator</a></li>
</ol>
</div>
</div>
<p>Android Virtual Devices (AVDs) are configurations of emulator options that let
you better model an actual device.</p>
<p>Each AVD is made up of: </p>
<ul>
<li>A hardware profile.&nbsp;&nbsp;You can set options to define the hardware
features of the virtual device. For example, you can define whether the device
has a camera, whether it uses a physical QWERTY keyboard or a dialing pad, how
much memory it has, and so on. </li>
<li>A mapping to a system image.&nbsp;&nbsp;You can define what version of the
Android platform will run on the virtual device. You can choose a version of the
standard Android platform or the system image packaged with an SDK add-on.</li>
<li>Other options.&nbsp;&nbsp;You can specify the emulator skin you want to use
with the AVD, which lets you control the screen dimensions, appearance, and so
on. You can also specify the emulated SD card to use with the AVD.</li>
<li>A dedicated storage area on your development machine, in which is stored the
device's user data (installed applications, settings, and so on) and emulated SD
card.</li>
</ul>
<p>You can create as many AVDs as you need, based on the types of devices you
want to model and the Android platforms and external libraries you want to run
your application on. </p>
<p>In addition to the options in an AVD configuration, you can also
specify emulator command-line options at launch or by using the emulator
console to change behaviors or characteristics at run time. For a complete
reference of emulator options, please see the <a
href="{@docRoot}guide/developing/tools/emulator.html">Emulator</a>
documentation. </p>
<p>The easiest way to create an AVD is to use the graphical AVD Manager, which
you can launch from Eclipse or from the command line using the
<code>android</code> tool. The <code>android</code> tool is provided in the
<code>tools/</code> directory of the Android SDK. When you run the
<code>android</code> tool without options, it launches the graphical AVD
Manager.</p>
<p>For more information about how to work with AVDs from inside your development
environment, see <a
href="{@docRoot}guide/developing/eclipse-adt.html">Developing in Eclipse with
ADT</a> or <a href="{@docRoot}guide/developing/other-ide.html">Developing in
Other IDEs</a>, as appropriate for your environment.</p>
<h2 id="creating">Creating an AVD</h2>
<div class="sidebox-wrapper">
<div class="sidebox">
<p>The Android SDK does not include any preconfigured AVDs, so
you need to create an AVD before you can run any application in the emulator
(even the Hello World application).</p>
</div>
</div>
<p>The easiest way to create an AVD is to use the graphical AVD Manager, but the
<code>android</code> tool also offers a <a href="#options">command line option</a>.</p>
<p>To create an AVD:</p>
<ol>
<li>In Eclipse, choose <strong>Window &gt; Android SDK and AVD Manager</strong>. </li>
<p>Alternatively, you can launch the graphical AVD Manager by running the
<code>android</code> tool with no options.</p>
<li>Select <strong>Virtual Devices</strong> in the left panel.</li>
<li>Click <strong>New</strong>. </li>
<p>The <strong>Create New AVD</strong> dialog appears.</p> <a
href="{@docRoot}images/developing/avd-dialog.png"><img
src="{@docRoot}images/developing/avd-dialog.png" alt="AVD
Dialog" /></a>
<li>Type the name of the AVD, such as "my_avd".</li>
<li>Choose a target. </li>
<p>The target is the system image that you want to run on the emulator,
from the set of platforms that are installed in your SDK environment. You can
choose a version of the standard Android platform or an SDK add-on. For more
information about how to add platforms to your SDK, see <a
href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a>. </p>
<li>Optionally specify any additional settings: </li>
<dl>
<dt><em>SD Card</em></dt> <dd>The path to the SD card image to use with this
AVD, or the size of a new SD card image to create for this AVD.</dd> </dl>
<dt><em>Skin</em></dt>
<dd>The skin to use for this AVD, identified by name or dimensions.</dd>
<dt><em>Hardware</em></dt>
<dd>The hardware emulation options for the device. For a list of the options, see
<a href="#hardwareopts">Setting hardware emulation options</a>.</dd>
</dl>
<li>Click <strong>Create AVD</strong>.</li>
</ol>
<h3 id="hardwareopts">Setting hardware emulation options</h3>
<p>When you create a new AVD that uses a standard Android system image ("Type:
platform"), the AVD Manager
lets you set hardware emulation
options for your virtual device.
The table below lists the options available and the
default values, as well as the names of properties that store the emulated
hardware options in the AVD's configuration file (the <code>config.ini</code> file in the
AVD's local directory). </p>
<table>
<tr>
<th>Characteristic</th>
<th>Description</th>
<th>Property</th>
</tr>
<tr>
<td>Device ram size</td>
<td>The amount of physical RAM on the device, in megabytes. Default value is "96".
<td>hw.ramSize</td>
</tr>
<tr>
<td>Touch-screen support</td>
<td>Whether there is a touch screen or not on the device. Default value is "yes".</td>
<td>hw.touchScreen
<tr>
<td>Trackball support </td>
<td>Whether there is a trackball on the device. Default value is "yes".</td>
<td>hw.trackBall</td>
</tr>
<tr>
<td>Keyboard support</td>
<td>Whether the device has a QWERTY keyboard. Default value is "yes".</td>
<td>hw.keyboard</td>
</tr>
<tr>
<td>DPad support</td>
<td>Whether the device has DPad keys. Default value is "yes".</td>
<td>hw.dPad</td>
</tr>
<tr>
<td>GSM modem support</td>
<td>Whether there is a GSM modem in the device. Default value is "yes".</td>
<td>hw.gsmModem</td>
</tr>
<tr>
<td>Camera support</td>
<td>Whether the device has a camera. Default value is "no".</td>
<td>hw.camera</td>
</tr>
<tr>
<td>Maximum horizontal camera pixels</td>
<td>Default value is "640".</td>
<td>hw.camera.maxHorizontalPixels</td>
</tr>
<tr>
<td>Maximum vertical camera pixels</td>
<td>Default value is "480".</td>
<td>hw.camera.maxVerticalPixels</td>
</tr>
<tr>
<td>GPS support</td>
<td>Whether there is a GPS in the device. Default value is "yes".</td>
<td>hw.gps</td>
</tr>
<tr>
<td>Battery support</td>
<td>Whether the device can run on a battery. Default value is "yes".</td>
<td>hw.battery</td>
</tr>
<tr>
<td>Accelerometer</td>
<td>Whether there is an accelerometer in the device. Default value is "yes".</td>
<td>hw.accelerometer</td>
</tr>
<tr>
<td>Audio recording support</td>
<td>Whether the device can record audio. Default value is "yes".</td>
<td>hw.audioInput</td>
</tr>
<tr>
<td>Audio playback support</td>
<td>Whether the device can play audio. Default value is "yes".</td>
<td>hw.audioOutput</td>
</tr>
<tr>
<td>SD Card support</td>
<td>Whether the device supports insertion/removal of virtual SD Cards. Default value is "yes".</td>
<td>hw.sdCard</td>
</tr>
<tr>
<td>Cache partition support</td>
<td>Whether we use a /cache partition on the device. Default value is "yes".</td>
<td>disk.cachePartition</td>
</tr>
<tr>
<td>Cache partition size</td>
<td>Default value is "66MB".</td>
<td>disk.cachePartition.size </td>
</tr>
<tr>
<td>Abstracted LCD density</td>
<td>Sets the generalized density characteristic used by the AVD's screen. Most
skins come with a value (which you can modify), but if a skin doesn't provide
its own value, the default is 160. </td>
<td>hw.lcd.density </td>
</tr>
<tr>
<td>Max VM application heap size</td>
<td>The maximum heap size a Dalvik application might allocate before being
killed by the system. Value is in megabytes. Most skins come with a value (which
you can modify), but if a skin doesn't provide its own value, the default is
16.</td>
<td>vm.heapSize</td>
</tr>
</table>
<h3 id="location">Default location of the AVD files</h3>
<p>When you create an AVD, the AVD Manager creates a dedicated directory for it
on your development computer. The directory contains the AVD configuration file,
the user data image and SD card image (if available), and any other files
associated with the device. Note that the directory does not contain a system
image &mdash; instead, the AVD configuration file contains a mapping to the
system image, which it loads when the AVD is launched. </p>
<p>The AVD Manager also creates a <code>&lt;AVD name&gt;.ini</code> file for the
AVD at the root of the <code>.android/avd</code> directory on your computer. The file
specifies the location of the AVD directory and always remains at the root the
.android directory.</p>
<p>By default, the AVD Manager creates the AVD directory inside
<code>~/.android/avd/</code> (on Linux/Mac), <code>C:\Documents and
Settings\&lt;user&gt;\.android\</code> on Windows XP, and
<code>C:\Users\&lt;user&gt;\.android\</code> on Windows Vista.
If you want to use a custom location for the AVD directory, you
can do so by using the <code>-p &lt;path&gt;</code> option when
you create the AVD (command line tool only): </p>
<pre>android create avd -n my_android1.5 -t 2 -p path/to/my/avd</pre>
<p>If the <code>.android</code> directory is hosted on a network drive, we recommend using
the <code>-p</code> option to place the AVD directory in another location.
The AVD's <code>.ini</code> file remains in the <code>.android</code> directory on the network
drive, regardless of the location of the AVD directory. </p>
<h2 id="managing">Managing AVDs</h2>
<p>The sections below provide more information about how to manage AVDs once you've created them. </p>
<h3 id="moving">Moving an AVD</h3>
<p>If you want to move or rename an AVD, you can do so using this command:</p>
<pre>android move avd -n &lt;name&gt; [-&lt;option&gt; &lt;value&gt;] ...</pre>
<p>The options for this command are listed in <a href="#options">Command-line
options for AVDs</a> at the bottom of this page. </p>
<h3 id="updating">Updating an AVD</h3>
<p>
If you rename or move the root directory of a platform (or add-on), an AVD configured to use that platform will no longer be able to load the system image properly. To fix the AVD, use the <strong>Repair...</strong> button in the AVD Manager. From the command line, you can also use the <code>android update avd</code> command to recompute the path to the system images.</p>
<h3 id="deleting">Deleting an AVD</h3>
<p>You can delete an AVD in the AVD Manager by selecting the
AVD and clicking <strong>Delete</strong>.</p>
<p>Alternatively, you can use the <code>android</code> tool to delete an AVD. Here is the command usage:</p>
<pre>android delete avd -n &lt;name&gt; </pre>
<p>When you issue the command, the <code>android</code> tool looks for an AVD matching the
specified name deletes the AVD's directory and files. </p>
<h2 id="options">Command-line options</h2>
<p>You can use the <code>android</code> tool to create and manage AVDs.</p>
<p>The command line for creating an AVD has the following syntax:</p>
<pre>
android create avd -n &lt;name&gt; -t &lt;targetID&gt; [-&lt;option&gt; &lt;value&gt;] ...
</pre>
<p>Here's an example that creates an AVD with the name "my_android2.2" and target ID "3":</p>
<pre>
android create avd -n my_android2.2 -t 3
</pre>
<p>The table below lists the command-line options you can use with the
<code>android</code> tool. </p>
<table>
<tr>
<th width="15%">Action</th>
<th width="20%">Option</th>
<th width="30%">Description</th>
<th>Comments</th>
</tr>
<tr>
<td><code>list&nbsp;avds</code></td>
<td>&nbsp;</td>
<td>List all known AVDs, with name, path, target, and skin. </td>
<td>&nbsp;</td>
</tr>
<tr>
<td rowspan="6"><code>create&nbsp;avd</code></td>
<td><code>-n &lt;name&gt; or <br></code></td>
<td>The name for the AVD.</td>
<td>Required</td>
</tr>
<tr>
<td><code>-t &lt;targetID&gt;</code></td>
<td>Target ID of the system image to use with the new AVD.</td>
<td>Required. To obtain a list of available targets, use <code>android list
targets</code>.</td>
</tr>
<tr>
<td><code>-c &lt;path&gt;</code> or <br>
<code>-c &lt;size&gt;[K|M]</code></td>
<td>The path to the SD card image to use with this AVD or the size of a new SD
card image to create for this AVD.</td>
<td>Examples: <code>-c path/to/sdcard</code> or <code>-c 1000M</code></td>
</tr>
<tr>
<td><code>-f</code></td>
<td>Force creation of the AVD</td>
<td>By default, if the name of the AVD being created matches that of an
existing AVD, the <code>android</code> tool will not create the new AVD or overwrite
the existing AVD. If you specify the <code>-f</code> option, however, the
<code>android</code> tool will automatically overwrite any existing AVD that has the
same name as the new AVD. The files and data of the existing AVD are
deleted. </td>
</tr>
<tr>
<td><code>-p &lt;path&gt;</code></td>
<td>Path to the location at which to create the directory for this AVD's
files.</td>
<td>&nbsp;</td>
</tr>
<tr>
<td><code>-s &lt;name&gt;</code> or <br>
<code>-s &lt;width&gt;-&lt;height&gt;</code> </td>
<td>The skin to use for this AVD, identified by name or dimensions.</td>
<td>The <code>android</code> tool scans for a matching skin by name or dimension in the
<code>skins/</code> directory of the target referenced in the <code>-t
&lt;targetID&gt;</code> argument. Example: <code>-s HVGA-L</code></td>
</tr>
<tr>
<td><code>delete&nbsp;avd</code></td>
<td><code>-n &lt;name&gt;</code></td>
<td>Delete the specified AVD.</td>
<td>Required</td>
</tr>
<tr>
<td rowspan="3"><code>move&nbsp;avd</code></td>
<td><code>-n &lt;name&gt;</code></td>
<td>The name of the AVD to move.</td>
<td>Required</td>
</tr>
<tr>
<td><code>-p &lt;path&gt;</code></td>
<td>The path to the new location for the AVD.</td>
<td>&nbsp;</td>
</tr>
<tr>
<td><code>-r &lt;new-name&gt;</code></td>
<td>Rename the AVD.</td>
<td>&nbsp;</td>
</tr>
<tr>
<td><code>update&nbsp;avds</code></td>
<td>&nbsp;</td>
<td>Recompute the paths to all system images.</td>
<td>&nbsp;</td>
</tr>
</table>
base/docs/html/guide/developing/tools/bmgr.jd
+191
View File
@@ -0,0 +1,191 @@
page.title=bmgr
@jd:body
<!-- quickview box content here -->
<div id="qv-wrapper">
<div id="qv">
<h2>bmgr quickview</h2>
<p><code>bmgr</code> lets you control the backup/restore system on an Android device.
<h2>In this document</h2>
<ol>
<li><a href="#backup">Forcing a Backup Operation</a></li>
<li><a href="#restore">Forcing a Restore Operation</a></li>
<li><a href="#other">Other Commands</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}guide/topics/data/backup.html">Data Backup</a></li>
</ol>
</div>
</div>
<!-- normal page content here -->
<p><code>bmgr</code> is a shell tool you can use to interact with the Backup Manager
on Android devices supporting API Level 8 or greater. It provides commands to induce backup
and restore operations so that you don't need to repeatedly wipe data or take similar
intrusive steps in order to test your application's backup agent. These commands are
accessed via the <a href="{@docRoot}guide/developing/tools/adb.html">adb</a> shell.
<p>For information about adding support for backup in your application, read <a
href="{@docRoot}guide/topics/data/backup.html">Data Backup</a>, which includes a guide to testing
your application using {@code bmgr}.</p>
<h2 id="backup">Forcing a Backup Operation</h2>
<p>Normally, your application must notify the Backup Manager when its data has changed, via {@link
android.app.backup.BackupManager#dataChanged()}. The Backup Manager will then invoke your
backup agent's {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} implementation at some time in the future. However, instead of calling {@link
android.app.backup.BackupManager#dataChanged()}, you can invoke a backup request from the command
line by running the <code>bmgr backup</code> command:
<pre class="no-pretty-print">adb shell bmgr backup <em>&lt;package&gt;</em></pre>
<p><code><em>&lt;package&gt;</em></code> is the formal package name of the application you wish to
schedule for
backup. When you execute this backup command, your application's backup agent will be invoked to
perform a backup operation at some time in the future (via your {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} method), though there is no guarantee when it will occur. However, you can force all
pending backup operations to run immediately by using the <code>bmgr run</code> command:
<pre class="no-pretty-print">adb shell bmgr run</pre>
<p>This causes a backup pass to execute immediately, invoking the backup agents of all applications
that had previously called {@link android.app.backup.BackupManager#dataChanged()} since the
last backup operation, plus any applications which had been manually scheduled for
backup via <code>bmgr backup</code>.
<h2 id="restore">Forcing a Restore Operation</h2>
<p>Unlike backup operations, which are batched together and run on an occasional basis, restore
operations execute immediately. The Backup Manager currently provides two kinds of restore
operations. The first kind restores an entire device with the data that has been backed up. This
is typically performed only when a device is first provisioned (to replicate settings and other
saved state from the user's previous device) and is an operation that only the system can
perform. The second kind of restore operation restores
a single application to its "active" data set; that is, the application will abandon its current
data and revert to the last-known-good data that is held in the current backup image. You can
invoke this second restore operation with the {@link
android.app.backup.BackupManager#requestRestore(RestoreObserver) requestRestore()} method. The
Backup Manager will then invoke your backup agent's {@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor)
onRestore()} implementation.
<p>While testing your application, you can immediately invoke the restore operation (bypassing the
{@link android.app.backup.BackupManager#requestRestore(RestoreObserver) requestRestore()} method)
for your application by using the <code>bmgr restore</code> command:
<pre class="no-pretty-print">adb shell bmgr restore <em>&lt;package&gt;</em></pre>
<p><code><em>&lt;package&gt;</em></code> is the formal Java-style package name of the application
participating in the backup/restore mechanism, which you would like to restore. The Backup
Manager will immediately instantiate the application's backup agent and invoke it for restore. This
will happen even if your application is not currently running.
<h2 id="other">Other Commands</h2>
<h3>Wiping data</h3>
<p>The data for a single application can be erased from the active data set on demand. This is
very useful while you're developing a backup agent, in case bugs lead you to write corrupt data
or saved state information. You can wipe an application's data with the <code>bmgr wipe</code>
command:
<pre class="no-pretty-print">adb shell bmgr wipe <em>&lt;package&gt;</em></pre>
<p><code><em>&lt;package&gt;</em></code> is the formal package name of the application whose data
you wish to
erase. The next backup operation that the application's agent processes will look as
though the application had never backed anything up before.
<h3>Enabling and disabling backup</h3>
<p>You can see whether the Backup Manager is operational at all with the <code>bmgr
enabled</code> command:
<pre class="no-pretty-print">adb shell bmgr enabled</pre>
<p>This might be useful if your application's backup agent is never being invoked for backup, to
verify whether the operating system thinks it should be performing such operations at all.</p>
<p>You can also directly disable or enable the Backup Manager with this command:
<pre class="no-pretty-print">adb shell bmgr enable <em>&lt;boolean&gt;</em></pre>
<p><code><em>&lt;boolean&gt;</em></code> is either <code>true</code> or <code>false</code>.
This is equivalent to disabling or enabling backup in the device's main Settings UI.</p>
<p class="warning"><strong>Warning!</strong> When backup is disabled, the current backup transport
will explicitly wipe
the entire active data set from its backend storage. This is so that when a user says
they do <em>not</em> want their data backed up, the Backup Manager respects that wish. No further
data will be saved from the device, and no restore operations will be possible, unless the Backup
Manager is re-enabled (either through Settings or through the above <code>bmgr</code> command).
<!-- The following is not useful to applications, but may be some useful information some day...
<h2 id="transports">Applying a Backup Transport</h2>
<p>A "backup transport" is the code module responsible for moving backup and restore data
to and from some storage location. A device can have multipe transports installed, though only
one is active at any given time. Transports are identified by name. You can see what
transports are available on your device or emulator by running the
<code>bmgr list transports</code> command:
<pre class="no-pretty-print">adb shell bmgr list transports</pre>
<p>The output of this command is a list of the transports available on the device. The currently
active transport is flagged with a <code>*</code> character. Transport names may look like
component names (for example, <code>android/com.android.internal.backup.LocalTransport</code>),
but they need not be, and the strings are never used as direct class references. The use of
a component-like naming scheme is simply for purposes of preventing name collisions.
<p>You can change which transport is currently active from the command line as well:
<pre class="no-pretty-print">adb shell bmgr transport <em>&lt;name&gt;</em></pre>
<p><code><em>&lt;name&gt;</em></code> is one of the names as printed by the <code>bmgr list
transports</code>
command. From this point forward, backup and restore operations will be directed through the
newly-selected transport. Backup state tracking is managed separately for each transport, so
switching back and forth between them will not corrupt the saved state.
<h2 id="restoresets">Viewing Restore Sets</h2>
<p>All of the application data that a device has written to its backup transport is tracked
as a group that is collectively called a "restore set," because each data set is
most often manipulated during a restore operation. When a device is provisioned for the first
time, a new restore set is established. You can get a listing of all the restore sets available to
the current transport by running the <code>bmgr list sets</code> command:
<pre class="no-pretty-print">adb shell bmgr list sets</pre>
<p>The output is a listing of available restore sets, one per line. The first item on each line is
a token (a hexadecimal value that identifies the restore set to the transport). Following
the token is a string that briefly identifies the restore set.
Only the token is used within the backup and restore mechanism.
-->
base/docs/html/guide/developing/tools/ddms.jd
+251
View File
@@ -0,0 +1,251 @@
page.title=Using the Dalvik Debug Monitor
@jd:body
<p>Android ships with a debugging tool called the Dalvik Debug Monitor Server (DDMS),
which provides port-forwarding services, screen capture on the device, thread
and heap information on the device, logcat, process, and radio state information,
incoming call and SMS spoofing, location data spoofing, and more. This page
provides a modest discussion of DDMS features; it is not an exhaustive exploration of
all the features and capabilities.</p>
<p>DDMS ships in the <code>tools/</code> directory of the SDK.
Enter this directory from a terminal/console and type <code>ddms</code> (or <code>./ddms</code>
on Mac/Linux) to run it. DDMS will work with both the emulator and a connected device. If both are
connected and running simultaneously, DDMS defaults to the emulator.</p>
<h2 id="how-ddms-works">How DDMS works</h2>
<p>DDMS acts as a middleman to connect the IDE to the applications running on
the device. On Android, every application runs in its own process,
each of which hosts its own virtual machine (VM). And each process
listens for a debugger on a different port.</p>
<p>When it starts, DDMS connects to <a href="{@docRoot}guide/developing/tools/adb.html">adb</a> and
starts a device monitoring service between the two, which will notify DDMS when a device is
connected or disconnected. When a device is connected, a VM monitoring service is created
between adb and DDMS, which will notify DDMS when a VM on the device is started
or terminated. Once a VM is running, DDMS retrieves the the VM's process ID (pid), via adb,
and opens a connection to the VM's debugger, through the adb daemon (adbd) on the device.
DDMS can now talk to the VM using a custom wire protocol.</p>
<p>For each VM on the device, DDMS opens a port upon which it will listen for a debugger. For the first VM, DDMS listens for a debugger on port 8600, the next on 8601, and so on. When a debugger connects to one of these ports, all traffic is forwarded between the debugger and the associated VM. Debugging can then process like any remote debugging session.</p>
<p>DDMS also opens another local port, the DDMS "base port" (8700, by default), upon which it also listens for a debugger. When a debugger connects to this base port, all traffic is forwarded to the VM currently selected in DDMS, so this is typically where you debugger should connect.</p>
<p>For more information on port-forwarding with DDMS,
read <a href="{@docRoot}guide/developing/debug-tasks.html#ide-debug-port">Configuring your IDE to attach
to port 8700 for debugging</a>.</p>
<p class="note"><strong>Tip:</strong>
You can set a number of DDMS preferences in <strong>File</strong> > <strong>Preferences</strong>.
Preferences are saved to &quot;$HOME/.ddmsrc&quot;. </p>
<p class="warning"><strong>Known debugging issues with Dalvik</strong><br/>
Debugging an application in the Dalvik VM should work the same as it does
in other VMs. However, when single-stepping out of synchronized code, the "current line"
cursor may jump to the last line in the method for one step.</p>
<h2 id="left-pane">Left Pane</h2>
<p>The left side of the Debug Monitor shows each emulator/device currently found, with a list of
all the VMs currently running within each.
VMs are identified by the package name of the application it hosts.</p>
<p>Use this list to find and attach to the VM
running the activity(ies) that you want to debug. Next to each VM in the
list is a &quot;debugger pass-through&quot; port (in the right-most column).
If you connect your debugger to one of the the ports listed, you
will be connected to the corresponding VM on the device. However, when using
DDMS, you need only connect to port 8700, as DDMS forwards all traffic here to the
currently selected VM. (Notice, as you select a VM in the list, the listed port includes 8700.)
This way, there's no need to reconfigure the debugger's port each time you switch between VMs.</p>
<p>When an application running on the device calls {@link android.os.Debug#waitForDebugger()}
(or you select this option in the <a href="{@docRoot}guide/developing/debug-tasks.html#additionaldebugging">developer
options</a>), a red icon will be shown next to the client name, while it waits for the
debugger to attach to the VM. When a debugger is connected, the icon will turn green. </p>
<p>If you see a crossed-out bug icon, this means that the DDMS was unable to complete a
connection between the debugger and the VM because it was unable to open the VM's local port.
If you see this for all VMs on the device, it is likely because you have another instance of
DDMS running (this includes the Eclipse plugin).</p>
<p>If you see a question mark in place of an application package, this means that,
once DDMS received the application pid from adb, it
somehow failed to make a successful handshake with the VM process. Try restarting DDMS.</p>
<h2 id="right-pane">Right pane</h2>
<p>On the right side, the Debug Monitor provides tabs that display useful information
and some pretty cool tools.</p>
<h3 id="info">Info</h3>
<p>This view shows some general information about the selected VM, including the process
ID, package name, and VM version.</p>
<h3 id="threads">Threads</h3>
<p> The threads view has a list of threads running in the process of the target VM.
To reduce the amount
of data sent over the wire, the thread updates are only sent when explicitly
enabled by toggling the &quot;threads&quot; button
in the toolbar. This toggle is maintained per VM. This tab includes the following
information: </p>
<ul>
<li> <strong>ID</strong> - a VM-assigned unique thread ID. In Dalvik, these are
odd numbers starting from 3. </li>
<li> <strong>Tid</strong> - the Linux thread ID. For the main thread in a process,
this will match the process ID. </li>
<li> <strong>Status</strong> - the VM thread status. Daemon threads are
shown with an asterisk (*). This will be one of the following:
<ul>
<li> <em>running</em> - executing application code </li>
<li> <em>sleeping</em> - called Thread.sleep() </li>
<li> <em>monitor</em> - waiting to acquire a monitor lock </li>
<li> <em>wait</em> - in Object.wait() </li>
<li> <em>native</em> - executing native code </li>
<li> <em>vmwait</em> - waiting on a VM resource </li>
<li> <em>zombie</em> - thread is in the process of dying </li>
<li> <em>init</em> - thread is initializing (you shouldn't see this) </li>
<li> <em>starting</em> - thread is about to start (you shouldn't see
this either) </li>
</ul>
</li>
<li> <strong>utime</strong> - cumulative time spent executing user code, in &quot;jiffies&quot; (usually
10ms). </li>
<li> <strong>stime</strong> - cumulative time spent executing system code, in &quot;jiffies&quot; (usually
10ms). </li>
<li> <strong>Name</strong> - the name of the thread</li>
</ul>
<p> &quot;ID&quot; and &quot;Name&quot; are set when the thread is started. The remaining
fields are updated periodically (default is every 4 seconds). </p>
<h3 id="vm-heap">VM Heap</h3>
<p> Displays some heap stats, updated during garbage collection. If, when a VM is selected,
the VM Heap view says that heap updates are not enabled, click the "Show heap updates" button,
located in the top-left toolbar. Back in the VM Heap view, click <strong>Cause GC</strong>
to perform garbage collection and update the heap stats.</p>
<h3 id="allocation-tracker">Allocation Tracker</h3>
<p>In this view, you can track the memory allocation of each virtual machine.
With a VM selected in the left pane, click <strong>Start Tracking</strong>, then
<strong>Get Allocations</strong> to view all allocations since tracking started.
The table below will be filled with all the relevant
data. Click it again to refresh the list.</p>
<h3 id="emulator-control">Emulator Control</h3>
<p>With these controls, you can simulate special device states and activities.
Features include:</p>
<ul>
<li><strong>Telephony Status</strong> - change the state of the phone's Voice and Data plans
(home, roaming, searching, etc.), and simulate different kinds of network Speed and Latency
(GPRS, EDGE, UTMS, etc.).</li>
<li><strong>Telephony Actions</strong> - perform simulated phone calls and SMS messages to the emulator.</li>
<li><strong>Location Controls</strong> - send mock location data to the emulator so that you can perform
location-aware operations like GPS mapping.
<p>To use the Location Controls, launch your application in the Android emulator and open DDMS.
Click the Emulator Controls tab and scroll down to Location Controls.
From here, you can:</p>
<ul class="listhead">
<li>Manually send individual longitude/latitude coordinates to the device.
<p>Click <strong>Manual</strong>,
select the coordinate format, fill in the fields and click <strong>Send</strong>.
</p>
</li>
<li>Use a GPX file describing a route for playback to the device.
<p>Click <strong>GPX</strong> and load the file. Once loaded,
click the play button to playback the route for your location-aware application.</p>
<p>When performing playback from GPX, you can adjust the speed of
playback from the DDMS panel and control playback with the pause and skip buttons.
DDMS will parse both the waypoints (<code>&lt;wpt></code>, in the first table),
and the tracks (<code>&lt;trk></code>,
in the second table, with support for multiple segments, <code>&lt;trkseg></code>,
although they are simply
concatenated). Only the tracks can be played. Clicking a waypoint in the first list simply
sends its coordinate to the device, while selecting a track lets you play it.</p>
</li>
<li>Use a KML file describing individual placemarks for sequenced playback to the device.
<p>Click <strong>KML</strong> and load the file. Once loaded,
click the play button to send the coordinates to your location-aware application.</p>
<p>When using a KML file, it is parsed for a <code>&lt;coordinates&gt;</code>
element. The value of which should be a single
set of longitude, latitude and altitude figures. For example:</p>
<pre>&lt;coordinates>-122.084143,37.421972,4&lt;/coordinates></pre>
<p>In your file, you may include multiple <code>&lt;Placemark></code> elements, each containing
a <code>&lt;coordinates></code> element. When you do so, the collection of placemarks will
be added as tracks. DDMS will send one placemark per second to the device.</p>
<p>One way to generate a suitable KML file is to find a location in Google Earth.
Right-click the location entry that appears on the left and select "Save place as..."
with the save format set to Kml.</p>
<p class="note"><strong>Note:</strong> DDMS does not support routes created with the
<code>&lt;MultiGeometry>&lt;LineString>lat1, long1, lat2, long2, ....&lt;/LineString>&lt;/MultiGeometry></code> methods.
There is also currently no support for the <code>&lt;TimeStamp></code> node inside
the <code>&lt;Placemark></code>.
Future releases may support timed placement and routes within a single coordinate element.</p>
</li>
</ul>
<p>For <em>additional</em> methods of setting up mocks of location-based data, see the
<a href="{@docRoot}guide/topics/location/index.html">Location</a> topic.</p>
</li>
</ul>
<!-- <h4>Event Log</h4> -->
<h2 id="file-explorer">File Explorer</h2>
<p>With the File Explorer, you can view the device file system and perform basic management,
like pushing and pulling files. This circumvents using the <a href="{@docRoot}guide/developing/tools/adb.html">adb</a>
<code>push</code> and <code>pull</code> commands, with a GUI experience.</p>
<p>With DDMS open, select <strong>Device</strong> > <strong>File Explorer...</strong> to open the
File Explorer window. You can drag-and-drop into the device directories, but cannot drag <em>out</em> of them.
To copy files from the device, select the file and click the <strong>Pull File from Device</strong>
button in the toolbar. To delete files, use the <strong>Delete</strong> button in the toolbar.</p>
<p>If you're interested in using an SD card image on the emulator, you're still required to use
the <code>mksdcard</code> command to create an image, and then mount it during emulator bootup.
For example, from the <code>/tools</code> directory, execute:</p>
<pre>
<b>$</b> mksdcard 1024M ./img
<b>$</b> emulator -sdcard ./img
</pre>
<p>Now, when the emulator is running, the DDMS File Explorer will be able to read and write to the
sdcard directory. However, your files may not appear automatically. For example, if you add an
MP3 file to the sdcard, the media player won't see them until you restart the emulator. (When restarting
the emulator from command line, be sure to mount the sdcard again.)</p>
<p>For more information on creating an SD card image, see the
<a href="{@docRoot}guide/developing/tools/othertools.html#mksdcard">Other Tools</a> document.</p>
<h2 id="screen-capture">Screen Capture</h2>
<p>You can capture screen images on the device or emulator by selecting <strong>Device</strong>
&gt; <strong>Screen capture...</strong> in the menu bar, or press CTRL-S.
Be sure to select a device first.</p>
<h2 id="exploring-processes">Exploring Processes</h2>
<p>You can see the output of <code>ps -x</code> for a specific VM by selecting <strong>Device</strong>
&gt; <strong>Show process status</strong>... in the menu bar.</p>
<h2 id="cause-a-gc-to-occur">Cause a GC to Occur</h2>
<p>Cause garbage collection to occur in the selected application by pressing the trash can button on the toolbar. </p>
<h2 id="running-dumpsys-and-dumpstate">Running Dumpsys and Dumpstate on the Device (logcat)<a name="logcat" id="logcat"></a> </h2>
<ul>
<li>To run <strong>dumpsys</strong> (logcat) from Dalvik, select <strong>Device</strong> &gt;
<strong>Run logcat...</strong> in the menu bar.</li>
<li>To run <strong>dumpstate</strong> from Dalvik, select <strong>Device</strong> &gt; <strong>Dump device
state...</strong> in the menu bar. </li>
</ul>
<h2 id="examine-radio-state">Examine Radio State</h2>
<p>By default, radio state is not output during a standard logcat (it is a lot of
information). To see radio information, either click <strong>Device</strong> &gt; <strong>Dump radio
state...</strong> or run logcat as described in <a href="{@docRoot}guide/developing/debug-tasks.html#logradio">Logging
Radio Information</a>. </p>
<h2 id="stop-a-vitrual-machine">Stop a Virtual Machine </h2>
<p>You can stop a virtual machine by selecting <strong>Actions</strong> &gt; <strong>Halt
VM</strong>. Pressing this button causes the VM to call <code>Runtime.halt(1)</code>.</p>
<h2 id="known-issues" style="color:#FF0000">Known issues with DDMS </h2>
<p>DDMS has the following known limitations:</p>
<ul>
<li>If you connect and disconnect a debugger, ddms drops and reconnects the
client so the VM realizes that the debugger has gone away. This will be fixed
eventually. </li>
</ul>
base/docs/html/guide/developing/tools/draw9patch.jd
+57
View File
@@ -0,0 +1,57 @@
page.title=Draw 9-patch
@jd:body
<p>The Draw 9-patch tool allows you to easily create a
{@link android.graphics.NinePatch} graphic using a WYSIWYG editor.</p>
<p>For an introduction to Nine-patch graphics and how they work, please read
the section about Nine-patch in the
<a href="{@docRoot}guide/topics/graphics/2d-graphics.html#nine-patch">2D Graphics</a>
document.</p>
<img src="{@docRoot}images/draw9patch-norm.png" style="float:right" alt="" height="300" width="341"
/>
<p>Here's a quick guide to create a Nine-patch graphic using the Draw 9-patch tool.
You'll need the PNG image with which you'd like to create a NinePatch.</p>
<ol>
<li>From a terminal, launch the <code>draw9patch</code> application from your SDK
<code>/tools</code> directory.
</li>
<li>Drag your PNG image into the Draw 9-patch window
(or <strong>File</strong> > <strong>Open 9-patch...</strong> to locate the file).
Your workspace will now open.
<p>The left pane is your drawing area, in which you can edit the lines for the
stretchable patches and content area. The right
pane is the preview area, where you can preview your graphic when stretched.</p>
</li>
<li>Click within the 1-pixel perimeter to draw the lines that define the stretchable
patches and (optional) content area. Right-click (or hold Shift and click, on Mac) to erase
previously drawn lines.
</li>
<li>When done, select <strong>File</strong> > <strong>Save 9-patch...</strong>
<p>Your image will be saved with the <code>.9.png</code> file name.</p>
</li>
</ol>
<p class="note"><strong>Note:</strong> A normal PNG file (<code>*.png</code>) will be
loaded with an empty one-pixel border added around the image, in which you can draw
the stretchable patches and content area.
A previously saved 9-patch file (<code>*.9.png</code>) will be loaded as-is,
with no drawing area added, because it already exists.</p>
<img src="{@docRoot}images/draw9patch-bad.png" style="float:right" alt="" height="300" width="341"
/>
<p>Optional controls include:</p>
<ul>
<li><strong>Zoom</strong>: Adjust the zoom level of the graphic in the drawing area.</li>
<li><strong>Patch scale</strong>: Adjust the scale of the images in the preview area.</li>
<li><strong>Show lock</strong>: Visualize the non-drawable area of the graphic on mouse-over.</li>
<li><strong>Show patches</strong>: Preview the stretchable patches in the drawing area (pink is a
stretchable patch).</li>
<li><strong>Show content</strong>: Highlight the content area in the preview images
(purple is the area in which content is allowed).</li>
<li><strong>Show bad patches</strong>: Adds a red border around patch areas that may
produce artifacts in the graphic when stretched. Visual coherence of your stretched
image will be maintained if you eliminate all bad patches.</li>
<ul>
base/docs/html/guide/developing/tools/emulator.jd
+1771
View File
File diff suppressed because it is too large Load Diff
base/docs/html/guide/developing/tools/hierarchy-viewer.jd
+98
View File
@@ -0,0 +1,98 @@
page.title=Hierarchy Viewer
@jd:body
<p>The Hierarchy Viewer application allows you to debug and optimize your user
interface. It provides a visual representation of the layout's View hierarchy
(the Layout View) and a magnified inspector of the display (the Pixel Perfect View).
</p>
<p>To get the Hierarchy Viewer started:</p>
<ol>
<li>Connect your device or launch an emulator.</li>
<li>From a terminal, launch <code>hierarchyviewer</code> from your SDK
<code>/tools</code> directory.
</li>
<li>In the window that opens, you'll see a list of <strong>Devices</strong>. When a device is
selected, a list of currently active <strong>Windows</strong> is displayed
on the right. The <em>&lt;Focused Window></em> is the window currently in
the foreground, and also the default window loaded if you do not select another.
</li>
<li>Select the window that you'd like to inspect and click
<strong>Load View Hierarchy</strong>. The Layout View will be loaded.
You can then load the Pixel Perfect View by clicking the second
icon at the bottom-left of the window.
</li>
</ol>
<p>If you've navigated to a different window on the device, press <strong>Refresh Windows</strong>
to refresh the list of available windows on the right.</p>
<h2>Layout View</h2>
<p>The Layout View offers a look at the View layout and properties. It has three views:</p>
<ul>
<li>Tree View: a hierarchy diagram of the Views, on the left.</li>
<li>Properties View: a list of the selected View's properties, on the top-right.</li>
<li>Wire-frame View: a wire-frame drawing of the layout, on the bottom-right.</li>
</ul>
<br/>
<img src="{@docRoot}images/hierarchyviewer-layout.png" alt="" height="509" width="700" />
<p>Select a node in the Tree View to display the properties of that element in
the Properties View. When a node is selected, the Wire-frame View
also indicates the bounds of the element with a red rectangle.
Double click a node in the tree (or select it, and click <strong>Display
View</strong>) to open a new window with a rendering of that element.</p>
<p>The Layout View includes a couple other helpful features for debugging your layout:
<strong>Invalidate</strong> and <strong>Request Layout</strong>. These buttons execute the
respective View calls, {@link android.view.View#invalidate()} and {@link android.view.View#requestLayout()},
on the View element currently selected in the tree. Calling these methods on any View can
be very useful when simultaneously running a debugger on your application.</p>
<p>The Tree View can be resized by adjusting the zoom slider, below
the diagram. The number of View elements in the window is also given here. You
should look for ways to minimize the number of Views. The fewer View elements there
are in a window, the faster it will perform.</p>
<p>If you interact with the device and change the focused View, the diagram will not automatically refresh.
You must reload the Layout View by clicking <strong>Load View Hierarchy</strong>.
<h2>Pixel Perfect View</h2>
<p>The Pixel Perfect View provides a magnified look at the current device window. It has three views:</p>
<ul>
<li>Explorer View: shows the View hierarchy as a list, on the left.</li>
<li>Normal View: a normal view of the device window, in the middle.</li>
<li>Loupe View: a magnified, pixel-grid view of the device window, on the right.</li>
</ul>
<br/>
<img src="{@docRoot}images/hierarchyviewer-pixelperfect.png" alt="" height="509" width="700" />
<p>Click on an element in the Explorer View and a "layout box" will be drawn in the
Normal View to indicate the layout position of that element. The layout box uses multiple rectangles, to indicate the normal bounds, the padding and the margin (as needed). The purple or green rectangle indicates
the normal bounds of the element (the height and width). The inner white or black rectangle indicates
the content bounds, when padding is present. A black or white rectangle outside the normal purple/green
rectangle indicates any present margins.
(There are two colors for each rectangle, in order to provide the best contrast
based on the colors currently in the background.)</p>
<p>A very handy feature for designing your UI is the ability to overlay an image in the Normal and Loupe
Views. For example, you might have a mock-up image of how you'd like to layout your interface.
By selecting <strong>Load...</strong> from the controls in the Normal View, you can choose the
image from your computer and it will be placed atop the preview. Your chosen image will anchor at the bottom left corner of the screen. You can then adjust the opacity of the overlay and begin fine-tuning your layout to match the mock-up.</p>
<p>The Normal View and Loupe View refresh at regular intervals (5 seconds by default), but the
Explorer View does not. If you navigate away and focus on a different View, then you should refresh the
Explorer's hierarchy by clicking <strong>Load View Hierarchy</strong>. This is even true
when you're working in a window that holds multiple Views that are not always visible. If you do not,
although the previews will refresh, clicking a View in the Explorer will not provide the proper layout box
in the Normal View, because the hierarchy believes you are still focused on the prior View.</p>
<p>Optional controls include:</p>
<ul>
<li><strong>Overlay</strong>: Load an overlay image onto the view and adjust its opacity.</li>
<li><strong>Refresh Rate</strong>: Adjust how often the Normal and Loupe View refresh their display.</li>
<li><strong>Zoom</strong>: Adjust the zoom level of the Loupe View.</li>
</ul>
base/docs/html/guide/developing/tools/index.jd
+109
View File
@@ -0,0 +1,109 @@
page.title=Tools Overview
@jd:body
<img src="{@docRoot}assets/images/android_wrench.png" alt="" align="right">
<p>The Android SDK includes a variety of custom tools that help you develop mobile
applications on the Android platform. The most important of these are the Android
Emulator and the Android Development Tools plugin for Eclipse, but the SDK also
includes a variety of other tools for debugging, packaging, and installing your
applications on the emulator. </p>
<dl>
<dt><a href="adt.html">Android Development Tools Plugin</a> (for the Eclipse IDE)</dt>
<dd>The ADT plugin adds powerful extensions to the Eclipse integrated environment,
making creating and debugging your Android applications easier and faster. If you
use Eclipse, the ADT plugin gives you an incredible boost in developing Android
applications.</dd>
<dt><a href="emulator.html">Android Emulator</a></dt>
<dd>A QEMU-based device-emulation tool that you can use to design,
debug, and test your applications in an actual Android run-time environment. </dd>
<dt><a href="avd.html">Android Virtual Devices (AVDs)</a></dt>
<dd>Virtual device configurations that you create, to model device
characteristics in the Android Emulator. In each configuration, you can
specify the Android platform to run, the hardware options, and the
emulator skin to use. Each AVD functions as an independent device with
it's own storage for user data, SD card, and so on. </dd>
<dt><a href="hierarchy-viewer.html">Hierarchy Viewer</a></dt>
<dd>The Hierarchy Viewer tool allows you to debug and optimize your user interface.
It provides a visual representation of your layout's hierarchy of Views and a magnified inspector
of the current display with a pixel grid, so you can get your layout just right.
</dd>
<dt><a href="layoutopt.html">layoutopt</a></dt>
<dd>This tool lets you quickly analyze your application's layouts for
efficiency.
</dd>
<dt><a href="draw9patch.html">Draw 9-patch</a></dt>
<dd>The Draw 9-patch tool allows you to easily create a
{@link android.graphics.NinePatch} graphic using a WYSIWYG editor. It also previews stretched
versions of the image, and highlights the area in which content is allowed.
</dd>
<dt><a href="ddms.html" >Dalvik Debug Monitor
Service</a> (ddms)</dt>
<dd>Integrated with Dalvik, the Android platform's custom VM, this tool
lets you manage processes on an emulator or device and assists in debugging.
You can use it to kill processes, select a specific process to debug,
generate trace data, view heap and thread information, take screenshots
of the emulator or device, and more. </dd>
<dt><a href="adb.html" >Android Debug Bridge</a> (adb)</dt>
<dd>The adb tool lets you install your application's .apk files on an
emulator or device and access the emulator or device from a command line.
You can also use it to link a standard debugger to application code running
on an Android emulator or device.
<p>This is located in {@code &lt;sdk&gt;/platform-tools/}.</p></dd>
<dt><a href="aapt.html">Android Asset
Packaging Tool</a> (aapt)</dt>
<dd>The aapt tool lets you create .apk files containing the binaries and
resources of Android applications.</dd>
<dt><a href="aidl.html" >Android Interface
Description Language</a> (aidl)</dt>
<dd>Lets you generate code for an interprocess interface, such as what
a service might use.</dd>
<dt><a href="adb.html#sqlite">sqlite3</a></dt>
<dd>Included as a convenience, this tool lets you access the SQLite data
files created and used by Android applications.</dd>
<dt><a href="traceview.html" >Traceview</a></dt>
<dd> This tool produces graphical analysis views of trace log data that you
can generate from your Android application. </dd>
<dt><a href="othertools.html#mksdcard">mksdcard</a></dt>
<dd>Helps you create a disk image that you can use with the emulator,
to simulate the presence of an external storage card (such as an SD card).</dd>
<dt><a href="othertools.html#dx">dx</a></dt>
<dd>The dx tool rewrites .class bytecode into Android bytecode
(stored in .dex files.)</dd>
<dt><a href="monkey.html">UI/Application
Exerciser Monkey</a></dt>
<dd>The Monkey is a program that runs on your emulator or device and generates pseudo-random
streams of user events such as clicks, touches, or gestures, as well as a number of system-
level events. You can use the Monkey to stress-test applications that you are developing,
in a random yet repeatable manner.</dd>
<dt><a href="monkeyrunner_concepts.html">monkeyrunner</a></dt>
<dd>
The monkeyrunner tool provides an API for writing Python programs that control an Android device
or emulator from outside of Android code.
</dd>
<dt><a href="othertools.html#android">android</a></dt>
<dd>A script that lets you manage AVDs and generate <a
href="http://ant.apache.org/" title="Ant">Ant</a> build files that
you can use to compile your Android applications. </dd>
<dt><a href="zipalign.html">zipalign</a></dt>
<dd>An important .apk optimization tool. This tool ensures that all uncompressed data starts
with a particular alignment relative to the start of the file. This should always be used
to align .apk files after they have been signed.</dd>
</dl>
base/docs/html/guide/developing/tools/layoutopt.jd
+62
View File
@@ -0,0 +1,62 @@
page.title=layoutopt
@jd:body
<p><code>layoutopt</code> is a command-line tool that helps you optimize the
layouts and layout hierarchies of your applications. You can run it against your
layout files or resource directories to quickly check for inefficiencies or
other types of problems that could be affecting the performance of your
application. </p>
<p>To run the tool, open a terminal and launch <code>layoutopt
&lt;resources&gt;</code> from your SDK <code>tools/</code> directory. In the
command, supply a list of uncompiled resource xml files or directories that you
want to analyze. </p>
<p>When run, the tool loads the specified XML files and analyzes their layout
structures and hierarchies according to a set of predefined rules. If it detects
issues, it outputs information about the issues, giving filename, line numbers,
description of issue, and for some types of issues a suggested resolution. </p>
<p>Here's an example of the output:</p>
<pre>$ layoutopt samples/
samples/compound.xml
7:23 The root-level &lt;FrameLayout/&gt; can be replaced with &lt;merge/&gt;
11:21 This LinearLayout layout or its FrameLayout parent is useless
samples/simple.xml
7:7 The root-level &lt;FrameLayout/&gt; can be replaced with &lt;merge/&gt;
samples/too_deep.xml
-1:-1 This layout has too many nested layouts: 13 levels, it should have &lt= 10!
20:81 This LinearLayout layout or its LinearLayout parent is useless
24:79 This LinearLayout layout or its LinearLayout parent is useless
28:77 This LinearLayout layout or its LinearLayout parent is useless
32:75 This LinearLayout layout or its LinearLayout parent is useless
36:73 This LinearLayout layout or its LinearLayout parent is useless
40:71 This LinearLayout layout or its LinearLayout parent is useless
44:69 This LinearLayout layout or its LinearLayout parent is useless
48:67 This LinearLayout layout or its LinearLayout parent is useless
52:65 This LinearLayout layout or its LinearLayout parent is useless
56:63 This LinearLayout layout or its LinearLayout parent is useless
samples/too_many.xml
7:413 The root-level &lt;FrameLayout/&gt; can be replaced with &lt;merge/&gt;
-1:-1 This layout has too many views: 81 views, it should have &lt= 80!
samples/useless.xml
7:19 The root-level &lt;FrameLayout/&gt; can be replaced with &lt;merge/&gt;
11:17 This LinearLayout layout or its FrameLayout parent is useless</pre>
<p>The <code>layoutopt</code> tool is available in SDK Tools, Revision 3 or
later. If you do not have SDK Tools r3 or later installed in your SDK, you can
download it from the Android SDK repository site using the Android SDK and AVD
Manager. For information, see <a
href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a>.</p>
<h3>Usage</h3>
<p>To run <code>layoutopt</code> against a given list of layout resources:</p>
<pre>layoutopt &lt;list of xml files or directories></pre>
<p>For example:</p>
<pre>$ layoutopt res/layout-land</pre>
<pre>$ layoutopt res/layout/main.xml res/layout-land/main.xml</pre>
base/docs/html/guide/developing/tools/monkey.jd
+240
View File
@@ -0,0 +1,240 @@
page.title=UI/Application Exerciser Monkey
@jd:body
<p>The Monkey is a program that runs on your
<a href="{@docRoot}guide/developing/tools/emulator.html">emulator</a> or device and generates pseudo-random
streams of user events such as clicks, touches, or gestures, as well as a number of system-level
events. You can use the Monkey to stress-test applications that you are developing, in a random
yet repeatable manner.</p>
<a name="overview"></a>
<h2>Overview</h2>
<p>The Monkey is a command-line tool that that you can run on any emulator
instance or on a device. It sends a pseudo-random stream of
user events into the system, which acts as a stress test on the application software you are
developing.</p>
<p>The Monkey includes a number of options, but they break down into four primary
categories:</p>
<ul>
<li>Basic configuration options, such as setting the number of events to attempt.</li>
<li>Operational constraints, such as restricting the test to a single package.</li>
<li>Event types and frequencies.</li>
<li>Debugging options.</li>
</ul>
<p>When the Monkey runs, it generates events and sends them to the system. It also <i>watches</i>
the system under test and looks for three conditions, which it treats specially:</p>
<ul>
<li>If you have constrained the Monkey to run in one or more specific packages, it
watches for attempts to navigate to any other packages, and blocks them.</li>
<li>If your application crashes or receives any sort of unhandled exception, the Monkey
will stop and report the error.</li>
<li>If your application generates an <i>application not responding</i> error, the Monkey
will stop and report the error.</li>
</ul>
<p>Depending on the verbosity level you have selected, you will also see reports on the progress
of the Monkey and the events being generated.</p>
<a name="basics"></a>
<h2>Basic Use of the Monkey</h2>
<p>You can launch the Monkey using a command line on your development machine or from a script.
Because the Monkey runs in the emulator/device environment, you must launch it from a shell in
that environment. You can do this by prefacing <code>adb shell</code> to each command,
or by entering the shell and entering Monkey commands directly.</p>
<p>The basic syntax is: </p>
<pre>$ adb shell monkey [options] &lt;event-count&gt;</pre>
<p>With no options specified, the Monkey will launch in a quiet (non-verbose) mode, and will send
events to any (and all) packages installed on your target. Here is a more typical command line,
which will launch your application and send 500 pseudo-random events to it:</p>
<pre>$ adb shell monkey -p your.package.name -v 500</pre>
<a name="reference"></a>
<h2>Command Options Reference</h2>
<p>The table below lists all options you can include on the Monkey command line.</p>
<table>
<tr>
<th>Category</th>
<th>Option</th>
<th>Description</th>
</tr>
<tr>
<td rowspan="2">General</td>
<td><code>--help</code></td>
<td>Prints a simple usage guide.</td>
</tr>
<tr>
<td><code>-v</code></td>
<td>Each -v on the command line will increment the verbosity level.
Level 0 (the default) provides little information beyond startup notification, test completion, and
final results.
Level 1 provides more details about the test as it runs, such as individual events being sent to
your activities.
Level 2 provides more detailed setup information such as activities selected or not selected for
testing.</td>
</tr>
<tr>
<td rowspan="10">Events</td>
<td><code>-s &lt;seed&gt;</code></td>
<td>Seed value for pseudo-random number generator. If you re-run the Monkey with the same seed
value, it will generate the same sequence of events.</td>
</tr>
<tr>
<td><code>--throttle &lt;milliseconds&gt;</code></td>
<td>Inserts a fixed delay between events. You can use this option to slow down the Monkey.
If not specified, there is no delay and the events are generated as rapidly as possible.</td>
</tr>
<tr>
<td><code>--pct-touch &lt;percent&gt;</code></td>
<td>Adjust percentage of touch events.
(Touch events are a down-up event in a single place on the screen.)</td>
</tr>
<tr>
<td><code>--pct-motion &lt;percent&gt;</code></td>
<td>Adjust percentage of motion events.
(Motion events consist of a down event somewhere on the screen, a series of pseudo-random
movements, and an up event.)</td>
</tr>
<tr>
<td><code>--pct-trackball &lt;percent&gt;</code></td>
<td>Adjust percentage of trackball events.
(Trackball events consist of one or more random movements, sometimes followed by a click.)</td>
</tr>
<tr>
<td><code>--pct-nav &lt;percent&gt;</code></td>
<td>Adjust percentage of "basic" navigation events.
(Navigation events consist of up/down/left/right, as input from a directional input device.)</td>
</tr>
<tr>
<td><code>--pct-majornav &lt;percent&gt;</code></td>
<td>Adjust percentage of "major" navigation events.
(These are navigation events that will typically cause actions within your UI, such as
the center button in a 5-way pad, the back key, or the menu key.)</td>
</tr>
<tr>
<td><code>--pct-syskeys &lt;percent&gt;</code></td>
<td>Adjust percentage of "system" key events.
(These are keys that are generally reserved for use by the system, such as Home, Back, Start Call,
End Call, or Volume controls.)</td>
</tr>
<tr>
<td><code>--pct-appswitch &lt;percent&gt;</code></td>
<td>Adjust percentage of activity launches. At random intervals, the Monkey will issue a startActivity() call, as a way of maximizing
coverage of all activities within your package.</td>
</tr>
<tr>
<td><code>--pct-anyevent &lt;percent&gt;</code></td>
<td>Adjust percentage of other types of events. This is a catch-all for all other types of events such as keypresses, other less-used
buttons on the device, and so forth.</td>
</tr>
<tr>
<td rowspan="2">Constraints</td>
<td><code>-p &lt;allowed-package-name&gt;</code></td>
<td>If you specify one or more packages this way, the Monkey will <i>only</i> allow the system
to visit activities within those packages. If your application requires access to activities in
other packages (e.g. to select a contact) you'll need to specify those packages as well.
If you don't specify any packages, the Monkey will allow the system to launch activities
in all packages. To specify multiple packages, use the -p option multiple times &mdash; one -p
option per package.</td>
</tr>
<tr>
<td><code>-c &lt;main-category&gt;</code></td>
<td>If you specify one or more categories this way, the Monkey will <i>only</i> allow the
system to visit activities that are listed with one of the specified categories.
If you don't specify any categories, the Monkey will select activities listed with the category
Intent.CATEGORY_LAUNCHER or Intent.CATEGORY_MONKEY. To specify multiple categories, use the -c
option multiple times &mdash; one -c option per category.</td>
</tr>
<tr>
<td rowspan="8">Debugging</td>
<td><code>--dbg-no-events</code></td>
<td>When specified, the Monkey will perform the initial launch into a test activity, but
will not generate any further events.
For best results, combine with -v, one or more package constraints, and a non-zero throttle to keep the Monkey
running for 30 seconds or more. This provides an environment in which you can monitor package
transitions invoked by your application.</td>
</tr>
<tr>
<td><code>--hprof</code></td>
<td>If set, this option will generate profiling reports immediately before and after
the Monkey event sequence.
This will generate large (~5Mb) files in data/misc, so use with care. See
<a href="{@docRoot}guide/developing/tools/traceview.html" title="traceview">Traceview</a> for more information
on trace files.</td>
</tr>
<tr>
<td><code>--ignore-crashes</code></td>
<td>Normally, the Monkey will stop when the application crashes or experiences any type of
unhandled exception. If you specify this option, the Monkey will continue to send events to
the system, until the count is completed.</td>
</tr>
<tr>
<td><code>--ignore-timeouts</code></td>
<td>Normally, the Monkey will stop when the application experiences any type of timeout error such
as a "Application Not Responding" dialog. If you specify this option, the Monkey will continue to
send events to the system, until the count is completed.</td>
</tr>
<tr>
<td><code>--ignore-security-exceptions</code></td>
<td>Normally, the Monkey will stop when the application experiences any type of permissions error,
for example if it attempts to launch an activity that requires certain permissions. If you specify
this option, the Monkey will continue to send events to the system, until the count is
completed.</td>
</tr>
<tr>
<td><code>--kill-process-after-error</code></td>
<td>Normally, when the Monkey stops due to an error, the application that failed will be left
running. When this option is set, it will signal the system to stop the process in which the error
occurred.
Note, under a normal (successful) completion, the launched process(es) are not stopped, and
the device is simply left in the last state after the final event.</td>
</tr>
<tr>
<td><code>--monitor-native-crashes</code></td>
<td>Watches for and reports crashes occurring in the Android system native code. If --kill-process-after-error is set, the system will stop.</td>
</tr>
<tr>
<td><code>--wait-dbg</code></td>
<td>Stops the Monkey from executing until a debugger is attached to it.</td>
</tr>
</table>
<!-- TODO: add a section called "debugging" that covers ways to use it,
need to clear data, use of the seed, etc. -->
<!-- TODO: add a section that lays down a contract for Monkey output so it can be
scripted safely. -->
base/docs/html/guide/developing/tools/monkeyrunner_concepts.jd
+308
View File
@@ -0,0 +1,308 @@
page.title=monkeyrunner
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li>
<a href="#SampleProgram">A Simple monkeyrunner Program</a>
</li>
<li>
<a href="#APIClasses">The monkeyrunner API</a>
</li>
<li>
<a href="#RunningMonkeyRunner">Running monkeyrunner</a>
</li>
<li>
<a href="#Help">monkeyrunner Built-in Help</a>
</li>
<li>
<a href="#Plugins">Extending monkeyrunner with Plugins</a>
</li>
</ol>
<h2>See Also</h2>
<ol>
<li>
<a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Fundamentals</a>
</li>
</ol>
</div>
</div>
<p>
The monkeyrunner tool provides an API for writing programs that control an Android device
or emulator from outside of Android code. With monkeyrunner, you can write a Python program
that installs an Android application or test package, runs it, sends keystrokes to it,
takes screenshots of its user interface, and stores screenshots on the workstation. The
monkeyrunner tool is primarily designed to test applications and devices at the
functional/framework level and for running unit test suites, but you are free to use it for
other purposes.
</p>
<p>
The monkeyrunner tool is not related to the
<a href="{@docRoot}guide/developing/tools/monkey.html">UI/Application Exerciser Monkey</a>,
also known as the <code>monkey</code> tool. The <code>monkey</code> tool runs in an
<code><a href="{@docRoot}guide/developing/tools/adb.html">adb</a></code> shell directly on the
device or emulator and generates pseudo-random streams of user and system events. In comparison,
the monkeyrunner tool controls devices and emulators from a workstation by sending specific
commands and events from an API.
</p>
<p>
The monkeyrunner tool provides these unique features for Android testing:
</p>
<ul>
<li>
Multiple device control: The monkeyrunner API can apply one or more
test suites across multiple devices or emulators. You can physically attach all the devices
or start up all the emulators (or both) at once, connect to each one in turn
programmatically, and then run one or more tests. You can also start up an emulator
configuration programmatically, run one or more tests, and then shut down the emulator.
</li>
<li>
Functional testing: monkeyrunner can run an automated start-to-finish test of an Android
application. You provide input values with keystrokes or touch events, and view the results
as screenshots.
</li>
<li>
Regression testing - monkeyrunner can test application stability by running an application
and comparing its output screenshots to a set of screenshots that are known to be correct.
</li>
<li>
Extensible automation - Since monkeyrunner is an API toolkit, you can develop an entire
system of Python-based modules and programs for controlling Android devices. Besides using
the monkeyrunner API itself, you can use the standard Python
<code><a href="http://docs.python.org/library/os.html">os</a></code> and
<code><a href="http://docs.python.org/library/subprocess.html">subprocess</a></code>
modules to call Android tools such as
<a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a>.
<p>
You can also add your own classes to the monkeyrunner API. This is described
in more detail in the section
<a href="#Plugins">Extending monkeyrunner with plugins</a>.
</p>
</li>
</ul>
<p>
The monkeyrunner tool uses <a href="http://www.jython.org/">Jython</a>, a
implementation of Python that uses the Java programming language. Jython allows the
monkeyrunner API to interact easily with the Android framework. With Jython you can
use Python syntax to access the constants, classes, and methods of the API.
</p>
<h2 id="SampleProgram">A Simple monkeyrunner Program</h2>
<p>
Here is a simple monkeyrunner program that connects to a device, creating a
<code><a href="{@docRoot}guide/developing/tools/MonkeyDevice.html">MonkeyDevice</a></code>
object. Using the <code>MonkeyDevice</code> object, the program installs an Android application
package, runs one of its activities, and sends key events to the activity.
The program then takes a screenshot of the result, creating a
<code><a href="{@docRoot}guide/developing/tools/MonkeyImage.html">MonkeyImage</a></code> object.
From this object, the program writes out a <code>.png</code> file containing the screenshot.
</p>
<pre>
# Imports the monkeyrunner modules used by this program
from com.android.monkeyrunner import MonkeyRunner, MonkeyDevice
# Connects to the current device, returning a MonkeyDevice object
device = MonkeyRunner.waitForConnection()
# Installs the Android package. Notice that this method returns a boolean, so you can test
# to see if the installation worked.
device.installPackage('myproject/bin/MyApplication.apk')
# Runs an activity in the application
device.startActivity(component='com.example.android.myapplication.MainActivity')
# Presses the Menu button
device.press('KEYCODE_MENU','DOWN_AND_UP')
# Takes a screenshot
result = device.takeSnapShot
# Writes the screenshot to a file
result.writeToFile('myproject/shot1.png','png')
</pre>
<h2 id="APIClasses">The monkeyrunner API</h2>
<p>
The monkeyrunner API is contained in three modules in the package
<code>com.android.monkeyrunner</code>:
</p>
<ul>
<li>
<code><a href="{@docRoot}guide/developing/tools/MonkeyRunner.html">MonkeyRunner</a></code>:
A class of utility methods for monkeyrunner programs. This class provides a method for
connecting monkeyrunner to a device or emulator. It also provides methods for
creating UIs for a monkeyrunner program and for displaying the built-in help.
</li>
<li>
<code><a href="{@docRoot}guide/developing/tools/MonkeyDevice.html">MonkeyDevice</a></code>:
Represents a device or emulator. This class provides methods for installing and
uninstalling packages, starting an Activity, and sending keyboard or touch events to an
application. You also use this class to run test packages.
</li>
<li>
<code><a href="{@docRoot}guide/developing/tools/MonkeyImage.html">MonkeyImage</a></code>:
Represents a screen capture image. This class provides methods for capturing screens,
converting bitmap images to various formats, comparing two MonkeyImage objects, and
writing an image to a file.
</li>
</ul>
<p>
In a Python program, you access each class as a Python module. The monkeyrunner tool
does not import these modules automatically. To import a module, use the
Python <code>from</code> statement:
</p>
<pre>
from com.android.monkeyrunner import &lt;module&gt;
</pre>
<p>
where <code>&lt;module&gt;</code> is the class name you want to import. You can import more
than one module in the same <code>from</code> statement by separating the module names with
commas.
</p>
<h2 id="RunningMonkeyRunner">Running monkeyrunner</h2>
<p>
You can either run monkeyrunner programs from a file, or enter monkeyrunner statements in
an interactive session. You do both by invoking the <code>monkeyrunner</code> command
which is found in the <code>tools/</code> subdirectory of your SDK directory.
If you provide a filename as an argument, the <code>monkeyrunner</code> command
runs the file's contents as a Python program; otherwise, it starts an interactive session.
</p>
<p>
The syntax of the <code>monkeyrunner</code> command is
</p>
<pre>
monkeyrunner -plugin &lt;plugin_jar&gt; &lt;program_filename&gt; &lt;program_options&gt;
</pre>
<p>
Table 1 explains the flags and arguments.
</p>
<p class="table-caption" id="table1">
<strong>Table 1.</strong> <code>monkeyrunner</code> flags and arguments.</p>
<table>
<tr>
<th>Argument</th>
<th>Description</th>
</tr>
<tr>
<td>
<nobr>
<code>-plugin &lt;plugin_jar&gt;</code>
</nobr>
</td>
<td>
(Optional) Specifies a <code>.jar</code> file containing a plugin for monkeyrunner.
To learn more about monkeyrunner plugins, see
<a href="#Plugins">Extending monkeyrunner with plugins</a>. To specify more than one
file, include the argument multiple times.
</td>
</tr>
<tr>
<td>
<nobr>
<code>&lt;program_filename&gt;</code>
</nobr>
</td>
<td>
If you provide this argument, the <code>monkeyrunner</code> command runs the contents
of the file as a Python program. If the argument is not provided, the command starts an
interactive session.
</td>
</tr>
<tr>
<td>
<code>&lt;program_options&gt;</code>
</td>
<td>
(Optional) Flags and arguments for the program in &lt;program_file&gt;.
</td>
</tr>
</table>
<h2 id="Help">monkeyrunner Built-in Help</h2>
<p>
You can generate an API reference for monkeyrunner by running:
</p>
<pre>
monkeyrunner &lt;format&gt; help.py &lt;outfile&gt;
</pre>
<p>
The arguments are:
</p>
<ul>
<li>
<code>&lt;format&gt;</code> is either <code>text</code> for plain text output
or <code>html</code> for HTML output.
</li>
<li>
<code>&lt;outfile&gt;</code> is a path-qualified name for the output file.
</li>
</ul>
<h2 id="Plugins">Extending monkeyrunner with Plugins</h2>
<p>
You can extend the monkeyrunner API with classes you write in the Java programming language
and build into one or more <code>.jar</code> files. You can use this feature to extend the
monkeyrunner API with your own classes or to extend the existing classes. You can also use this
feature to initialize the monkeyrunner environment.
</p>
<p>
To provide a plugin to monkeyrunner, invoke the <code>monkeyrunner</code> command with the
<code>-plugin &lt;plugin_jar&gt;</code> argument described in
<a href="#table1">table 1</a>.
</p>
<p>
In your plugin code, you can import and extend the the main monkeyrunner classes
<code>MonkeyDevice</code>, <code>MonkeyImage</code>, and <code>MonkeyRunner</code> in
<code>com.android.monkeyrunner</code> (see <a href="#APIClasses">The monkeyrunner API</a>).
</p>
<p>
Note that plugins do not give you access to the Android SDK. You can't import packages
such as <code>com.android.app</code>. This is because monkeyrunner interacts with the
device or emulator below the level of the framework APIs.
</p>
<h3>The plugin startup class</h3>
<p>
The <code>.jar</code> file for a plugin can specify a class that is instantiated before
script processing starts. To specify this class, add the key
<code>MonkeyRunnerStartupRunner</code> to the <code>.jar</code> file's
manifest. The value should be the name of the class to run at startup. The following
snippet shows how you would do this within an <code>ant</code> build script:
</p>
<pre>
&lt;jar jarfile=&quot;myplugin&quot; basedir="&#36;&#123;build.dir&#125;&quot;&gt;
&lt;manifest&gt;
&lt;attribute name=&quot;MonkeyRunnerStartupRunner&quot; value=&quot;com.myapp.myplugin&quot;/&gt;
&lt;/manifest&gt;
&lt;/jar&gt;
</pre>
<p>
To get access to monkeyrunner's runtime environment, the startup class can implement
<code>com.google.common.base.Predicate&lt;PythonInterpreter&gt;</code>. For example, this
class sets up some variables in the default namespace:
</p>
<pre>
package com.android.example;
import com.google.common.base.Predicate;
import org.python.util.PythonInterpreter;
public class Main implements Predicate&lt;PythonInterpreter&gt; {
&#64;Override
public boolean apply(PythonInterpreter anInterpreter) {
/*
* Examples of creating and initializing variables in the monkeyrunner environment's
* namespace. During execution, the monkeyrunner program can refer to the variables "newtest"
* and "use_emulator"
*
*/
anInterpreter.set("newtest", "enabled");
anInterpreter.set("use_emulator", 1);
return true;
}
}
</pre>
base/docs/html/guide/developing/tools/othertools.jd
+95
View File
@@ -0,0 +1,95 @@
page.title=Other Tools
@jd:body
<p>The sections below describe other tools that you can use when building
Android applications. </p>
<p>All of the tools are included in the Android SDK and are accessible from the
<code>&lt;sdk&gt;/tools/</code> directory.</p>
<h2>Contents</h2>
<dl>
<dt><a href="#android">android</a></dd>
<dt><a href="#mksdcard">mksdcard</a></dt>
<dt><a href="#dx">dx</a></dt>
</dl>
<a name="activitycreator"></a>
<h2 id="android">android</h2>
<p>{@code android} is an important development tool that lets you:</p>
<ul>
<li>Create, delete, and view Android Virtual Devices (AVDs). See
<a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a>.</li>
<li>Create and update Android projects. See
<a href="{@docRoot}guide/developing/other-ide.html">Developing in Other IDEs</a>.</li>
<li>Update your Android SDK with new platforms, add-ons, and documentation. See
<a href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a>.</li>
</ul>
<p>If you develop in Eclipse with the ADT plugin, you can perform
these tasks directly from the IDE. To create
Android projects and AVDs from Eclipse, see <a href="{@docRoot}guide/developing/eclipse-adt.html">Developing
In Eclipse</a>. To update your SDK from Eclipse, see
<a href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a>.
</p>
<a name="mksdcard"></a>
<h2>mksdcard</h2>
<p>The mksdcard tool lets you quickly create a FAT32 disk image that you can
load in the emulator, to simulate the presence of an SD card in the device.
Here is the usage for mksdcard:</p>
<pre>mksdcard [-l label] &lt;size&gt;[K|M] &lt;file&gt;</pre>
<p>The table below lists the available options/arguments</p>
<table>
<tr>
<th>Argument</th>
<th>Description</th>
</tr>
<tr>
<td><code>-l</code></td>
<td>A volume label for the disk image to create. </td>
</tr>
<tr>
<td><code>size</code></td>
<td>An integer that specifies the size (in bytes) of disk image to create.
You can also specify size in kilobytes or megabytes, by appending a "K" or "M" to
&lt;size&gt;. For example, <code>1048576K</code>, <code>1024M</code>.</td>
</tr>
<tr>
<td><code>file</code></td>
<td>The path/filename of the disk image to create. </td>
</tr>
</table>
<p>Once you have created the disk image file, you can load it in the emulator at
startup using the emulator's -sdcard option. For more information, see
<a href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a>.</p>
<pre>emulator -sdcard &lt;file&gt;</pre>
<a name="dx"></a>
<h2>dx</h2>
<p>The dx tool lets you generate Android bytecode from .class files. The tool
converts target files and/or directories to Dalvik executable format (.dex) files,
so that they can run in the Android environment. It can also dump the class files
in a human-readable format and run a target unit test. You can get the usage and
options for this tool by using <code>dx --help</code>.</p>
base/docs/html/guide/developing/tools/proguard.jd
+187
View File
@@ -0,0 +1,187 @@
page.title=ProGuard
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#enabling">Enabling ProGuard</a></li>
<li><a href="#configuring">Configuring ProGuard</a></li>
<li>
<a href="#decoding">Decoding Obfuscated Stack Traces</a>
<ol>
<li><a href="#considerations">Debugging considerations for published
applications</a></li>
</ol>
</li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="http://proguard.sourceforge.net/manual/introduction.html">ProGuard
Manual</a></li>
<li><a href="http://proguard.sourceforge.net/manual/retrace/introduction.html">ProGuard
ReTrace Manual</a></li>
</ol>
</div>
</div>
<p>The ProGuard tool shrinks, optimizes, and obfuscates your code by removing unused code and
renaming classes, fields, and methods with semantically obscure names. The result is a smaller
sized <code>.apk</code> file that is more difficult to reverse engineer. Because ProGuard makes your
application harder to reverse engineer, it is important that you use it
when your application utilizes features that are sensitive to security like when you are
<a href="{@docRoot}guide/publishing/licensing.html">Licensing Your Applications</a>.</p>
<p>ProGuard is integrated into the Android build system, so you do not have to invoke it
manually. ProGuard runs only when you build your application in release mode, so you do not
have to deal with obfuscated code when you build your application in debug mode.
Having ProGuard run is completely optional, but highly recommended.</p>
<p>This document describes how to enable and configure ProGuard as well as use the
<code>retrace</code> tool to decode obfuscated stack traces.</p>
<h2 id="enabling">Enabling ProGuard</h2>
<p>When you create an Android project, a <code>proguard.cfg</code> file is automatically
generated in the root directory of the project. This file defines how ProGuard optimizes and
obfuscates your code, so it is very important that you understand how to customize it for your
needs. The default configuration file only covers general cases, so you most likely have to edit
it for your own needs. See the following section about <a href="#configuring">Configuring ProGuard</a> for information on
customizing the ProGuard configuration file.</p>
<p>To enable ProGuard so that it runs as part of an Ant or Eclipse build, set the
<code>proguard.config</code> property in the <code>&lt;project_root&gt;/default.properties</code>
file. The path can be an absolute path or a path relative to the project's root.</p>
<p>If you left the <code>proguard.cfg</code> file in its default location (the project's root directory),
you can specify its location like this:</p>
<pre class="no-pretty-print">
proguard.config=proguard.cfg
</pre>
<p>
You can also move the the file to anywhere you want, and specify the absolute path to it:
</p>
<pre class="no-pretty-print">
proguard.config=/path/to/proguard.cfg
</pre>
<p>When you build your application in release mode, either by running <code>ant release</code> or
by using the <em>Export Wizard</em> in Eclipse, the build system automatically checks to see if
the <code>proguard.config</code> property is set. If it is, ProGuard automatically processes
the application's bytecode before packaging everything into an <code>.apk</code> file. Building in debug mode
does not invoke ProGuard, because it makes debugging more cumbersome.</p>
<p>ProGuard outputs the following files after it runs:</p>
<dl>
<dt><code>dump.txt</code></dt>
<dd>Describes the internal structure of all the class files in the <code>.apk</code> file</dd>
<dt><code>mapping.txt</code></dt>
<dd>Lists the mapping between the original and obfuscated class, method, and field names.
This file is important when you receive a bug report from a release build, because it
translates the obfuscated stack trace back to the original class, method, and member names.
See <a href="#decoding">Decoding Obfuscated Stack Traces</a> for more information.</dd>
<dt><code>seeds.txt</code></dt>
<dd>Lists the classes and members that are not obfuscated</dd>
<dt><code>usage.txt</code></dt>
<dd>Lists the code that was stripped from the <code>.apk</code></dd>
</ul>
<p>These files are located in the following directories:</p>
<ul>
<li><code>&lt;project_root&gt;/bin/proguard</code> if you are using Ant.</li>
<li><code>&lt;project_root&gt;/proguard</code> if you are using Eclipse.</li>
</ul>
<p class="caution"><strong>Caution:</strong> Every time you run a build in release mode, these files are
overwritten with the latest files generated by ProGuard. Save a copy of them each time you release your
application in order to de-obfuscate bug reports from your release builds.
For more information on why saving these files is important, see
<a href="#considerations">Debugging considerations for published applications</a>.
</p>
<h2 id="configuring">Configuring ProGuard</h2>
<p>For some situations, the default configurations in the <code>proguard.cfg</code> file will
suffice. However, many situations are hard for ProGuard to analyze correctly and it might remove code
that it thinks is not used, but your application actually needs. Some examples include:</p>
<ul>
<li>a class that is referenced only in the <code>AndroidManifest.xml</code> file</li>
<li>a method called from JNI</li>
<li>dynamically referenced fields and methods</li>
</ul>
<p>The default <code>proguard.cfg</code> file tries to cover general cases, but you might
encounter exceptions such as <code>ClassNotFoundException</code>, which happens when ProGuard
strips away an entire class that your application calls.</p>
<p>You can fix errors when ProGuard strips away your code by adding a <code>-keep</code> line in
the <code>proguard.cfg</code> file. For example:</p>
<pre>
-keep public class &lt;MyClass&gt;
</pre>
<p>There are many options and considerations when using the <code>-keep</code> option, so it is
highly recommended that you read the <a href="http://proguard.sourceforge.net/manual/introduction.html">ProGuard
Manual</a> for more information about customizing your configuration file. The <a href=
"http://proguard.sourceforge.net/manual/usage.html#keepoverview">Overview of Keep options</a> and
<a href="http://proguard.sourceforge.net/index.html#/manual/examples.html">Examples section</a>
are particularly helpful. The <a href=
"http://proguard.sourceforge.net/manual/troubleshooting.html">Troubleshooting</a> section of the
ProGuard Manual outlines other common problems you might encounter when your code gets stripped
away.</p>
<h2 id="decoding">Decoding Obfuscated Stack Traces</h2>
<p>When your obfuscated code outputs a stack trace, the method names are obfuscated, which makes
debugging hard, if not impossible. Fortunately, whenever ProGuard runs, it outputs a
<code>&lt;project_root&gt;/bin/proguard/mapping.txt</code> file, which shows you the original
class, method, and field names mapped to their obfuscated names.</p>
<p>The <code>retrace.bat</code> script on Windows or the <code>retrace.sh</code> script on Linux
or Mac OS X can convert an obfuscated stack trace to a readable one. It is located in the
<code>&lt;sdk_root&gt;/tools/proguard/</code> directory. The syntax for executing the
<code>retrace</code> tool is:</p>
<pre>retrace.bat|retrace.sh [-verbose] mapping.txt [&lt;stacktrace_file&gt;]</pre>
<p>For example:</p>
<pre>retrace.bat -verbose mapping.txt obfuscated_trace.txt</pre>
<p>If you do not specify a value for <em>&lt;stacktrace_file&gt;</em>, the <code>retrace</code> tool reads
from standard input.</p>
<h3 id="considerations">Debugging considerations for published applications</h3>
<p>Save the <code>mapping.txt</code> file for every release that you publish to your users.
By retaining a copy of the <code>mapping.txt</code> file for each release build,
you ensure that you can debug a problem if a user encounters a bug and submits an obfuscated stack trace.
A project's <code>mapping.txt</code> file is overwritten every time you do a release build, so you must be
careful about saving the versions that you need.</p>
<p>For example, say you publish an application and continue developing new features of
the application for a new version. You then do a release build using ProGuard soon after. The
build overwrites the previous <code>mapping.txt</code> file. A user submits a bug report
containing a stack trace from the application that is currently published. You no longer have a way
of debugging the user's stack trace, because the <code>mapping.txt</code> file associated with the version
on the user's device is gone. There are other situations where your <code>mapping.txt</code> file can be overwritten, so
ensure that you save a copy for every release that you anticipate you have to debug.</p>
<p>How you save the <code>mapping.txt</code> file is your decision. For example, you can rename them to
include a version or build number, or you can version control them along with your source
code.</p>
base/docs/html/guide/developing/tools/traceview.jd
+319
View File
@@ -0,0 +1,319 @@
page.title=Traceview: A Graphical Log Viewer
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#creatingtracefiles">Creating Trace Files</a></li>
<li><a href="#copyingfiles">Copying Trace Files to a Host Machine</a></li>
<li><a href="#runningtraceview">Viewing Trace Files in Traceview</a>
<ol>
<li><a href="#timelinepanel">Timeline Panel</a></li>
<li><a href="#profilepanel">Profile Panel</a></li>
</ol></li>
<li><a href="#format">Traceview File Format</a>
<ol>
<li><a href="#datafileformat">Data File Format</a></li>
<li><a href="#keyfileformat">Key File Format</a></li>
</ol></li>
<li><a href="#knownissues">Traceview Known Issues</a></li>
<li><a href="#dmtracedump">Using dmtracedump</a></li>
</ol>
</div>
</div>
<p>Traceview is a graphical viewer for execution logs
saved by your application. Traceview can help you debug your application and
profile its performance. The sections below describe how to use the program. </p>
<a name="creatingtracefiles"></a>
<h2>Creating Trace Files</h2>
<p>To use Traceview, you need to generate log files containing the trace information you want to analyze. To do that, you include the {@link android.os.Debug}
class in your code and call its methods to start and stop logging of trace information
to disk. When your application quits, you can then use Traceview to examine the log files
for useful run-time information such
as method calls and run times. </p>
<p>To create the trace files, include the {@link android.os.Debug} class and call one
of the {@link android.os.Debug#startMethodTracing() startMethodTracing()} methods.
In the call, you specify a base name for the trace files that the system generates.
To stop tracing, call {@link android.os.Debug#stopMethodTracing() stopMethodTracing()}.
These methods start and stop method tracing across the entire virtual machine. For
example, you could call startMethodTracing() in your activity's onCreate()
method, and call stopMethodTracing() in that activity's onDestroy() method.</p>
<pre>
// start tracing to "/sdcard/calc.trace"
Debug.startMethodTracing("calc");
// ...
// stop tracing
Debug.stopMethodTracing();
</pre>
<p>When your application calls startMethodTracing(), the system creates a
file called <code>&lt;trace-base-name>.trace</code>. This contains the
binary method trace data and a mapping table with thread and method names.</p>
<p>The system then begins buffering the generated trace data, until your application calls
stopMethodTracing(), at which time it writes the buffered data to the
output file.
If the system reaches the maximum buffer size before stopMethodTracing()
is called, the system stops tracing and sends a notification
to the console. </p>
<p>Interpreted code will run more slowly when profiling is enabled. Don't
try to generate absolute timings from the profiler results (i.e. "function
X takes 2.5 seconds to run"). The times are only
useful in relation to other profile output, so you can see if changes
have made the code faster or slower. </p>
<p>When using the Android emulator, you must create an SD card image upon which
the trace files will be written. For example, from the <code>/tools</code> directory, you
can create an SD card image named "imgcd" and mount it when launching the emulator like so:</p>
<pre>
<b>$</b> mksdcard 1024M ./imgcd
<b>$</b> emulator -sdcard ./imgcd
</pre>
<p>For more information, read about the
<a href="{@docRoot}guide/developing/tools/othertools.html#mksdcard">mksdcard tool</a>.</p>
<p>The format of the trace files is described <a href="#format">later
in this document</a>. </p>
<a name="copyingfiles"></a>
<h2>Copying Trace Files to a Host Machine</h2>
<p>After your application has run and the system has created your trace files <code>&lt;trace-base-name>.trace</code>
on a device or emulator, you must copy those files to your development computer. You can use <code>adb pull</code> to copy
the files. Here's an example that shows how to copy an example file,
calc.trace, from the default location on the emulator to the /tmp directory on
the emulator host machine:</p>
<pre>adb pull /sdcard/calc.trace /tmp</pre>
<a name="runningtraceview"></a>
<h2>Viewing Trace Files in Traceview</h2>
<p>To run traceview and view the trace files, enter <code>traceview &lt;trace-base-name></code>.
For example, to run Traceview on the example files copied in the previous section,
you would use: </p>
<pre>traceview /tmp/calc</pre>
<p>Traceview loads the log files and displays their data in a window that has two panels:</p>
<ul>
<li>A <a href="#timelinepanel">timeline panel</a> -- describes when each thread
and method started and stopped</li>
<li>A <a href="#timelinepanel">profile panel</a> -- provides a summary of what happened inside a method</li>
</ul>
<p>The sections below provide addition information about the traceview output panes. </p>
<a name="timelinepanel"></a>
<h3>Timeline Panel </h3>
<p>The image below shows a close up of the timeline panel. Each thread&rsquo;s
execution is shown in its own row, with time increasing to the right. Each method
is shown in another color (colors are reused in a round-robin fashion starting
with the methods that have the most inclusive time). The thin lines underneath
the first row show the extent (entry to exit) of all the calls to the selected
method. The method in this case is LoadListener.nativeFinished() and it was
selected in the profile view. </p>
<p><img src="/images/traceview_timeline.png" alt="Traceview timeline panel" width="893" height="284"></p>
<a name="profilepanel"></a>
<h3>Profile Panel</h3>
<p>The image below shows the profile pane. The profile pane shows a
summary of all the time spent in a method. The table shows
both the inclusive and exclusive times (as well as the percentage of the total
time). Exclusive time is the time spent in the method. Inclusive time is the
time spent in the method plus the time spent in any called functions. We refer
to calling methods as &quot;parents&quot; and called methods as &quot;children.&quot;
When a method is selected (by clicking on it), it expands to show the parents
and children. Parents are shown with a purple background and children
with a yellow background. The last column in the table shows the number of calls
to this method plus the number of recursive calls. The last column shows the
number of calls out of the total number of calls made to that method. In this
view, we can see that there were 14 calls to LoadListener.nativeFinished(); looking
at the timeline panel shows that one of those calls took an unusually
long time.</p>
<p><img src="/images/traceview_profile.png" alt="Traceview profile panel." width="892" height="630"></p>
<a name="format"></a>
<h2>Traceview File Format</h2>
<p>Tracing creates two distinct pieces of output: a <em>data</em> file,
which holds the trace data, and a <em>key</em> file, which
provides a mapping from binary identifiers to thread and method names.
The files are concatenated when tracing completes, into a
single <em>.trace</em> file. </p>
<p class="note"><strong>Note:</strong> The previous version of Traceview did not concatenate
these files for you. If you have old key and data files that you'd still like to trace, you
can concatenate them yourself with <code>cat mytrace.key mytrace.data > mytrace.trace</code>.</p>
<a name="datafileformat"></a>
<h3>Data File Format</h3>
<p>The data file is binary, structured as
follows (all values are stored in little-endian order):</p>
<pre>* File format:
* header
* record 0
* record 1
* ...
*
* Header format:
* u4 magic 0x574f4c53 ('SLOW')
* u2 version
* u2 offset to data
* u8 start date/time in usec
*
* Record format:
* u1 thread ID
* u4 method ID | method action
* u4 time delta since start, in usec
</pre>
<p>The application is expected to parse all of the header fields, then seek
to &quot;offset to data&quot; from the start of the file. From there it just
reads
9-byte records until EOF is reached.</p>
<p><em>u8 start date/time in usec</em> is the output from gettimeofday().
It's mainly there so that you can tell if the output was generated yesterday
or three months ago.</p>
<p><em>method action</em> sits in the two least-significant bits of the
<em>method</em> word. The currently defined meanings are: </p>
<ul>
<li>0 - method entry </li>
<li>1 - method exit </li>
<li>2 - method &quot;exited&quot; when unrolled by exception handling </li>
<li>3 - (reserved)</li>
</ul>
<p>An unsigned 32-bit integer can hold about 70 minutes of time in microseconds.
</p>
<a name="keyfileformat"></a>
<h3>Key File Format</h3>
<p>The key file is a plain text file divided into three sections. Each
section starts with a keyword that begins with '*'. If you see a '*' at the start
of a line, you have found the start of a new section.</p>
<p>An example file might look like this:</p>
<pre>*version
1
clock=global
*threads
1 main
6 JDWP Handler
5 Async GC
4 Reference Handler
3 Finalizer
2 Signal Handler
*methods
0x080f23f8 java/io/PrintStream write ([BII)V
0x080f25d4 java/io/PrintStream print (Ljava/lang/String;)V
0x080f27f4 java/io/PrintStream println (Ljava/lang/String;)V
0x080da620 java/lang/RuntimeException &lt;init&gt; ()V
[...]
0x080f630c android/os/Debug startMethodTracing ()V
0x080f6350 android/os/Debug startMethodTracing (Ljava/lang/String;Ljava/lang/String;I)V
*end</pre>
<dl>
<dt><em>version section</em></dt>
<dd>The first line is the file version number, currently
1.
The second line, <code>clock=global</code>, indicates that we use a common
clock across all threads. A future version may use per-thread CPU time counters
that are independent for every thread.</dd>
<dt><em>threads section</em></dt>
<dd>One line per thread. Each line consists of two parts: the thread ID, followed
by a tab, followed by the thread name. There are few restrictions on what
a valid thread name is, so include everything to the end of the line.</dd>
<dt><em>methods section </em></dt>
<dd>One line per method entry or exit. A line consists of four pieces,
separated by tab marks: <em>method-ID</em> [TAB] <em>class-name</em> [TAB]
<em>method-name</em> [TAB]
<em>signature</em> . Only
the methods that were actually entered or exited are included in the list.
Note that all three identifiers are required to uniquely identify a
method.</dd>
</dl>
<p>Neither the threads nor methods sections are sorted.</p>
<a name="knownissues"></a>
<h2>Traceview Known Issues</h2>
<dl>
<dt>Threads</dt>
<dd>Traceview logging does not handle threads well, resulting in these two problems:
<ol>
<li> If a thread exits during profiling, the thread name is not emitted; </li>
<li>The VM reuses thread IDs. If a thread stops and another starts, they
may get the same ID. </li>
</ol>
</dd>
<a name="dmtracedump"></a>
<h2>Using dmtracedump</h2>
<p>The Android SDK includes dmtracedump, a tool that gives you an alternate way
of generating graphical call-stack diagrams from trace log files. The tool
uses the Graphviz Dot utility to create the graphical output, so you need to
install Graphviz before running dmtracedump.</p>
<p>The dmtracedump tool generates the call stack data as a tree diagram, with each call
represented as a node. It shows call flow (from parent node to child nodes) using
arrows. The diagram below shows an example of dmtracedump output.</p>
<img src="{@docRoot}images/tracedump.png" width="485" height="401" style="margin-top:1em;"/>
<p style="margin-top:1em;">For each node, dmtracedump shows <code>&lt;ref> <em>callname</em> (&lt;inc-ms>,
&lt;exc-ms>,&lt;numcalls>)</code>, where</p>
<ul>
<li><code>&lt;ref></code> -- Call reference number, as used in trace logs</li>
<li><code>&lt;inc-ms></code> -- Inclusive elapsed time (milliseconds spent in method, including all child methods)</li>
<li><code>&lt;exc-ms></code> -- Exclusive elapsed time (milliseconds spent in method, not including any child methods)</li>
<li><code>&lt;numcalls></code> -- Number of calls</li>
</ul>
<p>The usage for dmtracedump is: </p>
<pre>dmtracedump [-ho] [-s sortable] [-d trace-base-name] [-g outfile] &lt;trace-base-name></pre>
<p>The tool then loads trace log data from &lt;trace-base-name>.data and &lt;trace-base-name>.key.
The table below lists the options for dmtracedump.</p>
<table>
<tr>
<th>Option</td>
<th>Description</th>
</tr>
<tr>
<td><code>-d&nbsp;&lt;trace-base-name> </code></td>
<td>Diff with this trace name</td>
</tr>
<tr>
<td><code>-g&nbsp;&lt;outfile> </code></td>
<td>Generate output to &lt;outfile></td>
</tr>
<tr>
<td><code>-h </code></td>
<td>Turn on HTML output</td>
</tr>
<tr>
<td><code>-o </code></td>
<td>Dump the trace file instead of profiling</td>
</tr>
<tr>
<td><code>-d&nbsp;&lt;trace-base-name> </code></td>
<td>URL base to the location of the sortable javascript file</td>
</tr>
<tr>
<td><code>-t&nbsp;&lt;percent> </code></td>
<td>Minimum threshold for including child nodes in the graph (child's inclusive
time as a percentage of parent inclusive time). If this option is not used,
the default threshold is 20%. </td>
</tr>
</table>
base/docs/html/guide/developing/tools/zipalign.jd
+65
View File
@@ -0,0 +1,65 @@
page.title=zipalign
@jd:body
<p>zipalign is an archive alignment tool that provides important
optimization to Android application (.apk) files.
The purpose is to ensure that all uncompressed data starts
with a particular alignment relative to the start of the file. Specifically,
it causes all uncompressed data within the .apk, such as images or raw files,
to be aligned on 4-byte boundaries. This
allows all portions to be accessed directly with {@code mmap()} even if they
contain binary data with alignment restrictions.
The benefit is a reduction in the amount of RAM consumed
when running the application.</p>
<p>This tool should always be used to align your .apk file before
distributing it to end-users. The Android build tools can handle
this for you. When using Eclipse with the ADT plugin, the Export Wizard
will automatically zipalign your .apk after it signs it with your private key.
The build scripts used
when compiling your application with Ant will also zipalign your .apk,
as long as you have provided the path to your keystore and the key alias in
your project {@code build.properties} file, so that the build tools
can sign the package first.</p>
<p class="caution"><strong>Caution:</strong> zipalign must only be performed
<strong>after</strong> the .apk file has been signed with your private key.
If you perform zipalign before signing, then the signing procedure will undo
the alignment. Also, do not make alterations to the aligned package.
Alterations to the archive, such as renaming or deleting entries, will
potentially disrupt the alignment of the modified entry and all later
entries. And any files added to an "aligned" archive will not be aligned.</p>
<p>The adjustment is made by altering the size of
the "extra" field in the zip Local File Header sections. Existing data
in the "extra" fields may be altered by this process.</p>
<p>For more information about how to use zipalign when building your
application, please read <a href="{@docRoot}guide/publishing/app-signing.html">Signing
Your Application</a>.</p>
<h3>Usage</h3>
<p>To align {@code infile.apk} and save it as {@code outfile.apk}:</p>
<pre>zipalign [-f] [-v] &lt;alignment> infile.apk outfile.apk</pre>
<p>To confirm the alignment of {@code existing.apk}:</p>
<pre>zipalign -c -v &lt;alignment> existing.apk</pre>
<p>The {@code &lt;alignment>} is an integer that defines the byte-alignment boundaries.
This must always be 4 (which provides 32-bit alignment) or else it effectively
does nothing.</p>
<p>Flags:</p>
<ul>
<li>{@code -f} : overwrite existing outfile.zip</li>
<li>{@code -v} : verbose output</li>
<li>{@code -c} : confirm the alignment of the given file</li>
</ul>