Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: InfoPros, Project 01, Batch 02

Browse Source 
- Removing/Replacing Eclipse ADT references in docs
- 10 files

b/25192800

Change-Id: I0312015a33e3553088c6a76f64967574bf46c513
This commit is contained in:
Joe Fernandez
2015-12-07 11:00:46 -08:00
parent df43875e66
commit 67afa981a2
10 changed files with 533 additions and 605 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
docs/html/guide/appendix/glossary.jd Normal file → Executable file
View File

@@ -41,8 +41,8 @@ excludeFromSuggestions=true
<dt id="adb">adb</dt>
<dd>Android Debug Bridge, a command-line debugging application included with the
SDK. It provides tools to browse the device, copy tools on the device, and
forward ports for debugging. If you are developing in Eclipse using the
ADT Plugin, adb is integrated into your development environment. See
forward ports for debugging. If you are developing in Android Studio,
adb is integrated into your development environment. See
<a href="{@docRoot}tools/help/adb.html">Android Debug Bridge</a>
for more information. </dd>
@@ -90,8 +90,8 @@ excludeFromSuggestions=true
<dt id="ddms">DDMS</dt>
<dd>Dalvik Debug Monitor Service, a GUI debugging application included
with the SDK. It provides screen capture, log dump, and process
examination capabilities. If you are developing in Eclipse using the ADT
Plugin, DDMS is integrated into your development environment. See <a
examination capabilities. If you are developing in Android Studio,
DDMS is integrated into your development environment. See <a
href="{@docRoot}tools/debugging/ddms.html">Using DDMS</a> to learn more about the program.</dd>
<dt id="dialog">Dialog</dt> <dd> A floating window that acts as a lightweight
@@ -290,4 +290,4 @@ excludeFromSuggestions=true
in your application. </dd>
</dl>
</dl>

4
docs/html/guide/practices/seamlessness.jd Normal file → Executable file
View File

@@ -209,8 +209,8 @@ likely to be unpopular.</p>
you're using the emulator, since the emulator uses your desktop computer's
network connection. That's almost guaranteed to be much faster than a cell
network, so you'll want to change the settings on the emulator that simulate
slower network speeds. You can do this in Eclipse, in the "Emulator Settings"
tab of your launch configuration or via a <a
slower network speeds. You can do this in Android Studio via the AVD Manager,
or via a <a
href="{@docRoot}tools/help/emulator.html#netspeed">command-line
option</a> when starting the emulator.</p>

13
docs/html/guide/topics/connectivity/sip.jd Normal file → Executable file
View File

@@ -478,14 +478,19 @@ wireless, so you must test on an actual device. Testing on AVD won't work.</li>
<ol>
<li>On your device, connect to wireless (<strong>Settings > Wireless & networks
> Wi-Fi > Wi-Fi settings</strong>)</li>
> Wi-Fi > Wi-Fi settings</strong>).</li>
<li>Set up your mobile device for testing, as described in <a
href="{@docRoot}tools/device.html">Developing on a Device</a>.</li>
<li>Run your application on your mobile device, as described in <a
href="{@docRoot}tools/device.html">Developing on a Device</a>.</li>
<li>If you are using Eclipse, you can view the application log output in Eclipse
using LogCat (<strong>Window > Show View > Other > Android >
LogCat</strong>).</li>
<li>If you are using Android Studio, you can view the application log output by
opening the Event Log console (<strong>View > Tool Windows > Event Log</strong>).
<li>Ensure your application is configured to launch Logcat automatically when it runs:
<ol TYPE=a>
<li>Select <strong>Run > Edit Configurations</strong>.
<li>Select the <strong>Miscellaneous</strong> tab in the <strong>Run/Debug Configurations</strong> window.
<li>Under <strong>Logcat</strong>, select <strong>Show logcat automatically</strong> then
select <strong>OK</strong>.</li></ol>
</ol>

26
docs/html/guide/topics/manifest/uses-feature-element.jd Normal file → Executable file
View File

@@ -486,10 +486,22 @@ determine the features that your application requires. </p>
<ol>
<li>First, build and export your application as an unsigned <code>.apk</code>.
If you are developing in Eclipse with ADT, right-click the project and select
<strong>Android Tools</strong> &gt; <strong>Export Unsigned Application
Package</strong>. Select a destination filename and path and click
<strong>OK</strong>. </li>
If you are developing in Android Studio, build your application with Gradle:
<ol TYPE=a>
<li>Open the project and select <strong>Run > Edit Configurations</strong>.
<li>Select the plus sign near the top-left corner of the <strong>Run/Debug
Configurations</strong> window.
<li>Select <strong>Gradle.</strong>
<li>Enter <code>Unsigned APK</code> in <strong>Name</strong>.
<li>Choose your module from the <strong>Gradle project</strong> section.
<li>Enter <code>assemble</code> in <strong>Tasks</strong>.
<li>Select <strong>OK</strong> to complete the new configuration.
<li>Make sure the <strong>Unsigned APK</strong> run configuration is selected
in the toolbar and select <strong>Run > Run 'Unsigned APK'</strong>.</li>
</ol>
You can find your unsigned <code>.apk</code> in the
<code>&lt;<em>ProjectName</em>&gt;/app/build/outputs/apk/</code> directory.
<li>Next, locate the <code>aapt</code> tool, if it is not already in your PATH.
If you are using SDK Tools r8 or higher, you can find <code>aapt</code> in the
<code>&lt;<em>SDK</em>&gt;/platform-tools/</code> directory.
@@ -563,9 +575,9 @@ is sensitive to delays or lag in sound input or output.</td>
<td rowspan="6">Camera</td>
<td><code>android.hardware.camera</code></td>
<td>The application uses the device's back-facing (main) camera.</td>
<td>Devices with only a front-facing camera do not list this feature, so the
<code>android.hardware.camera.any</code> feature should be
used instead if a camera facing any direction is acceptable for the
<td>Devices with only a front-facing camera do not list this feature, so
the <code>android.hardware.camera.any</code> feature should be used
instead if a camera facing any direction is acceptable for the
application.</td>
</tr>
<tr>

4
docs/html/guide/topics/providers/content-provider-creating.jd Normal file → Executable file
View File

@@ -879,8 +879,8 @@ vnd.android.cursor.<strong>item</strong>/vnd.com.example.provider.table1
A contract class also helps developers because it usually has mnemonic names for its constants,
so developers are less likely to use incorrect values for column names or URIs. Since it's a
class, it can contain Javadoc documentation. Integrated development environments such as
Eclipse can auto-complete constant names from the contract class and display Javadoc for the
constants.
Android Studio can auto-complete constant names from the contract class and display Javadoc for
the constants.
</p>
<p>
Developers can't access the contract class's class file from your application, but they can

968
docs/html/guide/topics/resources/localization.jd Normal file → Executable file
View File

@@ -1,484 +1,484 @@
page.title=Localizing with Resources
parent.title=Application Resources
page.tags="localizing","localization","resources", "formats", "l10n"
parent.link=index.html
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>Quickview</h2>
<ul>
<li>Use resource sets to create a localized app.</li>
<li>Android loads the correct resource set for the user's language and locale.</li>
<li>If localized resources are not available, Android loads your default resources.</li>
</ul>
<h2>In this document</h2>
<ol>
<li><a href="#resource-switching">Overview: Resource-Switching in Android</a></li>
<li><a href="#using-framework">Using Resources for Localization</a></li>
<li><a href="#strategies">Localization Tips</a></li>
<li><a href="#testing">Testing Localized Applications</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}distribute/tools/localization-checklist.html">Localization Checklist</a></li>
<li><a href="{@docRoot}guide/topics/resources/providing-resources.html">Providing Resources</a></li>
<li><a href="{@docRoot}guide/topics/ui/declaring-layout.html">Layouts</a></li>
<li><a href="{@docRoot}reference/android/app/Activity.html#ActivityLifecycle">Activity Lifecycle</a></li>
</ol>
</div>
</div>
<p>Android will run on many devices in many regions. To reach the most users,
your application should handle text, audio files, numbers, currency, and
graphics in ways appropriate to the locales where your application will be used.
</p>
<p>This document describes best practices for localizing Android
applications. The principles apply whether you are developing your application
using ADT with Eclipse, Ant-based tools, or any other IDE. </p>
<p>You should already have a working knowledge of Java and be familiar with
Android resource loading, the declaration of user interface elements in XML,
development considerations such as Activity lifecycle, and general principles of
internationalization and localization. </p>
<p>It is good practice to use the Android resource framework to separate the
localized aspects of your application as much as possible from the core Java
functionality:</p>
<ul>
<li>You can put most or all of the <em>contents</em> of your application's
user interface into resource files, as described in this document and in <a
href="{@docRoot}guide/topics/resources/providing-resources.html">Providing Resources</a>.</li>
<li>The <em>behavior</em> of the user interface, on the other hand, is driven
by your Java code.
For example, if users input data that needs to be formatted or sorted
differently depending on locale, then you would use Java to handle the data
programmatically. This document does not cover how to localize your Java code.
</li>
</ul>
<p>For a short guide to localizing strings in your app, see the training lesson, <a
href="{@docRoot}training/basics/supporting-devices/languages.html">Supporting Different Languages</a>. </p>
<h2 id="resource-switching">Overview: Resource-Switching in Android</h2>
<p>Resources are text strings, layouts, sounds, graphics, and any other static
data that your Android application needs. An application can include multiple
sets of resources, each customized for a different device configuration. When a
user runs the application, Android automatically selects and loads the
resources that best match the device.</p>
<p>(This document focuses on localization and locale. For a complete description
of resource-switching and all the types of configurations that you can
specify &#8212; screen orientation, touchscreen type, and so on &#8212; see <a
href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">Providing
Alternative Resources</a>.)</p>
<table border="0" cellspacing="0" cellpadding="0">
<tr border="0">
<td width="180" style="border: 0pt none ;"><p class="special-note">
<strong>When you write your application:</strong>
<br><br>
You create a set of default resources, plus alternatives to be used in
different locales.</p></td>
<td style="border: 0pt none; padding:0">
<p style="border:0; padding:0"><img src="../../../images/resources/right-arrow.png" alt="right-arrow"
width="51" height="17"></p></td>
<td width="180" style="border: 0pt none ;"><p class="special-note">
<strong>When a user runs your application:</strong>
<br><br>The Android system selects which resources to load, based on the
device's locale.</p></td>
</tr>
</table>
<p>When you write your application, you create default and alternative resources
for your application to use. To create resources, you place files within
specially named subdirectories of the project's <code>res/</code> directory.
</p>
<h3 id="defaults-r-important">Why Default Resources Are Important</h3>
<p>Whenever the application runs in a locale for which you have not provided
locale-specific text, Android will load the default strings from
<code>res/values/strings.xml</code>. If this default file is absent, or if it
is missing a string that your application needs, then your application will not run
and will show an error.
The example below illustrates what can happen when the default text file is incomplete. </p>
<p><em>Example:</em>
<p>An application's Java code refers to just two strings, <code>text_a</code> and
<code>text_b</code>. This application includes a localized resource file
(<code>res/values-en/strings.xml</code>) that defines <code>text_a</code> and
<code>text_b</code> in English. This application also includes a default
resource file (<code>res/values/strings.xml</code>) that includes a
definition for <code>text_a</code>, but not for <code>text_b</code>:
<ul>
<li>This application might compile without a problem. An IDE such as Eclipse
will not highlight any errors if a resource is missing.</li>
<li>When this application is launched on a device with locale set to English,
the application might run without a problem, because
<code>res/values-en/strings.xml</code> contains both of the needed text
strings.</li>
<li>However, <strong>the user will see an error message and a Force Close
button</strong> when this application is launched on a device set to a
language other than English. The application will not load.</li>
</ul>
<p>To prevent this situation, make sure that a <code>res/values/strings.xml</code>
file exists and that it defines every needed string. The situation applies to
all types of resources, not just strings: You
need to create a set of default resource files containing all
the resources that your application calls upon &#8212; layouts, drawables,
animations, etc. For information about testing, see <a href="#test-for-default">
Testing for Default Resources</a>.</p>
<h2 id="using-framework">Using Resources for Localization</h2>
<h3 id="creating-defaults">How to Create Default Resources</h3>
<p>Put the application's default text in
a file with the following location and name:</p>
<p><code>&nbsp;&nbsp;&nbsp;&nbsp;res/values/strings.xml</code> (required directory)</p>
<p>The text strings in <code>res/values/strings.xml</code> should use the
default language, which is the language that you expect most of your application's users to
speak. </p>
<p>The default resource set must also include any default drawables and layouts,
and can include other types of resources such as animations.
<br>
<code>&nbsp;&nbsp;&nbsp;&nbsp;res/drawable/</code>(required directory holding at least
one graphic file, for the application's icon on Google Play)<br>
<code>&nbsp;&nbsp;&nbsp;&nbsp;res/layout/</code> (required directory holding an XML
file that defines the default layout)<br>
<code>&nbsp;&nbsp;&nbsp;&nbsp;res/anim/</code> (required if you have any
<code>res/anim-<em>&lt;qualifiers&gt;</em></code> folders)<br>
<code>&nbsp;&nbsp;&nbsp;&nbsp;res/xml/</code> (required if you have any
<code>res/xml-<em>&lt;qualifiers&gt;</em></code> folders)<br>
<code>&nbsp;&nbsp;&nbsp;&nbsp;res/raw/</code> (required if you have any
<code>res/raw-<em>&lt;qualifiers&gt;</em></code> folders)
</p>
<p class="note"><strong>Tip:</strong> In your code, examine each reference to
an Android resource. Make sure that a default resource is defined for each
one. Also make sure that the default string file is complete: A <em>
localized</em> string file can contain a subset of the strings, but the
<em>default</em> string file must contain them all.
</p>
<h3 id="creating-alternatives">How to Create Alternative Resources</h3>
<p>A large part of localizing an application is providing alternative text for
different languages. In some cases you will also provide alternative graphics,
sounds, layouts, and other locale-specific resources. </p>
<p>An application can specify many <code>res/<em>&lt;qualifiers&gt;</em>/</code>
directories, each with different qualifiers. To create an alternative resource for
a different locale, you use a qualifier that specifies a language or a
language-region combination. (The name of a resource directory must conform
to the naming scheme described in
<a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">Providing
Alternative Resources</a>,
or else it will not compile.)</p>
<p><em>Example:</em></p>
<p>Suppose that your application's default language is English. Suppose also
that you want to localize all the text in your application to French, and most
of the text in your application (everything except the application's title) to
Japanese. In this case, you could create three alternative <code>strings.xml</code>
files, each stored in a locale-specific resource directory:</p>
<ol>
<li><code>res/values/strings.xml</code><br>
Contains English text for all the strings that the application uses,
including text for a string named <code>title</code>.</li>
<li><code>res/values-fr/strings.xml</code><br>
Contain French text for all the strings, including <code>title</code>.</li>
<li><code>res/values-ja/strings.xml</code><br>
Contain Japanese text for all the strings <em>except</em>
<code>title</code>.<br>
<code></code></li>
</ol>
<p>If your Java code refers to <code>R.string.title</code>, here is what will
happen at runtime:</p>
<ul>
<li>If the device is set to any language other than French, Android will load
<code>title</code> from the <code>res/values/strings.xml</code> file.</li>
<li>If the device is set to French, Android will load <code>title</code> from
the <code>res/values-fr/strings.xml</code> file.</li>
</ul>
<p>Notice that if the device is set to Japanese, Android will look for
<code>title</code> in the <code>res/values-ja/strings.xml</code> file. But
because no such string is included in that file, Android will fall back to the
default, and will load <code>title</code> in English from the
<code>res/values/strings.xml</code> file. </p>
<h3 id="resource-precedence">Which Resources Take Precedence?</h3>
<p> If multiple resource files match a device's configuration, Android follows a
set of rules in deciding which file to use. Among the qualifiers that can be
specified in a resource directory name, <strong>locale almost always takes
precedence</strong>. </p>
<p><em>Example:</em></p>
<p>Assume that an application includes a default set of graphics and two other
sets of graphics, each optimized for a different device setup:</p>
<ul>
<li><code>res/drawable/</code><br>
Contains
default graphics.</li>
<li><code>res/drawable-small-land-stylus/</code><br>
Contains graphics optimized for use with a device that expects input from a
stylus and has a QVGA low-density screen in landscape orientation.</li>
<li><code>res/drawable-ja/</code> <br>
Contains graphics optimized for use with Japanese.</li>
</ul>
<p>If the application runs on a device that is configured to use Japanese,
Android will load graphics from <code>res/drawable-ja/</code>, even if the
device happens to be one that expects input from a stylus and has a QVGA
low-density screen in landscape orientation.</p>
<p class="note"><strong>Exception:</strong> The only qualifiers that take
precedence over locale in the selection process are MCC and MNC (mobile country
code and mobile network code). </p>
<p><em>Example:</em></p>
<p>Assume that you have the following situation:</p>
<ul>
<li>The application code calls for <code>R.string.text_a</code></li>
<li>Two relevant resource files are available:
<ul>
<li><code>res/values-mcc404/strings.xml</code>, which includes
<code>text_a</code> in the application's default language, in this case
English.</li>
<li><code>res/values-hi/strings.xml</code>, which includes
<code>text_a</code> in Hindi.</li>
</ul>
</li>
<li>The application is running on a device that has the following
configuration:
<ul>
<li>The SIM card is connected to a mobile network in India (MCC 404).</li>
<li>The language is set to Hindi (<code>hi</code>).</li>
</ul>
</li>
</ul>
<p>Android will load <code>text_a</code> from
<code>res/values-mcc404/strings.xml</code> (in English), even if the device is
configured for Hindi. That is because in the resource-selection process, Android
will prefer an MCC match over a language match. </p>
<p>The selection process is not always as straightforward as these examples
suggest. Please read <a
href="{@docRoot}guide/topics/resources/providing-resources.html#BestMatch">How Android Finds
the Best-matching Resource</a> for a more nuanced description of the
process. All the qualifiers are described and listed in order of
precedence in <a
href="{@docRoot}guide/topics/resources/providing-resources.html#table2">Table 2 of Providing
Alternative Resources</a>.</p>
<h3 id="referring-to-resources">Referring to Resources in Java</h3>
<p>In your application's Java code, you refer to resources using the syntax
<code>R.<em>resource_type</em>.<em>resource_name</em></code> or
<code>android.R.<em>resource_type</em>.<em>resource_name</em></code><em>.</em>
For more about this, see <a
href="{@docRoot}guide/topics/resources/accessing-resources.html">Accessing Resources</a>.</p>
<h2 id="checklist">Localization Checklist</h2>
<p>For a complete overview of the process of localizing and distributing an Android application,
see the <a href="{@docRoot}distribute/tools/localization-checklist.html">Localization
Checklist</a> document.</p>
<h2 id="strategies">Localization Tips</h2>
<h4 id="failing2">Design your application to work in any locale</h4>
<p>You cannot assume anything about the device on which a user will
run your application. The device might have hardware that you were not
anticipating, or it might be set to a locale that you did not plan for or that
you cannot test. Design your application so that it will function normally or fail gracefully no
matter what device it runs on.</p>
<p class="note"><strong>Important:</strong> Make sure that your application
includes a full set of default resources.</p> <p>Make sure to include
<code>res/drawable/</code> and a <code>res/values/</code> folders (without any
additional modifiers in the folder names) that contain all the images and text
that your application will need. </p>
<p>If an application is missing even one default resource, it will not run on a
device that is set to an unsupported locale. For example, the
<code>res/values/strings.xml</code> default file might lack one string that
the application needs: When the application runs in an unsupported locale and
attempts to load <code>res/values/strings.xml</code>, the user will see an
error message and a Force Close button. An IDE such as Eclipse will not
highlight this kind of error, and you will not see the problem when you
test the application on a device or emulator that is set to a supported locale.</p>
<p>For more information, see <a href="#test-for-default">Testing for Default Resources</a>.</p>
<h4>Design a flexible layout</h4>
<p> If you need to rearrange your layout to fit a certain language (for example
German with its long words), you can create an alternative layout for that
language (for example <code>res/layout-de/main.xml</code>). However, doing this
can make your application harder to maintain. It is better to create a single
layout that is more flexible.</p>
<p>Another typical situation is a language that requires something different in
its layout. For example, you might have a contact form that should include two
name fields when the application runs in Japanese, but three name fields when
the application runs in some other language. You could handle this in either of
two ways:</p>
<ul>
<li>Create one layout with a field that you can programmatically enable or
disable, based on the language, or</li>
<li>Have the main layout include another layout that includes the changeable
field. The second layout can have different configurations for different
languages.</li>
</ul>
<h4>Avoid creating more resource files and text strings than you need</h4>
<p>You probably do not need to create a locale-specific
alternative for every resource in your application. For example, the layout
defined in the <code>res/layout/main.xml</code> file might work in any locale,
in which case there would be no need to create any alternative layout files.
</p>
<p>Also, you might not need to create alternative text for every
string. For example, assume the following:</p>
<ul>
<li>Your application's default language is American
English. Every string that the application uses is defined, using American
English spellings, in <code>res/values/strings.xml</code>. </li>
<li>For a few important phrases, you want to provide
British English spelling. You want these alternative strings to be used when your
application runs on a device in the United Kingdom. </li>
</ul>
<p>To do this, you could create a small file called
<code>res/values-en-rGB/strings.xml</code> that includes only the strings that
should be different when the application runs in the U.K. For all the rest of
the strings, the application will fall back to the defaults and use what is
defined in <code>res/values/strings.xml</code>.</p>
<h4>Use the Android Context object for manual locale lookup</h4>
<p>You can look up the locale using the {@link android.content.Context} object
that Android makes available:</p>
<pre>String locale = context.getResources().getConfiguration().locale.getDisplayName();</pre>
<h2 id="testing">Testing Localized Applications</h2>
<h3 id="device">Testing on a Device</h3>
<p>Keep in mind that the device you are testing may be significantly different from
the devices available to consumers in other geographies. The locales available
on your device may differ from those available on other devices. Also, the
resolution and density of the device screen may differ, which could affect
the display of strings and drawables in your UI.</p>
<p>To change the locale or language on a device, use the Settings application.</p>
<h3 id="emulator">Testing on an Emulator</h3>
<p>For details about using the emulator, see See <a
href="{@docRoot}tools/help/emulator.html">Android Emulator</a>.</p>
<h4>Creating and using a custom locale</h4>
<p>A &quot;custom&quot; locale is a language/region combination that the Android
system image does not explicitly support. (For a list of supported locales in
Android platforms see the Version Notes in the <a
href="{@docRoot}sdk/index.html">SDK</a> tab). You can test
how your application will run in a custom locale by creating a custom locale in
the emulator. There are two ways to do this:</p>
<ul>
<li>Use the Custom Locale application, which is accessible from the
Application tab. (After you create a custom locale, switch to it by
pressing and holding the locale name.)</li>
<li>Change to a custom locale from the adb shell, as described below.</li>
</ul>
<p>When you set the emulator to a locale that is not available in the Android
system image, the system itself will display in its default language. Your
application, however, should localize properly.</p>
<h4>Changing the emulator locale from the adb shell</h4>
<p>To change the locale in the emulator by using the adb shell. </p>
<ol>
<li>Pick the locale you want to test and determine its BCP-47 language tag, for
example, Canadian French would be <code>fr-CA</code>.<br>
</li>
<li>Launch an emulator.</li>
<li>From a command-line shell on the host computer, run the following
command:<br>
<code>adb shell</code><br>
or if you have a device attached, specify that you want the emulator by adding
the <code>-e</code> option:<br>
<code>adb -e shell</code></li>
<li>At the adb shell prompt (<code>#</code>), run this command: <br>
<code>setprop persist.sys.locale [<em>BCP-47 language tag</em>];stop;sleep 5;start <br>
</code>Replace bracketed sections with the appropriate codes from Step
1.</li>
</ol>
<p>For instance, to test in Canadian French:</p>
<p><code>setprop persist.sys.locale fr-CA;stop;sleep 5;start </code></p>
<p>This will cause the emulator to restart. (It will look like a full reboot,
but it is not.) Once the Home screen appears again, re-launch your application (for
example, click the Run icon in Eclipse), and the application will launch with
the new locale. </p>
<h3 id="test-for-default">Testing for Default Resources</h3>
<p>Here's how to test whether an application includes every string resource that it needs: </p>
<ol><li>Set the emulator or device to a language that your application does not
support. For example, if the application has French strings in
<code>res/values-fr/</code> but does not have any Spanish strings in
<code>res/values-es/</code>, then set the emulator's locale to Spanish.
(You can use the Custom Locale application to set the emulator to an
unsupported locale.)</li>
<li>Run the application.</li>
<li>If the application shows an error message and a Force Close button, it might
be looking for a string that is not available. Make sure that your
<code>res/values/strings.xml</code> file includes a definition for
every string that the application uses.</li>
</ol>
</p>
<p>If the test is successful, repeat it for other types of
configurations. For example, if the application has a layout file called
<code>res/layout-land/main.xml</code> but does not contain a file called
<code>res/layout-port/main.xml</code>, then set the emulator or device to
portrait orientation and see if the application will run.
page.title=Localizing with Resources
parent.title=Application Resources
page.tags="localizing","localization","resources", "formats", "l10n"
parent.link=index.html
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>Quickview</h2>
<ul>
<li>Use resource sets to create a localized app.</li>
<li>Android loads the correct resource set for the user's language and locale.</li>
<li>If localized resources are not available, Android loads your default resources.</li>
</ul>
<h2>In this document</h2>
<ol>
<li><a href="#resource-switching">Overview: Resource-Switching in Android</a></li>
<li><a href="#using-framework">Using Resources for Localization</a></li>
<li><a href="#strategies">Localization Tips</a></li>
<li><a href="#testing">Testing Localized Applications</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}distribute/tools/localization-checklist.html">
Localization Checklist</a></li>
<li><a href="{@docRoot}guide/topics/resources/providing-resources.html">
Providing Resources</a></li>
<li><a href="{@docRoot}guide/topics/ui/declaring-layout.html">
Layouts</a></li>
<li><a href="{@docRoot}reference/android/app/Activity.html#ActivityLifecycle">
Activity Lifecycle</a></li>
</ol>
</div>
</div>
<p>Android will run on many devices in many regions. To reach the most users,
your application should handle text, audio files, numbers, currency, and
graphics in ways appropriate to the locales where your application will be used.
</p>
<p>This document describes best practices for localizing Android
applications.</p>
<p>You should already have a working knowledge of Java and be familiar with
Android resource loading, the declaration of user interface elements in XML,
development considerations such as Activity lifecycle, and general principles of
internationalization and localization. </p>
<p>It is good practice to use the Android resource framework to separate the
localized aspects of your application as much as possible from the core Java
functionality:</p>
<ul>
<li>You can put most or all of the <em>contents</em> of your application's
user interface into resource files, as described in this document and in <a
href="{@docRoot}guide/topics/resources/providing-resources.html">
Providing Resources</a>.</li>
<li>The <em>behavior</em> of the user interface, on the other hand, is driven
by your Java code.
For example, if users input data that needs to be formatted or sorted
differently depending on locale, then you would use Java to handle the data
programmatically. This document does not cover how to localize your Java code.
</li>
</ul>
<p>For a short guide to localizing strings in your app, see the training lesson,
<a href="{@docRoot}training/basics/supporting-devices/languages.html">
Supporting Different Languages</a>. </p>
<h2 id="resource-switching">Overview: Resource-Switching in Android</h2>
<p>Resources are text strings, layouts, sounds, graphics, and any other static
data that your Android application needs. An application can include multiple
sets of resources, each customized for a different device configuration. When a
user runs the application, Android automatically selects and loads the
resources that best match the device.</p>
<p>(This document focuses on localization and locale. For a complete description
of resource-switching and all the types of configurations that you can
specify &#8212; screen orientation, touchscreen type, and so on &#8212;
see <a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">
Providing Alternative Resources</a>.)</p>
<table border="0" cellspacing="0" cellpadding="0">
<tr border="0">
<td width="180" style="border: 0pt none ;"><p class="special-note">
<strong>When you write your application:</strong>
<br><br>
You create a set of default resources, plus alternatives to be used in
different locales.</p></td>
<td style="border: 0pt none; padding:0">
<p style="border:0; padding:0">
<img src="../../../images/resources/right-arrow.png" alt="right-arrow"
width="51" height="17"></p></td>
<td width="180" style="border: 0pt none ;"><p class="special-note">
<strong>When a user runs your application:</strong>
<br><br>The Android system selects which resources to load, based on the
device's locale.</p></td>
</tr>
</table>
<p>When you write your application, you create default and alternative resources
for your application to use. To create resources, you place files within
specially named subdirectories of the project's <code>res/</code> directory.
</p>
<h3 id="defaults-r-important">Why Default Resources Are Important</h3>
<p>Whenever the application runs in a locale for which you have not provided
locale-specific text, Android will load the default strings from
<code>res/values/strings.xml</code>. If this default file is absent, or if it
is missing a string that your application needs, then your application will not run
and will show an error.
The example below illustrates what can happen when the default text file is
incomplete. </p>
<p><em>Example:</em>
<p>An application's Java code refers to just two strings, <code>text_a</code> and
<code>text_b</code>. This application includes a localized resource file
(<code>res/values-en/strings.xml</code>) that defines <code>text_a</code> and
<code>text_b</code> in English. This application also includes a default
resource file (<code>res/values/strings.xml</code>) that includes a
definition for <code>text_a</code>, but not for <code>text_b</code>:
<ul>
<li>When this application is launched on a device with locale set to English,
the application might run without a problem, because
<code>res/values-en/strings.xml</code> contains both of the needed text
strings.</li>
<li>However, <strong>the user will see an error message and a Force Close
button</strong> when this application is launched on a device set to a
language other than English. The application will not load.</li>
</ul>
<p>To prevent this situation, make sure that a <code>res/values/strings.xml</code>
file exists and that it defines every needed string. The situation applies to
all types of resources, not just strings: You
need to create a set of default resource files containing all
the resources that your application calls upon &#8212; layouts, drawables,
animations, etc. For information about testing, see <a href="#test-for-default">
Testing for Default Resources</a>.</p>
<h2 id="using-framework">Using Resources for Localization</h2>
<h3 id="creating-defaults">How to Create Default Resources</h3>
<p>Put the application's default text in
a file with the following location and name:</p>
<p><code>&nbsp;&nbsp;&nbsp;&nbsp;res/values/strings.xml</code> (required directory)</p>
<p>The text strings in <code>res/values/strings.xml</code> should use the
default language, which is the language that you expect most of your application's users to
speak. </p>
<p>The default resource set must also include any default drawables and layouts,
and can include other types of resources such as animations.
<br>
<code>&nbsp;&nbsp;&nbsp;&nbsp;res/drawable/</code>(required directory holding at least
one graphic file, for the application's icon on Google Play)<br>
<code>&nbsp;&nbsp;&nbsp;&nbsp;res/layout/</code> (required directory holding an XML
file that defines the default layout)<br>
<code>&nbsp;&nbsp;&nbsp;&nbsp;res/anim/</code> (required if you have any
<code>res/anim-<em>&lt;qualifiers&gt;</em></code> folders)<br>
<code>&nbsp;&nbsp;&nbsp;&nbsp;res/xml/</code> (required if you have any
<code>res/xml-<em>&lt;qualifiers&gt;</em></code> folders)<br>
<code>&nbsp;&nbsp;&nbsp;&nbsp;res/raw/</code> (required if you have any
<code>res/raw-<em>&lt;qualifiers&gt;</em></code> folders)
</p>
<p class="note"><strong>Tip:</strong> In your code, examine each reference to
an Android resource. Make sure that a default resource is defined for each
one. Also make sure that the default string file is complete: A <em>
localized</em> string file can contain a subset of the strings, but the
<em>default</em> string file must contain them all.
</p>
<h3 id="creating-alternatives">How to Create Alternative Resources</h3>
<p>A large part of localizing an application is providing alternative text for
different languages. In some cases you will also provide alternative graphics,
sounds, layouts, and other locale-specific resources. </p>
<p>An application can specify many <code>res/<em>&lt;qualifiers&gt;</em>/</code>
directories, each with different qualifiers. To create an alternative resource for
a different locale, you use a qualifier that specifies a language or a
language-region combination. (The name of a resource directory must conform
to the naming scheme described in
<a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">Providing
Alternative Resources</a>,
or else it will not compile.)</p>
<p><em>Example:</em></p>
<p>Suppose that your application's default language is English. Suppose also
that you want to localize all the text in your application to French, and most
of the text in your application (everything except the application's title) to
Japanese. In this case, you could create three alternative <code>strings.xml</code>
files, each stored in a locale-specific resource directory:</p>
<ol>
<li><code>res/values/strings.xml</code><br>
Contains English text for all the strings that the application uses,
including text for a string named <code>title</code>.</li>
<li><code>res/values-fr/strings.xml</code><br>
Contain French text for all the strings, including <code>title</code>.</li>
<li><code>res/values-ja/strings.xml</code><br>
Contain Japanese text for all the strings <em>except</em>
<code>title</code>.<br>
<code></code></li>
</ol>
<p>If your Java code refers to <code>R.string.title</code>, here is what will
happen at runtime:</p>
<ul>
<li>If the device is set to any language other than French, Android will load
<code>title</code> from the <code>res/values/strings.xml</code> file.</li>
<li>If the device is set to French, Android will load <code>title</code> from
the <code>res/values-fr/strings.xml</code> file.</li>
</ul>
<p>Notice that if the device is set to Japanese, Android will look for
<code>title</code> in the <code>res/values-ja/strings.xml</code> file. But
because no such string is included in that file, Android will fall back to the
default, and will load <code>title</code> in English from the
<code>res/values/strings.xml</code> file. </p>
<h3 id="resource-precedence">Which Resources Take Precedence?</h3>
<p> If multiple resource files match a device's configuration, Android follows a
set of rules in deciding which file to use. Among the qualifiers that can be
specified in a resource directory name, <strong>locale almost always takes
precedence</strong>. </p>
<p><em>Example:</em></p>
<p>Assume that an application includes a default set of graphics and two other
sets of graphics, each optimized for a different device setup:</p>
<ul>
<li><code>res/drawable/</code><br>
Contains
default graphics.</li>
<li><code>res/drawable-small-land-stylus/</code><br>
Contains graphics optimized for use with a device that expects input from a
stylus and has a QVGA low-density screen in landscape orientation.</li>
<li><code>res/drawable-ja/</code> <br>
Contains graphics optimized for use with Japanese.</li>
</ul>
<p>If the application runs on a device that is configured to use Japanese,
Android will load graphics from <code>res/drawable-ja/</code>, even if the
device happens to be one that expects input from a stylus and has a QVGA
low-density screen in landscape orientation.</p>
<p class="note"><strong>Exception:</strong> The only qualifiers that take
precedence over locale in the selection process are MCC and MNC (mobile country
code and mobile network code). </p>
<p><em>Example:</em></p>
<p>Assume that you have the following situation:</p>
<ul>
<li>The application code calls for <code>R.string.text_a</code></li>
<li>Two relevant resource files are available:
<ul>
<li><code>res/values-mcc404/strings.xml</code>, which includes
<code>text_a</code> in the application's default language, in this case
English.</li>
<li><code>res/values-hi/strings.xml</code>, which includes
<code>text_a</code> in Hindi.</li>
</ul>
</li>
<li>The application is running on a device that has the following
configuration:
<ul>
<li>The SIM card is connected to a mobile network in India (MCC 404).</li>
<li>The language is set to Hindi (<code>hi</code>).</li>
</ul>
</li>
</ul>
<p>Android will load <code>text_a</code> from
<code>res/values-mcc404/strings.xml</code> (in English), even if the device is
configured for Hindi. That is because in the resource-selection process, Android
will prefer an MCC match over a language match. </p>
<p>The selection process is not always as straightforward as these examples
suggest. Please read <a
href="{@docRoot}guide/topics/resources/providing-resources.html#BestMatch">How Android Finds
the Best-matching Resource</a> for a more nuanced description of the
process. All the qualifiers are described and listed in order of
precedence in <a
href="{@docRoot}guide/topics/resources/providing-resources.html#table2">Table 2 of Providing
Alternative Resources</a>.</p>
<h3 id="referring-to-resources">Referring to Resources in Java</h3>
<p>In your application's Java code, you refer to resources using the syntax
<code>R.<em>resource_type</em>.<em>resource_name</em></code> or
<code>android.R.<em>resource_type</em>.<em>resource_name</em></code><em>.</em>
For more about this, see <a
href="{@docRoot}guide/topics/resources/accessing-resources.html">Accessing Resources</a>.</p>
<h2 id="checklist">Localization Checklist</h2>
<p>For a complete overview of the process of localizing and distributing an Android application,
see the <a href="{@docRoot}distribute/tools/localization-checklist.html">Localization
Checklist</a> document.</p>
<h2 id="strategies">Localization Tips</h2>
<h4 id="failing2">Design your application to work in any locale</h4>
<p>You cannot assume anything about the device on which a user will
run your application. The device might have hardware that you were not
anticipating, or it might be set to a locale that you did not plan for or that
you cannot test. Design your application so that it will function normally or fail gracefully no
matter what device it runs on.</p>
<p class="note"><strong>Important:</strong> Make sure that your application
includes a full set of default resources.</p> <p>Make sure to include
<code>res/drawable/</code> and a <code>res/values/</code> folders (without any
additional modifiers in the folder names) that contain all the images and text
that your application will need. </p>
<p>If an application is missing even one default resource, it will not run on a
device that is set to an unsupported locale. For example, the
<code>res/values/strings.xml</code> default file might lack one string that
the application needs: When the application runs in an unsupported locale and
attempts to load <code>res/values/strings.xml</code>, the user will see an
error message and a Force Close button.</p>
<p>For more information, see <a href="#test-for-default">Testing for Default Resources</a>.</p>
<h4>Design a flexible layout</h4>
<p> If you need to rearrange your layout to fit a certain language (for example
German with its long words), you can create an alternative layout for that
language (for example <code>res/layout-de/main.xml</code>). However, doing this
can make your application harder to maintain. It is better to create a single
layout that is more flexible.</p>
<p>Another typical situation is a language that requires something different in
its layout. For example, you might have a contact form that should include two
name fields when the application runs in Japanese, but three name fields when
the application runs in some other language. You could handle this in either of
two ways:</p>
<ul>
<li>Create one layout with a field that you can programmatically enable or
disable, based on the language, or</li>
<li>Have the main layout include another layout that includes the changeable
field. The second layout can have different configurations for different
languages.</li>
</ul>
<h4>Avoid creating more resource files and text strings than you need</h4>
<p>You probably do not need to create a locale-specific
alternative for every resource in your application. For example, the layout
defined in the <code>res/layout/main.xml</code> file might work in any locale,
in which case there would be no need to create any alternative layout files.
</p>
<p>Also, you might not need to create alternative text for every
string. For example, assume the following:</p>
<ul>
<li>Your application's default language is American
English. Every string that the application uses is defined, using American
English spellings, in <code>res/values/strings.xml</code>. </li>
<li>For a few important phrases, you want to provide
British English spelling. You want these alternative strings to be used when your
application runs on a device in the United Kingdom. </li>
</ul>
<p>To do this, you could create a small file called
<code>res/values-en-rGB/strings.xml</code> that includes only the strings that
should be different when the application runs in the U.K. For all the rest of
the strings, the application will fall back to the defaults and use what is
defined in <code>res/values/strings.xml</code>.</p>
<h4>Use the Android Context object for manual locale lookup</h4>
<p>You can look up the locale using the {@link android.content.Context} object
that Android makes available:</p>
<pre>String locale = context.getResources().getConfiguration().locale.getDisplayName();</pre>
<h2 id="testing">Testing Localized Applications</h2>
<h3 id="device">Testing on a Device</h3>
<p>Keep in mind that the device you are testing may be significantly different from
the devices available to consumers in other geographies. The locales available
on your device may differ from those available on other devices. Also, the
resolution and density of the device screen may differ, which could affect
the display of strings and drawables in your UI.</p>
<p>To change the locale or language on a device, use the Settings application.</p>
<h3 id="emulator">Testing on an Emulator</h3>
<p>For details about using the emulator, see See <a
href="{@docRoot}tools/help/emulator.html">Android Emulator</a>.</p>
<h4>Creating and using a custom locale</h4>
<p>A &quot;custom&quot; locale is a language/region combination that the Android
system image does not explicitly support. (For a list of supported locales in
Android platforms see the Version Notes in the <a
href="{@docRoot}sdk/index.html">SDK</a> tab). You can test
how your application will run in a custom locale by creating a custom locale in
the emulator. There are two ways to do this:</p>
<ul>
<li>Use the Custom Locale application, which is accessible from the
Application tab. (After you create a custom locale, switch to it by
pressing and holding the locale name.)</li>
<li>Change to a custom locale from the adb shell, as described below.</li>
</ul>
<p>When you set the emulator to a locale that is not available in the Android
system image, the system itself will display in its default language. Your
application, however, should localize properly.</p>
<h4>Changing the emulator locale from the adb shell</h4>
<p>To change the locale in the emulator by using the adb shell. </p>
<ol>
<li>Pick the locale you want to test and determine its BCP-47 language tag, for
example, Canadian French would be <code>fr-CA</code>.<br>
</li>
<li>Launch an emulator.</li>
<li>From a command-line shell on the host computer, run the following
command:<br>
<code>adb shell</code><br>
or if you have a device attached, specify that you want the emulator by adding
the <code>-e</code> option:<br>
<code>adb -e shell</code></li>
<li>At the adb shell prompt (<code>#</code>), run this command: <br>
<code>setprop persist.sys.locale [<em>BCP-47 language tag</em>];stop;sleep 5;start <br>
</code>Replace bracketed sections with the appropriate codes from Step
1.</li>
</ol>
<p>For instance, to test in Canadian French:</p>
<p><code>setprop persist.sys.locale fr-CA;stop;sleep 5;start </code></p>
<p>This will cause the emulator to restart. (It will look like a full reboot,
but it is not.) Once the Home screen appears again, re-launch your application,
and the application launches with the new locale. </p>
<h3 id="test-for-default">Testing for Default Resources</h3>
<p>Here's how to test whether an application includes every string
resource that it needs: </p>
<ol><li>Set the emulator or device to a language that your application does not
support. For example, if the application has French strings in
<code>res/values-fr/</code> but does not have any Spanish strings in
<code>res/values-es/</code>, then set the emulator's locale to Spanish.
(You can use the Custom Locale application to set the emulator to an
unsupported locale.)</li>
<li>Run the application.</li>
<li>If the application shows an error message and a Force Close button, it might
be looking for a string that is not available. Make sure that your
<code>res/values/strings.xml</code> file includes a definition for
every string that the application uses.</li>
</ol>
</p>
<p>If the test is successful, repeat it for other types of
configurations. For example, if the application has a layout file called
<code>res/layout-land/main.xml</code> but does not contain a file called
<code>res/layout-port/main.xml</code>, then set the emulator or device to
portrait orientation and see if the application will run.

20
docs/html/ndk/guides/concepts.jd Normal file → Executable file
View File

@@ -18,12 +18,9 @@ page.title=Concepts
<h2 id="bb">Before Beginning</h2>
<p>This guide assumes that you are:</p>
<ul>
<li>Already familiar with concepts inherent in native programming and in
<a href="{@docRoot}">Android development</a>.</li>
<li>Working in <a href="{@docRoot}sdk/index.html">Eclipse, and using the Android
Development Tools (ADT)</a>, except where otherwise noted.</li>
<p>This guide assumes that you are already familiar with concepts inherent in native programming and
in <a href="{@docRoot}developer/index.html">Android development</a>.</p>
</ul>
<h2 id="intro">Introduction</h2>
@@ -151,15 +148,13 @@ native code.
<p class="note"><strong>Note:</strong> While it is possible to completely avoid Java, you are likely
to find the Android Java framework useful for tasks including controlling the display and UI.</p>
</li>
<li>Create an Android app Project in Eclipse as you would for any other Android project.</li>
<li>Create an Android app Project as you would for any other Android project.</li>
<li>If you are writing a native-only app, declare the {@link android.app.NativeActivity} class in
{@code AndroidManifest.xml}. You can do so from the Eclipse/ADT Android Manifest Editor, or by
hand-editing the file. For more information, see the <a href="#naa">Native Activities and
{@code AndroidManifest.xml}. For more information, see the <a href="#naa">Native Activities and
Applications</a>.
</li>
<li>Create an {@code Android.mk} file describing the native library, including name, flags, linked
libraries, and source files to be compiled in the ‘JNI’ directory.</li>
libraries, and source files to be compiled in the "JNI" directory.</li>
<li>Optionally, you can create an {@code Application.mk} file configuring the target ABIs,
toolchain, release/debug mode, and STL. For any of these that you do not specify, the following
default values are used, respectively:
@@ -184,7 +179,6 @@ STL: system
needed for your app to run.
</ol>
<p>Note that Eclipse can perform steps 7. through 9. in a single operation.</p>
<h2 id="naa">Native Activities and Applications</h2>
@@ -300,7 +294,7 @@ $ cd &lt;path&gt;/&lt;to&gt;/&lt;project&gt;
$ &lt;ndk&gt;/ndk-build
</pre>
<li>Build and install your Android project as usual, using Ant or Eclipse. If your native code is in
<li>Build and install your Android project as usual. If your native code is in
the {@code jni/} directory, the build script automatically packages the {@code .so} file(s) built
from it into the APK.</li>
</ol>

2
docs/html/ndk/guides/standalone_toolchain.jd Normal file → Executable file
View File

@@ -17,7 +17,7 @@ page.title=Standalone Toolchain
</div>
<p>You can use the toolchains provided with the Android NDK independently, or as plug-ins
with an existing IDE, such as Eclipse. This flexibility
with an existing IDE. This flexibility
can be useful if you already have your own build system, and only need the ability to invoke the
cross-compiler in order to add support to Android for it.</p>

17
docs/html/tools/help/gltracer.jd Normal file → Executable file
View File

@@ -26,17 +26,6 @@ Level 16) or higher.</p>
<h2 id="running">Running Tracer</h2>
<p>Tracer can be run as part of the Eclipse Android Development Tools (ADT) plugin or as part of the
Device Monitor tool.</p>
<p>To run Tracer in Eclipse:</p>
<ol>
<li>Start Eclipse and open a workspace that contains an Android project.</li>
<li>Activate the perspective for Tracer by choosing <strong>Window > Open Perspective >
Other...</strong></li>
<li>Select <strong>Tracer for OpenGL ES</strong> and click <strong>OK</strong>.</li>
</ol>
<p>To run Tracer in Device Monitor:</p>
@@ -64,7 +53,7 @@ analysis.</p>
<ol>
<li>Connect the Android device using a USB cable and make sure it is enabled for debugging. For
more information, see <a href="{@docRoot}tools/device.html">Using Hardware Devices</a>.</li>
<li>In Eclipse or Device Monitor, activate the <strong>Tracer for OpenGL ES</strong>
<li>In the Device Monitor, activate the <strong>Tracer for OpenGL ES</strong>
perspective.</li>
<li>On the toolbar, click the trace capture button (<img
src="{@docRoot}images/gltracer/icon-capture.png">).</li>
@@ -94,10 +83,10 @@ Be aware that using this option can result in large trace files.</p>
<p>To review a captured trace:</p>
<ol>
<li>In Eclipse or Device Monitor, activate the <strong>Tracer for OpenGL ES</strong>
<li>In Device Monitor, activate the <strong>Tracer for OpenGL ES</strong>
perspective.</li>
<li>On the toolbar, click the trace load button (<img
src="{@docRoot}images/gltracer/icon-load-trace.png">).</li>
<li>After loading a trace, select a frame and review the OpenGL ES calls. Drawing commands are
highlighted in blue.</li>
</ol>
</ol>

74
docs/html/tools/help/proguard.jd Normal file → Executable file
View File

@@ -117,76 +117,6 @@ parent.link=index.html
</pre>
<h2 id="enabling">Enabling ProGuard (Ant Builds)</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;/project.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 ProGuard configuration file will
@@ -246,9 +176,7 @@ proguard.config=/path/to/proguard.cfg
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. For Eclipse, this file is stored in
<code>&lt;project_root&gt;/bin/proguard/</code>. For Android Studio, this file is stored in
the app <code>build/outs/</code> folder. </p>
careful about saving the versions that you need. The file is stored in the app <code>build/outs/</code> folder. </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