1Subject: How to build use a Cupcake Android SDK & ADT Eclipse plugin. 2Date: 2009/03/27 3 4 5Table 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---------- 170- 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----------- 371- Foreword 38----------- 39 40This explains how to use the "new" SDK provided starting with cupcake. 41The new SDK has as a different structure than the pre-cupcake ones. 42 43This 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---------------------- 502- Installation steps 51---------------------- 52 53First you will need to grab the zip of the SDK for your platform or build it 54yourself. Please refer to the accompanying document "howto_build_SDK.txt" if 55needed. 56 57Unzip the SDK somewhere. We'll call that directory "SDK" in command-line 58examples. 59 60Grab the new ADT Eclipse plugin zip file or build it yourself. Keep it 61somewhere (no need to unzip). 62 63 64 65-------------------- 663- For Eclipse users 67-------------------- 68 69 70Below we'll explain how you can upgrade your Eclipse install to the new plugin. 71If you already have a working Eclipse installation with a pre-0.9 ADT, 72another suggestion is to simply install a new copy of Eclipse and create a 73new empty workspace. This is just a precaution. The update process should 74be otherwise harmless. 75 76 77 78A- 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 104B- Updating older projects 105-------------------------- 106 107If you have pre-0.9 projects in your Eclipse workspace, or if you import them 108from your code repository, these projects will fail to build at first. 109 110First 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 117The new plugin creates a "gen" folder in your project where it puts the R.java 118and all automatically generated AIDL java files. If you get an error such as: 119 120 "The type R is already defined" 121 122that means you must check to see if your old R.java or your old auto-generated 123AIDL Java files are still present in the "src" folder. If yes, remove them. 124 125Note: this does not apply to your own hand-crafted parcelable AIDL java files. 126 127Note: 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 131C- New Wizards 132-------------- 133 134The "New Android Project" wizard has been expanded to use the multi-platform 135capabilities of the new SDK. 136 137There is now a "New XML File" wizard that lets you create skeleton XML resource 138files for your Android projects. This makes it easier to create a new layout, a 139new strings file, etc. 140 141Both wizard are available via File > New... as well as new icons in the main 142icon bar. If you do not see the new icons, you may need to use Window > Reset 143Perspective on your Java perspective. 144 145 146Please see step 5 "Emulator changes" below for important details on how to run 147the emulator. 148 149 150 151---------------- 1524- For Ant users 153---------------- 154 155 156A- build.xml has changed 157------------------------ 158 159You must re-create your build.xml file. 160 161First 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 167Then use the new "android" tool to create a new build.xml: 168 169 $ SDK/tools/android update project --path /path/to/my-project 170 171or 172 173 $ cd my-project 174 $ SDK/tools/android update project --path . 175 176 177A "gen" folder will be created the first time you build and your R.java and 178your AIDL Java files will be generated in this "gen" folder. You MUST remove 179the old R.java and old auto-generated AIDL java files manually. (Note: this 180does not apply to your own hand-crafted parcelabe AIDL java files.) 181 182 183B- Where is activitycreator? 184---------------------------- 185 186Note that the "activitycreator" tool has been replaced by the new "android" 187tool 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 194Please see paragraph 5 below for important details on how to run the emulator 195and the meaning of that "--target 1" parameter. 196 197 198 199---------------------------------- 2005- Targets, AVDs, Emulator changes 201---------------------------------- 202 203This applies to BOTH Eclipse and Ant users. 204 205One major change with the emulator is that now you must pre-create an "Android 206Virtual Device" (a.k.a "AVD") before you run the emulator. 207 208 209 210A- What is an AVD and why do I need one? 211---------------------------------------- 212 213What 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 221There is a lot more explanation given by the emulator. Please run the help 222command given above to read the rest. 223 224The bottom line is that you can create many emulator configurations, or "AVDs", 225each with their own system image and most important each with their own user 226data and SD card data. Then you tell Eclipse or the emulator which one to use 227to debug or run your applications. 228 229 230Note for Eclipse users: eventually there will be a user interface to do all of 231these operations. For right now, please use the command line interface. 232 233 234B- Listing targets and AVDs 235--------------------------- 236 237There is a new tool called "android" in the SDK that lets you know which 238"target" and AVDs you can use. 239 240A target is a specific version of Android that you can use. By default the SDK 241comes with an "Android 1.5" target, codenamed "cupcake". In the future there 242will be more versions of Android to use, e.g. "Android 2.0" or specific add-ons 243provided by hardware manufacturers. When you want to run an emulator, you need 244to specify a given flavor of Android: this is the "target". 245 246 247To learn about available targets in your SDK, use this command: 248 249 $ SDK/tools/android list targets 250 251This 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 258Note the "[1]". Later you will need to reference this as "--target 1" on the 259command line. 260 261 262Similarly you can list the available AVDs: 263 264 $ SDK/tools/android list avds 265 266Which 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 277C- Creating an AVD 278------------------ 279 280To create a configuration: 281 282 $ SDK/tools/android create avd --name my_avd_name --target 1 283 284 285where "target 1" is the index of a target listed by "android list targets". 286 287The AVD name is purely an identifier used to refer to the AVD later. 288Since it is used as directory name, please avoid using shell or path specific 289characters. 290 291To learn the various options available when creating an AVD, simply type: 292 293 $ SDK/tools/android create avd 294 295The android tool will automatically print an explanation of required arguments. 296 297 298 299D- Invoking an AVD from the command-line 300---------------------------------------- 301 302To use this AVD in the emulator from the command-line, type: 303 304 $ SDK/tools/emulator @my_avd_name 305 306 307For more options, please consult the emulator help: 308 309 $ SDK/tools/emulator -help-virtual-device 310 311 312 313E- Invoking an AVD from Eclipse 314------------------------------- 315 316By default Android projects in Eclipse have an "automatic target" mode. 317In 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 325Alternatively you can edit the "launch configuration" on your Android project 326in Eclipse by selecting the menu Run > Run Configurations. In the "target" tab 327of 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 338F- AVD concurrency 339------------------ 340 341You can no longer run several emulators at the same time on the same 342configuration. 343 344Before this used to put the second or more emulators in a transient read-only 345mode that would not save user data. 346 347Now you just need to create as many AVDs as you want to run emulators. 348 349For example if you are working on a client/server application for Android, you 350could create a "client" AVD and a "server" AVD then run them both at once. The 351emulator window will show you the AVD name so that you know which one is which. 352 353Example: 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------------- 3636- Conclusion 364------------- 365 366This completes the howto guide on how to use the new Cupcake SDK. 367Feedback is welcome on the public Android Open Source forums: 368 http://source.android.com/community 369 370-end- 371 372