Imported Upstream version 1.0.0.9910upstream/1.0.0.9910

4 files changed, 137 insertions, 18 deletions

diff --git a/Documentation/building/android.md b/Documentation/building/android.md
new file mode 100644
index 0000000000..cfb509dc2f
--- /dev/null
+++ b/Documentation/building/android.md
@@ -0,0 +1,102 @@
+Cross Compilation for Android on Linux
+======================================
+
+Through cross compilation, on Linux it is possible to build CoreCLR for arm64 Android.
+
+Requirements
+------------
+
+You'll need to generate a toolchain and a sysroot for Android. There's a script which takes care of the required steps.
+
+Generating the rootfs
+---------------------
+
+To generate the rootfs, run the following command in the `coreclr` folder:
+
+```
+cross/init-android-rootfs.sh
+```
+
+This will download the NDK and any packages required to compile Android on your system. It's over 1 GB of data, so it may take a while.
+
+
+Cross compiling CoreCLR
+-----------------------
+Once the rootfs has been generated, it will be possible to cross compile CoreCLR. 
+
+When cross compiling, you need to set both the `CONFIG_DIR` and `ROOTFS_DIR` variables.
+
+To compile for arm64, run:
+
+```
+CONFIG_DIR=`realpath cross/android/arm64` ROOTFS_DIR=`realpath cross/android-rootfs/toolchain/arm64/sysroot` ./build.sh cross arm64 skipgenerateversion skipmscorlib cmakeargs -DENABLE_LLDBPLUGIN=0
+```
+
+The resulting binaries will be found in `bin/Product/Linux.BuildArch.BuildType/`
+
+Running the PAL tests on Android
+--------------------------------
+
+You can run the PAL tests on an Android device. To run the tests, you first copy the PAL tests to your Android phone using
+`adb`, and then run them in an interactive Android shell using `adb shell`:
+
+To copy the PAL tests over to an Android phone:
+```
+adb push bin/obj/Linux.arm64.Debug/src/pal/tests/palsuite/ /data/local/tmp/coreclr/src/pal/tests/palsuite
+adb push cross/android/toolchain/arm64/sysroot/usr/lib/libuuid.so.1 /data/local/tmp/coreclr/lib
+adb push cross/android/toolchain/arm64/sysroot/usr/lib/libintl.so /data/local/tmp/coreclr/lib
+adb push cross/android/toolchain/arm64/sysroot/usr/lib/libandroid-support.so /data/local/tmp/coreclr/lib/
+adb push cross/android/toolchain/arm64/sysroot/usr/lib/libandroid-glob.so /data/local/tmp/coreclr/lib/
+adb push src/pal/tests/palsuite/paltestlist.txt /data/local/tmp/coreclr
+adb push src/pal/tests/palsuite/runpaltests.sh /data/local/tmp/coreclr/
+```
+
+Then, use `adb shell` to launch a shell on Android. Inside that shell, you can launch the PAL tests:
+```
+LD_LIBRARY_PATH=/data/local/tmp/coreclr/lib ./runpaltests.sh /data/local/tmp/coreclr/
+```
+
+Debugging coreclr on Android
+----------------------------
+
+You can debug coreclr on Android using a remote lldb server which you run on your Android device.
+
+First, push the lldb server to Android:
+
+```
+adb push cross/android/lldb/2.2/android/arm64-v8a/lldb-server /data/local/tmp/
+```
+
+Then, launch the lldb server on the Android device. Open a shell using `adb shell` and run:
+
+```
+adb shell
+cd /data/local/tmp
+./lldb-server platform --listen *:1234
+```
+
+After that, you'll need to forward port 1234 from your Android device to your PC:
+```
+adb forward tcp:1234 tcp:1234
+```
+
+Finally, install lldb on your PC and connect to the debug server running on your Android device:
+
+```
+lldb-3.9
+(lldb) platform select remote-android
+  Platform: remote-android
+ Connected: no
+(lldb) platform connect connect://localhost:1234
+  Platform: remote-android
+    Triple: aarch64-*-linux-android
+OS Version: 23.0.0 (3.10.84-perf-gf38969a)
+    Kernel: #1 SMP PREEMPT Fri Sep 16 11:29:29 2016
+  Hostname: localhost
+ Connected: yes
+WorkingDir: /data/local/tmp
+
+(lldb) target create coreclr/pal/tests/palsuite/file_io/CopyFileA/test4/paltest_copyfilea_test4
+(lldb) env LD_LIBRARY_PATH=/data/local/tmp/coreclr/lib
+(lldb) run
+```
diff --git a/Documentation/building/cross-building.md b/Documentation/building/cross-building.md
index ab5897a24a..30c7aca741 100644
--- a/Documentation/building/cross-building.md
+++ b/Documentation/building/cross-building.md
@@ -21,11 +21,12 @@ and conversely for arm64:
 
 Generating the rootfs
 ---------------------
-The `cross\build-rootfs.sh` script can be used to download the files needed for cross compilation. It will generate an Ubuntu 14.04 rootfs as this is what CoreCLR targets.
+The `cross\build-rootfs.sh` script can be used to download the files needed for cross compilation. It will generate an rootfs as this is what CoreCLR targets.
 
-    Usage: build-rootfs.sh [BuildArch] [UbuntuCodeName]
-    BuildArch can be: arm, arm-softfp, arm64
-    UbuntuCodeName - optional, Code name for Ubuntu, can be: trusty(default), vivid, wily
+    Usage: ./cross/build-rootfs.sh [BuildArch] [LinuxCodeName] [lldbx.y] [--skipunmount]
+    BuildArch can be: arm(default), armel, arm64, x86
+    LinuxCodeName - optional, Code name for Linux, can be: trusty(default), vivid, wily, xenial. If BuildArch is armel, LinuxCodeName is jessie(default) or tizen.
+    lldbx.y - optional, LLDB version, can be: lldb3.6(default), lldb3.8
 
 The `build-rootfs.sh` script must be run as root as it has to make some symlinks to the system, it will by default generate the rootfs in `cross\rootfs\<BuildArch>` however this can be changed by setting the `ROOTFS_DIR` environment variable.
 
@@ -33,7 +34,7 @@ For example, to generate an arm rootfs:
 
     ben@ubuntu ~/git/coreclr/ $ sudo ./cross/build-rootfs.sh arm
 
-You can choose Ubuntu code name to match your target, give `vivid` for `15.04`, `wily` for `15.10`. Default is `trusty`, version `14.04`.
+You can choose Linux code name to match your target, give `vivid` for `Ubuntu 15.04`, `wily` for `Ubuntu 15.10`. Default is `trusty`, version `Ubuntu 14.04`.
 
     ben@ubuntu ~/git/coreclr/ $ sudo ./cross/build-rootfs.sh arm wily
 
@@ -41,6 +42,18 @@ and if you wanted to generate the rootfs elsewhere:
 
     ben@ubuntu ~/git/coreclr/ $ sudo ROOTFS_DIR=/home/ben/coreclr-cross/arm ./cross/build-rootfs.sh arm
 
+For example, to generate an armel rootfs:
+
+    hqu@ubuntu ~/git/coreclr/ $ sudo ./cross/build-rootfs.sh armel
+
+You can choose code name to match your target, give `jessie` for `Debian`, `tizen` for `Tizen`. Default is `jessie`.
+
+    hque@ubuntu ~/git/coreclr/ $ sudo ./cross/build-rootfs.sh armel tizen
+
+and if you wanted to generate the rootfs elsewhere:
+
+    hque@ubuntu ~/git/coreclr/ $ sudo ROOTFS_DIR=/home/ben/coreclr-cross/armel ./cross/build-rootfs.sh armel tizen
+
 
 Cross compiling CoreCLR
 -----------------------
@@ -117,7 +130,7 @@ prajwal@ubuntu ~/coreclr $ ./tests/scripts/arm32_ci_script.sh \
     --skipTests
 ```
 
-The Linux ARM Emulator is based on soft floating point and thus the native binaries in coreclr are built for the arm-softfp architecture. The coreclr binaries generated by the above command (native and mscorlib) can be found at `~/coreclr/bin/Product/Linux.arm-softfp.Release`.
+The Linux ARM Emulator is based on soft floating point and thus the native binaries in coreclr are built for the armel architecture. The coreclr binaries generated by the above command (native and mscorlib) can be found at `~/coreclr/bin/Product/Linux.armel.Release`.
 
 To build libcoreclr and mscorlib, and run selected coreclr unit tests on the emulator, do the following:
 * Download the latest Coreclr unit test binaries (or build on Windows) from here: [Debug](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/debug_windows_nt_bld/lastSuccessfulBuild/artifact/bin/tests/tests.zip) and [Release](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/release_windows_nt_bld/lastSuccessfulBuild/artifact/bin/tests/tests.zip).  
diff --git a/Documentation/building/testing-with-corefx.md b/Documentation/building/testing-with-corefx.md
index 4f9886f78d..defc8f8e8b 100644
--- a/Documentation/building/testing-with-corefx.md
+++ b/Documentation/building/testing-with-corefx.md
@@ -3,18 +3,23 @@ Testing with CoreFX
 
 It may be valuable to use CoreFX tests to validate your changes to CoreCLR or mscorlib.
 
-**Windows**
+**NOTE:** The `BUILDTOOLS_OVERRIDE_RUNTIME` property no longer works.
 
-As part of building tests, CoreFX restores a copy of the runtime from myget, in order to update the runtime that is deployed, a special build property `BUILDTOOLS_OVERRIDE_RUNTIME` can be used. If this is set, the CoreFX testing targets will copy all the files in the folder it points to into the test folder, overwriting any files that exist.
+**Replace runtime between build.[cmd|sh] and build-tests.[cmd|sh]**
 
-To run tests, follow the procedure for [running tests in CoreFX](https://github.com/dotnet/corefx/blob/master/Documentation/building/windows-instructions.md). You can pass `/p:BUILDTOOLS_OVERRIDE_RUNTIME=<path-to-coreclr>\bin\Product\Windows_NT.x64.Release` to build.cmd to set this property, e.g. (note the space between the "--" and the "/p" option):
+Use the following instructions to test a change to the dotnet/coreclr repo using dotnet/corefx tests.  Refer to the [CoreFx Developer Guide](https://github.com/dotnet/corefx/blob/master/Documentation/project-docs/developer-guide.md) for information about CoreFx build scripts.
 
-```
-build.cmd -Release -- /p:BUILDTOOLS_OVERRIDE_RUNTIME=<root of coreclr repo>\bin\Product\Windows_NT.x64.Checked
-```
+1. Build the CoreClr runtime you wish to test under `<coreclr_root>`
+2. Build the CoreFx repo (`build.[cmd|sh]`) under `<corefx_root>`, but don't build tests yet
+3. Copy the contents of the CoreCLR binary root you wish to test into the CoreFx runtime folder (`<flavor>` below) created in step #2.  For example:
 
-**FreeBSD, Linux, NetBSD, OS X**
+  `copy <coreclr_root>\bin\Product\Windows_NT.<arch>.<build_type>\* <corefx_root>\bin\runtime\<flavor>`  
+  -or-  
+  `cp <coreclr_root>/bin/Product/<os>.<arch>.<build_type>/* <corefx_root>/bin/runtime/<flavor>`  
+  
+4. Run the CoreFx `build-tests.[cmd|sh]` script as described in the Developer Guide.
+
+**CI Script**
+
+[run-corefx-tests.py](https://github.com/dotnet/coreclr/blob/master/tests/scripts/run-corefx-tests.py) will clone dotnet/corefx and run steps 2-4 above automatically.  It is primarily intended to be run by the dotnet/coreclr CI system, but it might provide a useful reference or shortcut for individuals running the tests locally.
 
-Refer to the procedure for [running tests in CoreFX](https://github.com/dotnet/corefx/blob/master/Documentation/building/cross-platform-testing.md)
-- Note the --coreclr-bins and --mscorlib-bins arguments to [run-test.sh](https://github.com/dotnet/corefx/blob/master/run-test.sh)
-- Pass in paths to your private build of CoreCLR
diff --git a/Documentation/building/unix-test-instructions.md b/Documentation/building/unix-test-instructions.md
index 9cf7507443..563c3e8c68 100644
--- a/Documentation/building/unix-test-instructions.md
+++ b/Documentation/building/unix-test-instructions.md
@@ -36,8 +36,7 @@ Run tests (`Debug` may be replaced with `Release` or `Checked`, depending on whi
 >     --testNativeBinDir=~/coreclr/bin/obj/Linux.x64.Debug/tests
 >     --coreClrBinDir=~/coreclr/bin/Product/Linux.x64.Debug
 >     --mscorlibDir=/media/coreclr/bin/Product/Linux.x64.Debug
->     --coreFxBinDir="~/corefx/bin/Linux.AnyCPU.Debug;~/corefx/bin/Unix.AnyCPU.Debug;~/corefx/bin/AnyOS.AnyCPU.Debug"
->     --coreFxNativeBinDir=~/corefx/bin/Linux.x64.Debug
+>     --coreFxBinDir=~/corefx/bin/runtime/netcoreapp-Linux-Debug-x64
 > ```
 
 The method above will copy dependencies from the set of directories provided to create an 'overlay' directory.