blob: b13123043db65aa28d06a217029091c4b027970f [file] [log] [blame]
Raphael Moll11fcb512009-03-31 14:16:11 -07001Subject: 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/discuss
369
370-end-
371