Joe Fernandez | 5ffbba6 | 2013-07-15 15:53:03 -0700 | [diff] [blame] | 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> |
Scott Main | 27c5755 | 2013-08-01 11:31:38 -0700 | [diff] [blame] | 13 | <li><a href="#add-library">Adding Support Libraries</a> |
Joe Fernandez | 5ffbba6 | 2013-07-15 15:53:03 -0700 | [diff] [blame] | 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 |
Scott Main | 27c5755 | 2013-08-01 11:31:38 -0700 | [diff] [blame] | 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> |
Joe Fernandez | 5ffbba6 | 2013-07-15 15:53:03 -0700 | [diff] [blame] | 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> |
Joe Fernandez | a9a65c6 | 2013-07-23 23:24:13 -0700 | [diff] [blame] | 116 | <li>Create a {@code libs/} directory in the root of your application project.</li> |
Joe Fernandez | 5ffbba6 | 2013-07-15 15:53:03 -0700 | [diff] [blame] | 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 |
Joe Fernandez | a9a65c6 | 2013-07-23 23:24:13 -0700 | [diff] [blame] | 119 | application's project {@code libs/} directory. |
Joe Fernandez | 5ffbba6 | 2013-07-15 15:53:03 -0700 | [diff] [blame] | 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> |
Joe Fernandez | a9a65c6 | 2013-07-23 23:24:13 -0700 | [diff] [blame] | 133 | <li>Make sure you have downloaded the <strong>Android Support Repository</strong> |
Joe Fernandez | 5ffbba6 | 2013-07-15 15:53:03 -0700 | [diff] [blame] | 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 | |
Scott Main | d041301 | 2013-07-19 19:04:45 -0700 | [diff] [blame] | 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> |
Joe Fernandez | 5ffbba6 | 2013-07-15 15:53:03 -0700 | [diff] [blame] | 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> |
Joe Fernandez | a9a65c6 | 2013-07-23 23:24:13 -0700 | [diff] [blame] | 179 | <li>In the new library project, expand the {@code libs/} folder, right-click each {@code .jar} |
Joe Fernandez | 5ffbba6 | 2013-07-15 15:53:03 -0700 | [diff] [blame] | 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> |
Joe Fernandez | 6cb431f | 2013-11-13 14:49:42 -0800 | [diff] [blame] | 183 | <li>Right-click the library project folder and select <strong>Build Path > Configure |
| 184 | Build Path</strong>.</li> |
Joe Fernandez | 5ffbba6 | 2013-07-15 15:53:03 -0700 | [diff] [blame] | 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> |
Joe Fernandez | 6cb431f | 2013-11-13 14:49:42 -0800 | [diff] [blame] | 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> |
Joe Fernandez | 5ffbba6 | 2013-07-15 15:53:03 -0700 | [diff] [blame] | 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> |
Joe Fernandez | 6cb431f | 2013-11-13 14:49:42 -0800 | [diff] [blame] | 206 | <li>In the properties window, click <strong>OK</strong>.</li> |
Joe Fernandez | 5ffbba6 | 2013-07-15 15:53:03 -0700 | [diff] [blame] | 207 | </ol> |
| 208 | |
Joe Fernandez | c6735c0 | 2014-01-07 15:15:43 -0800 | [diff] [blame] | 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 | |
Joe Fernandez | 5ffbba6 | 2013-07-15 15:53:03 -0700 | [diff] [blame] | 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 | |