1 Subject: How to build use a Cupcake Android SDK & ADT Eclipse plugin. 2 Date: 2009/03/27 3 4 5 Table of content: 6 0- License 7 1- Foreword 8 2- Installation steps 9 3- For Eclipse users 10 4- For Ant users 11 5- Targets, AVDs, Emulator changes 12 6- Conclusion 13 14 15 16 ---------- 17 0- License 18 ---------- 19 20 Copyright (C) 2009 The Android Open Source Project 21 22 Licensed under the Apache License, Version 2.0 (the "License"); 23 you may not use this file except in compliance with the License. 24 You may obtain a copy of the License at 25 26 http://www.apache.org/licenses/LICENSE-2.0 27 28 Unless required by applicable law or agreed to in writing, software 29 distributed under the License is distributed on an "AS IS" BASIS, 30 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 31 See the License for the specific language governing permissions and 32 limitations under the License. 33 34 35 36 ----------- 37 1- Foreword 38 ----------- 39 40 This explains how to use the "new" SDK provided starting with cupcake. 41 The new SDK has as a different structure than the pre-cupcake ones. 42 43 This means: 44 - The new SDK does not work with older Eclipse plugins (ADT 0.8) 45 - The old SDKs (1.0 and 1.1) do NOT work with this Eclipse plugin (ADT 0.9) 46 47 48 49 ---------------------- 50 2- Installation steps 51 ---------------------- 52 53 First you will need to grab the zip of the SDK for your platform or build it 54 yourself. Please refer to the accompanying document "howto_build_SDK.txt" if 55 needed. 56 57 Unzip the SDK somewhere. We'll call that directory "SDK" in command-line 58 examples. 59 60 Grab the new ADT Eclipse plugin zip file or build it yourself. Keep it 61 somewhere (no need to unzip). 62 63 64 65 -------------------- 66 3- For Eclipse users 67 -------------------- 68 69 70 Below we'll explain how you can upgrade your Eclipse install to the new plugin. 71 If you already have a working Eclipse installation with a pre-0.9 ADT, 72 another suggestion is to simply install a new copy of Eclipse and create a 73 new empty workspace. This is just a precaution. The update process should 74 be otherwise harmless. 75 76 77 78 A- Setting up Eclipse 79 --------------------- 80 81 - You must have Eclipse 3.3 or 3.4. Eclipse 3.2 is not longer supported. 82 83 There are many flavors, or "editions", of Eclipse. To develop, we'd recommend 84 the "Java" edition. The "RCP" one is totally suitable too. The J2EE one is 85 probably overkill. 86 87 88 - If updating an existing Eclipse, use Help > Software Update and please 89 uninstall the two features of the previous ADT: the "editors" feature and the 90 ADT feature itself. 91 92 => If you don't you will get a conflict on editors when installing 93 the new one. 94 95 - Using Help > Software Update, add a new "archived site", point it to the new 96 adt.zip (e.g. android-eclipse-<some-id>.zip), select the "Install" button at 97 the top right and restart eclipse as needed. 98 99 - After it restarts, please use Window > Preferences > Android and select 100 the new SDK folder that you unzipped in paragraph 2. 101 102 103 104 B- Updating older projects 105 -------------------------- 106 107 If you have pre-0.9 projects in your Eclipse workspace, or if you import them 108 from your code repository, these projects will fail to build at first. 109 110 First right-click on the project and select "Properties": 111 112 - In the properties, open the Android panel and select the platform to use. 113 The SDK comes with a 1.5 platform. Select it and close the properties panel. 114 - Do a clean build. 115 116 117 The new plugin creates a "gen" folder in your project where it puts the R.java 118 and all automatically generated AIDL java files. If you get an error such as: 119 120 "The type R is already defined" 121 122 that means you must check to see if your old R.java or your old auto-generated 123 AIDL Java files are still present in the "src" folder. If yes, remove them. 124 125 Note: this does not apply to your own hand-crafted parcelable AIDL java files. 126 127 Note: if you want to reuse the project with an older Eclipse ADT install, 128 simply remove the "gen" folder from the build path of the project. 129 130 131 C- New Wizards 132 -------------- 133 134 The "New Android Project" wizard has been expanded to use the multi-platform 135 capabilities of the new SDK. 136 137 There is now a "New XML File" wizard that lets you create skeleton XML resource 138 files for your Android projects. This makes it easier to create a new layout, a 139 new strings file, etc. 140 141 Both wizard are available via File > New... as well as new icons in the main 142 icon bar. If you do not see the new icons, you may need to use Window > Reset 143 Perspective on your Java perspective. 144 145 146 Please see step 5 "Emulator changes" below for important details on how to run 147 the emulator. 148 149 150 151 ---------------- 152 4- For Ant users 153 ---------------- 154 155 156 A- build.xml has changed 157 ------------------------ 158 159 You must re-create your build.xml file. 160 161 First if you had customized your build.xml, make a copy of it: 162 163 $ cd my-project 164 $ cp build.xml build.xml.old 165 166 167 Then use the new "android" tool to create a new build.xml: 168 169 $ SDK/tools/android update project --path /path/to/my-project 170 171 or 172 173 $ cd my-project 174 $ SDK/tools/android update project --path . 175 176 177 A "gen" folder will be created the first time you build and your R.java and 178 your AIDL Java files will be generated in this "gen" folder. You MUST remove 179 the old R.java and old auto-generated AIDL java files manually. (Note: this 180 does not apply to your own hand-crafted parcelabe AIDL java files.) 181 182 183 B- Where is activitycreator? 184 ---------------------------- 185 186 Note that the "activitycreator" tool has been replaced by the new "android" 187 tool too. Example of how to create a new Ant project: 188 189 $ SDK/tools/android create project --path /path/to/my/project --name ProjectName 190 --package com.mycompany.myapp --activity MyActivityClass 191 --target 1 --mode activity 192 193 194 Please see paragraph 5 below for important details on how to run the emulator 195 and the meaning of that "--target 1" parameter. 196 197 198 199 ---------------------------------- 200 5- Targets, AVDs, Emulator changes 201 ---------------------------------- 202 203 This applies to BOTH Eclipse and Ant users. 204 205 One major change with the emulator is that now you must pre-create an "Android 206 Virtual Device" (a.k.a "AVD") before you run the emulator. 207 208 209 210 A- What is an AVD and why do I need one? 211 ---------------------------------------- 212 213 What is an "AVD"? If you forget, just run: 214 215 $ SDK/tools/emulator -help-virtual-device 216 217 An Android Virtual Device (AVD) models a single virtual device running the 218 Android platform that has, at least, its own kernel, system image and data 219 partition. 220 221 There is a lot more explanation given by the emulator. Please run the help 222 command given above to read the rest. 223 224 The bottom line is that you can create many emulator configurations, or "AVDs", 225 each with their own system image and most important each with their own user 226 data and SD card data. Then you tell Eclipse or the emulator which one to use 227 to debug or run your applications. 228 229 230 Note for Eclipse users: eventually there will be a user interface to do all of 231 these operations. For right now, please use the command line interface. 232 233 234 B- Listing targets and AVDs 235 --------------------------- 236 237 There is a new tool called "android" in the SDK that lets you know which 238 "target" and AVDs you can use. 239 240 A target is a specific version of Android that you can use. By default the SDK 241 comes with an "Android 1.5" target, codenamed "cupcake". In the future there 242 will be more versions of Android to use, e.g. "Android 2.0" or specific add-ons 243 provided by hardware manufacturers. When you want to run an emulator, you need 244 to specify a given flavor of Android: this is the "target". 245 246 247 To learn about available targets in your SDK, use this command: 248 249 $ SDK/tools/android list targets 250 251 This will give you an output such as: 252 253 Available Android targets: 254 [1] Android 1.5 255 API level: 3 256 Skins: HVGA (default), HVGA-L, HVGA-P, QVGA-L, QVGA-P 257 258 Note the "[1]". Later you will need to reference this as "--target 1" on the 259 command line. 260 261 262 Similarly you can list the available AVDs: 263 264 $ SDK/tools/android list avds 265 266 Which might output something as: 267 268 Available Android Virtual Devices: 269 Name: my_avd 270 Path: C:\Users\<username>\.android\avd\my_avd.avd 271 Target: Android 1.5 (API level 3) 272 Skin: 320x480 273 Sdcard: 16M 274 275 276 277 C- Creating an AVD 278 ------------------ 279 280 To create a configuration: 281 282 $ SDK/tools/android create avd --name my_avd_name --target 1 283 284 285 where "target 1" is the index of a target listed by "android list targets". 286 287 The AVD name is purely an identifier used to refer to the AVD later. 288 Since it is used as directory name, please avoid using shell or path specific 289 characters. 290 291 To learn the various options available when creating an AVD, simply type: 292 293 $ SDK/tools/android create avd 294 295 The android tool will automatically print an explanation of required arguments. 296 297 298 299 D- Invoking an AVD from the command-line 300 ---------------------------------------- 301 302 To use this AVD in the emulator from the command-line, type: 303 304 $ SDK/tools/emulator @my_avd_name 305 306 307 For more options, please consult the emulator help: 308 309 $ SDK/tools/emulator -help-virtual-device 310 311 312 313 E- Invoking an AVD from Eclipse 314 ------------------------------- 315 316 By default Android projects in Eclipse have an "automatic target" mode. 317 In this mode, when a project is deployed in debug or run, it checks: 318 - If there's one running device or emulator, this is used for deployment. 319 - If there's more than one running device or emulator, a "device chooser" is 320 shown to let the user select which one to use. 321 - If there are no running devices or emulators, ADT looks at available AVDs. 322 If one matches the project configuration (e.g. same API level), it is 323 automatically used. 324 325 Alternatively you can edit the "launch configuration" on your Android project 326 in Eclipse by selecting the menu Run > Run Configurations. In the "target" tab 327 of the configuration, you can choose: 328 329 - Manual or automatic targetting mode. 330 331 - Manual means to always present the device chooser. 332 - Automatic is the behavior explained above. 333 334 - In automatic mode, which AVD is preferred. If none is selected, the first 335 suitable is used. 336 337 338 F- AVD concurrency 339 ------------------ 340 341 You can no longer run several emulators at the same time on the same 342 configuration. 343 344 Before this used to put the second or more emulators in a transient read-only 345 mode that would not save user data. 346 347 Now you just need to create as many AVDs as you want to run emulators. 348 349 For example if you are working on a client/server application for Android, you 350 could create a "client" AVD and a "server" AVD then run them both at once. The 351 emulator window will show you the AVD name so that you know which one is which. 352 353 Example: 354 355 $ SDK/tools/android create avd --name client --target 1 --sdcard 16M --skin HVGA 356 $ SDK/tools/android create avd --name server --target 1 --sdcard 32M --skin HVGA-P 357 $ SDK/tools/emulator @server & 358 $ SDK/tools/emulator @client & 359 360 361 362 ------------- 363 6- Conclusion 364 ------------- 365 366 This completes the howto guide on how to use the new Cupcake SDK. 367 Feedback is welcome on the public Android Open Source forums: 368 http://source.android.com/community 369 370 -end- 371 372