[SR-1264] Fix missing information in Android docs

* Add instructions to symlink the Android linker.
* Make it clear that paths to `android-ndk-r11c` and `libiconv-libicu-android` may be different based on where the user may have downloaded them by prefixing the paths, such as `/path/to/android-ndk-r11c`.
* Link to https://bugs.swift.org/browse/SR-1321 and recommend Ubuntu 15.10 for now.
* Use HTTPS when invoking `git clone`.

docs/Android.md

@@ -26,9 +26,10 @@ Swift-to-Java bridging.
 
 To follow along with this guide, you'll need:
 
-1. A Linux environment capable of building Swift from source. The stdlib is
-   currently only buildable for Android from a Linux environment. Before
-   attempting to build for Android, please make sure you are able to build
+1. A Linux environment capable of building Swift from source, specifically
+   Ubuntu 15.10 (Ubuntu 14.04 is [not currently supported](Swift Android libicuuc link step fails on Ubuntu 14.04)).
+   The stdlib is currently only buildable for Android from a Linux environment.
+   Before attempting to build for Android, please make sure you are able to build
    for Linux by following the instructions in the Swift project README.
 2. The latest version of the Android NDK (r11c at the time of this writing),
    available to download here:
@@ -57,7 +58,7 @@ Alternatively, you may choose to build libiconv and libicu for Android yourself:
    `git` installed.
 2. Clone the [SwiftAndroid/libiconv-libicu-android](https://github.com/SwiftAndroid/libiconv-libicu-android)
    project. From the command-line, run the following command:
-   `git clone git@github.com:SwiftAndroid/libiconv-libicu-android.git`.
+   `git clone https://github.com/SwiftAndroid/libiconv-libicu-android.git`.
 3. From the command-line, run `which ndk-build`. Confirm that the path to
    the `ndk-build` executable in the Android NDK you downloaded is displayed.
    If not, you may need to add the Android NDK directory to your `PATH`.
@@ -75,14 +76,14 @@ Android NDK, as well as the directories that contain the `libicuuc.so` and
 
 ```
 $ utils/build-script \
-    -R \                                # Build in ReleaseAssert mode.
-    --android \                         # Build for Android.
-    --android-ndk ~/android-ndk-r11c \  # Path to an Android NDK.
-    --android-api-level 21 \            # The Android API level to target. Swift only supports 21 or greater.
-    --android-icu-uc ~/libicu-android/armeabi-v7a \
-    --android-icu-uc-include ~/libicu-android/armeabi-v7a/icu/source/common \
-    --android-icu-i18n ~/libicu-android/armeabi-v7a \
-    --android-icu-i18n-include ~/libicu-android/armeabi-v7a/icu/source/i18n/
+    -R \                                       # Build in ReleaseAssert mode.
+    --android \                                # Build for Android.
+    --android-ndk /path/to/android-ndk-r11c \  # Path to an Android NDK.
+    --android-api-level 21 \                   # The Android API level to target. Swift only supports 21 or greater.
+    --android-icu-uc /path/to/libicu-android/armeabi-v7a \
+    --android-icu-uc-include /path/to/libicu-android/armeabi-v7a/icu/source/common \
+    --android-icu-i18n /path/to/libicu-android/armeabi-v7a \
+    --android-icu-i18n-include /path/to/libicu-android/armeabi-v7a/icu/source/i18n/
 ```
 
 ### 3. Compiling `hello.swift` to run on an Android device
@@ -93,15 +94,24 @@ Create a simple Swift file named `hello.swift`:
 print("Hello, Android")
 ```
 
-Use the built Swift compiler from the previous step to compile a Swift source
-file, targeting Android:
+To compile it, we need to make sure the correct linker is used. Symlink the
+gold linker in the Android NDK into your `PATH`:
 
 ```
-$ build/Ninja/ReleaseAssert/swift-linux-x86_64/swiftc \                   # The Swift compiler built in the previous step.
-    -target armv7-none-linux-androideabi \                                # Targeting android-armv7.
-    -sdk ~/android-ndk-r11c/platforms/android-21/arch-arm \               # Use the same NDK path and API version as you used to build the stdlib in the previous step.
-    -L ~/android-ndk-r11c/sources/cxx-stl/llvm-libc++/libs/armeabi-v7a \  # Link the Android NDK's libc++ and libgcc.
-    -L ~/android-ndk-r11c/toolchains/arm-linux-androideabi-4.9/prebuilt/linux-x86_64/lib/gcc/arm-linux-androideabi/4.9 \
+$ sudo ln -s \
+    /path/to/android-ndk-r11c/toolchains/arm-linux-androideabi-4.9/prebuilt/linux-x86_64/arm-linux-androideabi/bin/ld.gold \
+    /usr/bin/armv7-none-linux-androideabi-ld.gold
+```
+
+Then use the built Swift compiler from the previous step to compile a Swift
+source file, targeting Android:
+
+```
+$ build/Ninja-ReleaseAssert/swift-linux-x86_64/bin/swiftc \                      # The Swift compiler built in the previous step.
+    -target armv7-none-linux-androideabi \                                       # Targeting android-armv7.
+    -sdk /path/to/android-ndk-r11c/platforms/android-21/arch-arm \               # Use the same NDK path and API version as you used to build the stdlib in the previous step.
+    -L /path/to/android-ndk-r11c/sources/cxx-stl/llvm-libc++/libs/armeabi-v7a \  # Link the Android NDK's libc++ and libgcc.
+    -L /path/to/android-ndk-r11c/toolchains/arm-linux-androideabi-4.9/prebuilt/linux-x86_64/lib/gcc/arm-linux-androideabi/4.9 \
     hello.swift
 ```
 
@@ -135,7 +145,7 @@ $ adb push build/Ninja-ReleaseAssert/swift-linux-x86_64/lib/swift/android/libswi
 In addition, you'll also need to copy the Android NDK's libc++:
 
 ```
-$ adb push ~/android-ndk-r11c/sources/cxx-stl/llvm-libc++/libs/armeabi-v7a/libc++_shared.so /data/local/tmp
+$ adb push /path/to/android-ndk-r11c/sources/cxx-stl/llvm-libc++/libs/armeabi-v7a/libc++_shared.so /data/local/tmp
 ```
 
 Finally, you'll need to copy the `hello` executable you built in the
@@ -150,7 +160,7 @@ You can use the `adb shell` command to execute the `hello` executable on
 the Android device:
 
 ```
-$ adb shell LD_LIBRARY_PATH=/data/local/tmp hello
+$ adb shell LD_LIBRARY_PATH=/data/local/tmp /data/local/tmp/hello
 ```
 
 You should see the following output: