docs/howto_use_cupcake_sdk.txt - platform/development - Git at Google

 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/discuss

 -end-
	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/discuss

	-end-