1 page.title=Support Library Setup 2 3 @jd:body 4 5 6 <div id="qv-wrapper"> 7 <div id="qv"> 8 9 <h2>In this document</h2> 10 <ol> 11 <li><a href="#download">Downloading the Support Library</a></li> 12 <li><a href="#choosing">Choosing Support Libraries</a></li> 13 <li><a href="#add-library">Adding Support Libraries</a> 14 <ol> 15 <li><a href="#libs-without-res">Adding libraries without resources</a></li> 16 <li><a href="#libs-with-res">Adding libraries with resources</a></li> 17 </ol> 18 </li> 19 <li><a href="#using-apis">Using Support Library APIs</a> 20 <ol> 21 <li><a href="#manifest">Manifest Declaration Changes</a></li> 22 </ol> 23 </li> 24 <li><a href="#samples">Code Samples</a></li> 25 </ol> 26 27 <h2>See also</h2> 28 <ol> 29 <li><a href="{@docRoot}tools/support-library/index.html#revisions"> 30 Support Library Revisions</a></li> 31 <li><a href="{@docRoot}tools/support-library/features.html"> 32 Support Library Features</a></li> 33 </ol> 34 35 </div> 36 </div> 37 38 <p>How you setup the Android Support Libraries in your development project depends on what features 39 you want to use and what range of Android platform versions you want to support with your 40 application.</p> 41 42 <p>This document guides you through downloading the Support Library package and adding libraries 43 to your development environment.</p> 44 45 46 <h2 id="download">Downloading the Support Libraries</h2> 47 48 <p>The Android Support Library package is provided as a supplemental download to the Android SDK 49 and is available through the Android 50 <a href="{@docRoot}tools/help/sdk-manager.html">SDK Manager</a>. Follow the 51 instructions below to obtain the Support Library files. 52 </p> 53 54 <p>To download the Support Library through the SDK Manager:</p> 55 56 <ol> 57 <li>Start the Android <a href="{@docRoot}tools/help/sdk-manager.html">SDK Manager</a>.</li> 58 <li>In the SDK Manager window, scroll to the end of the <em>Packages</em> list, 59 find the <em>Extras</em> folder and, if necessary, expand to show its contents.</li> 60 <li>Select the <strong>Android Support Library</strong> item. 61 <p class="note"> 62 <strong>Note:</strong> If you're developing with Android Studio, select and install the 63 <strong>Android Support Repository</strong> item instead. 64 </p> 65 </li> 66 <li>Click the <strong>Install packages...</strong> button.</li> 67 </ol> 68 69 <img src="{@docRoot}images/tools/sdk-manager-support-libs.png" width="525" alt="" /> 70 <p class="img-caption"><strong>Figure 1.</strong> The Android SDK Manager with the 71 Android Support Library selected.</p> 72 73 <p>After downloading, the tool installs the Support Library files to your existing Android SDK 74 directory. The library files are located in the following subdirectory of your SDK: 75 {@code <sdk>/extras/android/support/} directory.</p> 76 77 78 <h2 id="choosing">Choosing Support Libraries</h2> 79 80 <p>Before adding a Support Library to your application, decide what features you want to include 81 and the lowest Android versions you want to support. For more information on the features 82 provided by the different libraries, see 83 <a href="{@docRoot}tools/support-library/features.html">Support Library Features</a>.</p> 84 85 86 <h2 id="add-library">Adding Support Libraries</h2> 87 88 <p>In order to use a Support Library, you must modify your application's project's 89 classpath dependencies within your development environment. You must perform this procedure for 90 each Support Library you want to use.</p> 91 92 <p>Some Support Libraries contain resources beyond compiled code classes, such as images or XML 93 files. For example, the <a href="{@docRoot}tools/support-library/features.html#v7-appcompat">v7 94 appcompat</a> and <a href="{@docRoot}tools/support-library/features.html#v7-gridlayout">v7 95 gridlayout</a> libraries include resources.</p> 96 97 <p>If you are not sure if a library contains resources, check the 98 <a href="{@docRoot}tools/support-library/features.html">Support Library Features</a> page. 99 The following sections describe how to add a Support Library with or without resources to your 100 application project. </p> 101 102 103 <h3 id="libs-without-res">Adding libraries without resources</h3> 104 105 <p>To add a Support Library without resources to your application project:</p> 106 107 <ol> 108 <li>Make sure you have downloaded the <strong>Android Support Repository</strong> 109 using the <a href="#download">SDK Manager</a>.</li> 110 <li>Open the {@code build.gradle} file for your application.</li> 111 <li>Add the support library to the {@code dependencies} section. For example, to add the v4 112 support library, add the following lines: 113 <pre> 114 dependencies { 115 ... 116 <b>compile "com.android.support:support-v4:18.0.+"</b> 117 } 118 </pre> 119 </li> 120 </ol> 121 122 123 <h3 id="libs-with-res">Adding libraries with resources</h3> 124 125 <p>To add a Support Library with resources (such as 126 <a href="{@docRoot}tools/support-library/features.html#v7-appcompat">v7 127 appcompat</a> for action bar) to your application project:</p> 128 129 <ol> 130 <li>Make sure you have downloaded the <strong>Android Support Repository</strong> 131 using the <a href="#download">SDK Manager</a>.</li> 132 <li>Open the {@code build.gradle} file for your application.</li> 133 <li>Add the support library feature project identifier to the {@code dependencies} section. 134 For example, to include the {@code appcompat} project add 135 {@code compile "com.android.support:appcompat-v7:18.0.+"} to the dependencies section, as 136 shown in the following example: 137 <pre> 138 dependencies { 139 ... 140 <b>compile "com.android.support:appcompat-v7:18.0.+"</b> 141 } 142 </pre> 143 </li> 144 </ol> 145 146 147 <h2 id="using-apis">Using Support Library APIs</h2> 148 149 <p>Support Library classes that provide support for existing framework APIs typically have the 150 same name as framework class but are located in the <code>android.support</code> class packages, 151 or have a <code>*Compat</code> suffix.</p> 152 153 <div class="caution"> 154 <p><strong>Caution:</strong> When using classes from the Support Library, be certain you import 155 the class from the appropriate package. For example, when applying the {@code ActionBar} 156 class:</p> 157 <ul> 158 <li>{@code android.support.v7.app.ActionBar} when using the Support Library.</li> 159 <li>{@code android.app.ActionBar} when developing only for API level 11 or higher.</li> 160 </ul> 161 </div> 162 163 <p class="note"> 164 <strong>Note:</strong> After including the Support Library in your application project, we 165 strongly recommend using the 166 <a href="{@docRoot}tools/help/proguard.html">ProGuard</a> tool to prepare your application APK 167 for release. In addition to protecting your source code, the ProGuard tool also removes unused 168 classes from any libraries you include in your application, which keeps the download size of 169 your application as small as possible. For more information, see 170 <a href="{@docRoot}tools/help/proguard.html">ProGuard</a>. 171 </p> 172 173 <p>Further guidance for using some Support Library features is provided in the Android developer 174 <a href="{@docRoot}training/index.html">training classes</a>, 175 <a href="{@docRoot}guide/components/index.html">guides</a> 176 and samples. For more information about the individual Support Library classes and methods, see 177 the {@link android.support.v4.app android.support} packages in the API reference. 178 </p> 179 180 181 <h3 id="manifest">Manifest Declaration Changes</h3> 182 183 <p>If you are increasing the backward compatibility of your existing application to an earlier 184 version of the Android API with the Support Library, make sure to update your application's 185 manifest. Specifically, you should update the <code>android:minSdkVersion</code> 186 element of the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"> 187 <code><uses-sdk></code></a> tag in the manifest to the new, lower version number, as 188 shown below:</p> 189 190 <pre> 191 <uses-sdk 192 android:minSdkVersion="<b>7</b>" 193 android:targetSdkVersion="17" /> 194 </pre> 195 196 <p>The manifest setting tells Google Play that your application can be installed on devices with Android 197 2.1 (API level 7) and higher. </p> 198 199 <p>If you are using Gradle build files, the <code>minSdkVersion</code> setting in the build file 200 overrides the manifest settings. </p> 201 202 <pre> 203 apply plugin: 'com.android.application' 204 205 android { 206 ... 207 208 defaultConfig { 209 minSdkVersion 8 210 ... 211 } 212 ... 213 } 214 </pre> 215 216 <p>In this case, the build file setting tells Google Play that the default build variant of your 217 application can be installed on devices with Android 2.2 (API level 8) and higher. For more 218 information about build variants, see 219 <a href="{@docRoot}studio/build/index.html">Build System Overview</a>. </p> 220 221 <p class="note"> 222 <strong>Note:</strong> If you are including the v4 support and v7 appcompat libraries in your 223 application, you should specify a minimum SDK version of <code>"7"</code> (and not 224 <code>"4"</code>). The highest support library level you include in your application determines 225 the lowest API version in which it can operate. 226 </p> 227 228 229 <h2 id="samples">Code Samples</h2> 230 231 <p>Each Support Library includes code samples to help you get started using the support 232 APIs. The code is included in the download from the SDK Manager and is placed inside the Android 233 SDK installation directory, as listed below:</p> 234 235 <ul> 236 <li>4v Samples: {@code <sdk>/extras/android/support/samples/Support4Demos/}</li> 237 <li>7v Samples: {@code <sdk>/extras/android/support/samples/Support7Demos/}</li> 238 <li>13v Samples: {@code <sdk>/extras/android/support/samples/Support13Demos/}</li> 239 <li>App Navigation: {@code <sdk>/extras/android/support/samples/SupportAppNavigation/}</li> 240 </ul> 241 242
