diff options
Diffstat (limited to 'docs')
| -rwxr-xr-x | docs/Notes_on_WST_StructuredDocument.txt | 183 | ||||
| -rw-r--r-- | docs/howto_SDK_git_cygwin.txt | 189 | ||||
| -rw-r--r-- | docs/howto_build_SDK.txt | 235 | ||||
| -rw-r--r-- | docs/howto_use_cupcake_sdk.txt | 371 |
4 files changed, 0 insertions, 978 deletions
diff --git a/docs/Notes_on_WST_StructuredDocument.txt b/docs/Notes_on_WST_StructuredDocument.txt deleted file mode 100755 index dcf124d56..000000000 --- a/docs/Notes_on_WST_StructuredDocument.txt +++ /dev/null @@ -1,183 +0,0 @@ -Notes on WST StructuredDocument -------------------------------- - -Created: 2010/11/26 -References: WST 3.1.x, Eclipse 3.5 Galileo - -To manipulate XML documents in refactorings, we sometimes use the WST/SEE -"StructuredDocument" API. There isn't exactly a lot of documentation on -this out there, so this is a short explanation of how it works, totally -based on _empirical_ evidence. As such, it must be taken with a grain of salt. - -Examples of usage can be found in - sdk/eclipse/plugins/com.android.ide.eclipse.adt/src/com/android/ide/eclipse/adt/internal/refactorings/ - - -1- Get a document instance --------------------------- - -To get a document from an existing IFile resource: - - IModelManager modelMan = StructuredModelManager.getModelManager(); - IStructuredDocument sdoc = modelMan.createStructuredDocumentFor(file); - -Note that the IStructuredDocument and all the associated interfaces we'll use -below are all located in org.eclipse.wst.sse.core.internal.provisional, -meaning they _might_ change later. - -Also note that this parses the content of the file on disk, not of a buffer -with pending unsaved modifications opened in an editor. - -There is a counterpart for non-existent resources: - - IModelManager.createNewStructuredDocumentFor(IFile) - -However our goal so far has been to _parse_ existing documents, find -the place that we wanted to modify and then generate a TextFileChange -for a refactoring operation. Consequently this document doesn't say -anything about using this model to modify content directly. - - -2- Structured Document overview -------------------------------- - -The IStructuredDocument is organized in "regions", which are little pieces -of text. - -The document contains a list of region collections, each one being -a list of regions. Each region has a type, as well as text. - -Since we use this to parse XML, let's look at this XML example: - -<?xml version="1.0" encoding="utf-8"?> \n -<resource> \n - <color/> - <string name="my_string">Some Value</string> <!-- comment -->\n -</resource> - - -This will result in the following regions and sub-regions: -(all the constants below are located in DOMRegionContext) - -XML_PI_OPEN - XML_PI_OPEN:<? - XML_TAG_NAME:xml - XML_TAG_ATTRIBUTE_NAME:version - XML_TAG_ATTRIBUTE_EQUALS:= - XML_TAG_ATTRIBUTE_VALUE:"1.0" - XML_TAG_ATTRIBUTE_NAME:encoding - XML_TAG_ATTRIBUTE_EQUALS:= - XML_TAG_ATTRIBUTE_VALUE:"utf-8" - XML_PI_CLOSE:?> - -XML_CONTENT - XML_CONTENT:\n - -XML_TAG_NAME - XML_TAG_OPEN:< - XML_TAG_NAME:resources - XML_TAG_CLOSE:> - -XML_CONTENT - XML_CONTENT:\n + whitespace before color - -XML_TAG_NAME - XML_TAG_OPEN:< - XML_TAG_NAME:color - XML_EMPTY_TAG_CLOSE:/> - -XML_CONTENT - XML_CONTENT:\n + whitespace before string - -XML_TAG_NAME - XML_TAG_OPEN:< - XML_TAG_NAME:string - XML_TAG_ATTRIBUTE_NAME:name - XML_TAG_ATTRIBUTE_EQUALS:= - XML_TAG_ATTRIBUTE_VALUE:"my_string" - XML_TAG_CLOSE:> - -XML_CONTENT - XML_CONTENT:Some Value - -XML_TAG_NAME - XML_END_TAG_OPEN:</ - XML_TAG_NAME:string - XML_TAG_CLOSE:> - -XML_CONTENT - XML_CONTENT: (2 spaces before the comment) - -XML_COMMENT_TEXT - XML_COMMENT_OPEN:<!-- - XML_COMMENT_TEXT: comment - XML_COMMENT_CLOSE:-- - -XML_CONTENT - XML_CONTENT: \n after comment - -XML_TAG_NAME - XML_END_TAG_OPEN:</ - XML_TAG_NAME:resources - XML_TAG_CLOSE:> - -XML_CONTENT - XML_CONTENT: - - -3- Iterating through regions ----------------------------- - -To iterate through all regions, we need to process the list of top-level regions and then -iterate over inner regions: - - for (IStructuredDocumentRegion regions : sdoc.getStructuredDocumentRegions()) { - // process inner regions - for (int i = 0; i < regions.getNumberOfRegions(); i++) { - ITextRegion region = regions.getRegions().get(i); - String type = region.getType(); - String text = regions.getText(region); - } - } - -Each "region collection" basically matches one XML tag, with sub-regions for all the tokens -inside a tag. - -Note that an XML_CONTENT region is actually the whitespace, was is known as a TEXT in the w3c DOM. - -Also note that each outer region has a type, but the inner regions also reuse a similar type. -So for example an outer XML_TAG_NAME region collection is a proper XML tag, and it will contain -an opening tag, a closing tag but also an XML_TAG_NAME that is the tag name itself. - -Surprisingly, the inner regions do not have many access methods we can use on them, except their -type and start/length/end. There are two length and end methods: -- getLength() and getEnd() take any whitespace into account. -- getTextLength() and getTextEnd() exclude some typical trailing whitespace. - -Note that regarding the trailing whitespace, empirical evidence shows that in the XML case -here, the only case where it matters is in a tag such as <string name="my_string">: for the -XML_TAG_NAME region, getLength is 7 (string + space) and getTextLength is 6 (string, no space). -Spacing between XML element is its own collapsed region. - -If you want the text of the inner region, you actually need to query it from the outer region. -The outer IStructuredDocumentRegion (the region collection) contains lots more useful access -methods, some of which return details on the inner regions: -- getText : without the whitespace. -- getFullText : with the whitespace. -- getStart / getLength / getEnd : type-dependent offset, including whitespace. -- getStart / getTextLength / getTextEnd : type-dependent offset, excluding "irrelevant" whitespace. -- getStartOffset / getEndOffset / getTextEndOffset : relative to document. - -Empirical evidence shows that there is no discernible difference between the getStart/getEnd -values and those returned by getStartOffset/getEndOffset. Please abide by the javadoc. - -All offsets start at zero. - -Given a region collection, you can also browse regions either using a getRegions() list, or -using getFirst/getLastRegion, or using getRegionAtCharacterOffset(). Iterating the region -list seems the most useful scenario. There's no actual iterator provided for inner regions. - -There are a few other methods available in the regions classes. This was not an exhaustive list. - - ----- diff --git a/docs/howto_SDK_git_cygwin.txt b/docs/howto_SDK_git_cygwin.txt deleted file mode 100644 index 622c5928b..000000000 --- a/docs/howto_SDK_git_cygwin.txt +++ /dev/null @@ -1,189 +0,0 @@ -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. - - -Subject: How to get the android source code using Cygwin and Git -Date: 2009/04/27 -Updated: 2009/05/21 -Updated: 2010/03/30 - - -Table of content: - 1- Goals and Requirements - 2- Getting the code, the simple way - 3- SSH issues - 4- Advanced Tricks - - -------------------------- -1- Goals and Requirements -------------------------- - -This document explains how to checkout the Android source from the git -repositories under Windows. - -As stated in development/docs/howto_build_SDK.txt, one can't build the whole -Android source code under Windows. You can only build the SDK tools for -Windows. - -There are a number of caveats in checking out the code from Git under Windows. -This document tries to explain them. - -First you will need to meet the following requirements: -- You must have Cygwin installed. But wait! You CANNOT use the latest Cygwin 1.7. - Instead you MUST use the "legacy Cygwin 1.5" that you can find at this page: - - http://cygwin.org/win-9x.html - - Don't mind the page title, just grab setup-legacy.exe and it will works just fine - under XP or Vista. - -- You must install Cyginw using the "Unix / Binary" mode. - If you don't do that, git will fail to properly compute some SHA1 keys. - -- You need the "git" and "curl" packages to checkout the code. - If you plan to contribute, you might want to get "gitk" also. - - Note: if you want to build the SDK, check the howto_build_SDK.txt file - for a list of extra required packages. - The short summary is that you need at least these: - autoconf, bison, curl, flex, gcc, g++, git, gnupg, make, mingw-zlib, python, unzip, zip - and you must avoid the "readline" package. - - ------------------------------------ -2- Getting the code, the simple way ------------------------------------ - -Out of the box, "repo" and "git" will work just fine under Cygwin: - - $ repo init -u git://android.git.kernel.org/platform/manifest.git - $ repo sync - -And you're done. You can build as explained in howto_build_SDK.txt and ignore -the rest of this document. - - -------------- -3- SSH issues -------------- - -If you maintain your own private repository using an SSH server, you might get -some "mux/ssh" errors. In this case try this: - - $ repo init -u ssh://my.private.ssh.repo/platform/manifest.git - $ export GIT_SSH=ssh - $ repo sync - - ------------------- -4- Advanced Tricks ------------------- - -There is one remaining issue with the default repo/git options: - -If you plan on contributing, you will notice that even after a fresh "repo -sync" some projects are marked as having modified files. This happens on the -"bionic" and the "external/iptables" project. The issue is that they have files -which have the same name yet differ only by their case-sensitivity. Since the -Windows filesystem is not case-sensitive, this confuses Git. - -Solution: we can simply ignore these projects as they are not needed to build -the Windows SDK. - -To do this you just need to create a file .repo/local_manifest.xml that -provides a list of projects to ignore: - -<?xml version="1.0" encoding="UTF-8"?> -<manifest> - <remove-project name="platform/external/iptables" /> -</manifest> - -The other thing we can do is tell git not to track the files that cause -problems: - - cd bionic - git update-index --assume-unchanged \ - libc/kernel/common/linux/netfilter/xt_CONNMARK.h \ - libc/kernel/common/linux/netfilter/xt_MARK.h \ - libc/kernel/common/linux/netfilter_ipv6/ip6t_HL.h - - cd external/tcpdump; - git update-index --assume-unchanged \ - tests/print-X.new \ - tests/print-XX.new - - -Here's a script that takes care of all these details. It performs the repo -init, creates the appropriate local_manifest.xml, does a repo sync as -needed and tell git to ignore the offending files: - ------------- -#!/bin/bash - -set -e # fail on errors - -URL=ssh://android-git.corp.google.com:29418/platform/manifest.git -BRANCH=donut -if [ "$1" == "-b" ]; then shift; BRANCH=$1; shift; fi - -# repo init if there's no .repo directory -if [[ ! -d .repo ]]; then - repo init -u $URL -b $BRANCH -fi - -# create a local_manifest to exclude projects that cause problems under Windows -# due to the case-insenstivines of the file system. -L=.repo/local_manifest.xml -if [[ ! -f $L ]]; then - - cat > $L <<EOF -<?xml version="1.0" encoding="UTF-8"?> -<manifest> -<remove-project name="platform/external/iptables" /> -</manifest> -EOF -fi - -# sync using the native ssh client if necessary -[[ $URL != ${URL/ssh/} ]] && export GIT_SSH=ssh -repo sync $@ - - -# These files cause trouble too, we need to ignore them -(cd bionic; -git update-index --assume-unchanged \ - libc/kernel/common/linux/netfilter/xt_CONNMARK.h \ - libc/kernel/common/linux/netfilter/xt_MARK.h \ - libc/kernel/common/linux/netfilter_ipv6/ip6t_HL.h -) -(cd external/tcpdump; -git update-index --assume-unchanged \ - tests/print-X.new \ - tests/print-XX.new -) ------------- - -Simply extract this to a "my_sync.sh" file and try the following: - $ mkdir android_src - $ cd android_src - $ chmod +x mysync.sh - $ ./mysync.sh - - --end- - - - - diff --git a/docs/howto_build_SDK.txt b/docs/howto_build_SDK.txt deleted file mode 100644 index e8228ba33..000000000 --- a/docs/howto_build_SDK.txt +++ /dev/null @@ -1,235 +0,0 @@ -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. - - -Subject: How to build an Android SDK & ADT Eclipse plugin. -Date: 2009/03/27 -Updated: 2015/09/09 - - -Table of content: - 0- License - 1- Foreword - 2- Building an SDK for MacOS and Linux - 3- Building an SDK for Windows - 4- Building an ADT plugin for Eclipse - 5- 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 document explains how to build the Android SDK and the ADT Eclipse plugin. - -It is designed for advanced users which are proficient with command-line -operations and know how to setup the pre-required software. - -Basically it's not trivial yet when done right it's not that complicated. - - - --------------------------------------- -2- Building an SDK for MacOS and Linux --------------------------------------- - -First, setup your development environment and get the Android source code from -git as explained here: - - http://source.android.com/source/download.html - -For example for the cupcake branch: - - $ mkdir ~/my-android-git - $ cd ~/my-android-git - $ repo init -u https://android.googlesource.com/platform/manifest -b master -g all,-notdefault,tools - $ repo sync - -Then once you have all the source, simply build the SDK using: - - $ cd ~/my-android-git - $ . build/envsetup.sh - $ lunch sdk-eng - $ make sdk - -This will take a while, maybe between 20 minutes and several hours depending on -your machine. After a while you'll see this in the output: - - Package SDK: out/host/darwin-x86/sdk/android-sdk_eng.<build-id>_mac-x86.zip - -Some options: - -- Depending on your machine you can tell 'make' to build more things in - parallel, e.g. if you have a dual core, use "make -j4 sdk" to build faster. - -- You can define "BUILD_NUMBER" to control the build identifier that gets - incorporated in the resulting archive. The default is to use your username. - One suggestion is to include the date, e.g.: - - $ export BUILD_NUMBER=${USER}-`date +%Y%m%d-%H%M%S` - - There are certain characters you should avoid in the build number, typically - everything that might confuse 'make' or your shell. So for example avoid - punctuation and characters like $ & : / \ < > , and . - - - ------------------------------- -3- Building an SDK for Windows ------------------------------- - -Full Windows SDK builds are now only supported on Linux -- most of the -framework is not designed to be built on Windows so technically the Windows -SDK is build on top of a Linux SDK where a few binaries are replaced. So it -cannot be built on Windows, and it cannot be built on Mac, only on Linux. - -I'll repeat this again because it's important: - - To build the Android SDK for Windows, you need to use a *Linux* box. - - -A- Pre-requisites ------------------ - -Before you can even think of building the Android SDK for Windows, you need to -perform the steps from section "2- Building an SDK for MacOS and Linux" above: -setup and build a regular Linux SDK. Once this working, please continue here. - -Under Ubuntu, you will need the following extra packages: - -$ sudo apt-get install tofrodos - -tofrodos adds a unix2dos command - - -B- Building ------------ - -To build, perform the following steps: - -$ . build/envsetup.sh -$ lunch sdk-eng -$ make win_sdk - -Note that this will build both a Linux SDK then a Windows SDK. -The result is located at - out/host/windows/sdk/android-sdk_eng.${USER}_windows/ - - -C- Building just the tools --------------------------------------- - -You can also build isolated windows tools directly on Linux without building -the full SDK. - -To build, perform the following steps: - - $ cd ~/my-android-git - $ . build/envsetup.sh - $ lunch sdk-eng - $ make winsdk-tools - -A specific tool can be built using: - - $ make host_cross_adb - -Then the binaries are located at - out/host/windows-x86/bin/adb.exe - - -------------------------------------- -4- Building an ADT plugin for Eclipse -------------------------------------- - -We've simplified the steps here. -It used to be that you'd have to download a specific version of -Eclipse and install it at a special location. That's not needed -anymore. - -Instead you just change directories to your git repository and invoke the -build script by giving it a destination directory and an optional build number: - - $ mkdir ~/mysdk - $ cd ~/my-android-git # <-- this is where you did your "repo sync" - $ sdk/eclipse/scripts/build_server.sh ~/mysdk $USER - - -The first argument is the destination directory. It must be absolute. Do not -give a relative destination directory such as "../mysdk" -- this would make the -Eclipse build fail with a cryptic message: - - BUILD SUCCESSFUL - Total time: 1 minute 5 seconds - **** Package in ../mysdk - Error: Build failed to produce ../mysdk/android-eclipse - Aborting - -The second argument is the build "number". The example used "$USER" but it -really is a free identifier of your choice. It cannot contain spaces nor -periods (dashes are ok.) If the build number is missing, a build timestamp will -be used instead in the filename. - -The build should take something like 5-10 minutes. - - -When the build succeeds, you'll see something like this at the end of the -output: - - ZIP of Update site available at ~/mysdk/android-eclipse-v200903272328.zip -or - ZIP of Update site available at ~/mysdk/android-eclipse-<buildnumber>.zip - -When you load the plugin in Eclipse, its feature and plugin name will look like -"com.android.ide.eclipse.adt_0.9.0.v200903272328-<buildnumber>.jar". The -internal plugin ID is always composed of the package, the build timestamp and -then your own build identifier (a.k.a. the "build number"), if provided. This -means successive builds with the same build identifier are incremental and -Eclipse will know how to update to more recent ones. - - - -------------- -5- Conclusion -------------- - -This completes the howto guide on building your own SDK and ADT plugin. -Feedback is welcome on the public Android Open Source forums: - http://source.android.com/discuss - -If you are upgrading from a pre-cupcake to a cupcake or later SDK please read -the accompanying document "howto_use_cupcake_sdk.txt". - --end- - diff --git a/docs/howto_use_cupcake_sdk.txt b/docs/howto_use_cupcake_sdk.txt deleted file mode 100644 index 81073578d..000000000 --- a/docs/howto_use_cupcake_sdk.txt +++ /dev/null @@ -1,371 +0,0 @@ -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- - |