docs: Add building coreclr for emulator

Added documentation for building coreclr for the Linux ARM Emulator.

Signed-off-by: Prajwal A N <an.prajwal@samsung.com>
Commit migrated from https://github.com/dotnet/coreclr/commit/3c277086192d6a600f81e752239dd0ec2d02ae83

diff --git a/docs/coreclr/building/cross-building.md b/docs/coreclr/building/cross-building.md
index 30e8a08562085328e113f2301050cb12ae8b3455..ba268678e90e9e51a7e9f803ca6606bdac3cdb66 100644 (file)
--- a/docs/coreclr/building/cross-building.md
+++ b/docs/coreclr/building/cross-building.md
@@ -95,4 +95,43 @@ The output is at bin/Product/<BuildOS>.arm.Debug/mscorlib.dll.
     (console) ARMv7 Thumb Mono/.Net assembly, for MS Windows
 ```
 
+Building coreclr for Linux ARM Emulator
+=======================================
 
+It is possible to build coreclr binaries (native and mscorlib.dll) and run coreclr unit tests on the Linux ARM Emulator (latest version provided here: [#3805](https://github.com/dotnet/coreclr/issues/3805)).
+The `tests/scripts/arm32_ci_script.sh` script does this.
+
+The following instructions assume that:
+* You have set up the extracted emulator at `/opt/linux-arm-emulator` (such that `/opt/linux-arm-emulator/platform/rootfs-t30.ext4` exists)  
+The emulator rootfs is of 4GB size by default. But to enable testing of coreclr binaries on the emulator, you need to resize the rootfs (to atleast 7GB) using the instructions given in the `doc/RESIZE-IMAGE.txt` file of the extracted emulator.
+* The mount path for the emulator rootfs is `/opt/linux-arm-emulator-root` (change this path if you have a working directory at this path).
+
+All the following instructions are for the Release mode. Change the commands and files accordingly for the Debug mode.
+
+To just build libcoreclr and mscorlib for the Linux ARM Emulator, run the following command:
+```
+prajwal@ubuntu ~/coreclr $ ./tests/scripts/arm32_ci_script.sh \
+    --emulatorPath=/opt/linux-arm-emulator \
+    --mountPath=/opt/linux-arm-emulator-root \
+    --buildConfig=Release \
+    --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`.
+
+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).  
+Setup the binaries at `~/coreclr/bin/tests/Windows_NT.x64.Release`.
+* Build corefx binaries for the Emulator as given [here](https://github.com/dotnet/corefx/blob/master/Documentation/building/cross-building.md#building-corefx-for-linux-arm-emulator).  
+Setup these binaries at `~/corefx/bin/Linux.arm-softfp.Release`, `~/corefx/bin/Linux.AnyCPU.Release`, `~/corefx/bin/Unix.AnyCPU.Release`, and `~/corefx/bin/AnyOS.AnyCPU.Release`.
+* Run the following command (change value of `--testDirFile` argument to the file containing your selection of tests):
+```
+prajwal@ubuntu ~/coreclr $ ./tests/scripts/arm32_ci_script.sh \
+    --emulatorPath=/opt/linux-arm-emulator \
+    --mountPath=/opt/linux-arm-emulator-root \
+    --buildConfig=Release \
+    --testRootDir=~/coreclr/bin/tests/Windows_NT.x64.Release \
+    --coreFxNativeBinDir=~/corefx/bin/Linux.arm-softfp.Release \
+    --coreFxBinDir="~/corefx/bin/Linux.AnyCPU.Release;~/corefx/bin/Unix.AnyCPU.Release;~/corefx/bin/AnyOS.AnyCPU.Release" \
+    --testDirFile=~/coreclr/tests/testsRunningInsideARM.txt
+```