Commit: b3fb2a6ef1df3534dee5b1d09ab72d129d3697c7 - development (git)

development

Commit MetaInfo

• Révision: b3fb2a6ef1df3534dee5b1d09ab72d129d3697c7 (tree)
• l'heure: 2009-03-31 11:31:28
• Auteur: Ralf <ralf@andr...>
• Commiter: Ralf

Message de Log

ADT #1742875: Document the SDK build process and new cupcake SDK changes.

Change Summary

• add: docs/howto_build_SDK.txt
• add: docs/howto_use_cupcake_sdk.txt

Modification

--- /dev/null
+++ b/docs/howto_build_SDK.txt
@@ -0,0 +1,280 @@
+Subject: How to build an Android SDK & ADT Eclipse plugin.
+Date:    2009/03/27
+
+
+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/download
+
+For example for the cupcake branch:
+
+  $ mkdir ~/my-android-git
+  $ cd ~/my-android-git
+  $ repo init -u git://android.git.kernel.org/platform/manifest.git -b cupcake
+  $ repo sync
+
+Then once you have all the source, simply build the SDK using:
+
+  $ cd ~/my-android-git
+  $ . build/envsetup.sh
+  $ 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
+------------------------------
+
+A- SDK pre-requisite
+--------------------
+
+First you need to build an SDK for MacOS and Linux. The Windows build works by
+updating an existing MacOS or Linux SDK zip file and replacing the unix
+binaries by Windows binaries.
+
+
+
+B- Cygwin pre-requisite & code checkout
+---------------------------------------
+
+Second you need to install Cygwin and configure it:
+- Get the installer at http://sources.redhat.com/cygwin/
+- When installing Cygwin, set Default Text File Type to Unix/binary, not DOS/text.
+  This is really important, otherwise you will get errors when trying to
+  checkout code using git.
+- Packages that you must install or not:
+  - Required packages: autoconf, bison, curl, flex, gcc, g++, git, gnupg, make,
+                       mingw-zlib, python, zip, unzip.
+  - Suggested extra packages: diffutils, emacs, openssh, rsync, vim, wget.
+  - Packages that must not be installed: readline.
+
+Once you installed Cygwin properly, checkout the code from git as you did
+for MacOS or Linux. Make sure to get the same branch, and if possible keep
+it as close to the other one as possible:
+
+  $ mkdir ~/my-android-git
+  $ cd ~/my-android-git
+  $ repo init -u git://android.git.kernel.org/platform/manifest.git -b cupcake
+  $ repo sync
+
+
+
+C- Building the Windows SDK
+---------------------------
+
+Now it's time to build that Windows SDK. You need:
+- The path to the MacOS or Linux SDK zip.
+- A directory where to place the final SDK. It will also hold some temporary
+  files.
+- The build number will be extracted from the SDK zip filename, but this will
+  only work if that build number has no underscores in it. It is suggested you
+  just define SDK_NUMBER (and not BUILD_NUMBER!) on the command line before
+  invoking the script.
+
+  Note that the "SDK number" is really a free identifier of your choice. It
+  doesn't need to be strictly a number. As always it is suggested you avoid
+  too much punctuation and special shell/make characters. Underscores cannot
+  be used.
+
+
+To summarize, the steps on the command line would be something like this:
+
+  $ mkdir ~/mysdk
+  $ export SDK_NUMBER=${USER}-`date +%Y%m%d-%H%M%S`
+  $ cd ~/my-android-git
+  $ development/build/tools/make_windows_sdk.sh /path/to/macos/or/linux/sdk.zip ~/mysdk
+
+This will take a while to build some Windows-specific binaries, including the
+emulator, unzip the previous zip, rename & replace things and rezip the final
+Windows SDK zip file. A typical build time should be around 5-10 minutes.
+
+
+
+-------------------------------------
+4- Building an ADT plugin for Eclipse
+-------------------------------------
+
+Requirements:
+- You can currently only build an ADT plugin for Eclipse under Linux.
+- You must have a working version of Eclipse 3.4 "ganymede" RCP installed.
+- You need X11 to run Eclipse at least once.
+- You need a lot of patience. The trick is to do the initial setup correctly
+  once, after it's a piece of cake.
+
+
+
+A- Pre-requisites
+-----------------
+
+Note for Ubuntu or Debian users: your apt repository probably only has Eclipse
+3.2 available and it's probably not suitable to build plugins in the first
+place. Forget that and install a working 3.4 manually as described below.
+
+- Visit http://www.eclipse.org/downloads/ to grab the
+  "Eclipse for RCP/Plug-in Developers (176 MB)" download for Linux.
+  32-bit and 64-bit versions are available, depending on your Linux installation.
+
+  Note: we've always used a 32-bit one, so use the 64-bit one at your own risk.
+
+  Note: Eclipse comes in various editions. Do yourself a favor and just stick
+  to the RCP for building this plugin. For example the J2EE contains too many
+  useless features that will get in the way, and the "Java" version lacks some
+  plugins you need to build other plugins. Please just use the RCP one.
+
+- Unpack "eclipse-rcp-ganymede-SR2-linux-gtk.tar.gz" in the directory of
+  your choice, e.g.:
+
+  $ mkdir ~/eclipse-3.4
+  $ cd ~/eclipse-3.4
+  $ tar xvzf eclipse-rcp-ganymede-SR2-linux-gtk.tar.gz
+
+  This will create an "eclipse" directory in the current directory.
+
+- Set ECLIPSE_HOME to that "eclipse" directory:
+
+  $ export ECLIPSE_HOME=~/eclipse-3.4/eclipse
+
+  Note: it is important you set ECLIPSE_HOME before starting the build.
+  Otherwise the build process will try to download and install its own Eclipse
+  installation in /buildroot, which is probably limited to root.
+
+- Now, before you can build anything, it is important that you start Eclipse
+  *manually* once using the same user that you will use to build later. That's
+  because your Eclipse installation is not finished: Eclipse must be run at
+  least once to create some files in ~/.eclipse/. So run Eclipse now:
+
+  $ ~/eclipse-3.4/eclipse/eclipse &
+
+  Wait for it load, create a workspace when requested and then simply quit
+  using the File > Quit menu. That's it. You won't need to run it manually
+  again.
+
+
+
+B- Building ADT
+---------------
+
+Finally, you have Eclipse, it's installed and it created its own config files,
+so now you can build your ADT plugin. To do that you'll 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"
+  $ development/tools/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 will 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-
+

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