eerhardt · eerhardt · Mar 11, 2016 · Mar 11, 2016 · Mar 11, 2016 · Mar 11, 2016
diff --git a/.gitattributes b/.gitattributes
@@ -62,6 +62,6 @@
 #*.rtf   diff=astextplain
 #*.RTF   diff=astextplain
 
-# Force bash scripts to always use lf line endings so that if a repro is accessed
+# Force bash scripts to always use lf line endings so that if a repo is accessed
 # in Unix via a file share from Windows, the scripts will work.
 *.sh text eol=lf
diff --git a/.gitignore b/.gitignore
@@ -24,6 +24,9 @@ bld/
 [Oo]bj/
 msbuild.log
 
+# Cross building rootfs
+cross/rootfs/
+
 # Visual Studio 2015
 .vs/
 
@@ -76,6 +79,7 @@ _Chutzpah*
 ipch/
 *.aps
 *.ncb
+*.opendb
 *.opensdf
 *.sdf
 *.cachefile
@@ -140,6 +144,7 @@ publish/
 
 # NuGet Packages
 *.nuget.props
+*.nuget.targets
 *.nupkg
 **/packages/*
 

diff --git a/BuildToolsVersion.txt b/BuildToolsVersion.txt
@@ -1 +1 @@
-1.0.25-prerelease-00151
+1.0.25-prerelease-00208
diff --git a/Documentation/README.md b/Documentation/README.md
@@ -47,6 +47,7 @@ Coding Guidelines
 - [Breaking Changes](coding-guidelines/breaking-changes.md)
 - [Breaking Change Definitions](coding-guidelines/breaking-change-definitions.md)
 - [Breaking Change Rules](coding-guidelines/breaking-change-rules.md)
+- [Project Guidelines](coding-guidelines/project-guidelines.md)
 
 Building from Source
 ====================

diff --git a/Documentation/architecture/net-platform-standard.md b/Documentation/architecture/net-platform-standard.md
diff --git a/Documentation/architecture/net-standard-applications.md b/Documentation/architecture/net-standard-applications.md
@@ -0,0 +1,40 @@
+#.NET Standard Applications
+
+NETStandardApp is the [target framework](https://docs.nuget.org/Create/TargetFrameworks) that represents .NET Core applications
+
+Property | Value
+---------|---------
+Target framework identifier | `.NETStandardApp`
+Target framework version | `1.5`
+Target framework moniker | `.NETStandardApp,Version=v1.5`
+Friendly name | .NET Standard Application
+NuGet folder name | `netstandardapp1.5`
+NETStandard version supported | `netstandard1.5`
+
+##FAQ
+**Q: What is a .NET Standard application?**  
+**A:** A .NET Standard application is an application that can run on any .NET Core runtime: CoreCLR (current), .NETNative (future). It can run on one of many .NET core platforms (Windows, OSX, Linux).  It relies on the host provided by the given runtime.  It's a composable framework built from the packages on which the application depends.  Its assembly loading policy permits newer versions of dependencies without any application configuration (eg: BindingRedirects are not required).
+
+**Q: Can I share source between a .NET Standard application, and other target frameworks?**  
+**A:** Yes.  Most of the API supported by .NET Standard application is also part of .NET Standard.  That source could be compiled as a .NET Standard library and shared with a .NET Standard application and a .NET Framework application as a binary.  Alternatively, the source could be shared and cross-compiled between a .NET Standard application and a .NET Framework application.
+
+**Q: Can a .NET Standard application depend on more packages than just those in the `NETStandard.Library` package?**  
+**A:** Yes
+
+**Q: Why is there only one version of `.NETStandardApp` (1.5), but there are many of `.NETStandard`?**  
+**A:** `.NETStandard` is an abstract representation of API that covers all historical platforms that have ever supported that API.  `.NETStandardApp` represents a concrete application type with a runnable implementation.  We are shipping one version of this implementation at this point and it supports `netstandard1.5`.  As we version `.NETStandard` in the future we will update the implementation of `.NETStandardApp` to support the new API and ship a new version of `.NETStandardApp`.
+
+**Q: Can a .NET Standard application depend on platform specific packages like `Microsoft.Win32.Registry`?**  
+**A:** Yes, but it will only run on the platforms that support those packages.
+
+**Q: How is this different than `.NETCore`?**  
+**A:** The `.NETCore` target framework represents Windows 8, Windows 8.1, and Universal Windows Platform applications.  For compatibility purposes this moniker cannot be reused for “.NET Core applications”.  The branding overlap is unfortunate.
+
+**Q: How is this different than `DNXCore`?**  
+**A:** The `DNXCore` target framework represents ASP.NET V5 applications that run in DNX and use XProj.  As such the TFM already had more characteristics associated with it than those we associate with .NET standard application.  .NET standard applications need not be ASP.NET applications and can run on any host and runtime supported by .NET Core.
+
+**Q: How is this different than `.NETStandard`?**  
+**A:** The `NETStandard` target framework is an abstract target framework that represents API surface of many frameworks and platforms.  As such `NETStandard` assemblies can run on any platform that supports the `NETStandard` targeted by that assembly, for example: .NET Desktop, Windows Phone, Universal Windows Platform applications, .NET Standard applications, etc.  `NETStandardApplication` is a concrete target framework that represents a single platform with both API surface and implementation.  .NET standard applications are runnable on their own.  .NETStandard libraries must be published-for or consumed-by a specific concrete target framework to be used in that type of application.
+
+**Q: How is this different than `.NETFramework`, AKA: Full .NET, Desktop .NET, Big .NET, old .NET?**  
+**A:** `.NETFramework` is another concrete framework like `.NETStandardApp` but has a different implementation and runtime and supports a different set of API.  Both `.NETFramework` and `.NETStandardApp` support a common version of `.NETStandard` and the API it exposes.  As such a `.NETStandard` assembly can be used by both `.NETFramework` and `.NETStandardApp`, but a `.NETStandardApp` assembly is not meant to run on `.NETFramework`, nor is a `.NETFramework` assembly meant to run on `.NETStandardApp`.
diff --git a/Documentation/building/cross-building.md b/Documentation/building/cross-building.md
@@ -0,0 +1,90 @@
+Cross Compilation for ARM on Linux
+==================================
+
+Through cross compilation, on Linux it is possible to build CoreFX for arm or arm64.
+It is very similar to the cross compilation procedure of CoreCLR. 
+
+Requirements
+------------
+
+You need a Debian based host, and the following packages need to be installed:
+
+    lgs@ubuntu ~/git/corefx/ $ sudo apt-get install qemu qemu-user-static binfmt-support debootstrap
+
+In addition, to cross compile CoreFX, the binutils for the target are required. So for arm you need:
+
+    lgs@ubuntu ~/git/corefx/ $ sudo apt-get install binutils-arm-linux-gnueabihf
+
+and for arm64 you need:
+
+    lgs@ubuntu ~/git/corefx/ $ 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 CoreFX targets.
+
+    Usage: build-rootfs.sh [BuildArch]
+    BuildArch can be: arm, arm64
+
+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:
+
+    lgs@ubuntu ~/git/corefx/ $ sudo ./cross/build-rootfs.sh arm
+
+and if you wanted to generate the rootfs elsewhere:
+
+    lgs@ubuntu ~/git/corefx/ $ sudo ROOTFS_DIR=/home/lgs/corefx-cross/arm ./build-rootfs.sh arm
+
+
+Cross compiling for native CoreFX
+---------------------------------
+Once the rootfs has been generated, it will be possible to cross compile CoreFX. If `ROOTFS_DIR` was set when generating the rootfs, then it must also be set when running `build.sh`.
+
+So, without `ROOTFS_DIR`:
+
+    lgs@ubuntu ~/git/corefx/ $ ./build.sh native arm debug verbose clean cross
+
+And with:
+
+    lgs@ubuntu ~/git/corefx/ $ ROOTFS_DIR=/home/lgs/corefx-cross/arm ./build.sh native arm debug verbose clean cross
+
+As usual the generated binaries will be found in `bin/BuildOS.BuildArch.BuildType/Native` as following:
+
+    lgs@ubuntu ~/git/corefx/ ls -al ./bin/Linux.arm.Debug/Native
+    total 988
+    drwxrwxr-x 2 lgs lgs   4096  3  6 18:33 .
+    drwxrwxr-x 3 lgs lgs   4096  3  6 18:33 ..
+    -rw-r--r-- 1 lgs lgs  19797  3  6 18:33 System.IO.Compression.Native.so
+    -rw-r--r-- 1 lgs lgs 428232  3  6 18:33 System.Native.a
+    -rw-r--r-- 1 lgs lgs 228279  3  6 18:33 System.Native.so
+    -rw-r--r-- 1 lgs lgs  53089  3  6 18:33 System.Net.Http.Native.so
+    -rw-r--r-- 1 lgs lgs 266720  3  6 18:33 System.Security.Cryptography.Native.so
+    lgs@ubuntu ~/git/corefx/ file ./bin/Linux.arm.Debug/Native/System.Native.so 
+    ./bin/Linux.arm.Debug/Native/System.Native.so: 
+    ELF 32-bit LSB  shared object, ARM, EABI5 version 1 (SYSV), 
+    dynamically linked, BuildID[sha1]=fac50f1bd657c1759f0ad6cf5951511ddf252e67, not stripped
+
+
+Compiling for managed CoreFX
+============================
+The managed components of CoreFX are architecture-independent and thus do not require a special build for arm or arm64.
+
+Many of the managed binaries are also OS-independent, e.g. System.Linq.dll, while some are OS-specific, e.g. System.IO.FileSystem.dll, with different builds for Windows and Linux.
+
+    lgs@ubuntu ~/git/corefx/ $ ./build.sh managed debug clean verbose 
+
+The output is at bin/<BuildOS>.AnyCPU.Debug.
+
+    lgs@ubuntu ~/git/corefx/ $ ls -al ./bin
+    drwxrwxr-x  17 lgs lgs  4096  3  6 21:00 .
+    drwxrwxr-x  10 lgs lgs  4096  3 12 15:04 ..
+    drwx------  98 lgs lgs  4096  3  6 21:36 AnyOS.AnyCPU.Debug
+    drwx------  98 lgs lgs  4096  3  6 19:40 AnyOS.AnyCPU.Release
+    drwx------ 284 lgs lgs 20480  3  6 22:30 Linux.AnyCPU.Debug
+    drwx------ 284 lgs lgs 20480  3  6 20:45 Linux.AnyCPU.Release
+    drwx------  33 lgs lgs  4096  3  6 21:33 Windows_NT.AnyCPU.Debug
+    drwx------  33 lgs lgs  4096  3  6 19:36 Windows_NT.AnyCPU.Release
+
+
diff --git a/Documentation/building/unix-instructions.md b/Documentation/building/unix-instructions.md
@@ -1,75 +1,58 @@
 Building CoreFX on FreeBSD, Linux and OS X
 ==========================================
 
-CoreFx can be built on top of current [Mono CI builds](#installing-mono-packages) or a direct [build/install of Mono](http://www.mono-project.com/docs/compiling-mono/). It builds using MSBuild and Roslyn and requires changes that have not yet made it to official released builds.
+Building CoreFX is pretty straightforward. Clone the repo and run the build script.
 
-After preparing Mono, clone if you haven't already, and run the build script.
-
-```
+```bash
 git clone https://github.com/dotnet/corefx.git
 cd corefx
 ./build.sh
 ```
 
->These instructions have been validated on:
-* Ubuntu 15.04, 14.04, and 12.04
-* Fedora 22
-* MacOS 10.10 (Yosemite)
+### `build.sh` Usage
+ `./build.sh [managed] [native] [BuildArch] [BuildType] [clean] [verbose] [clangx.y] [platform]`
 
+**Example:**
 
-# Installing Mono Packages
-_Mono installation instructions are taken from ["Install Mono"](http://www.mono-project.com/docs/getting-started/install/) and ["Continuous Integration Packages"](http://www.mono-project.com/docs/getting-started/install/linux/ci-packages/)._
+`./build.sh native x64 verbose clang3.9`
 
-_**Note:** CI packages are not produced for Mac. As CoreFx needs current bits you must build Mono [yourself](http://www.mono-project.com/docs/compiling-mono/)._
-### Add Mono key and package sources
-##### Debian/Ubuntu (and other derivatives)
-Add the Mono Project GPG signing key and the package repository to your system:
-```
-sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF
-echo "deb http://download.mono-project.com/repo/debian wheezy main" | sudo tee /etc/apt/sources.list.d/mono-xamarin.list
-```
-Debian requires a second package repository for libgdiplus (this is not applicable to Ubuntu):
-```
-echo "deb http://download.mono-project.com/repo/debian wheezy-libjpeg62-compat main" | sudo tee -a /etc/apt/sources.list.d/mono-xamarin.list
-```
-Then, run a package upgrade:
-```
-sudo apt-get update
-```
+**Options:**
 
-##### Fedora/CentOS (and other derivatives)
-```
-sudo rpm --import "http://keyserver.ubuntu.com/pks/lookup?op=get&search=0x3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF"
-sudo yum-config-manager --add-repo http://download.mono-project.com/repo/centos/
-sudo yum upgrade
-``` 
-### Install Mono build and reference assemblies
-Install a recent Mono build and the PCL reference assemblies.
-##### Debian/Ubuntu (and other derivatives)
-```
-sudo apt-get install mono-devel referenceassemblies-pcl
-```
-##### Fedora/CentOS (and other derivatives)
-```
-sudo yum install mono-devel referenceassemblies-pcl
+```bash
+    managed            # optional argument to build the managed code
+    native             # optional argument to build the native code
+
+    # The following arguments affect native builds only:
+
+    BuildArch          # build architecture (x64, x86, arm, arm64)
+    BuildType          # build configuration type (Debug, Release)
+    clean              # optional argument to force a clean build
+    verbose            # optional argument to enable verbose build output
+    clangx.y           # optional argument to build using clang version x.y
 ```
 
-# Known Issues
+### Prerequisites
+
+* bash
+* curl (devel)
+* icu
+* clang
+* llvm
+* lldb
+
+> Note: These instructions have been validated on:
+* Ubuntu 15.04, 14.04, and 12.04
+* Fedora 22
+* OS X 10.10 (Yosemite)
+* FreeBSD 10.2
+* NetBSD 7.0
+* Alpine Linux 3.3
+
+### Known Issues
 If you see errors along the lines of `SendFailure (Error writing headers)` you may need to import trusted root certificates:
-```
+
+```sh
 mozroots --import --sync
 ```
-PCL reference assemblies and targets are not installed by default. They also are not available for snapshot builds, and must be copied, linked in, or use the ReferenceAssemblyRoot override. The build script will use an MSBuild override, the following is how to link the PCL folder in the right place:
-```
-sudo ln -s /usr/lib/mono/xbuild-frameworks/.NETPortable/ $MONO_PREFIX/lib/mono/xbuild-frameworks/
-```
-If you are seeing errors like the following you likely either have not installed the package or haven't linked it properly.
-```
-warning MSB3252: The currently targeted framework ".NETPortable,Version=v4.5,Profile=Profile7" does not include the referenced assembly
-MSB3644: The reference assemblies for framework ".NETPortable,Version=v4.5,Profile=Profile7" were not found.
-```
-Mono may intermittently fail when compiling. Retry if you see sigfaults or other unexpected issues.
-
-PDBs aren't generated by Roslyn on Unix. https://github.com/dotnet/roslyn/issues/2449
 
-System.Diagnostics.Debug.Tests does not build on Unix. https://github.com/dotnet/corefx/issues/1609
+`System.Diagnostics.Debug.Tests` does not build on Unix. https://github.com/dotnet/corefx/issues/1609
diff --git a/Documentation/building/windows-instructions.md b/Documentation/building/windows-instructions.md
@@ -14,6 +14,8 @@ The following free downloads are compatible:
 
 Note: In order to build our C++ projects be sure to select "Programming Languages | Visual C++ | Common Tools for Visual C++ 2015" while installing VS 2015 (or modify your install to include it).
 
+We also require that [Visual Studio 2015 Update 1](https://www.visualstudio.com/en-us/news/vs2015-update1-vs.aspx) be installed.
+
 [CMake](https://cmake.org/) is required to build the native libraries for Windows. To build these libraries cmake must be installed from [the CMake download page](https://cmake.org/download/) and added to your path.
 
 ## Building From the Command Line
@@ -24,11 +26,23 @@ the core tests for the project. Visual Studio Solution (.sln) files exist for
 related groups of libraries. These can be loaded to build, debug and test inside
 the Visual Studio IDE.
 
+### Building individual DLLs of the CoreFX
+
+Under the src directory is a set of directories, each of which represents a particular assembly in CoreFX.  
+For example the src\System.Diagnostics.DiagnosticSource directory holds the source code for the System.Diagnostics.DiagnosticSource.dll assembly.   Each of these directories has a .sln solution 
+file that typically includes two projects, one for the DLL being built and one for the tests.   Thus
+you can build both the DLL and Tests for System.Diagnostics.DiagnosticSource.dll by going to 
+src\System.Diagnostics.DiagnosticSource and typing `msbuild`. You can build just the System.Diagnostics.DiagnosticSource.dll (without the tests) by going to the src\System.Diagnostics.DiagnosticsSource\src directory and again typing `msbuild`. The DLL ends up as  bin\AnyOS.AnyCPU.Debug\System.Diagnostics.DiagnosticSource\System.DiagnosticSource.dll.
+
+There is also a pkg directory, and if you go into it and type `msbuild`, it will build the DLL (if needed)
+and then also build the Nuget package for it.   The Nuget package ends up in the bin\pkg directory.  
+
+### Building other OSes
+
 By default building from the root will only build the libraries for the OS you are running on. One can
-build for another OS by specifying `/p:FilterOSGroup=[Windows_NT|Linux|OSX|FreeBSD]` or build for all by specifying
+build for another OS by specifying `/p:FilterToOSGroup=[Windows_NT|Linux|OSX|FreeBSD]` or build for all by specifying
 `/p:BuildAllOSGroups=true`.
 
-
 [Building CoreFX on FreeBSD, Linux and OS X](unix-instructions.md)
 ## Tests
 
@@ -48,7 +62,7 @@ msbuild /t:BuildAndTest (or /t:Test to just run the tests if the binaries are al
 
 It is possible to pass parameters to the underlying xunit runner via the `XunitOptions` parameter, e.g.:
 ```cmd
-msbuild /t:Test "/p:XunitOptions=-class Test.ClassUnderTests -notrait category=outerloop"
+msbuild /t:Test "/p:XunitOptions=-class Test.ClassUnderTests"
 ```
 
 There may be multiple projects in some directories so you may need to specify the path to a specific test project to get it to build and run the tests.
@@ -61,7 +75,7 @@ _**`OuterLoop`:**_
 This attribute applies the 'outerloop' category; to run outerloop tests, use the following commandline
 ```cmd
 xunit.console.netcore.exe *.dll -trait category=outerloop
-build.cmd *.csproj /p:RunTestsWithCategories=OuterLoop
+build.cmd *.csproj /p:WithCategories=OuterLoop
 ```
 
 _**`PlatformSpecific(Xunit.PlatformID platforms)`:**_

diff --git a/Documentation/coding-guidelines/breaking-change-rules.md b/Documentation/coding-guidelines/breaking-change-rules.md
@@ -19,8 +19,12 @@ Breaking Change Rules
 ### Property, Field, Parameter and Return Values
 &#10003; **Allowed**
 * Increasing the range of accepted values for a property or parameter if the member _is not_ `virtual`
+
+ > Note that the range can only increase to the extent that it does not impact the static type. e.g. it is OK to remove `if (x > 10) throw new ArgumentOutOfRangeException("x")`, but it is not OK to change the type of `x` from `int` to `long`.
 
-* Returning a more derived type for a property, field, return or `out` value
+* Returning a value of a more derived type for a property, field, return or `out` value
+
+ > Note, again, that the static type cannot change. e.g. it is OK to return a `string` instance where an `object` was returned previously, but it is not OK to change the return type from `object` to `string`.
 
 &#10007; **Disallowed**  
 * Increasing the range of accepted values for a property or parameter if the member _is_ `virtual`