docs/howto_use_cupcake_sdk.txt

   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