Imported Upstream version 1.1.0upstream/1.1.0

14 files changed, 1751 insertions, 0 deletions

diff --git a/Documentation/building/buildinglldb.md b/Documentation/building/buildinglldb.md
new file mode 100644
index 0000000000..053c64f924
--- /dev/null
+++ b/Documentation/building/buildinglldb.md
@@ -0,0 +1,87 @@
+Building LLDB
+=============
+
+1. Clone the llvm, clang, and lldb repos like this:
+
+        llvm
+        |
+        `-- tools
+            |
+            +-- clang
+            |
+            `-- lldb
+
+   ```
+	cd $HOME
+	git clone http://llvm.org/git/llvm.git
+	cd $HOME/llvm/tools
+	git clone http://llvm.org/git/clang.git 
+	git clone http://llvm.org/git/lldb.git 
+   ```
+
+2. Checkout the "release_38" branches in llvm/clang/lldb:
+
+   ```
+   cd $HOME/llvm
+   git checkout release_38
+   cd $HOME/llvm/tools/clang
+   git checkout release_38
+   cd $HOME/llvm/tools/lldb
+   git checkout release_38 
+   ```
+
+3. Install the prerequisites:
+
+   For Linux (Debian or Ubuntu):
+   ```
+   sudo apt-get install build-essential subversion swig python2.7-dev libedit-dev libncurses5-dev
+   ```
+   
+   For OSX, the latest Xcode needs to be installed and I use Homebrew to install the rest:
+   ```     
+   brew install python swig doxygen ocaml
+   ```
+   
+   There may be more prerequisites required, when building the cmake files it should let
+   you know if there are any I missed.
+
+   See http://lldb.llvm.org/build.html for more details on these preliminaries.
+
+4. If building on OSX, carefully following the signing directions (before you build) 
+   here: $HOME/llvm/tools/lldb/docs/code-signing.txt. Even though those build directions
+   say to use Xcode to build lldb, I never got it to work, but cmake/make works.
+
+5. Building the cmake files (you can build either debug or release or both).
+
+   For debug:
+   ```
+   mkdir -p $HOME/build/debug    
+   cd $HOME/build/debug
+   cmake -DCMAKE_BUILD_TYPE=debug $HOME/llvm
+   ```
+   For release:
+   ```
+   mkdir -p $HOME/build/release    
+   cd $HOME/build/release
+   cmake -DCMAKE_BUILD_TYPE=release $HOME/llvm
+   ```
+6. Build lldb (release was picked in this example, but can be replaced with "debug"):
+   ```
+   cd $HOME/build/release/tools/lldb
+   make -j16
+   ```
+   When you build with -j16 (parallel build with 16 jobs), sometimes it fails. Just start again with just make.
+
+   For OS X, building in remote ssh shell won't sign properly, use a terminal window on the machine itself.
+
+7. To use the newly built lldb and to build the coreclr SOS plugin for it, set these environment variables in your .profile:
+   ```
+   export LLDB_INCLUDE_DIR=$HOME/llvm/tools/lldb/include
+   export LLDB_LIB_DIR=$HOME/build/release/lib
+   PATH=$HOME/build/release/bin:$PATH
+   ```
+   For OS X also set:
+   ```
+   export LLDB_DEBUGSERVER_PATH=$HOME/build/release/bin/debugserver
+   ```
+   It also seems to be necessary to run lldb as superuser e.g. `sudo -E $HOME/build/release/bin/lldb` (the -E is necessary so the above debug server environment variable is passed) if using a remote ssh, but it isn't necessary if run it in a local terminal session.
diff --git a/Documentation/building/cross-building.md b/Documentation/building/cross-building.md
new file mode 100644
index 0000000000..ab5897a24a
--- /dev/null
+++ b/Documentation/building/cross-building.md
@@ -0,0 +1,137 @@
+Cross Compilation for ARM on Linux
+==================================
+
+Through cross compilation, on Linux it is possible to build CoreCLR for arm or arm64.
+
+Requirements
+------------
+
+You need a Debian based host and the following packages needs to be installed:
+
+    ben@ubuntu ~/git/coreclr/ $ sudo apt-get install qemu qemu-user-static binfmt-support debootstrap
+
+In addition, to cross compile CoreCLR the binutils for the target are required. So for arm you need:
+
+    ben@ubuntu ~/git/coreclr/ $ sudo apt-get install binutils-arm-linux-gnueabihf
+
+and conversely for arm64:
+
+    ben@ubuntu ~/git/coreclr/ $ sudo apt-get install binutils-aarch64-linux-gnu
+
+
+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.
+
+    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
+
+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.
+
+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`.
+
+    ben@ubuntu ~/git/coreclr/ $ sudo ./cross/build-rootfs.sh arm wily
+
+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
+
+
+Cross compiling CoreCLR
+-----------------------
+Once the rootfs has been generated, it will be possible to cross compile CoreCLR. If `ROOTFS_DIR` was set when generating the rootfs, then it must also be set when running `build.sh`.
+
+So, without `ROOTFS_DIR`:
+
+    ben@ubuntu ~/git/coreclr/ $ ./build.sh arm debug verbose cross -rebuild
+
+And with:
+
+    ben@ubuntu ~/git/coreclr/ $ ROOTFS_DIR=/home/ben/coreclr-cross/arm ./build.sh arm debug verbose cross -rebuild
+
+As usual the resulting binaries will be found in `bin/Product/BuildOS.BuildArch.BuildType/`
+
+
+Compiling mscorlib for ARM Linux
+================================
+
+It is also possible to use a Windows and a Linux machine to build the managed components of CoreCLR for ARM Linux.  This can be useful when the build on the target platform fails, for example due to Mono issues.
+
+Build mscorlib on Windows
+-------------------------
+The following instructions assume you are on a Windows machine with a clone of the CoreCLR repo that has a correctly configured [environment](https://github.com/dotnet/coreclr/wiki/Windows-instructions#environment).
+
+To build mscorlib for Linux, run the following command:
+
+```
+D:\git\coreclr> build.cmd linuxmscorlib arm
+```
+
+The arguments `freebsdmscorlib` and `osxmscorlib` can be used instead to build mscorlib for FreeBSD or OS X.
+
+The output is at bin\Product\<BuildOS>.arm.Debug\mscorlib.dll.
+
+
+Build mscorlib on Ubuntu
+-------------------------
+The following instructions assume you are on a Linux machine such as Ubuntu 14.04 x86 64bit. 
+
+To build mscorlib for Linux, run the following command:
+
+```
+    lgs@ubuntu ~/git/coreclr/ $ build.sh arm debug verbose -rebuild
+```
+
+The output is at bin/Product/<BuildOS>.arm.Debug/mscorlib.dll.
+
+```
+    lgs@ubuntu ~/git/coreclr/ $ file ./bin/Product/Linux.arm.Debug/mscorlib.dll 
+    ./bin/Product/Linux.arm.Debug/mscorlib.dll: PE32 executable (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
+```
diff --git a/Documentation/building/crossgen.md b/Documentation/building/crossgen.md
new file mode 100644
index 0000000000..c74a5e680a
--- /dev/null
+++ b/Documentation/building/crossgen.md
@@ -0,0 +1,66 @@
+Using CrossGen to Create Native Images
+======================================
+
+Introduction
+------------
+
+When you create a .NET assembly using C# compiler, your assembly contains only MSIL code.
+When the app runs, the JIT compiler translates the MSIL code into native code, before the CPU can execute them.
+This execution model has some advantages. For example, your assembly code can be portable across all platforms and architectures that support .NET Core.
+However, this portability comes with a performance penalty. Your app starts up slower, because the JIT compiler has to spend time to translate the code.
+
+To help make your app start up faster, CoreCLR includes a tool called CrossGen, which can pre-compile the MSIL code into native code.
+
+Getting CrossGen
+----------------
+
+If you build CoreCLR yourself, the CrossGen tool (`crossgen.exe` on Windows, or `crossgen` on other platforms) is created as part of the build, and stored in the same output directory as other CoreCLR binaries.
+If you install CoreCLR using a NuGet package, you can find CrossGen in the `tools` folder of the NuGet package.
+
+Regardless of how you obtain CrossGen, it is very important that it must match other CoreCLR binaries.
+- If you build CrossGen yourself, you should use it with coreclr and mscorlib generated from the same build. Do not attempt to mix CrossGen from one build with binaries generated from another build.
+- If you install CrossGen from NuGet, make sure you use CrossGen from exactly the same NuGet package as the rest of your CoreCLR binaries. Do not attempt to mix binaries from multiple NuGet packages.
+
+If you do not follow the above rules, you are likely to encounter errors while running CrossGen.
+
+Using CrossGen
+--------------
+
+In most cases, the build script automatically runs CrossGen to create the native image for mscorlib.
+When this happens, you will find both `mscorlib.dll` and `mscorlib.ni.dll` in your output directory.
+`mscorlib.dll` is the MSIL assembly created by the C# compiler, while `mscorlib.ni.dll` is the native image that contains CPU-specific code.
+Once the build is done, you only need `mscorlib.ni.dll` to use CoreCLR.
+As a matter of fact, most CoreCLR NuGet packages contain only `mscorlib.ni.dll`, without `mscorlib.dll`
+
+If for some reason you did not get `mscorlib.ni.dll` with the rest of your CoreCLR, you can easily create it yourself using CrossGen.
+First, make sure you have `crossgen.exe` (on Windows) or `crossgen` (other platforms) in the same directory as `mscorlib.dll`.
+Then, run one of the following two commands (first command for Windows, second command for other platforms):
+
+    .\crossgen.exe mscorlib.dll
+    ./crossgen mscorlib.dll
+    
+To create native images for other assemblies, the command line is slightly more complex:
+
+    .\crossgen.exe /Platform_Assemblies_Paths "path1;path2;..." assemblyName.dll
+    ./crossgen /Platform_Assemblies_Paths "path1:path2:..." assemblyName.dll
+    
+The /Platform_Assemblies_Paths is used to specify the location of all the dependencies of the input assembly.
+You should use full paths for this locations. Relative paths do not always work.
+If there are multiple paths, separate them with semicolons (`;`) on Windows, or colons (`:`) on non-Windows platforms.
+It is generally a good idea to enclose the path list in quotes to protect any special characters from the shell.
+
+Using native images
+-------------------
+
+Running CrossGen on an assembly creates a "native image" file, with the extension of `.ni.dll` or `.ni.exe`.
+You should include the native images in your app, at the same location where you normally install the MSIL assemblies.
+Once you have included native images, you do not need to include the original MSIL assemblies in your apps.
+
+Common errors
+-------------
+
+The following are some of the command errors while creating or using native images:
+- "Could not load file or assembly 'mscorlib.dll' or one of its dependencies. The native image could not be loaded, because it was generated for use by a different version of the runtime. (Exception from HRESULT: 0x80131059)": This error indicates that there is a mismatch between CrossGen and mscorlib.ni.dll. Make sure to use CrossGen and mscorlib.ni.dll from the same build or NuGet package.
+- "Error: Could not load file or assembly '...' or one of its dependencies. The system cannot find the file specified. (Exception from HRESULT: 0x80070002)": CrossGen wasn't able to find a particular dependency that it needs. Verify that you have the assembly specified in the error message, and make sure its location is included in `/Platform_Assemblies_Paths`.
+- CoreCLR unable to initialize: While there are many possible causes of this error, one possibility is a mismatch between mscorlib.ni.dll and coreclr.dll (or libcoreclr.so). Make sure they come from the same build or NuGet package.
+- "Unable to load Jit Compiler": Please get a copy of `clrjit.dll` (or `libclrjit.so` or `libclrjit.dylib`, depending on your platform), and place it in the same directory as CrossGen. You can either build `clrjit.dll` yourself, or get it from `Microsoft.NETCore.Jit` NuGet package. To avoid possible issues, please use `clrjit.dll` from the same build as `crossgen.exe` if possible.
diff --git a/Documentation/building/debugging-instructions.md b/Documentation/building/debugging-instructions.md
new file mode 100644
index 0000000000..4c33f9af8a
--- /dev/null
+++ b/Documentation/building/debugging-instructions.md
@@ -0,0 +1,145 @@
+Debugging CoreCLR
+=================
+
+These instructions will lead you through debugging CoreCLR on Windows and Linux. They will be expanded to support OS X when we have good instructions for that.
+
+Debugging CoreCLR on Windows
+============================
+
+1. Perform a build of the repo.
+2. Open \<repo_root\>\bin\obj\Windows_NT.\<platform\>.\<configuration\>\CoreCLR.sln in VS. \<platform\> and \<configurtion\> are based
+    on type of build you did. By default they are 'x64' and 'Debug'.
+3. Right click the INSTALL project and choose ‘Set as StartUp Project’
+4. Bring up the properties page for the INSTALL project
+5. Select Configuration Properties->Debugging from the left side tree control
+6. Set Command=`$(SolutionDir)..\..\product\Windows_NT.$(Platform).$(Configuration)\corerun.exe`
+	1. This points to the folder where the built runtime binaries are present.
+7. Set Command Arguments=`<managed app you wish to run>` (e.g. HelloWorld.exe)
+8. Set Working Directory=`$(SolutionDir)..\..\product\Windows_NT.$(Platform).$(Configuration)`
+	1. This points to the folder containing CoreCLR binaries.
+9. Press F11 to start debugging at wmain in corerun (or set a breakpoint in source and press F5 to run to it)
+	1. As an example, set a breakpoint for the EEStartup function in ceemain.cpp to break into CoreCLR startup.
+
+Steps 1-8 only need to be done once, and then (9) can be repeated whenever you want to start debugging. The above can be done with Visual Studio 2013.
+
+Debugging CoreCLR on OS X
+==========================
+
+To use lldb on OS X, you first need to build it and the SOS plugin on the machine you intend to use it. See the instructions in [building lldb](buildinglldb.md). The rest of instructions on how to use lldb for Linux on are the same.
+
+Debugging CoreCLR on Linux
+==========================
+
+Only lldb is supported by the SOS plugin. gdb can be used to debug the coreclr code but with no SOS support. Visual Studio 2015 RTM remote debugging isn't currently supported.
+
+1. Perform a build of the coreclr repo.
+2. Install the corefx managed assemblies to the binaries directory.
+3. cd to build's binaries: `cd ~/coreclr/bin/Product/Linux.x64.Debug`
+4. Start lldb (the version the plugin was built with, currently 3.6): `lldb-3.6 corerun HelloWorld.exe linux`
+5. Now at the lldb command prompt, load SOS plugin: `plugin load libsosplugin.so`
+6. Launch program: `process launch -s`
+7. To stop annoying breaks on SIGUSR1/SIGUSR2 signals used by the runtime run: `process handle -s false SIGUSR1 SIGUSR2`
+8. Get to a point where coreclr is initialized by setting a breakpoint (i.e. `breakpoint set -n LoadLibraryExW` and then `process continue`) or stepping into the runtime.
+9. Run a SOS command like `sos ClrStack` or `sos VerifyHeap`.  The command name is case sensitive.
+
+You can combine steps 4-8 and pass everything on the lldb command line:
+
+`lldb-3.6 -o "plugin load libsosplugin.so" -o "process launch -s" -o "process handle -s false SIGUSR1 SIGUSR2" -o "breakpoint set -n LoadLibraryExW" corerun HelloWorld.exe linux`
+
+### SOS commands ###
+
+This is the full list of commands currently supported by SOS. LLDB is case-sensitive unlike windbg.
+
+	Type "soshelp <functionname>" for detailed info on that function.
+
+	Object Inspection                  Examining code and stacks
+	-----------------------------      -----------------------------
+	DumpObj (dumpobj)                  Threads (clrthreads)
+	DumpArray                          ThreadState
+	DumpStackObjects (dso)             IP2MD (ip2md)
+	DumpHeap (dumpheap)                u (clru)
+	DumpVC                             DumpStack (dumpstack)
+	GCRoot (gcroot)                    EEStack (eestack)
+	PrintException (pe)                ClrStack (clrstack)
+	                                   GCInfo
+	                                   EHInfo
+	                                   bpmd (bpmd)
+
+	Examining CLR data structures      Diagnostic Utilities
+	-----------------------------      -----------------------------
+	DumpDomain                         VerifyHeap
+	EEHeap (eeheap)                    FindAppDomain
+	Name2EE (name2ee)                  DumpLog (dumplog)
+	DumpMT (dumpmt)
+	DumpClass (dumpclass)
+	DumpMD (dumpmd)
+	Token2EE
+	DumpModule (dumpmodule)
+	DumpAssembly
+	DumpRuntimeTypes
+	DumpIL (dumpil)
+	DumpSig
+	DumpSigElem
+
+    Examining the GC history           Other
+    -----------------------------      -----------------------------
+    HistInit (histinit)                FAQ
+    HistRoot (histroot)                Help (soshelp)
+    HistObj  (histobj)
+    HistObjFind (histobjfind)
+    HistClear (histclear)
+
+###Aliases###
+
+By default you can reach all the SOS commands by using: _sos [command\_name]_
+However the common commands have been aliased so that you don't need the SOS prefix:
+
+    bpmd            -> sos bpmd
+    clrstack        -> sos ClrStack
+    clrthreads      -> sos Threads
+    clru            -> sos U
+    dso             -> sos DumpStackObjects
+    dumpclass       -> sos DumpClass
+    dumpheap        -> sos DumpHeap
+    dumpil          -> sos DumpIL
+    dumplog         -> sos DumpLog
+    dumpmd          -> sos DumpMD
+    dumpmodule      -> sos DumpModule
+    dumpmt          -> sos DumpMT
+    dumpobj         -> sos DumpObj
+    dumpstack       -> sos DumpStack     
+    eeheap          -> sos EEHeap
+    eestack         -> sos EEStack
+    gcroot          -> sos GCRoot
+    histinit        -> sos HistInit
+    histroot        -> sos HistRoot
+    histobj         -> sos HistObj
+    histobjfind     -> sos HistObjFind
+    histclear       -> sos HistClear
+    ip2md           -> sos IP2MD
+    name2ee         -> sos Name2EE
+    pe              -> sos PrintException
+    soshelp         -> sos Help
+
+
+### Problems and limitations of lldb and SOS ###
+
+Many of the SOS commands like clrstack or dso don't work on core dumps because lldb doesn't 
+return the actual OS thread id for a native thread. The "setsostid" command can be used to work
+around this lldb bug. Use the "clrthreads" to find the os tid and the lldb command "thread list"
+to find the thread index (#1 for example) for the current thread (* in first column). The first
+setsostid argument is the os tid and the second is the thread index: "setsosid ecd5 1".
+
+The "gcroot" command either crashes lldb 3.6 or returns invalid results. Works fine with lldb 3.7 and 3.8.
+
+Loading Linux core dumps with lldb 3.7 doesn't work. lldb 3.7 loads OS X and FreeBSD core dumps 
+just fine. lldb 3.8 loads all the platform's core dumps without problem.
+
+For more information on SOS commands see: https://msdn.microsoft.com/en-us/library/bb190764(v=vs.110).aspx
+
+Debugging Mscorlib and/or managed application
+=============================================
+
+To step into and debug managed code of Mscorlib.dll (or the managed application being executed by the runtime you built), using Visual Studio, is something that will be supported with Visual Studio 2015. We are actively working to enable this support. 
+
+Until then, you can use [WinDbg](https://msdn.microsoft.com/en-us/library/windows/hardware/ff551063(v=vs.85).aspx) and [SOS](https://msdn.microsoft.com/en-us/library/bb190764(v=vs.110).aspx) (an extension to WinDbg to support managed debugging) to step in and debug the generated managed code. This is what we do on the .NET Runtime team as well :)
diff --git a/Documentation/building/freebsd-instructions.md b/Documentation/building/freebsd-instructions.md
new file mode 100644
index 0000000000..c190ce7473
--- /dev/null
+++ b/Documentation/building/freebsd-instructions.md
@@ -0,0 +1,282 @@
+Build CoreCLR on FreeBSD
+======================
+
+This guide will walk you through building CoreCLR on FreeBSD and running Hello World.  We'll start by showing how to set up your environment from scratch.
+
+Environment
+===========
+
+These instructions are written assuming FreeBSD 10.1-RELEASE, since that's the release the team uses.
+
+These instructions assume you use the binary package tool `pkg` (analog to `apt-get` or `yum` on Linux) to install the environment. Compiling the dependencies from source using the ports tree might work too, but is untested.
+
+Minimum RAM required to build is 1GB. The build is known to fail on 512 MB VMs ([Issue 536](https://github.com/dotnet/coreclr/issues/536)).
+
+Toolchain Setup
+---------------
+
+Install the following packages for the toolchain: 
+
+- bash
+- cmake
+- llvm37 (includes LLVM 3.7, Clang 3.7 and LLDB 3.7)
+- libunwind
+- gettext
+- icu
+
+To install the packages you need:
+
+```sh
+janhenke@freebsd-frankfurt:~ % sudo pkg install bash cmake libunwind gettext llvm37 icu
+```
+
+The command above will install Clang and LLVM 3.7. For information on building CoreCLR with other versions, see section on [Clang/LLVM versions](#note-on-clangllvm-versions).
+
+Debugging CoreCLR (Optional)
+----------------------------
+
+Note: This step is not required to build CoreCLR itself. If you intend on hacking or debugging the CoreCLR source code, you need to follow these steps. You must follow these steps *before* starting the build itself.
+
+In order to debug CoreCLR you will also need to install [LLDB](http://lldb.llvm.org/), the LLVM debugger.
+
+To build with clang 3.7 from coreclr project root:
+
+```sh
+LLDB_LIB_DIR=/usr/local/llvm37/lib LLDB_INCLUDE_DIR=/usr/local/llvm37/include ./build.sh clang3.7 debug
+```
+
+Run tests:
+
+```sh
+./src/pal/tests/palsuite/runpaltests.sh $PWD/bin/obj/FreeBSD.x64.Debug $PWD/bin/paltestout
+```
+
+Git Setup
+---------
+
+This guide assumes that you've cloned the corefx and coreclr repositories into `~/git/corefx` and `~/git/coreclr` on your FreeBSD machine and the corefx and coreclr repositories into `D:\git\corefx` and `D:\git\coreclr` on Windows. If your setup is different, you'll need to pay careful attention to the commands you run. In this guide, I'll always show what directory I'm in on both the FreeBSD and Windows machine.
+
+Build the Runtime
+=================
+
+To build the runtime on FreeBSD, run build.sh from the root of the coreclr repository:
+
+```sh
+janhenke@freebsd-frankfurt:~/git/coreclr % ./build.sh
+```
+
+Note: FreeBSD 10.1-RELEASE system's Clang/LLVM is 3.4, the minimum version to compile CoreCLR runtime is 3.5. See [Note on Clang/LLVM versions](#note-on-clangllvm-versions).
+
+If the build fails with errors about resolving LLVM-components, the default Clang-version assumed (3.5) may not be appropriate for your system.
+Override it using the following syntax. In this example LLVM 3.6 is used:
+
+```sh
+janhenke@freebsd-frankfurt:~/git/coreclr % ./build.sh clang3.6
+```
+
+
+After the build is completed, there should some files placed in `bin/Product/FreeBSD.x64.Debug`.  The ones we are interested in are:
+
+* `corerun`: The command line host.  This program loads and starts the CoreCLR runtime and passes the managed program you want to run to it.
+* `libcoreclr.so`: The CoreCLR runtime itself.
+* `libcoreclrpal.so`: The platform abstraction library for the CoreCLR runtime. This library is temporary and the functionality will be merged back into `libcoreclr.so`
+
+In order to keep everything tidy, let's create a new directory for the runtime and copy the runtime and corerun into it.
+
+```sh
+janhenke@freebsd-frankfurt:~/git/coreclr % mkdir -p ~/coreclr-demo/runtime
+janhenke@freebsd-frankfurt:~/git/coreclr % cp bin/Product/FreeBSD.x64.Debug/corerun ~/coreclr-demo/runtime
+janhenke@freebsd-frankfurt:~/git/coreclr % cp bin/Product/FreeBSD.x64.Debug/libcoreclr*.so ~/coreclr-demo/runtime
+```
+
+Build the Framework Native Components
+======================================
+
+```sh
+janhenke@freebsd-frankfurt:~/git/corefx$ ./build-native.sh
+janhenke@freebsd-frankfurt:~/git/corefx$ cp bin/FreeBSD.x64.Debug/Native/*.so ~/coreclr-demo/runtime
+```
+
+Build the Framework Managed Components
+======================================
+
+We don't _yet_ have support for building managed code on FreeBSD, so you'll need a Windows machine with clones of both the CoreCLR and CoreFX projects.
+
+You will build `mscorlib.dll` out of the coreclr repository and the rest of the framework that out of the corefx repository.  For mscorlib (from a regular command prompt window) run:
+
+```
+D:\git\coreclr> build.cmd freebsdmscorlib
+```
+
+The output is placed in `bin\Product\FreeBSD.x64.Debug\mscorlib.dll`.  You'll want to copy this to the runtime folder on your FreeBSD machine. (e.g. `~/coreclr-demo/runtime`)
+
+For the rest of the framework, you need to pass some special parameters to build.cmd when building out of the CoreFX repository.
+
+```
+D:\git\corefx> build-managed.cmd -os=Linux -target-os=Linux -SkipTests
+```
+
+Note: We are using the Linux build currently, as CoreFX does not yet know about FreeBSD.
+
+It's also possible to add `/t:rebuild` to the build.cmd to force it to delete the previously built assemblies.
+
+For the purposes of Hello World, you need to copy over both `bin\Linux.AnyCPU.Debug\System.Console\System.Console.dll` and `bin\Linux.AnyCPU.Debug\System.Diagnostics.Debug\System.Diagnostics.Debug.dll`  into the runtime folder on FreeBSD. (e.g `~/coreclr-demo/runtime`).
+
+After you've done these steps, the runtime directory on FreeBSD should look like this:
+
+```
+janhenke@freebsd-frankfurt:~/git/coreclr % ls ~/coreclr-demo/runtime/
+System.Console.dll  System.Diagnostics.Debug.dll  corerun  libcoreclr.so  libcoreclrpal.so  mscorlib.dll
+```
+
+Download Dependencies
+=====================
+
+The rest of the assemblies you need to run are presently just facades that point to mscorlib.  We can pull these dependencies down via NuGet (which currently requires Mono).
+
+Create a folder for the packages:
+
+```sh
+janhenke@freebsd-frankfurt:~/git/coreclr % mkdir ~/coreclr-demo/packages
+janhenke@freebsd-frankfurt:~/git/coreclr % cd ~/coreclr-demo/packages
+```
+
+Install Mono
+------------
+
+If you don't already have Mono installed on your system, use the pkg tool again:
+
+```sh
+janhenke@freebsd-frankfurt:~/coreclr-demo/packages % sudo pkg install mono
+```
+
+Download the NuGet Client
+-------------------------
+
+Grab NuGet (if you don't have it already)
+
+```sh
+janhenke@freebsd-frankfurt:~/coreclr-demo/packages % curl -L -O https://nuget.org/nuget.exe
+```
+Download NuGet Packages
+-----------------------
+
+With Mono and NuGet in hand, you can use NuGet to get the required dependencies.
+
+Make a `packages.config` file with the following text. These are the required dependencies of this particular app. Different apps will have different dependencies and require a different `packages.config` - see [Issue #480](https://github.com/dotnet/coreclr/issues/480).
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<packages>
+  <package id="System.Console" version="4.0.0-beta-22703" />
+  <package id="System.Diagnostics.Contracts" version="4.0.0-beta-22703" />
+  <package id="System.Diagnostics.Debug" version="4.0.10-beta-22703" />
+  <package id="System.Diagnostics.Tools" version="4.0.0-beta-22703" />
+  <package id="System.Globalization" version="4.0.10-beta-22703" />
+  <package id="System.IO" version="4.0.10-beta-22703" />
+  <package id="System.IO.FileSystem.Primitives" version="4.0.0-beta-22703" />
+  <package id="System.Reflection" version="4.0.10-beta-22703" />
+  <package id="System.Resources.ResourceManager" version="4.0.0-beta-22703" />
+  <package id="System.Runtime" version="4.0.20-beta-22703" />
+  <package id="System.Runtime.Extensions" version="4.0.10-beta-22703" />
+  <package id="System.Runtime.Handles" version="4.0.0-beta-22703" />
+  <package id="System.Runtime.InteropServices" version="4.0.20-beta-22703" />
+  <package id="System.Text.Encoding" version="4.0.10-beta-22703" />
+  <package id="System.Text.Encoding.Extensions" version="4.0.10-beta-22703" />
+  <package id="System.Threading" version="4.0.10-beta-22703" />
+  <package id="System.Threading.Tasks" version="4.0.10-beta-22703" />
+</packages>
+
+```
+
+And restore your packages.config file:
+
+```sh
+janhenke@freebsd-frankfurt:~/coreclr-demo/packages % mono nuget.exe restore -Source https://www.myget.org/F/dotnet-corefx/ -PackagesDirectory .
+```
+
+NOTE: This assumes you already installed the default CA certs. If you have problems downloading the packages please see [Issue #602](https://github.com/dotnet/coreclr/issues/602#issuecomment-88203778). The command for FreeBSD is:
+
+```sh
+janhenke@freebsd-frankfurt:~/coreclr-demo/packages % mozroots --import --sync
+```
+
+Finally, you need to copy over the assemblies to the runtime folder.  You don't want to copy over System.Console.dll or System.Diagnostics.Debug however, since the version from NuGet is the Windows version.  The easiest way to do this is with a little find magic:
+
+```sh
+janhenke@freebsd-frankfurt:~/coreclr-demo/packages % find . -wholename '*/aspnetcore50/*.dll' -exec cp -n {} ~/coreclr-demo/runtime \;
+```
+
+Compile an App
+==============
+
+Now you need a Hello World application to run.  You can write your own, if you'd like.  Personally, I'm partial to the one on corefxlab which will draw Tux for us.
+
+```sh
+janhenke@freebsd-frankfurt:~/coreclr-demo/packages % cd ~/coreclr-demo/runtime
+janhenke@freebsd-frankfurt:~/coreclr-demo/runtime % curl -O https://raw.githubusercontent.com/dotnet/corefxlab/master/demos/CoreClrConsoleApplications/HelloWorld/HelloWorld.cs
+```
+
+Then you just need to build it, with `mcs`, the Mono C# compiler. FYI: The Roslyn C# compiler will soon be available on FreeBSD.  Because you need to compile the app against the .NET Core surface area, you need to pass references to the contract assemblies you restored using NuGet:
+
+```sh
+janhenke@freebsd-frankfurt:~/coreclr-demo/runtime % mcs /nostdlib /noconfig /r:../packages/System.Console.4.0.0-beta-22703/lib/contract/System.Console.dll /r:../packages/System.Runtime.4.0.20-beta-22703/lib/contract/System.Runtime.dll HelloWorld.cs
+```
+
+Run your App
+============
+
+You're ready to run Hello World!  To do that, run corerun, passing the path to the managed exe, plus any arguments.  The HelloWorld from corefxlab will print a daemon if you pass "freebsd" as an argument, so:
+
+```sh
+janhenke@freebsd-frankfurt:~/coreclr-demo/runtime % ./corerun HelloWorld.exe freebsd
+```
+
+If all works, you should be greeted by a friendly daemon you know well.
+
+Over time, this process will get easier. We will remove the dependency on having to compile managed code on Windows. For example, we are working to get our NuGet packages to include both the Windows and FreeBSD versions of an assembly, so you can simply nuget restore the dependencies. 
+
+Pull Requests to enable building CoreFX and mscorlib on FreeBSD via Mono would be very welcome. A sample that builds Hello World on FreeBSD using the correct references but via XBuild or MonoDevelop would also be great! Some of our processes (e.g. the mscorlib build) rely on Windows specific tools, but we want to figure out how to solve these problems for FreeBSD as well. There's still a lot of work ahead, so if you're interested in helping, we're ready for you!
+
+
+Run the test suite
+==================
+
+If you've made changes to the CoreCLR PAL code, you might want to run the PAL tests directly to validate your changes.
+This can be done after a clean build, without any other dependencies.
+
+From the coreclr project directory:
+
+```sh
+janhenke@freebsd-frankfurt:~/coreclr % ./src/pal/tests/palsuite/runpaltests.sh  ~/coreclr/bin/obj/FreeBSD.x64.Debug ~/coreclr/bin/paltestout
+```
+
+This should run all the tests associated with the PAL.
+
+Note on Clang/LLVM versions
+===========================
+
+The minimum version to build CoreCLR is Clang 3.5 or above.
+
+FreeBSD 10.X releases ship with Clang 3.4.
+
+If you intend on building CoreCLR with LLDB debug support, pick llvm37 or llvm-devel.
+
+To install clang 3.5: `sudo pkg install clang35`
+
+To install clang 3.6: `sudo pkg install clang36`
+
+To install clang 3.7: `sudo pkg install llvm37`
+
+To install clang development snapshot: `sudo pkg install llvm-devel`
+
+clang35 and clang36 download llvm35 and llvm36 packages as a dependency. 
+
+llvm37 and llvm-devel include clang and lldb. Since clang is included with llvm 3.7 and onward, there is no clang37 package.
+
+After you have installed your desired version of LLVM you will need to specify the version to the build.sh script.
+
+For example if you chose to install llvm37 you would add the clangX.X to your build command as follows.
+```sh
+janhenke@freebsd-frankfurt:~/git/coreclr % ./build.sh clang3.7
+```
diff --git a/Documentation/building/linux-instructions.md b/Documentation/building/linux-instructions.md
new file mode 100644
index 0000000000..c948ecde20
--- /dev/null
+++ b/Documentation/building/linux-instructions.md
@@ -0,0 +1,220 @@
+Build CoreCLR on Linux
+======================
+
+This guide will walk you through building CoreCLR on Linux.  We'll start by showing how to set up your environment from scratch.
+
+Environment
+===========
+
+These instructions are written assuming the Ubuntu 14.04 LTS, since that's the distro the team uses. Pull Requests are welcome to address other environments as long as they don't break the ability to use Ubuntu 14.04 LTS.
+
+There have been reports of issues when using other distros or versions of Ubuntu (e.g. [Issue 95](https://github.com/dotnet/coreclr/issues/95)). If you're on another distribution, consider using docker's `ubuntu:14.04` image.
+
+Minimum RAM required to build is 1GB. The build is known to fail on 512 MB VMs ([Issue 536](https://github.com/dotnet/coreclr/issues/536)).
+
+Toolchain Setup
+---------------
+
+Install the following packages for the toolchain: 
+
+- cmake 
+- llvm-3.5 
+- clang-3.5 
+- lldb-3.6
+- lldb-3.6-dev 
+- libunwind8 
+- libunwind8-dev
+- gettext
+- libicu-dev
+- liblttng-ust-dev
+- libcurl4-openssl-dev
+- libssl-dev
+- uuid-dev
+
+In order to get lldb-3.6 on Ubuntu 14.04, we need to add an additional package source:
+
+```
+ellismg@linux:~$ echo "deb http://llvm.org/apt/trusty/ llvm-toolchain-trusty-3.6 main" | sudo tee /etc/apt/sources.list.d/llvm.list
+ellismg@linux:~$ wget -O - http://llvm.org/apt/llvm-snapshot.gpg.key | sudo apt-key add -
+ellismg@linux:~$ sudo apt-get update
+```
+
+Then install the packages you need:
+
+```
+ellismg@linux:~$ sudo apt-get install cmake llvm-3.5 clang-3.5 lldb-3.6 lldb-3.6-dev libunwind8 libunwind8-dev gettext libicu-dev liblttng-ust-dev libcurl4-openssl-dev libssl-dev uuid-dev
+```
+
+You now have all the required components.
+
+Git Setup
+---------
+
+This guide assumes that you've cloned the corefx and coreclr repositories into `~/git/corefx` and `~/git/coreclr` on your Linux machine. If your setup is different, you'll need to pay careful attention to the commands you run. In this guide, I'll always show what directory I'm in.
+
+Set the maximum number of file-handles
+--------------------------------------
+
+To ensure that your system can allocate enough file-handles for the corefx build run `sysctl fs.file-max`. If it is less than 100000, add `fs.file-max = 100000` to `/etc/sysctl.conf`, and then run `sudo sysctl -p`.
+
+Build the Runtime and Microsoft Core Library
+=============================================
+
+To build the runtime on Linux, run build.sh from the root of the coreclr repository:
+
+```
+ellismg@linux:~/git/coreclr$ ./build.sh
+```
+
+After the build is completed, there should some files placed in `bin/Product/Linux.x64.Debug`.  The ones we are interested in are:
+
+* `corerun`: The command line host.  This program loads and starts the CoreCLR runtime and passes the managed program you want to run to it.
+* `libcoreclr.so`: The CoreCLR runtime itself.
+* `mscorlib.dll`: Microsoft Core Library.
+
+Build the Framework
+===================
+
+```
+ellismg@linux:~/git/corefx$ ./build.sh
+```
+
+After the build is complete you will be able to find the output in the `bin` folder.
+
+Build for ARM/Linux
+===================
+
+Libunwind-arm requires fixes that are not included in Ubuntu 14.04, yet. The fix allows libunwind-arm not to break when it is ordered to access unaccessible memory locations.
+
+First, import the patch from the libunwind upstream: http://git.savannah.gnu.org/gitweb/?p=libunwind.git;a=commit;h=770152268807e460184b4152e23aba9c86601090
+
+Then, expand the coverage of the upstream patch by:
+
+```
+diff --git a/src/arm/Ginit.c b/src/arm/Ginit.c
+index 1ed3dbf..c643032 100644
+--- a/src/arm/Ginit.c
++++ b/src/arm/Ginit.c
+@@ -128,6 +128,11 @@ access_mem (unw_addr_space_t as, unw_word_t addr, unw_word_t *val, int write,
+ {
+   if (write)
+     {
++      /* validate address */
++      const struct cursor *c = (const struct cursor *) arg;
++      if (c && validate_mem(addr))
++        return -1;
++
+       Debug (16, "mem[%x] <- %x\n", addr, *val);
+       *(unw_word_t *) addr = *val;
+     }
+```
+
+How to enable -O3 optimization level for ARM/Linux
+==================================================
+
+Currently, we can build coreclr with -O1 flag of clang in release build mode for Linux/ARM without any bugfix of llvm-3.6. This instruction is to enable -O3 optimization level of clang on Linux/ARM by fixing the bug of llvm.
+
+First, download latest version from the clang-3.6/llvm-3.6 upstream: 
+```
+lgs@ubuntu cd /work/dotnet/
+lgs@ubuntu wget http://llvm.org/releases/3.6.2/llvm-3.6.2.src.tar.xz
+lgs@ubuntu tar xJf llvm-3.6.2.src.tar.xz
+lgs@ubuntu cd ./llvm-3.6.2.src/tools/
+lgs@ubuntu wget http://llvm.org/releases/3.6.2/cfe-3.6.2.src.tar.xz
+lgs@ubuntu tar xJf cfe-3.6.2.src.tar.xz
+lgs@ubuntu mv cfe-3.6.2.src clang
+```
+
+Second, expand the coverage of the upstream patch by:
+https://bugs.launchpad.net/ubuntu/+source/llvm-defaults/+bug/1584089
+
+Third, build clang-3.6/llvm-3.6 source as following: 
+```
+lgs@ubuntu cmake -DCMAKE_BUILD_TYPE=Release -DLLVM_TARGETS_TO_BUILD="all" -DCMAKE_INSTALL_PREFIX=~/llvm-3.6.2 \
+-DLLVM_BUILD_LLVM_DYLIB=1 -DLLDB_DISABLE_LIBEDIT=1 -DLLDB_DISABLE_CURSES=1 -DLLDB_DISABLE_PYTHON=1 \
+-DLLVM_ENABLE_DOXYGEN=0 -DLLVM_ENABLE_TERMINFO=0 -DLLVM_INCLUDE_EXAMPLES=0 -DLLVM_BUILD_RUNTIME=0 \
+-DLLVM_INCLUDE_TESTS=0 -DPYTHON_INCLUDE_DIR=/usr/include/python2.7 /work/dotnet/llvm-3.6.2.src
+lgs@ubuntu  
+lgs@ubuntu sudo ln -sf /usr/bin/ld /usr/bin/ld.gold
+lgs@ubuntu time make -j8
+lgs@ubuntu time make -j8 install 
+lgs@ubuntu
+lgs@ubuntu sudo apt-get remove clang-3.6 llvm-3.6
+lgs@ubuntu  vi ~/.bashrc (or /etc/profile)
+# Setting new clang/llvm version
+export PATH=$HOME/llvm-3.6.2/bin/:$PATH
+export LD_LIBRARY_PATH=$HOME/llvm-3.6.2/lib:$LD_LIBRARY_PATH
+```
+
+For Ubuntu 14.04 X64 users, they can easily install the fixed clang/llvm3.6 package with "apt-get" command from the "ppa:leemgs/dotnet" Ubuntu repository, without the need to execute the above 1st, 2nd, and 3rd step.
+```
+lgs@ubuntu sudo add-apt-repository ppa:leemgs/dotnet
+lgs@ubuntu sudo apt-get update
+lgs@ubuntu sudo apt-get install clang-3.6 llvm-3.6 lldb-3.6
+```
+
+Finally, let's build coreclr with updated clang/llvm. If you meet a lldb related error message at build-time, try to build coreclr with "skipgenerateversion" option. 
+```
+lgs@ubuntu time ROOTFS_DIR=/work/dotnet/rootfs-coreclr/arm ./build.sh arm release clean cross 
+```
+
+Additional optimization levels for ARM/Linux: -Oz and -Ofast
+============================================================
+
+This instruction is to enable additional optimization levels such as -Oz and -Ofast on ARM/Linux. The below table shows what we have to enable for the code optimization of the CoreCLR run-time either the size or speed on embedded devices. 
+
+| **Content** | **Build Mode** | **Clang/LLVM (Linux)** |
+| --- | --- | --- |
+| -O0 | Debug | Disable optimization to generate the most debuggable code |
+| -O1 | - | Optimize for code size and execution time |
+| -O2 | Checked | Optimize more for code size and execution time |
+| -O3 | Release | Optimize more for code size and execution time to make program run faster |
+| -Oz | - | Optimize more to reduce code size further |
+| -Ofast | - | Enable all the optimizations from O3 along with other aggressive optimizations |
+
+If you want to focus on the size reduction for low-end devices, you have to modify clang-compile-override.txt to enable -Oz flag in the release build as following: 
+
+```
+--- a/src/pal/tools/clang-compiler-override.txt
++++ b/src/pal/tools/clang-compiler-override.txt
+@@ -3,13 +3,13 @@ SET (CMAKE_C_FLAGS_DEBUG_INIT          "-g -O0")
+ SET (CLR_C_FLAGS_CHECKED_INIT          "-g -O2")
+ # Refer to the below instruction to support __thread with -O2/-O3 on Linux/ARM
+ # https://github.com/dotnet/coreclr/blob/master/Documentation/building/linux-instructions.md
+-SET (CMAKE_C_FLAGS_RELEASE_INIT        "-g -O3")
++SET (CMAKE_C_FLAGS_RELEASE_INIT        "-g -Oz")
+ SET (CMAKE_C_FLAGS_RELWITHDEBINFO_INIT "-g -O2")
+
+ SET (CMAKE_CXX_FLAGS_INIT                "-Wall -Wno-null-conversion -std=c++11")
+ SET (CMAKE_CXX_FLAGS_DEBUG_INIT          "-g -O0")
+ SET (CLR_CXX_FLAGS_CHECKED_INIT          "-g -O2")
+-SET (CMAKE_CXX_FLAGS_RELEASE_INIT        "-g -O3")
++SET (CMAKE_CXX_FLAGS_RELEASE_INIT        "-g -Oz")
+ SET (CMAKE_CXX_FLAGS_RELWITHDEBINFO_INIT "-g -O2")
+
+ SET (CLR_DEFINES_DEBUG_INIT              DEBUG _DEBUG _DBG URTBLDENV_FRIENDLY=Checked BUILDENV_
+```
+
+
+If you want to focus on the speed optimization for high-end devices, you have to modify clang-compile-override.txt to enable -Ofast flag in the release build as following: 
+```
+--- a/src/pal/tools/clang-compiler-override.txt
++++ b/src/pal/tools/clang-compiler-override.txt
+@@ -3,13 +3,13 @@ SET (CMAKE_C_FLAGS_DEBUG_INIT          "-g -O0")
+ SET (CLR_C_FLAGS_CHECKED_INIT          "-g -O2")
+ # Refer to the below instruction to support __thread with -O2/-O3 on Linux/ARM
+ # https://github.com/dotnet/coreclr/blob/master/Documentation/building/linux-instructions.md
+-SET (CMAKE_C_FLAGS_RELEASE_INIT        "-g -O3")
++SET (CMAKE_C_FLAGS_RELEASE_INIT        "-g -Ofast")
+ SET (CMAKE_C_FLAGS_RELWITHDEBINFO_INIT "-g -O2")
+
+ SET (CMAKE_CXX_FLAGS_INIT                "-Wall -Wno-null-conversion -std=c++11")
+ SET (CMAKE_CXX_FLAGS_DEBUG_INIT          "-g -O0")
+ SET (CLR_CXX_FLAGS_CHECKED_INIT          "-g -O2")
+-SET (CMAKE_CXX_FLAGS_RELEASE_INIT        "-g -O3")
++SET (CMAKE_CXX_FLAGS_RELEASE_INIT        "-g -Ofast")
+ SET (CMAKE_CXX_FLAGS_RELWITHDEBINFO_INIT "-g -O2")
+
+ SET (CLR_DEFINES_DEBUG_INIT              DEBUG _DEBUG _DBG URTBLDENV_FRIENDLY=Checked BUILDENV_
+```
+
diff --git a/Documentation/building/netbsd-instructions.md b/Documentation/building/netbsd-instructions.md
new file mode 100644
index 0000000000..f678286122
--- /dev/null
+++ b/Documentation/building/netbsd-instructions.md
@@ -0,0 +1,129 @@
+Build CoreCLR on NetBSD
+=======================
+
+This guide will walk you through building CoreCLR on NetBSD.  We'll start by showing how to set up your environment from scratch.
+
+Environment
+===========
+
+These instructions are written on NetBSD 7.x on the amd64 platform, since that's the release the team uses.
+
+Older releases aren't supported because building CoreCLR requires the modern LLVM stack (Clang, libunwind, and LLDB) that is developed against the NetBSD-7.x branch.
+
+Pull Requests are welcome to address other ports (like i386 or evbarm) as long as they don't break the ability to use NetBSD/amd64.
+
+Minimum RAM required to build is 1GB.
+
+The pkgsrc framework is required to build .NET projects on NetBSD. Minimal pkgsrc version required is 2016Q1.
+
+pkgsrc setup
+------------
+
+Fetch pkgsrc and install to the system. By default it's done in the /usr directory as root:
+
+```
+ftp -o- ftp://ftp.netbsd.org/pub/pkgsrc/stable/pkgsrc.tar.gz | tar -zxpf- -C /usr
+```
+
+The .NET projects are tracked in pkgsrc-wip.
+
+In order to use pkgsrc-wip, git must be installed:
+
+
+```
+cd /usr/pkgsrc/devel/git-base && make install
+```
+
+To access resources over SSL link, mozilla-rootcerts must be installed:
+
+```
+cd /usr/pkgsrc/security/mozilla-rootcerts && make install
+```
+
+And follow the MESSAGE commands to finish the installation.
+
+
+Installing pkgsrc-wip
+---------------------
+
+Type the following command to fetch the pkgsrc-wip sources:
+
+
+```
+cd /usr/pkgsrc
+git clone --depth 1 git://wip.pkgsrc.org/pkgsrc-wip.git wip
+```
+
+Then install the CoreCLR package you need:
+
+```
+cd /usr/pkgsrc/wip/coreclr-git
+make install
+```
+
+CoreCLR is installed in `/usr/pkg/CoreCLR` subdirectory by default.
+
+
+PAL tests
+=========
+
+To run PAL tests on NetBSD, use the `make test` in the coreclr-git package from pkgsrc-wip:
+
+```
+cd /usr/pkgsrc/wip/coreclr-git
+make test
+```
+
+Build CoreFX
+============
+
+The CoreFX package is located in pkgsrc-wip as corefx-git. In order to build it you need to perform the following command:
+
+```
+cd /usr/pkgsrc/wip/corefx-git
+make
+```
+
+At the moment there is no install or test target in the pkgsrc framework.
+
+CoreFX tests
+============
+
+The steps to run CoreFX managed code tests:
+
+Build CoreCLR (with pkgsrc-wip/coreclr-git) on NetBSD x64, Debug and install the Product dir to /usr/pkg/CoreCLR:
+
+```
+cd /usr/pkgsrc/wip/coreclr-git && make install
+```
+
+Build CoreFX native x64 Debug and the work (build) dir is in /usr/pkgsrc/wip/corefx-git/work/corefx:
+
+```
+cd /usr/pkgsrc/wip/corefx-git && make
+```
+
+Build CoreCLR Debug x64 on Linux and copy mscorlib.dll from ./bin/Product/Linux.x64.Debug/mscorlib.dll to NetBSD machine under /usr/pkg/CoreCLR:
+
+```
+./build.sh mscorlib Debug
+```
+
+Build CoreFX Debug x64 on Linux and copy bin/ to NetBSD machine under /public/bin:
+
+```
+./build-native.sh -os=NetBSD
+./build-managed.sh NetBSD -SkipTests
+```
+
+Run ./run-test.sh:
+
+```
+$ pwd
+/usr/pkgsrc/wip/corefx-git/work/corefx
+$ ./run-test.sh \
+--coreclr-bins /usr/pkg/CoreCLR/ \
+--mscorlib-bins /usr/pkg/CoreCLR/ \
+--corefx-tests /public/bin/tests/NetBSD.AnyCPU.Debug/ \
+--corefx-native-bins ./bin/NetBSD.x64.Debug/Native/
+```
diff --git a/Documentation/building/osx-instructions.md b/Documentation/building/osx-instructions.md
new file mode 100644
index 0000000000..6d3469b2d9
--- /dev/null
+++ b/Documentation/building/osx-instructions.md
@@ -0,0 +1,80 @@
+Build CoreCLR on OS X
+=====================
+
+This guide will walk you through building CoreCLR on OS X. We'll start by showing how to set up your environment from scratch.
+
+Environment
+===========
+
+These instructions were validated on OS X Yosemite, although they probably work on earlier versions. Pull Requests are welcome to address other environments.
+
+If your machine has Command Line Tools for XCode 6.3 installed, you'll need to update them to the 6.3.1 version or higher in order to successfully build. There was an issue with the headers that shipped with version 6.3 that was subsequently fixed in 6.3.1.
+
+Git Setup
+---------
+
+Clone the CoreCLR and CoreFX repositories (either upstream or a fork).
+
+```sh
+dotnet-mbp:git richlander$ git clone https://github.com/dotnet/coreclr
+# Cloning into 'coreclr'...
+
+dotnet-mbp:git richlander$ git clone https://github.com/dotnet/corefx
+# Cloning into 'corefx'...
+```
+
+This guide assumes that you've cloned the coreclr and corefx repositories into `~/git/coreclr` and `~/git/corefx` on your OS X machine. If your setup is different, you'll need to pay careful attention to the commands you run. In this guide, I'll always show what directory I'm in.
+
+CMake
+-----
+
+CoreCLR has a dependency on CMake for the build. You can download it from [CMake downloads](http://www.cmake.org/download/).
+
+Alternatively, you can install CMake from [Homebrew](http://brew.sh/).
+
+```sh
+dotnet-mbp:~ richlander$ brew install cmake
+```
+
+ICU
+---
+ICU (International Components for Unicode) is also required to build and run. It can be obtained via [Homebrew](http://brew.sh/).
+
+```sh
+brew install icu4c
+brew link --force icu4c
+```
+
+OpenSSL
+-------
+The CoreFX cryptography libraries are built on OpenSSL. The version of OpenSSL included on OS X (0.9.8) has gone out of support, and a newer version is required. A supported version can be obtained via [Homebrew](http://brew.sh).
+
+```sh
+brew install openssl
+brew link --force openssl
+```
+
+Build the Runtime and Microsoft Core Library
+============================================
+
+To Build CoreCLR, run build.sh from the root of the coreclr repo.
+
+```sh
+dotnet-mbp:~ richlander$ cd ~/git/coreclr
+dotnet-mbp:coreclr richlander$ ./build.sh
+```
+
+After the build is completed, there should some files placed in `bin/Product/OSX.x64.Debug`. The ones we are interested in are:
+
+- `corerun`: The command line host. This program loads and starts the CoreCLR runtime and passes the managed program you want to run to it.
+- `libcoreclr.dylib`: The CoreCLR runtime itself.
+- `mscorlib.dll`: Microsoft Core Library.
+
+Build the Framework
+===================
+
+```sh
+dotnet-mbp:corefx richlander$ ./build.sh
+```
+
+After the build is complete you will be able to find the output in the `bin` folder.
diff --git a/Documentation/building/test-configuration.md b/Documentation/building/test-configuration.md
new file mode 100644
index 0000000000..931a540adb
--- /dev/null
+++ b/Documentation/building/test-configuration.md
@@ -0,0 +1,41 @@
+## General Test Infrastructure Notes ##
+
+### Kinds of Build Properties ###
+* Build Only
+> `<CLRTestKind>BuildOnly</CLRTestKind>`
+
+ * Builds an executable. 
+ * Will not execute it. 
+
+* Run Only
+> `<CLRTestKind>RunOnly</CLRTestKind>`
+
+ * Can use Ouput of Build and Run Project with different command line arguments. 
+* Build and Run
+> `<CLRTestKind>BuildAndRun</CLRTestKind>`
+
+ * Builds an executable.
+ * Will execute said executable. 
+* Shared Libraries
+> `<CLRTestKind>SharedLibrary</CLRTestKind>`
+
+ * For building libraries common to zero or more tests. 
+
+
+By default (i.e. if not specified explicitly) a project file is BuildAndRun.
+
+### Priority ###
+Testcases are categorized by their priority levels. The most important subset should be and is the smallest subset. This subset is called priority 0.
+ * By default, a testcase is priority 0. You must elect to de-prioritize a test.
+  * To de-prioritize a test, add a property _CLRTestPriority_ to the test's project file.
+> `<CLRTestPriority>2</CLRTestPriority>`
+ * Lower priority values are always run in conjunction when running higher priority value tests. I.e. if a developer elects to do a priority 2 test run, then all priority 0, 1 and 2 tests are run.
+
+### Adding Tests ###
+#### Converting an existing C# project ####
+  * Remove AssemblyName
+  * Swap in dir.props
+  * Swap in dir.targets
+  * Assign a CLRTestKind
+  * (optional) Assign a priority value
+
diff --git a/Documentation/building/testing-with-corefx.md b/Documentation/building/testing-with-corefx.md
new file mode 100644
index 0000000000..6609a0aaa7
--- /dev/null
+++ b/Documentation/building/testing-with-corefx.md
@@ -0,0 +1,16 @@
+Testing with CoreFX
+===================
+
+It may be valuable to use CoreFX tests to validate your changes to CoreCLR or mscorlib.
+
+**Windows**
+
+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.
+
+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.
+
+**FreeBSD, Linux, NetBSD, OS X**
+
+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
new file mode 100644
index 0000000000..9cf7507443
--- /dev/null
+++ b/Documentation/building/unix-test-instructions.md
@@ -0,0 +1,81 @@
+Building and running tests on Linux, OS X, and FreeBSD
+======================================================
+
+CoreCLR tests
+-------------
+
+**Building**
+
+Build CoreCLR and CoreFX. Refer to building instructions in the respective repository.
+
+To build only the tests, on the Windows machine:
+
+> `C:\coreclr>build-test.cmd -rebuild`
+
+**Running tests**
+
+The following instructions assume that on the Unix machine:
+- The CoreCLR repo is cloned at `~/coreclr`
+- The CoreFX repo is cloned at `~/corefx`
+- The Windows clone of the CoreCLR repo is mounted at `/media/coreclr`
+- The Windows clone of the CoreFX repo is mounted at `/media/corefx`
+
+Tests currently need to be built on Windows and copied over to the Unix machine for testing. Copy the test build over to the Unix machine:
+
+> `cp --recursive /media/coreclr/bin/tests/Windows_NT.x64.Debug ~/test/`
+
+See runtest.sh usage information:
+
+> `~/coreclr$ tests/runtest.sh --help`
+
+Run tests (`Debug` may be replaced with `Release` or `Checked`, depending on which Configuration you've built):
+
+> ```bash
+> ~/coreclr$ tests/runtest.sh
+>     --testRootDir=~/test/Windows_NT.x64.Debug
+>     --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
+> ```
+
+The method above will copy dependencies from the set of directories provided to create an 'overlay' directory.
+If you already have an overlay directory prepared with the dependencies you need, you can specify `--coreOverlayDir`
+instead of `--coreClrBinDir`, `--mscorlibDir`, `--coreFxBinDir`, and `--coreFxNativeBinDir`. It would look something like:
+
+
+> ```bash
+> ~/coreclr$ tests/runtest.sh
+>     --testRootDir=~/test/Windows_NT.x64.Debug
+>     --testNativeBinDir=~/coreclr/bin/obj/Linux.x64.Debug/tests
+>     --coreOverlayDir=/path/to/directory/containing/overlay
+> ```
+
+
+Test results will go into:
+
+> `~/test/Windows_NT.x64.Debug/coreclrtests.xml`
+
+**Unsupported and temporarily disabled tests**
+
+These tests are skipped by default:
+- Tests that are not supported outside Windows, are listed in:
+>> `~/coreclr/tests/testsUnsupportedOutsideWindows.txt`
+- Tests that are temporarily disabled outside Windows due to unexpected failures (pending investigation), are listed in:
+>> `~/coreclr/tests/testsFailingOutsideWindows.txt`
+
+To run only the set of temporarily disabled tests, pass in the `--runFailingTestsOnly` argument to `runtest.sh`.
+
+PAL tests
+---------
+
+Build CoreCLR on the Unix machine.
+
+Run tests:
+
+> `~/coreclr$ src/pal/tests/palsuite/runpaltests.sh ~/coreclr/bin/obj/Linux.x64.Debug`
+
+Test results will go into:
+
+> `/tmp/PalTestOutput/default/pal_tests.xml`
diff --git a/Documentation/building/viewing-jit-dumps.md b/Documentation/building/viewing-jit-dumps.md
new file mode 100644
index 0000000000..5303b47626
--- /dev/null
+++ b/Documentation/building/viewing-jit-dumps.md
@@ -0,0 +1,173 @@
+# Viewing JIT Dumps
+
+This document is intended for people interested in seeing the disassembly, GC info, or other details the JIT generates for a managed program.
+
+To make sense of the results, it is recommended you also read the [Reading a JitDump](../botr/ryujit-overview.md#reading-a-jitdump) section of the RyuJIT Overview.
+
+## Setting up our environment
+
+The first thing we want to do is setup the .NET Core app we want to dump. Here are the steps to do this, if you don't have one ready:
+
+* Perform a debug build of the CoreCLR repo
+* Install the [.NET CLI](http://microsoft.com/net/core), which we'll use to compile/publish our app
+* `cd` to where you want your app to be placed, and run `dotnet new`
+* Modify your `project.json` file so that it contains a RID (runtime ID) corresponding to the OS you're using in the `runtimes` section. For example, I have a Windows 10 x64 machine, so here's my project file:
+
+```json
+{
+  "buildOptions": {
+    "emitEntryPoint": true
+  },
+  "dependencies": {
+    "Microsoft.NETCore.App": "1.0.0-*"
+  },
+  "frameworks": {
+    "netcoreapp1.0": {
+      "imports": [
+        "dnxcore50",
+        "portable-net45+win8"
+      ]
+    }
+  },
+  "runtimes": {
+    "win10-x64": {}
+  }
+}
+```
+
+You can find a list of RIDs and their corresponding OSes [here](http://dotnet.github.io/docs/core-concepts/rid-catalog.html).
+
+* Edit `Program.cs`, and call the method(s) you want to dump in there. Make sure they are, directly or indirectly, called from `Main`. In this example, we'll be looking at the disassembly of our custom function `InefficientJoin`:
+
+```cs
+using System;
+using System.Collections.Generic;
+using System.Runtime.CompilerServices;
+
+namespace ConsoleApplication
+{
+    public class Program
+    {
+        public static void Main(string[] args)
+        {
+            Console.WriteLine(InefficientJoin(args));
+        }
+        
+        // Add NoInlining to prevent this from getting
+        // mixed up with the rest of the code in Main
+        [MethodImpl(MethodImplOptions.NoInlining)]
+        private static string InefficientJoin(IEnumerable<string> args)
+        {
+            var result = string.Empty;
+            foreach (var arg in args) result += (arg + ' ');
+            return result.Substring(0, result.Length - 1);
+        }
+    }
+}
+```
+
+* After you've finished editing the code, run `dotnet publish -c Release`. This should drop all of the binaries needed to run your app in `bin/Release/<configuration>/<rid>/publish`.
+* Overwrite the CLR dlls with the ones you've built locally. If you're a fan of the command line, here are some shell commands for doing this:
+
+```shell
+# Windows
+robocopy /e <coreclr path>\bin\Product\Windows_NT.<arch>.Debug <app root>\bin\Release\netcoreapp1.0\<rid>\publish > NUL
+
+# Unix
+cp -rT <coreclr path>/bin/Product/<OS>.<arch>.Debug <app root>/bin/Release/netcoreapp1.0/<rid>/publish
+```
+
+* Set the configuration knobs you need (see below) and run your published app. The info you want should be dumped to stdout.
+
+Here's some sample output on my machine showing the disassembly for `InefficientJoin`:
+
+```asm
+G_M2530_IG01:
+       55                   push     rbp
+       4883EC40             sub      rsp, 64
+       488D6C2440           lea      rbp, [rsp+40H]
+       33C0                 xor      rax, rax
+       488945F8             mov      qword ptr [rbp-08H], rax
+       488965E0             mov      qword ptr [rbp-20H], rsp
+
+G_M2530_IG02:
+       49BB60306927E5010000 mov      r11, 0x1E527693060
+       4D8B1B               mov      r11, gword ptr [r11]
+       4C895DF8             mov      gword ptr [rbp-08H], r11
+       49BB200058F7FD7F0000 mov      r11, 0x7FFDF7580020
+       3909                 cmp      dword ptr [rcx], ecx
+       41FF13               call     gword ptr [r11]System.Collections.Generic.IEnumerable`1[__Canon][System.__Canon]:GetEnumerator():ref:this
+       488945F0             mov      gword ptr [rbp-10H], rax
+
+; ...
+```
+
+## Setting configuration variables
+
+The behavior of the JIT can be controlled via a number of configuration variables. These are declared in [inc/clrconfigvalues.h](https://github.com/dotnet/coreclr/blob/master/src/inc/clrconfigvalues.h). When used as an environment variable, the string name generally has “COMPlus_” prepended. When used as a registry value name, the configuration name is used directly.
+
+These can be set in one of three ways:
+
+* Setting the environment variable `COMPlus_<flagname>`. For example, the following will set the `JitDump` flag so that the compilation of all methods named ‘Main’ will be dumped:
+
+```shell
+# Windows
+set COMPlus_JitDump=Main
+
+# Unix
+export COMPlus_JitDump=Main
+```
+
+* *Windows-only:* Setting the registry key `HKCU\Software\Microsoft\.NETFramework`, Value `<flagName>`, type `REG_SZ` or `REG_DWORD` (depending on the flag).
+* *Windows-only:* Setting the registry key `HKLM\Software\Microsoft\.NETFramework`, Value `<flagName>`, type `REG_SZ` or `REG_DWORD` (depending on the flag).
+
+## Specifying method names
+
+The complete syntax for specifying a single method name (for a flag that takes a method name, such as `COMPlus_JitDump`) is:
+
+```
+[[<Namespace>.]<ClassName>::]<MethodName>[([<types>)]
+```
+
+For example
+
+```
+System.Object::ToString(System.Object)
+```
+
+The namespace, class name, and argument types are optional, and if they are not present, default to a wildcard. Thus stating:
+
+```
+Main
+```
+
+will match all methods named Main from any class and any number of arguments.
+
+<types> is a comma separated list of type names. Note that presently only the number of arguments and not the types themselves are used to distinguish methods. Thus, `Main(Foo, Bar)` and `Main(int, int)` will both match any main method with two arguments.
+
+The wildcard character ‘*’ can be used for <ClassName> and <MethodName>. In particular * by itself indicates every method.
+
+## Useful COMPlus variables
+
+Below are some of the most useful `COMPlus` variables. Where {method-list} is specified in the list below, you can supply a space-separated list of either fully-qualified or simple method names (the former is useful when running something that has many methods of the same name), or you can specific ‘*’ to mean all methods.
+
+* `COMPlus_JitDump`={method-list} – dump lots of useful information about what the JIT is doing. See [Reading a JitDump](../botr/ryujit-overview.md#reading-a-jitdump) for more on how to analyze this data.
+* `COMPlus_JitDisasm`={method-list} – dump a disassembly listing of each method.
+* `COMPlus_JitDiffableDasm` – set to 1 to tell the JIT to avoid printing things like pointer values that can change from one invocation to the next, so that the disassembly can be more easily compared.
+* `COMPlus_JitGCDump`={method-list} – dump the GC information.
+* `COMPlus_JitUnwindDump`={method-list} – dump the unwind tables.
+* `COMPlus_JitEHDump`={method-list} – dump the exception handling tables.
+* `COMPlus_JitTimeLogFile`={file name} – this specifies a log file to which timing information is written.
+* `COMPlus_JitTimeLogCsv`={file name} – this specifies a log file to which summary timing information can be written, in CSV form.
+
+See also: [CLR Configuration Knobs](../project-docs/clr-configuration-knobs.md)
+
+## Dumping native images
+
+If you followed the tutorial above and ran the sample app, you may be wondering why the disassembly for methods like `Substring` didn't show up in the output. This is because `Substring` lives in mscorlib, which (by default) is compiled ahead-of-time to a native image via [crossgen](../building/crossgen.md). Telling crossgen to dump the info works slightly differently.
+
+* First, perform a debug build of the native parts of the repo: `build skipmscorlib skiptests`.
+  * This should produce the binaries for crossgen in `bin/Product/<OS>.<arch>.Debug`.
+* Next, set the appropriate configuration knob for the info you want to dump. Usually, this is just the same as the corresponding JIT knob, except prefixed with `Ngen`; for example, to show the disassembly listing of a particular method you would `set COMPlus_NgenDisasm=Foo`.
+* Run crossgen on the assembly you want to dump: `crossgen MyLibrary.dll`
+  * If you want to see the output of crossgen specifically for mscorlib, invoke `build skipnative skiptests` from the repo root. The dumps should be written to a file in `bin/Logs` that you can just view.
diff --git a/Documentation/building/windows-instructions.md b/Documentation/building/windows-instructions.md
new file mode 100644
index 0000000000..f68ed2c8c7
--- /dev/null
+++ b/Documentation/building/windows-instructions.md
@@ -0,0 +1,188 @@
+Build CoreCLR on Windows
+========================
+
+These instructions will lead you through building CoreCLR and running a "Hello World" demo on Windows. 
+
+Environment
+===========
+
+You must install several components to build the CoreCLR and CoreFX repos. These instructions were tested on Windows 7+.
+
+Visual Studio
+-------------
+
+Visual Studio must be installed. Supported versions:
+
+- [Visual Studio 2015](https://www.visualstudio.com/downloads/visual-studio-2015-downloads-vs) (Community, Professional, Enterprise)
+
+To debug managed code, ensure you have installed atleast [Visual Studio 2015 Update 3](https://www.visualstudio.com/en-us/news/releasenotes/vs2015-update3-vs).
+
+Make sure that you install "VC++ Tools". By default, they will not be installed.
+
+To build for Arm32, you need to have [Windows SDK for Windows 10](https://developer.microsoft.com/en-us/windows/downloads) installed. 
+
+Visual Studio Express is not supported.
+
+CMake
+-----
+
+The CoreCLR repo build has been validated using CMake 3.5.2. 
+
+- Install [CMake](http://www.cmake.org/download) for Windows.
+- Add it to the PATH environment variable.
+
+Python
+---------
+Python is used in the build system. We are currently using python 2.7.9, although
+any recent (2.4+) version of Python should work, including Python 3.
+- Install [Python](https://www.python.org/downloads/) for Windows.
+- Add it to the PATH environment variable.
+
+PowerShell
+----------
+PowerShell is used in the build system. Ensure that it is accessible via the PATH environment variable. Typically this is %SYSTEMROOT%\System32\WindowsPowerShell\v1.0\.
+
+Powershell version must be 3.0 or higher. This should be the case for Windows 8 and later builds.
+- Windows 7 SP1 can install Powershell version 4 [here](https://www.microsoft.com/en-us/download/details.aspx?id=40855).
+
+Git Setup
+---------
+
+Clone the CoreCLR and CoreFX repositories (either upstream or a fork).
+
+```bat
+C:\git>git clone https://github.com/dotnet/coreclr
+C:\git>git clone https://github.com/dotnet/corefx
+```
+
+This guide assumes that you've cloned the CoreCLR and CoreFX repositories into C:\git using the default repo names. If your setup is different, you'll need to pay attention to the commands you run. The guide will always show you the current directory.
+
+The repository is configured to allow Git to make the right decision about handling CRLF. Specifically, if you are working on **Windows**, please ensure that **core.autocrlf** is set to **true**. On **non-Windows** platforms, please set it to **input**.
+
+Demo directory
+--------------
+
+In order to keep everything tidy, create a new directory for the files that you will build or acquire.
+
+```bat
+c:\git>mkdir \coreclr-demo\runtime
+c:\git>mkdir \coreclr-demo\ref
+```
+
+Build the Runtime
+=================
+
+To build CoreCLR, run `build.cmd` from the root of the coreclr repository. This will do a x64/Debug build of CoreCLR, its native components, mscorlib.dll, and the tests.
+
+	C:\git\coreclr>build -rebuild
+
+	[Lots of build spew]
+
+	Repo successfully built.
+
+	Product binaries are available at C:\git\coreclr\bin\Product\Windows_NT.x64.debug
+	Test binaries are available at C:\git\coreclr\bin\tests\Windows_NT.x64.debug
+
+**Note:** To avoid building the tests, pass the 'skiptestbuild' option to build.
+
+**build -?** will list supported parameters.
+
+Check the build output.
+
+- Product binaries will be dropped in `bin\Product\<OS>.<arch>.<flavor>` folder. 
+- A NuGet package, Microsoft.Dotnet.CoreCLR, will be created under `bin\Product\<OS>.<arch>.<flavor>\.nuget` folder. 
+- Test binaries will be dropped under `bin\Tests\<OS>.<arch>.<flavor>` folder
+
+You will see several files. The interesting ones are:
+
+- `corerun`: The command line host. This program loads and starts the CoreCLR runtime and passes the managed program you want to run to it.
+- `coreclr.dll`:  The CoreCLR runtime itself.
+- `mscorlib.dll`: The core managed library for CoreCLR, which contains all of the fundamental data types and functionality.
+
+Copy these files into the demo directory.
+
+```bat
+C:\git\coreclr>copy bin\Product\Windows_NT.x64.debug\clrjit.dll \coreclr-demo\runtime
+C:\git\coreclr>copy bin\Product\Windows_NT.x64.debug\CoreRun.exe \coreclr-demo\runtime
+C:\git\coreclr>copy bin\Product\Windows_NT.x64.debug\coreclr.dll \coreclr-demo\runtime
+C:\git\coreclr>copy bin\Product\Windows_NT.x64.debug\mscorlib.dll \coreclr-demo\runtime
+C:\git\coreclr>copy bin\Product\Windows_NT.x64.debug\System.Private.CoreLib.dll \coreclr-demo\runtime
+```
+
+Build the Framework
+===================
+
+Build the framework out of the corefx directory.
+
+	c:\git\corefx>build.cmd
+
+	[Lots of build spew]
+
+    0 Warning(s)
+    0 Error(s)
+	Time Elapsed 00:03:14.53
+	Build Exit Code = 0
+
+It's also possible to add -rebuild to build.cmd to force it to delete the previously built assemblies.
+
+For the purposes of this demo, you need to copy a few required assemblies to the demo folder.
+
+```bat
+C:\git\corefx>copy bin\Windows_NT.AnyCPU.Debug\System.Console\System.Console.dll \coreclr-demo\runtime
+C:\git\corefx>copy bin\Windows_NT.AnyCPU.Debug\System.Diagnostics.Debug\System.Diagnostics.Debug.dll \coreclr-demo\runtime
+C:\git\corefx>copy bin\AnyOS.AnyCPU.Debug\System.IO\System.IO.dll \coreclr-demo\runtime
+C:\git\corefx>copy bin\AnyOS.AnyCPU.Debug\System.IO.FileSystem.Primitives\System.IO.FileSystem.Primitives.dll \coreclr-demo\runtime
+C:\git\corefx>copy bin\AnyOS.AnyCPU.Debug\System.Runtime\System.Runtime.dll \coreclr-demo\runtime
+C:\git\corefx>copy bin\AnyOS.AnyCPU.Debug\System.Runtime.InteropServices\System.Runtime.InteropServices.dll \coreclr-demo\runtime
+C:\git\corefx>copy bin\AnyOS.AnyCPU.Debug\System.Text.Encoding\System.Text.Encoding.dll \coreclr-demo\runtime
+C:\git\corefx>copy bin\AnyOS.AnyCPU.Debug\System.Text.Encoding.Extensions\System.Text.Encoding.Extensions.dll \coreclr-demo\runtime
+C:\git\corefx>copy bin\AnyOS.AnyCPU.Debug\System.Threading\System.Threading.dll \coreclr-demo\runtime
+C:\git\corefx>copy bin\AnyOS.AnyCPU.Debug\System.Threading.Tasks\System.Threading.Tasks.dll \coreclr-demo\runtime
+```
+
+You also need to copy reference assemblies, which will be used during compilation.
+
+```bat
+C:\git\corefx>copy bin\ref\System.Runtime\4.0.0.0\System.Runtime.dll \coreclr-demo\ref
+C:\git\corefx>copy bin\ref\System.Console\4.0.0.0\System.Console.dll \coreclr-demo\ref
+```
+
+Compile the Demo
+================
+
+Now you need a Hello World application to run. You can write your own, if you'd like. Here's a very simple one:
+
+```C#
+using System;
+
+public class Program
+{
+    public static void Main()
+    {
+        Console.WriteLine("Hello, Windows");
+        Console.WriteLine("Love from CoreCLR.");
+    }
+}
+```
+
+Personally, I'm partial to the one on corefxlab which will print a picture for you. Download the [corefxlab demo](https://raw.githubusercontent.com/dotnet/corefxlab/master/demos/CoreClrConsoleApplications/HelloWorld/HelloWorld.cs) to `\coreclr-demo`.
+
+Then you just need to build it, with csc, the .NET Framework C# compiler. It may be easier to do this step within the "Developer Command Prompt for VS2015", if csc is not in your path. Because you need to compile the app against the .NET Core surface area, you need to pass references to the contract assemblies you restored using NuGet:
+
+```bat
+csc /nostdlib /noconfig /r:ref\System.Runtime.dll /r:ref\System.Console.dll /out:runtime\hello.exe hello.cs
+```
+
+Run the demo
+============
+
+You're ready to run Hello World! To do that, run corerun, passing the path to the managed exe, plus any arguments. In this case, no arguments are necessary.
+
+```bat
+C:\coreclr-demo>cd runtime
+C:\coreclr-demo\runtime>CoreRun.exe hello.exe
+```
+
+If `CoreRun.exe` fails for some reason, you will see an empty output. To diagnose the issue, you can use `/v` to switch verbose mode on: `CoreRun.exe /v hello.exe`.
+
+Over time, this process will get easier. Thanks for trying out CoreCLR. Feel free to try a more interesting demo.
diff --git a/Documentation/building/windows-test-instructions.md b/Documentation/building/windows-test-instructions.md
new file mode 100644
index 0000000000..8e8949ed00
--- /dev/null
+++ b/Documentation/building/windows-test-instructions.md
@@ -0,0 +1,106 @@
+Building and running tests on Windows
+=====================================
+
+**Building Tests**        
+
+To build the tests simply navigate to the tests directory above the repo and run,
+
+    C:\git\coreclr>build-test.cmd
+
+*Cleaning Tests*
+
+**Note:** Cleaning should be done before all tests to be sure that the test assets are initialized correctly. To do a clean build of the tests, in a clean command prompt, issue the following command: 
+
+    C:\git\coreclr>build-test.cmd -rebuild
+
+*Building tests that will be precompiled*
+
+    C:\git\coreclr>build-test.cmd crossgen
+
+This will use crossgen.exe to precompile the test executables before they are executed.
+
+*Building Other Priority Tests*
+
+    C:\git\coreclr>build-test.cmd -priority=2
+
+The number '2' is just an example. The default value (if no priority is specified) is 0. To clarify, if '2' is specified, all tests with CLRTestPriorty 0, 1 AND 2 will be built and consequently run.
+
+**Example**
+
+To run a clean, priority 1, crossgen test pass:
+
+    C:\git\coreclr>build-test.cmd -rebuild crossgen -priority=1
+
+**buildtest /?** will list additional supported parameters.
+
+Additionally, there is a Visual Studio solution, `<repo_root>\tests\src\AllTestProjects.sln`, where users can build a particular testcase, or all priority 0 testcases that are within it.
+
+**Building Individual Tests**
+
+Note: buildtest.cmd or build.cmd skipnative skipmscorlib needs to be run atleast once
+
+* Native Test: Build the generated Visual Studio solution or make file corresponding to Test cmake file.
+  
+* Managed Test: You can invoke msbuild on the project directly from Visual Studio Command Prompt.
+
+**Running Tests**
+
+In a clean command prompt: `<repo_root>\tests\runtest.cmd`
+
+**runtest /?** will list supported parameters.
+
+This will generate the report named as `TestRun_<arch>_<flavor>.html` (e.g. `TestRun_x64__release.html`) in the current folder. It will also copy all the test dependencies to the folder passed at the command line.
+
+**Investigating Test Failures**
+
+Upon completing a test run, you may find one or more tests have failed.
+
+The output of the Test will be available in Test reports directory, but the default the directory would be something like is `<repo_root>\binaries\tests\x64\debug\Reports\Exceptions\Finalization`.
+
+There are 2 files of interest: 
+
+- `Finalizer.output.txt` - Contains all the information logged by the test.
+- `Finalizer.error.txt`  - Contains the information reported by CoreRun.exe (which executed the test) when the test process crashes.
+
+**Rerunning a failed test**
+
+If you wish to re-run a failed test, please follow the following steps:
+
+1. Set an environment variable, `CORE_ROOT`, pointing to the path to product binaries that was passed to runtest.cmd. The command to set this environment variable is also specified in the test report for a failed test.
+2. Next, run the failed test, the command to which is also present in the test report for a failed test. It will be something like `<repo_root>\binaries\tests\x64\debug\Exceptions\Finalization\Finalizer.cmd`.
+
+If you wish to run the test under a debugger (e.g. [WinDbg](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551063(v=vs.85).aspx)), append `-debug <debuggerFullPath>` to the test command. For example:
+
+
+     <repo_root>\binaries\tests\x64\debug\Exceptions\Finalization\Finalizer.cmd -debug <debuggerFullPath>
+    
+**Modifying a test**
+
+If test changes are needed, make the change and build the test project. This will binplace the binaries in test binaries folder (e.g. `<repo_root>\binaries\tests\x64\debug\Exceptions\Finalization`). At this point, follow the steps to re-run a failed test to re-run the modified test.
+
+**Authoring Tests (in VS)**
+
+
+1. Use an existing test such as `<repo_root>\tests\src\Exceptions\Finalization\Finalizer.csproj` as a template and copy it to a new folder under `<repo_root>\tests\src`.
+2. Be sure that the AssemblyName has been removed (this causes confusion with the way tests are generally handled behind the scenes by the build system). 
+3. [Assign a CLRTestKind/CLRTestPriority.](test-configuration.md)
+4. Add the project of the new test to `<repo_root>\tests\src\AllTestProjects.sln` in VS
+5. Add source files to this newly added project.
+6. Indicate the success of the test by returning `100`.
+8. Add any other projects as a dependency, if needed.
+9. Build the test.
+10. Follow the steps to re-run a failed test to validate the new test.
+
+Note:
+
+1. You can disable building of a test per architecture or configuration by using DisableProjectBuild tag in the project. for example:
+
+  ``<PropertyGroup>``
+
+     ``<DisableProjectBuild Condition=" '$(Platform)' == 'arm64' ">true</DisableProjectBuild>``
+
+  ``</PropertyGroup>``
+
+2. To Add Nuget\MyGet Refernces use this (project.json)[https://github.com/dotnet/coreclr/blob/master/tests/src/Common/test_dependencies/project.json]
+
+3. To Build against the mscorlib facade add  ``<ReferenceLocalMscorlib>true</ReferenceLocalMscorlib>`` to your project