diff options
Diffstat (limited to 'docs/howto_use_cupcake_sdk.txt')
| -rw-r--r-- | docs/howto_use_cupcake_sdk.txt | 371 |
1 files changed, 371 insertions, 0 deletions
diff --git a/docs/howto_use_cupcake_sdk.txt b/docs/howto_use_cupcake_sdk.txt new file mode 100644 index 000000000..81073578d --- /dev/null +++ b/docs/howto_use_cupcake_sdk.txt @@ -0,0 +1,371 @@ +Subject: How to build use a Cupcake Android SDK & ADT Eclipse plugin. +Date: 2009/03/27 + + +Table of content: + 0- License + 1- Foreword + 2- Installation steps + 3- For Eclipse users + 4- For Ant users + 5- Targets, AVDs, Emulator changes + 6- Conclusion + + + +---------- +0- License +---------- + + Copyright (C) 2009 The Android Open Source Project + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + + +----------- +1- Foreword +----------- + +This explains how to use the "new" SDK provided starting with cupcake. +The new SDK has as a different structure than the pre-cupcake ones. + +This means: +- The new SDK does not work with older Eclipse plugins (ADT 0.8) +- The old SDKs (1.0 and 1.1) do NOT work with this Eclipse plugin (ADT 0.9) + + + +---------------------- +2- Installation steps +---------------------- + +First you will need to grab the zip of the SDK for your platform or build it +yourself. Please refer to the accompanying document "howto_build_SDK.txt" if +needed. + +Unzip the SDK somewhere. We'll call that directory "SDK" in command-line +examples. + +Grab the new ADT Eclipse plugin zip file or build it yourself. Keep it +somewhere (no need to unzip). + + + +-------------------- +3- For Eclipse users +-------------------- + + +Below we'll explain how you can upgrade your Eclipse install to the new plugin. +If you already have a working Eclipse installation with a pre-0.9 ADT, +another suggestion is to simply install a new copy of Eclipse and create a +new empty workspace. This is just a precaution. The update process should +be otherwise harmless. + + + +A- Setting up Eclipse +--------------------- + +- You must have Eclipse 3.3 or 3.4. Eclipse 3.2 is not longer supported. + + There are many flavors, or "editions", of Eclipse. To develop, we'd recommend + the "Java" edition. The "RCP" one is totally suitable too. The J2EE one is + probably overkill. + + +- If updating an existing Eclipse, use Help > Software Update and please + uninstall the two features of the previous ADT: the "editors" feature and the + ADT feature itself. + + => If you don't you will get a conflict on editors when installing + the new one. + +- Using Help > Software Update, add a new "archived site", point it to the new + adt.zip (e.g. android-eclipse-<some-id>.zip), select the "Install" button at + the top right and restart eclipse as needed. + +- After it restarts, please use Window > Preferences > Android and select + the new SDK folder that you unzipped in paragraph 2. + + + +B- Updating older projects +-------------------------- + +If you have pre-0.9 projects in your Eclipse workspace, or if you import them +from your code repository, these projects will fail to build at first. + +First right-click on the project and select "Properties": + +- In the properties, open the Android panel and select the platform to use. + The SDK comes with a 1.5 platform. Select it and close the properties panel. +- Do a clean build. + + +The new plugin creates a "gen" folder in your project where it puts the R.java +and all automatically generated AIDL java files. If you get an error such as: + + "The type R is already defined" + +that means you must check to see if your old R.java or your old auto-generated +AIDL Java files are still present in the "src" folder. If yes, remove them. + +Note: this does not apply to your own hand-crafted parcelable AIDL java files. + +Note: if you want to reuse the project with an older Eclipse ADT install, + simply remove the "gen" folder from the build path of the project. + + +C- New Wizards +-------------- + +The "New Android Project" wizard has been expanded to use the multi-platform +capabilities of the new SDK. + +There is now a "New XML File" wizard that lets you create skeleton XML resource +files for your Android projects. This makes it easier to create a new layout, a +new strings file, etc. + +Both wizard are available via File > New... as well as new icons in the main +icon bar. If you do not see the new icons, you may need to use Window > Reset +Perspective on your Java perspective. + + +Please see step 5 "Emulator changes" below for important details on how to run +the emulator. + + + +---------------- +4- For Ant users +---------------- + + +A- build.xml has changed +------------------------ + +You must re-create your build.xml file. + +First if you had customized your build.xml, make a copy of it: + + $ cd my-project + $ cp build.xml build.xml.old + + +Then use the new "android" tool to create a new build.xml: + + $ SDK/tools/android update project --path /path/to/my-project + +or + + $ cd my-project + $ SDK/tools/android update project --path . + + +A "gen" folder will be created the first time you build and your R.java and +your AIDL Java files will be generated in this "gen" folder. You MUST remove +the old R.java and old auto-generated AIDL java files manually. (Note: this +does not apply to your own hand-crafted parcelabe AIDL java files.) + + +B- Where is activitycreator? +---------------------------- + +Note that the "activitycreator" tool has been replaced by the new "android" +tool too. Example of how to create a new Ant project: + + $ SDK/tools/android create project --path /path/to/my/project --name ProjectName + --package com.mycompany.myapp --activity MyActivityClass + --target 1 --mode activity + + +Please see paragraph 5 below for important details on how to run the emulator +and the meaning of that "--target 1" parameter. + + + +---------------------------------- +5- Targets, AVDs, Emulator changes +---------------------------------- + +This applies to BOTH Eclipse and Ant users. + +One major change with the emulator is that now you must pre-create an "Android +Virtual Device" (a.k.a "AVD") before you run the emulator. + + + +A- What is an AVD and why do I need one? +---------------------------------------- + +What is an "AVD"? If you forget, just run: + + $ SDK/tools/emulator -help-virtual-device + + An Android Virtual Device (AVD) models a single virtual device running the + Android platform that has, at least, its own kernel, system image and data + partition. + +There is a lot more explanation given by the emulator. Please run the help +command given above to read the rest. + +The bottom line is that you can create many emulator configurations, or "AVDs", +each with their own system image and most important each with their own user +data and SD card data. Then you tell Eclipse or the emulator which one to use +to debug or run your applications. + + +Note for Eclipse users: eventually there will be a user interface to do all of +these operations. For right now, please use the command line interface. + + +B- Listing targets and AVDs +--------------------------- + +There is a new tool called "android" in the SDK that lets you know which +"target" and AVDs you can use. + +A target is a specific version of Android that you can use. By default the SDK +comes with an "Android 1.5" target, codenamed "cupcake". In the future there +will be more versions of Android to use, e.g. "Android 2.0" or specific add-ons +provided by hardware manufacturers. When you want to run an emulator, you need +to specify a given flavor of Android: this is the "target". + + +To learn about available targets in your SDK, use this command: + + $ SDK/tools/android list targets + +This will give you an output such as: + + Available Android targets: + [1] Android 1.5 + API level: 3 + Skins: HVGA (default), HVGA-L, HVGA-P, QVGA-L, QVGA-P + +Note the "[1]". Later you will need to reference this as "--target 1" on the +command line. + + +Similarly you can list the available AVDs: + + $ SDK/tools/android list avds + +Which might output something as: + + Available Android Virtual Devices: + Name: my_avd + Path: C:\Users\<username>\.android\avd\my_avd.avd + Target: Android 1.5 (API level 3) + Skin: 320x480 + Sdcard: 16M + + + +C- Creating an AVD +------------------ + +To create a configuration: + + $ SDK/tools/android create avd --name my_avd_name --target 1 + + +where "target 1" is the index of a target listed by "android list targets". + +The AVD name is purely an identifier used to refer to the AVD later. +Since it is used as directory name, please avoid using shell or path specific +characters. + +To learn the various options available when creating an AVD, simply type: + + $ SDK/tools/android create avd + +The android tool will automatically print an explanation of required arguments. + + + +D- Invoking an AVD from the command-line +---------------------------------------- + +To use this AVD in the emulator from the command-line, type: + + $ SDK/tools/emulator @my_avd_name + + +For more options, please consult the emulator help: + + $ SDK/tools/emulator -help-virtual-device + + + +E- Invoking an AVD from Eclipse +------------------------------- + +By default Android projects in Eclipse have an "automatic target" mode. +In this mode, when a project is deployed in debug or run, it checks: +- If there's one running device or emulator, this is used for deployment. +- If there's more than one running device or emulator, a "device chooser" is + shown to let the user select which one to use. +- If there are no running devices or emulators, ADT looks at available AVDs. + If one matches the project configuration (e.g. same API level), it is + automatically used. + +Alternatively you can edit the "launch configuration" on your Android project +in Eclipse by selecting the menu Run > Run Configurations. In the "target" tab +of the configuration, you can choose: + +- Manual or automatic targetting mode. + + - Manual means to always present the device chooser. + - Automatic is the behavior explained above. + +- In automatic mode, which AVD is preferred. If none is selected, the first + suitable is used. + + +F- AVD concurrency +------------------ + +You can no longer run several emulators at the same time on the same +configuration. + +Before this used to put the second or more emulators in a transient read-only +mode that would not save user data. + +Now you just need to create as many AVDs as you want to run emulators. + +For example if you are working on a client/server application for Android, you +could create a "client" AVD and a "server" AVD then run them both at once. The +emulator window will show you the AVD name so that you know which one is which. + +Example: + + $ SDK/tools/android create avd --name client --target 1 --sdcard 16M --skin HVGA + $ SDK/tools/android create avd --name server --target 1 --sdcard 32M --skin HVGA-P + $ SDK/tools/emulator @server & + $ SDK/tools/emulator @client & + + + +------------- +6- Conclusion +------------- + +This completes the howto guide on how to use the new Cupcake SDK. +Feedback is welcome on the public Android Open Source forums: + http://source.android.com/community + +-end- + |