SDK: updae howto_build_SDK.txt for cygwin.

Change-Id: I63ce0d33dc58d2c772f9f47e7aef5bd0974e7531

1 files changed, 105 insertions, 54 deletions

diff --git a/docs/howto_build_SDK.txt b/docs/howto_build_SDK.txt
index b9e908c..dbe51d9 100644
--- a/docs/howto_build_SDK.txt
+++ b/docs/howto_build_SDK.txt
@@ -74,7 +74,7 @@ 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 init -u https://android.googlesource.com/platform/manifest -b master
   $ repo sync
 
 Then once you have all the source, simply build the SDK using:
@@ -110,27 +110,61 @@ Some options:
 3- Building an SDK for Windows
 ------------------------------
 
-A- SDK pre-requisite
---------------------
+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.
 
-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.
+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
+-----------------
 
-B- Cygwin pre-requisite & code checkout
----------------------------------------
+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.
 
-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:
+Under Ubuntu, you will need the following extra packages: 
 
-  http://cygwin.org/win-9x.html
+$ sudo apt-get install mingw32 tofrodos
 
-Don't mind the page title, just grab setup-legacy.exe and it will works just fine
-under XP or Vista.
+mingw32 is the cross-compiler, 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/
+
+
+
+----------------------------
+4- Partial SDK Windows Tools
+----------------------------
+
+As explained above, you can only build a *full* SDK for Windows using Linux.
+However sometimes you need to develop one specific tools, e.g. adb.exe or
+aapt.exe, and it's just more convenient to do it on the same platform where
+you can actually test it. This is what this section explains.
+
+   
+A- Cygwin pre-requisite & code checkout
+---------------------------------------
+
+You must have Cygwin installed. You can use the latest Cygwin 1.7 or the
+the "legacy Cygwin 1.5" from:
+
+  http://cygwin.org/
 
-  
 Now configure it:
 - 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
@@ -142,44 +176,58 @@ Now configure it:
   - 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:
+for MacOS or Linux (see section 2 above.)
+
+
+
+C- Building the Windows Tools
+-----------------------------
+
+This is the easy part: run make on the tool you want.
+How do you know which tools you can build? Well obviously all the ones
+that come in an installed SDK/tools or SDK/platform-tools folder!
+
+Example, to build adb:
 
-  $ mkdir ~/my-android-git
   $ cd ~/my-android-git
-  $ repo init -u git://android.git.kernel.org/platform/manifest.git -b cupcake
-  $ repo sync
+  $ . build/envsetup.sh
+  $ lunch sdk-eng
+  $ make adb
 
+The result will be somewhere in out/host/windows-x86/bin/. Just look at
+the output from make to get the exact path. Since you are building this
+under cygwin, you get an unstripped binary that you can happily feed to
+gdb to get debugger symbols:
 
+  $ gdb --args out/host/windows-x86/bin/adb.exe <adb arguments>
 
-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.
+And before you ask, msys is not supported, nor is MSVC or windbg.
 
-  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.
+So you can build a lot of little parts of the SDK on Windows, one tool
+at a time, but not the full thing because basically building the whole
+platform is not supported. This means you cannot build "android.jar"
+nor "layoutlib.jar" under Windows. For this you want Linux.
 
 
-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`
+D- Building the Windows Tools on Linux
+--------------------------------------
+
+You can also build isolated windows tools directly on Linux.
+Again, it requires a checkout of the full android code and the usual
+setup like described above to build an SDK.
+
+Then to build an isolated Windows binary, you'd do something like this:
+  
   $ cd ~/my-android-git
-  $ development/build/tools/make_windows_sdk.sh /path/to/macos/or/linux/sdk.zip ~/mysdk
+  $ . build/envsetup.sh
+  $ lunch sdk-eng
+  $ USE_MINGW=1 make adb
 
-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.
+The special environment variable "USE_MINGW" must be set to 1. This is
+the clue to switch the make logic to cross-compiling to Windows under
+Linux.
 
 
 
@@ -189,7 +237,7 @@ Windows SDK zip file. A typical build time should be around 5-10 minutes.
 
 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 must have a working version of Eclipse 3.6 "helios" 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.
@@ -201,31 +249,32 @@ 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.
+place. Forget that and install a working 3.6 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
+  Note: You will need the CDT plugin but don't take a "CDT" flavor build as it
+  will lack the RCP tools. Instead take an RCP and then add CDT.
+  
+- Unpack "eclipse-rcp-*-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
+  $ mkdir ~/eclipse-3.6
+  $ cd ~/eclipse-3.6
+  $ tar xvzf eclipse-rcp-????-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
+  $ export ECLIPSE_HOME=~/eclipse-3.6/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
@@ -236,11 +285,13 @@ place. Forget that and install a working 3.4 manually as described below.
   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 &
+  $ ~/eclipse-3.6/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.
+- Since you have Eclipse loaded, now is a perfect time to pick up the
+  CDT plugin. (Another alternative is is to fetch the CDT from its archives
+  and manually dump all the *.jar in eclipse/plugins.)
+  
+  That's it. You won't need to run it manually again.
 
 
 
@@ -254,7 +305,7 @@ 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
+  $ 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 will make the