docs: Support Library Guide
Extending the Support Library documentation to explain how to
support mainstream features such as ActionBar across multiple
versions of Android.
Change-Id: I8ddeeb912884a39b2fb8717129d22993102ef650
diff --git a/docs/html/tools/support-library/setup.jd b/docs/html/tools/support-library/setup.jd
new file mode 100644
index 0000000..a2ece15
--- /dev/null
+++ b/docs/html/tools/support-library/setup.jd
@@ -0,0 +1,308 @@
+page.title=Support Library Setup
+
+@jd:body
+
+
+<div id="qv-wrapper">
+ <div id="qv">
+
+ <h2>In this document</h2>
+ <ol>
+ <li><a href="#download">Downloading the Support Library</a></li>
+ <li><a href="#choosing">Choosing Support Libraries</a></li>
+ <li><a href="add-library">Adding Support Libraries</a>
+ <ol>
+ <li><a href="#libs-without-res">Adding libraries without resources</a></li>
+ <li><a href="#libs-with-res">Adding libraries with resources</a></li>
+ </ol>
+ </li>
+ <li><a href="#using-apis">Using Support Library APIs</a>
+ <ol>
+ <li><a href="#manifest">Manifest Declaration Changes</a></li>
+ </ol>
+ </li>
+ <li><a href="#samples">Code Samples</a></li>
+ </ol>
+
+ <h2>See also</h2>
+ <ol>
+ <li><a href="{@docRoot}tools/support-library/index.html#revisions">
+ Support Library Revisions</a></li>
+ <li><a href="{@docRoot}tools/support-library/features.html">
+ Support Library Features</a></li>
+ </ol>
+
+ </div>
+</div>
+
+<p>How you setup the Android Support Libraries in your development project depends on what features
+ you want to use and what range of Android platform versions you want to support with your
+ application.</p>
+
+<p>This document guides you through downloading the Support Library package and adding libraries
+ to your development environment.</p>
+
+
+<h2 id="download">Downloading the Support Libraries</h2>
+
+<p>The Android Support Library package is provided as a supplemental download to the Android SDK
+ and is available through the Android
+ <a href="{@docRoot}tools/help/sdk-manager.html">SDK Manager</a>. Follow the
+ instructions below to obtain the Support Library files.
+</p>
+
+<p>To download the Support Library through the SDK Manager:</p>
+
+<ol>
+ <li>Start the Android <a href="{@docRoot}tools/help/sdk-manager.html">SDK Manager</a>.</li>
+ <li>In the SDK Manager window, scroll to the end of the <em>Packages</em> list,
+ find the <em>Extras</em> folder and, if necessary, expand to show its contents.</li>
+ <li>Select the <strong>Android Support Library</strong> item.
+ <p class="note">
+ <strong>Note:</strong> If you're developing with Android Studio, select and install the
+ <strong>Android Support Repository</strong> item instead.
+ </p>
+ </li>
+ <li>Click the <strong>Install packages...</strong> button.</li>
+</ol>
+
+<img src="{@docRoot}images/tools/sdk-manager-support-libs.png" width="525" alt="" />
+<p class="img-caption"><strong>Figure 1.</strong> The Android SDK Manager with the
+Android Support Library selected.</p>
+
+<p>After downloading, the tool installs the Support Library files to your existing Android SDK
+ directory. The library files are located in the following subdirectory of your SDK:
+ {@code <sdk>/extras/android/support/} directory.</p>
+
+
+<h2 id="choosing">Choosing Support Libraries</h2>
+
+<p>Before adding a Support Library to your application, decide what features you want to include
+ and the lowest Android versions you want to support. For more information on the features
+ provided by the different libraries, see
+ <a href="{@docRoot}tools/support-library/features.html">Support Library Features</a>.</p>
+
+
+<h2 id="add-library">Adding Support Libraries</h2>
+
+<p>In order to use a Support Library, you must modify your application's project's
+ classpath dependencies within your development environment. You must perform this procedure for
+ each Support Library you want to use.</p>
+
+<p>Some Support Libraries contain resources beyond compiled code classes, such as images or XML
+ files. For example, the <a href="tools/support-library/features.html#v7-appcompat">v7
+ appcompat</a> and <a href="tools/support-library/features.html#v7-gridlayout">v7 gridlayout</a>
+ libraries include resources.</p>
+
+<p>If you are not sure if a library contains resources, check the
+ <a href="{@docRoot}tools/support-library/features.html">Support Library Features</a> page.
+ The following sections describe how to add a Support Library with or without resources to your
+ application project. </p>
+
+
+<h3 id="libs-without-res">Adding libraries without resources</h3>
+
+<p>To add a Support Library without resources to your application project:</p>
+
+<div class="toggle-content closed">
+<p style="margin-top:5px"><a href="#" onclick="return toggleContent(this)">
+ <img src="/assets/images/triangle-closed.png" class="toggle-content-img" alt=""
+ />Using Eclipse</a></p>
+
+ <div class="toggle-content-toggleme">
+ <ol>
+ <li>Make sure you have downloaded the <strong>Android Support Library</strong>
+ using the <a href="#download">SDK Manager</a>.</li>
+ <li>Create a {@code /libs} directory in the root of your application project.</li>
+ <li>Copy the JAR file from your Android SDK installation directory (e.g.,
+ {@code <sdk>/extras/android/support/v4/android-support-v4.jar}) into your
+ application's project {@code /libs} directory.
+ <li>Right click the JAR file and select <strong>Build Path > Add to Build Path</strong>.
+ </li>
+ </ol>
+ </div>
+</div>
+
+<div class="toggle-content closed">
+<p style="margin-top:5px"><a href="#" onclick="return toggleContent(this)">
+ <img src="/assets/images/triangle-closed.png" class="toggle-content-img" alt=""
+ />Using Android Studio</a></p>
+
+ <div class="toggle-content-toggleme">
+ <ol>
+ <li>Make sure you have downloaded the <strong>Android Support Repository</strong>.
+ using the <a href="#download">SDK Manager</a>.</li>
+ <li>Open the {@code build.gradle} file for your application.</li>
+ <li>Add the support library to the {@code dependencies} section. For example, to add the v4
+ support library, add the following lines:
+<pre>
+dependencies {
+ ...
+ <b>compile "com.android.support:support-v4:18.0.+"</b>
+}
+</pre>
+ </li>
+ </ol>
+ </div>
+</div>
+
+
+<h3 id="libs-with-res">Adding libraries with resources</h3>
+
+<p>To add a Support Library with resources to your application project:</p>
+
+<div class="toggle-content closed">
+ <p style="margin-top:5px"><a href="#" onclick="return toggleContent(this)">
+ <img src="/assets/images/triangle-closed.png" class="toggle-content-img" alt=""
+ />Using Eclipse</a></p>
+ <div class="toggle-content-toggleme">
+
+<p>Create a <a href="{@docRoot}tools/projects/index.html#LibraryProjects">library
+project</a> based on the support library code:</p>
+
+<ol>
+ <li>Make sure you have downloaded the <strong>Android Support Library</strong>
+ using the <a href="#download">SDK Manager</a>.</li>
+ <li>Create a library project and ensure the required JAR files are included in the project's
+ build path:
+ <ol>
+ <li>Select <strong>File > Import</strong>.</li>
+ <li>Select <strong>Existing Android Code Into Workspace</strong> and click
+ <strong>Next</strong>.</li>
+ <li>Browse to the SDK installation directory and then to the Support Library folder.
+ For example, if you are adding the {@code appcompat} project, browse to
+ <code><sdk>/extras/android/support/v7/appcompat/</code>.</li>
+ <li>Click <strong>Finish</strong> to import the project. For the v7 appcompat project, you
+ should now see a new project titled <em>android-support-v7-appcompat</em>.</li>
+ <li>In the new library project, expand the {@code /libs} folder, right-click each {@code .jar}
+ file and select <strong>Build Path > Add to Build Path</strong>. For example, when
+ creating the the v7 appcompat project, add both the {@code android-support-v4.jar} and
+ {@code android-support-v7-appcompat.jar} files to the build path.</li>
+ <li>Right-click the project and select <strong>Build Path > Configure Build Path</strong>.
+ </li>
+ <li>In the <strong>Order and Export</strong> tab, check the <code>.jar</code> files you just
+ added to the build path, so they are available to projects that depend on this library
+ project. For example, the {@code appcompat} project requires you to export both the
+ {@code android-support-v4.jar} and {@code android-support-v7-appcompat.jar} files.</li>
+ <li>Uncheck <strong>Android Dependencies</strong>.</li>
+ <li>Click <strong>OK</strong> to complete the changes.</li>
+ </ol>
+ </li>
+</ol>
+
+<p>You now have a library project for your selected Support Library that you can use with one or
+ more application projects.</p>
+
+<p>Add the library to your application project:</p>
+ <ol>
+ <li>In the Project Explorer, right-click your project and select <strong>Properties</strong>.
+ <li>In the Library pane, click <strong>Add</strong>.
+ <li>Select the library project and click <strong>OK</strong>. For example, the
+ {@code appcompat} project should be listed as <strong>android-support-v7-appcompat</strong>.
+ </li>
+ <li>In the properties window, click <strong>OK</strong>.
+ </ol>
+
+ </div>
+</div>
+
+
+<div class="toggle-content closed">
+<p style="margin-top:5px"><a href="#" onclick="return toggleContent(this)">
+ <img src="/assets/images/triangle-closed.png" class="toggle-content-img" alt=""
+ />Using Android Studio</a></p>
+
+ <div class="toggle-content-toggleme">
+ <ol>
+ <li>Make sure you have downloaded the <strong>Android Support Repository</strong>
+ using the <a href="#download">SDK Manager</a>.</li>
+ <li>Open the {@code build.gradle} file for your application.</li>
+ <li>Add the support library feature project identifier to the {@code dependencies} section.
+ For example, to include the {@code appcompat} project add
+ {@code compile "com.android.support:appcompat-v7:18.0.+"} to the dependencies section, as
+ shown in the following example:
+<pre>
+dependencies {
+ ...
+ <b>compile "com.android.support:appcompat-v7:18.0.+"</b>
+}
+</pre>
+ </li>
+ </ol>
+ </div>
+</div>
+
+
+<h2 id="using-apis">Using Support Library APIs</h2>
+
+<p>Support Library classes that provide support for existing framework APIs typically have the
+ same name as framework class but are located in the <code>android.support</code> class packages,
+ or have a <code>*Compat</code> suffix.</p>
+
+<div class="caution">
+ <p><strong>Caution:</strong> When using classes from the Support Library, be certain you import
+ the class from the appropriate package. For example, when applying the {@code ActionBar}
+ class:</p>
+ <ul>
+ <li>{@code android.support.v7.app.ActionBar} when using the Support Library.</li>
+ <li>{@code android.app.ActionBar} when developing only for API level 11 or higher.</li>
+ </ul>
+</div>
+
+<p class="note">
+ <strong>Note:</strong> After including the Support Library in your application project, we
+ strongly recommend using the
+ <a href="{@docRoot}tools/help/proguard.html">ProGuard</a> tool to prepare your application APK
+ for release. In addition to protecting your source code, the ProGuard tool also removes unused
+ classes from any libraries you include in your application, which keeps the download size of
+ your application as small as possible. For more information, see
+ <a href="{@docRoot}tools/help/proguard.html">ProGuard</a>.
+</p>
+
+<p>Further guidance for using some Support Library features is provided in the Android developer
+ <a href="{@docRoot}training/index.html">training classes</a>,
+ <a href="{@docRoot}guide/components/index.html">guides</a>
+ and samples. For more information about the individual Support Library classes and methods, see
+ the {@link android.support.v4.app android.support} packages in the API reference.
+</p>
+
+
+<h3 id="manifest">Manifest Declaration Changes</h3>
+
+<p>If you are increasing the backward compatibility of your existing application to an earlier
+ version of the Android API with the Support Library, make sure to update your application's
+ manifest. Specifically, you should update the <code>android:minSdkVersion</code>
+ element of the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">
+ <code><uses-sdk></code></a> tag in the manifest to the new, lower version number, as
+ shown below:</p>
+
+<pre>
+ <uses-sdk
+ android:minSdkVersion="<b>7</b>"
+ android:targetSdkVersion="17" />
+</pre>
+
+<p>This change tells Google Play that your application can be installed on devices with Android
+ 2.1 (API level 7) and higher.</p>
+
+<p class="note">
+ <strong>Note:</strong> If you are including the v4 support and v7 appcompat libraries in your
+ application, you should specify a minimum SDK version of <code>"7"</code> (and not
+ <code>"4"</code>). The highest support library level you include in your application determines
+ the lowest API version in which it can operate.
+</p>
+
+
+<h2 id="samples">Code Samples</h2>
+
+<p>Each Support Library includes code samples to help you get started using the support
+APIs. The code is included in the download from the SDK Manager and is placed inside the Android
+SDK installation directory, as listed below:</p>
+
+<ul>
+ <li>4v Samples: {@code <sdk>/extras/android/support/samples/Support4Demos/}</li>
+ <li>7v Samples: {@code <sdk>/extras/android/support/samples/Support7Demos/}</li>
+ <li>13v Samples: {@code <sdk>/extras/android/support/samples/Support13Demos/}</li>
+ <li>App Navigation: {@code <sdk>/extras/android/support/samples/SupportAppNavigation/}</li>
+</ul>
+