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 <div class="toggle-content closed"> 108 <p style="margin-top:5px"><a href="#" onclick="return toggleContent(this)"> 109 <img src="/assets/images/triangle-closed.png" class="toggle-content-img" alt="" 110 />Using Eclipse</a></p> 111 112 <div class="toggle-content-toggleme"> 113 <ol> 114 <li>Make sure you have downloaded the <strong>Android Support Library</strong> 115 using the <a href="#download">SDK Manager</a>.</li> 116 <li>Create a {@code libs/} directory in the root of your application project.</li> 117 <li>Copy the JAR file from your Android SDK installation directory (e.g., 118 {@code <sdk>/extras/android/support/v4/android-support-v4.jar}) into your 119 application's project {@code libs/} directory. 120 <li>Right click the JAR file and select <strong>Build Path > Add to Build Path</strong>. 121 </li> 122 </ol> 123 </div> 124 </div> 125 126 <div class="toggle-content closed"> 127 <p style="margin-top:5px"><a href="#" onclick="return toggleContent(this)"> 128 <img src="/assets/images/triangle-closed.png" class="toggle-content-img" alt="" 129 />Using Android Studio</a></p> 130 131 <div class="toggle-content-toggleme"> 132 <ol> 133 <li>Make sure you have downloaded the <strong>Android Support Repository</strong> 134 using the <a href="#download">SDK Manager</a>.</li> 135 <li>Open the {@code build.gradle} file for your application.</li> 136 <li>Add the support library to the {@code dependencies} section. For example, to add the v4 137 support library, add the following lines: 138 <pre> 139 dependencies { 140 ... 141 <b>compile "com.android.support:support-v4:18.0.+"</b> 142 } 143 </pre> 144 </li> 145 </ol> 146 </div> 147 </div> 148 149 150 <h3 id="libs-with-res">Adding libraries with resources</h3> 151 152 <p>To add a Support Library with resources (such as 153 <a href="{@docRoot}tools/support-library/features.html#v7-appcompat">v7 154 appcompat</a> for action bar) to your application project:</p> 155 156 <div class="toggle-content closed"> 157 <p style="margin-top:5px"><a href="#" onclick="return toggleContent(this)"> 158 <img src="/assets/images/triangle-closed.png" class="toggle-content-img" alt="" 159 />Using Eclipse</a></p> 160 <div class="toggle-content-toggleme"> 161 162 <p>Create a <a href="{@docRoot}tools/projects/index.html#LibraryProjects">library 163 project</a> based on the support library code:</p> 164 165 <ol> 166 <li>Make sure you have downloaded the <strong>Android Support Library</strong> 167 using the <a href="#download">SDK Manager</a>.</li> 168 <li>Create a library project and ensure the required JAR files are included in the project's 169 build path: 170 <ol> 171 <li>Select <strong>File > Import</strong>.</li> 172 <li>Select <strong>Existing Android Code Into Workspace</strong> and click 173 <strong>Next</strong>.</li> 174 <li>Browse to the SDK installation directory and then to the Support Library folder. 175 For example, if you are adding the {@code appcompat} project, browse to 176 <code><sdk>/extras/android/support/v7/appcompat/</code>.</li> 177 <li>Click <strong>Finish</strong> to import the project. For the v7 appcompat project, you 178 should now see a new project titled <em>android-support-v7-appcompat</em>.</li> 179 <li>In the new library project, expand the {@code libs/} folder, right-click each {@code .jar} 180 file and select <strong>Build Path > Add to Build Path</strong>. For example, when 181 creating the the v7 appcompat project, add both the {@code android-support-v4.jar} and 182 {@code android-support-v7-appcompat.jar} files to the build path.</li> 183 <li>Right-click the library project folder and select <strong>Build Path > Configure 184 Build Path</strong>.</li> 185 <li>In the <strong>Order and Export</strong> tab, check the <code>.jar</code> files you just 186 added to the build path, so they are available to projects that depend on this library 187 project. For example, the {@code appcompat} project requires you to export both the 188 {@code android-support-v4.jar} and {@code android-support-v7-appcompat.jar} files.</li> 189 <li>Uncheck <strong>Android Dependencies</strong>.</li> 190 <li>Click <strong>OK</strong> to complete the changes.</li> 191 </ol> 192 </li> 193 </ol> 194 195 <p>You now have a library project for your selected Support Library that you can use with one or 196 more application projects.</p> 197 198 <p>Add the library to your application project:</p> 199 <ol> 200 <li>In the Project Explorer, right-click your project and select <strong>Properties</strong>.</li> 201 <li>In the category panel on the left side of the dialog, select <strong>Android</strong>.</li> 202 <li>In the Library pane, click the <strong>Add</strong> button.</li> 203 <li>Select the library project and click <strong>OK</strong>. For example, the 204 {@code appcompat} project should be listed as <strong>android-support-v7-appcompat</strong>. 205 </li> 206 <li>In the properties window, click <strong>OK</strong>.</li> 207 </ol> 208 209 <p class="note"> 210 <strong>Note:</strong> If you are using the {@code android-support-v7-mediarouter} support 211 library, you should note that it depends on the {@code android-support-v7-appcompat} library. 212 In order for the v7 mediarouter library to compile, you must import both library projects into 213 your development workspace. Then follow the procedure above to add the v7 appcompat project as a 214 library to the v7 mediarouter library project. 215 </p> 216 217 </div> 218 </div> 219 220 221 <div class="toggle-content closed"> 222 <p style="margin-top:5px"><a href="#" onclick="return toggleContent(this)"> 223 <img src="/assets/images/triangle-closed.png" class="toggle-content-img" alt="" 224 />Using Android Studio</a></p> 225 226 <div class="toggle-content-toggleme"> 227 <ol> 228 <li>Make sure you have downloaded the <strong>Android Support Repository</strong> 229 using the <a href="#download">SDK Manager</a>.</li> 230 <li>Open the {@code build.gradle} file for your application.</li> 231 <li>Add the support library feature project identifier to the {@code dependencies} section. 232 For example, to include the {@code appcompat} project add 233 {@code compile "com.android.support:appcompat-v7:18.0.+"} to the dependencies section, as 234 shown in the following example: 235 <pre> 236 dependencies { 237 ... 238 <b>compile "com.android.support:appcompat-v7:18.0.+"</b> 239 } 240 </pre> 241 </li> 242 </ol> 243 </div> 244 </div> 245 246 247 <h2 id="using-apis">Using Support Library APIs</h2> 248 249 <p>Support Library classes that provide support for existing framework APIs typically have the 250 same name as framework class but are located in the <code>android.support</code> class packages, 251 or have a <code>*Compat</code> suffix.</p> 252 253 <div class="caution"> 254 <p><strong>Caution:</strong> When using classes from the Support Library, be certain you import 255 the class from the appropriate package. For example, when applying the {@code ActionBar} 256 class:</p> 257 <ul> 258 <li>{@code android.support.v7.app.ActionBar} when using the Support Library.</li> 259 <li>{@code android.app.ActionBar} when developing only for API level 11 or higher.</li> 260 </ul> 261 </div> 262 263 <p class="note"> 264 <strong>Note:</strong> After including the Support Library in your application project, we 265 strongly recommend using the 266 <a href="{@docRoot}tools/help/proguard.html">ProGuard</a> tool to prepare your application APK 267 for release. In addition to protecting your source code, the ProGuard tool also removes unused 268 classes from any libraries you include in your application, which keeps the download size of 269 your application as small as possible. For more information, see 270 <a href="{@docRoot}tools/help/proguard.html">ProGuard</a>. 271 </p> 272 273 <p>Further guidance for using some Support Library features is provided in the Android developer 274 <a href="{@docRoot}training/index.html">training classes</a>, 275 <a href="{@docRoot}guide/components/index.html">guides</a> 276 and samples. For more information about the individual Support Library classes and methods, see 277 the {@link android.support.v4.app android.support} packages in the API reference. 278 </p> 279 280 281 <h3 id="manifest">Manifest Declaration Changes</h3> 282 283 <p>If you are increasing the backward compatibility of your existing application to an earlier 284 version of the Android API with the Support Library, make sure to update your application's 285 manifest. Specifically, you should update the <code>android:minSdkVersion</code> 286 element of the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"> 287 <code><uses-sdk></code></a> tag in the manifest to the new, lower version number, as 288 shown below:</p> 289 290 <pre> 291 <uses-sdk 292 android:minSdkVersion="<b>7</b>" 293 android:targetSdkVersion="17" /> 294 </pre> 295 296 <p>This change tells Google Play that your application can be installed on devices with Android 297 2.1 (API level 7) and higher.</p> 298 299 <p class="note"> 300 <strong>Note:</strong> If you are including the v4 support and v7 appcompat libraries in your 301 application, you should specify a minimum SDK version of <code>"7"</code> (and not 302 <code>"4"</code>). The highest support library level you include in your application determines 303 the lowest API version in which it can operate. 304 </p> 305 306 307 <h2 id="samples">Code Samples</h2> 308 309 <p>Each Support Library includes code samples to help you get started using the support 310 APIs. The code is included in the download from the SDK Manager and is placed inside the Android 311 SDK installation directory, as listed below:</p> 312 313 <ul> 314 <li>4v Samples: {@code <sdk>/extras/android/support/samples/Support4Demos/}</li> 315 <li>7v Samples: {@code <sdk>/extras/android/support/samples/Support7Demos/}</li> 316 <li>13v Samples: {@code <sdk>/extras/android/support/samples/Support13Demos/}</li> 317 <li>App Navigation: {@code <sdk>/extras/android/support/samples/SupportAppNavigation/}</li> 318 </ul> 319 320
