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 project and select <strong>Build Path > Configure Build Path</strong>. 184 </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>. 201 <li>In the Library pane, click <strong>Add</strong>. 202 <li>Select the library project and click <strong>OK</strong>. For example, the 203 {@code appcompat} project should be listed as <strong>android-support-v7-appcompat</strong>. 204 </li> 205 <li>In the properties window, click <strong>OK</strong>. 206 </ol> 207 208 </div> 209 </div> 210 211 212 <div class="toggle-content closed"> 213 <p style="margin-top:5px"><a href="#" onclick="return toggleContent(this)"> 214 <img src="/assets/images/triangle-closed.png" class="toggle-content-img" alt="" 215 />Using Android Studio</a></p> 216 217 <div class="toggle-content-toggleme"> 218 <ol> 219 <li>Make sure you have downloaded the <strong>Android Support Repository</strong> 220 using the <a href="#download">SDK Manager</a>.</li> 221 <li>Open the {@code build.gradle} file for your application.</li> 222 <li>Add the support library feature project identifier to the {@code dependencies} section. 223 For example, to include the {@code appcompat} project add 224 {@code compile "com.android.support:appcompat-v7:18.0.+"} to the dependencies section, as 225 shown in the following example: 226 <pre> 227 dependencies { 228 ... 229 <b>compile "com.android.support:appcompat-v7:18.0.+"</b> 230 } 231 </pre> 232 </li> 233 </ol> 234 </div> 235 </div> 236 237 238 <h2 id="using-apis">Using Support Library APIs</h2> 239 240 <p>Support Library classes that provide support for existing framework APIs typically have the 241 same name as framework class but are located in the <code>android.support</code> class packages, 242 or have a <code>*Compat</code> suffix.</p> 243 244 <div class="caution"> 245 <p><strong>Caution:</strong> When using classes from the Support Library, be certain you import 246 the class from the appropriate package. For example, when applying the {@code ActionBar} 247 class:</p> 248 <ul> 249 <li>{@code android.support.v7.app.ActionBar} when using the Support Library.</li> 250 <li>{@code android.app.ActionBar} when developing only for API level 11 or higher.</li> 251 </ul> 252 </div> 253 254 <p class="note"> 255 <strong>Note:</strong> After including the Support Library in your application project, we 256 strongly recommend using the 257 <a href="{@docRoot}tools/help/proguard.html">ProGuard</a> tool to prepare your application APK 258 for release. In addition to protecting your source code, the ProGuard tool also removes unused 259 classes from any libraries you include in your application, which keeps the download size of 260 your application as small as possible. For more information, see 261 <a href="{@docRoot}tools/help/proguard.html">ProGuard</a>. 262 </p> 263 264 <p>Further guidance for using some Support Library features is provided in the Android developer 265 <a href="{@docRoot}training/index.html">training classes</a>, 266 <a href="{@docRoot}guide/components/index.html">guides</a> 267 and samples. For more information about the individual Support Library classes and methods, see 268 the {@link android.support.v4.app android.support} packages in the API reference. 269 </p> 270 271 272 <h3 id="manifest">Manifest Declaration Changes</h3> 273 274 <p>If you are increasing the backward compatibility of your existing application to an earlier 275 version of the Android API with the Support Library, make sure to update your application's 276 manifest. Specifically, you should update the <code>android:minSdkVersion</code> 277 element of the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"> 278 <code><uses-sdk></code></a> tag in the manifest to the new, lower version number, as 279 shown below:</p> 280 281 <pre> 282 <uses-sdk 283 android:minSdkVersion="<b>7</b>" 284 android:targetSdkVersion="17" /> 285 </pre> 286 287 <p>This change tells Google Play that your application can be installed on devices with Android 288 2.1 (API level 7) and higher.</p> 289 290 <p class="note"> 291 <strong>Note:</strong> If you are including the v4 support and v7 appcompat libraries in your 292 application, you should specify a minimum SDK version of <code>"7"</code> (and not 293 <code>"4"</code>). The highest support library level you include in your application determines 294 the lowest API version in which it can operate. 295 </p> 296 297 298 <h2 id="samples">Code Samples</h2> 299 300 <p>Each Support Library includes code samples to help you get started using the support 301 APIs. The code is included in the download from the SDK Manager and is placed inside the Android 302 SDK installation directory, as listed below:</p> 303 304 <ul> 305 <li>4v Samples: {@code <sdk>/extras/android/support/samples/Support4Demos/}</li> 306 <li>7v Samples: {@code <sdk>/extras/android/support/samples/Support7Demos/}</li> 307 <li>13v Samples: {@code <sdk>/extras/android/support/samples/Support13Demos/}</li> 308 <li>App Navigation: {@code <sdk>/extras/android/support/samples/SupportAppNavigation/}</li> 309 </ul> 310 311
