xref: /frameworks/base/docs/html/tools/support-library/setup.jd

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 &lt;sdk&gt;/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="{@docRoot}tools/support-library/features.html#v7-appcompat">v7
  appcompat</a> and <a href="{@docRoot}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 &lt;sdk&gt;/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 &gt; 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 (such as
  <a href="{@docRoot}tools/support-library/features.html#v7-appcompat">v7
  appcompat</a> for action bar) 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 &gt; 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>&lt;sdk&gt;/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 &gt; 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 library project folder and select <strong>Build Path &gt; 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>
    <li>In the category panel on the left side of the dialog, select <strong>Android</strong>.</li>
    <li>In the Library pane, click the <strong>Add</strong> button.</li>
    <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>.</li>
  </ol>

<p class="note">
  <strong>Note:</strong> If you are using the {@code android-support-v7-mediarouter} support
  library, you should note that it depends on the {@code android-support-v7-appcompat} library.
  In order for the v7 mediarouter library to compile, you must import both library projects into
  your development workspace. Then follow the procedure above to add the v7 appcompat project as a
  library to the v7 mediarouter library project.
</p>

  </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>&lt;uses-sdk&gt;</code></a> tag in the manifest to the new, lower version number, as
  shown below:</p>

<pre>
  &lt;uses-sdk
      android:minSdkVersion="<b>7</b>"
      android:targetSdkVersion="17" /&gt;
</pre>

<p>The manifest setting tells Google Play that your application can be installed on devices with Android
  2.1 (API level 7) and higher.  </p>

<p>If you are using Gradle build files, the <code>minSdkVersion</code> setting in the build file
  overrides the manifest settings.  </p>

<pre>
apply plugin: 'com.android.application'

android {
    ...

    defaultConfig {
        minSdkVersion 8
        ...
    }
    ...
}
</pre>

<p>In this case, the build file setting tells Google Play that the default build variant of your
  application can be installed on devices with Android 2.2 (API level 8) and higher. For more
  information about build variants, see
  <a href="{@docRoot}sdk/installing/studio-build.html">Build System Overview</a>. </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 &lt;sdk&gt;/extras/android/support/samples/Support4Demos/}</li>
  <li>7v Samples: {@code &lt;sdk&gt;/extras/android/support/samples/Support7Demos/}</li>
  <li>13v Samples: {@code &lt;sdk&gt;/extras/android/support/samples/Support13Demos/}</li>
  <li>App Navigation: {@code &lt;sdk&gt;/extras/android/support/samples/SupportAppNavigation/}</li>
</ul>