Update required software and developer workflow

Documentation/building/advanced-inner-loop-testing.md

@@ -4,7 +4,7 @@
 
 This tutorial describes how to build and run application code that targets self-compiled .NET Core binaries without using Visual Studio,  the .NET Core SDK Host (`dotnet.exe`) or a project file (e.g. `csproj`). Follow these steps to quickly validate changes you've made in the product e.g. by running benchmarks or tests on it.
 
-If you are on Windows you currently need to use the `Developer Command Prompt for VS 2017` to build corefx/coreclr! For the sake of completeness, we have placed our repositories under `d:\git\`.
+For the sake of completeness, we have placed our repositories under `d:\git\`.
 
 ## Compile corefx with self-compiled coreclr binaries
 If you've made changes to coreclr make sure to also build it and pass its binaries to corefx.

Documentation/building/windows-instructions.md

@@ -6,14 +6,9 @@ You can build .NET Core either via the command line or by using Visual Studio.
 ## Required Software
 
 1. **Visual Studio** must be installed. Supported versions:
-    * [Visual Studio 2015](https://www.visualstudio.com/vs/older-downloads/) (Community, Professional, Enterprise).  The Community version is completely free.
-    * [Visual Studio 2017](https://www.visualstudio.com/downloads/) (Community, Professional, Enterprise).  The Community version is completely free.
-2. **[CMake](https://cmake.org/)** must be installed from [the CMake download page](https://cmake.org/download/#latest) and added to your path.
-
-### Visual Studio 2015
-
-* [Visual Studio 2015 Update 1](https://www.visualstudio.com/en-us/news/vs2015-update1-vs.aspx) is required.
-* You must select **Programming Languages | Visual C++ | Common Tools for Visual C++ 2015** while installing VS 2015 (or modify your install to include it).
+    * [Visual Studio 2017](https://www.visualstudio.com/downloads/) (Community, Professional, Enterprise). The Community version is completely free.
+2. **[.NET Core SDK](https://www.microsoft.com/net/download/windows)** must be installed which will add the `dotnet` CLI to your path.
+3. **[CMake](https://cmake.org/)** must be installed from [the CMake download page](https://cmake.org/download/#latest) and added to your path.
 
 ### Visual Studio 2017
 
@@ -47,11 +42,11 @@ The following are the minimum requirements:
   * Windows Universal CRT SDK
   * VC++ 2015.3 v140 Toolset (x86, x64)
 
-## Building From the Command Line
+For the best possible experience make sure to have the latest version of Visual Studio 2017 installed.
 
-You must use the Developer Command Prompt. It will have a name like "Developer Command Prompt for VS 2017" or similar in your start menu. 
+## Building From the Command Line
 
-From a (non-admin) Developer Command Prompt window:
+From a (non-admin) Command Prompt window:
 
 - `build.cmd` - Will cause basic tool initialization and build the default configuration for refs, libs, and packages.
 - `build-tests.cmd` - Will build and run tests for the default configuration.
@@ -60,8 +55,7 @@ For information on different configurations see [project-guidelines](../coding-g
 
 **Note**: Before working on individual projects or test projects you **must** run `build.cmd` from the root once before beginning that work. It is also a good idea to run `build.cmd` whenever you pull a large set of unknown changes into your branch.
 
-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.
+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.
 
 Note that when calling the script `build.cmd` attempts to build both the native and managed code.
 Only use it when the parameters that you are passing to the script apply for both components. Otherwise, use the scripts `build-native.cmd` and `build-managed.cmd` respectively.
@@ -81,11 +75,10 @@ For more details, or to test an individual project, see the [developer guide top
 
 ### Debugging tests in Visual Studio
 
-1. Install VS 2015 Preview or later including Web Developer Tools
-2. Open solution of interest in VS 2015
-3. Right click test project and select 'Set as startup project'
-4. Set breakpoint appropriately
-5. F5 (Debug)
+1. Open solution of interest
+2. Right click test project and select 'Set as startup project'
+3. Set breakpoint appropriately
+4. F5 (Debug)
 
 ### Debugging NETFX tests in Visual Studio
 
@@ -103,13 +96,8 @@ For advanced debugging using WinDBG see [Debugging CoreFX on Windows](https://gi
 
 ### Notes
 * At any given time, the corefx repo might be configured to use a more recent compiler than
-the one used by the most recent Visual Studio IDE release.  This means the corefx codebase might
+the one used by the installed .NET Core SDK. This means the corefx codebase might
 be using language features that are not understood by the IDE, which might result in errors that
-show up as red squiggles while writing code.  Such errors should, however, not affect the actual compilation.
+show up as red squiggles while writing code. Such errors should, however, not affect the actual compilation.
 
 * Running tests from using the VS test explorer does not currently work after we switched to running on CoreCLR. [We will be working on enabling full VS test integration](https://github.com/dotnet/corefx/issues/1318) but we don't have an ETA yet. In the meantime, use the steps above to launch/debug the tests using the console runner.
-
-* VS 2015 is required to debug tests running on CoreCLR as the CoreCLR
-debug engine is a VS 2015 component.
-
-* If the Xamarin PCL profiles are installed, the build will fail due to [issue #449](https://github.com/dotnet/corefx/issues/449).  A possible workaround is listed [in the issue](https://github.com/dotnet/corefx/issues/449#issuecomment-95117040) itself.

Documentation/project-docs/developer-guide.md

@@ -178,34 +178,32 @@ Under the src directory is a set of directories, each of which represents a part
 
 For example the src\System.Diagnostics.DiagnosticSource directory holds the source code for the System.Diagnostics.DiagnosticSource.dll assembly.
 
-You can build the DLL for System.Diagnostics.DiagnosticSource.dll by going to the `src\System.Diagnostics.DiagnosticsSource\src` directory and typing `msbuild`. The DLL ends up in `bin\AnyOS.AnyCPU.Debug\System.Diagnostics.DiagnosticSource` as well as `bin\runtime\[BuildConfiguration]`.
+You can build the DLL for System.Diagnostics.DiagnosticSource.dll by going to the `src\System.Diagnostics.DiagnosticsSource\src` directory and typing `dotnet msbuild`. The DLL ends up in `bin\AnyOS.AnyCPU.Debug\System.Diagnostics.DiagnosticSource` as well as `bin\runtime\[BuildConfiguration]`.
 
 You can build the tests for System.Diagnostics.DiagnosticSource.dll by going to
-`src\System.Diagnostics.DiagnosticSource\tests` and typing `msbuild`.
+`src\System.Diagnostics.DiagnosticSource\tests` and typing `dotnet msbuild`.
 
-Some libraries might also have a ref and/or a pkg directory and you can build them in a similar way by typing `msbuild` in that directory.
+Some libraries might also have a ref and/or a pkg directory and you can build them in a similar way by typing `dotnet msbuild` in that directory.
 
 For libraries that have multiple build configurations the configurations will be listed in the `<BuildConfigurations>` property group, commonly found in a configurations.props file next to the csproj. When building the csproj for a configuration the most compatible one in the list will be choosen and set for the build. For more information about `BuildConfigurations` see [project-guidelines](../coding-guidelines/project-guidelines.md).
 
 **Examples**
 
 - Build project for Linux for netcoreapp
 ```
-msbuild System.Net.NetworkInformation.csproj /p:OSGroup=Linux
+dotnet msbuild System.Net.NetworkInformation.csproj /p:OSGroup=Linux
 ```
 
 - Build project for uap (not if trying to build on non-windows you also need to specify OSGroup=Windows_NT)
 ```
-msbuild System.Net.NetworkInformation.csproj /p:TargetGroup=uap
+dotnet msbuild System.Net.NetworkInformation.csproj /p:TargetGroup=uap
 ```
 
 - Build release version of library
 ```
-msbuild System.Net.NetworkInformation.csproj /p:ConfigurationGroup=Release
+dotnet msbuild System.Net.NetworkInformation.csproj /p:ConfigurationGroup=Release
 ```
 
-**Note:** If building in a non-Windows environment, call `<repo-root>/Tools/msbuild.sh` instead of just `msbuild`.
-
 ### Building all for other OSes
 
 By default, building from the root will only build the libraries for the OS you are running on. One can
@@ -216,11 +214,11 @@ Note that you cannot generally build native components for another OS but you ca
 ### Building in Release or Debug
 
 By default, building from the root or within a project will build the libraries in Debug mode.
-One can build in Debug or Release mode from the root by doing `build -release` or `build -debug` or when building a project by specifying `/p:ConfigurationGroup=[Debug|Release]` after the `msbuild` command.
+One can build in Debug or Release mode from the root by doing `build -release` or `build -debug` or when building a project by specifying `/p:ConfigurationGroup=[Debug|Release]` after the `dotnet msbuild` command.
 
 ### Building other Architectures
 
-One can build 32- or 64-bit binaries or for any architecture by specifying in the root `build -buildArch=[value]` or in a project `/p:ArchGroup=[value]` after the `msbuild` command.
+One can build 32- or 64-bit binaries or for any architecture by specifying in the root `build -buildArch=[value]` or in a project `/p:ArchGroup=[value]` after the `dotnet msbuild` command.
 
 ### Tests
 
@@ -238,15 +236,14 @@ The easiest (and recommended) way to do it, is by simply building the test .cspr
 
 ```cmd
 cd src\System.Collections.Immutable\tests
-msbuild /t:BuildAndTest   ::or /t:Test to just run the tests if the binaries are already built
-msbuild /t:RebuildAndTest ::this will cause a test project to rebuild and then run tests
+dotnet msbuild /t:BuildAndTest   ::or /t:Test to just run the tests if the binaries are already built
+dotnet msbuild /t:RebuildAndTest ::this will cause a test project to rebuild and then run tests
 ```
 
 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"
+dotnet msbuild /t:Test "/p:XunitOptions=-class Test.ClassUnderTests"
 ```
-**Note:** If building in a non-Windows environment, call `./Tools/msbuild.sh` instead of just `msbuild`.
 
 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.
 
@@ -256,7 +253,7 @@ Tests participate in the incremental build.  This means that if tests have alrea
 
 To quickly run or debug a single test from the command line, set the XunitMethodName property (found in Tools\tests.targets) to the full method name (including namespace), e.g.:
 ```cmd
-msbuild /t:RebuildAndTest /p:XunitMethodName={FullyQualifiedNamespace}.{ClassName}.{MethodName}
+dotnet msbuild /t:RebuildAndTest /p:XunitMethodName={FullyQualifiedNamespace}.{ClassName}.{MethodName}
 ```
 
 #### Running tests in a different target framework
@@ -265,7 +262,7 @@ Each test project can potentially have multiple build configurations. There are
 
 ```cmd
 cd src\System.Runtime\tests
-msbuild System.Runtime.Tests.csproj /p:TargetGroup=netfx
+dotnet msbuild System.Runtime.Tests.csproj /p:TargetGroup=netfx
 ```
 
 #### Filtering tests using traits
@@ -277,15 +274,15 @@ The tests can also be filtered based on xunit trait attributes defined in [`xuni
 ```cs
 [OuterLoop()]
 ```
-Tests marked as `Outerloop` are for scenarios that don't need to run every build. They may take longer than normal tests, cover seldom hit code paths, or require special setup or resources to execute. These tests are excluded by default when testing through msbuild but can be enabled manually by adding the  `Outerloop` property e.g.
+Tests marked as `Outerloop` are for scenarios that don't need to run every build. They may take longer than normal tests, cover seldom hit code paths, or require special setup or resources to execute. These tests are excluded by default when testing through `dotnet msbuild` but can be enabled manually by adding the `Outerloop` property e.g.
 
 ```cmd
 build-managed -Outerloop
 ```
 
 To run <b>only</b> the Outerloop tests, use the following command:
 ```cmd
-msbuild <csproj_file> /t:BuildAndTest /p:WithCategories=OuterLoop
+dotnet msbuild <csproj_file> /t:BuildAndTest /p:WithCategories=OuterLoop
 ```
 
 #### PlatformSpecificAttribute
@@ -302,11 +299,11 @@ Use this attribute on test methods to specify that this test may only be run on
 
 When running tests by building a test project, tests that don't apply to the `OSGroup` are not run. For example, to run Linux-specific tests on a Linux box, use the following command line:
 ```sh
-<repo-root>/Tools/msbuild.sh <csproj_file> /t:BuildAndTest /p:OSGroup=Linux
+dotnet msbuild <csproj_file> /t:BuildAndTest /p:OSGroup=Linux
 ```
 To run all Linux-compatible tests that are failing:
 ```sh
-<repo-root>/Tools/msbuild.sh <csproj_file> /t:BuildAndTest /p:OSGroup=Linux /p:WithCategories=failing
+dotnet msbuild <csproj_file> /t:BuildAndTest /p:OSGroup=Linux /p:WithCategories=failing
 ```
 
 #### ActiveIssueAttribute
@@ -422,11 +419,11 @@ _**A few common examples with the above attributes:**_
 
 - Run all tests acceptable on Windows that are not failing:
 ```cmd
-msbuild <csproj_file> /t:BuildAndTest /p:OSGroup=Windows_NT
+dotnet msbuild <csproj_file> /t:BuildAndTest /p:OSGroup=Windows_NT
 ```
 - Run all outer loop tests acceptable on OS X that are currently associated with active issues:
 ```sh
-<repo-root>/Tools/msbuild.sh <csproj_file> /t:BuildAndTest /p:OSGroup=OSX /p:WithCategories="OuterLoop;failing""
+dotnet msbuild <csproj_file> /t:BuildAndTest /p:OSGroup=OSX /p:WithCategories="OuterLoop;failing""
 ```
 
 Alternatively, you can directly invoke the XUnit executable by changing your working directory to the test execution directory at `bin\tests\{OSPlatformConfig)\{Project}.Tests\{TargetGroup}.{TestTFM}\` which is created when the test project is built.  For example, the following command runs all Linux-supported inner-loop tests:
@@ -444,23 +441,22 @@ build-tests -Coverage
 
 :: To run a single project with code coverage enabled pass the /p:Coverage=true property
 cd src\System.Collections.Immutable\tests
-msbuild /t:BuildAndTest /p:Coverage=true
+dotnet msbuild /t:BuildAndTest /p:Coverage=true
 ```
 If coverage succeeds, the code coverage report will be generated automatically and placed in the bin\tests\coverage directory.  You can view the full report by opening index.htm
 
 Code coverage reports from the continuous integration system are available from the links on the front page of the corefx repo.
 
 ### Building tests with .NET Native (Windows only)
 
-.NET Native is a technology that allows compiling IL applications down into a native executable and minimal set of native DLLs, containing all needed functionality from the .NET Framework in native format.  For CoreFX tests, .NET Native support in CoreFX is relatively early, but supported.
+.NET Native is a technology that allows compiling IL applications down into a native executable and minimal set of native DLLs, containing all needed functionality from the .NET Framework in native format.
 
 ```cmd
 :: To run a single project with the .NET Native toolchain, set the appropriate build flags:
 cd src\Microsoft.CSharp\tests
-::TODO: The exact properties needed for .NET Native tests runs after engineering work is TBD
-msbuild /t:BuildAndTest /p:TargetGroup=uap /p:UseDotNetNativeToolchain=true
+msbuild /t:BuildAndTest /p:TargetGroup=uapaot
 ```
-If native compilation succeeds, the test will build and run as a native executable named "xunit.console.netcore.exe" in a folder named "native" in the test execution folder.  Note many tests in CoreFX are not ready to run though native compilation yet.
+If native compilation succeeds, the test will build and run as a native executable named "xunit.console.netcore.exe" in a folder named "uapaot" in the test execution folder. The .NET Native toolchain, required to build with TargetGroup `uapaot` is currently not available for external contributors.
 
 A slight variation on these arguments will allow you to build and run against `uap`, the managed version of the UWP Framework subset, used when debugging UWP applications in Visual Studio:
 ```cmd
@@ -486,7 +482,7 @@ build.cmd -- /p:CoreCLROverridePath=d:\git\coreclr\bin\Product\Windows_NT.x64.Re
 When we copy the files to override the CoreCLR we do a hard-link copy, so in general if you rebuild CoreCLR the new binaries should be reflected in CoreFx for subsequent builds of individual projects in corefx. However if you want to force refresh or if you want to just update the CoreCLR after you already ran `build.cmd` from CoreFx you can run the following command:
 
 ```
-msbuild /p:CoreCLROverridePath=d:\git\coreclr\bin\Product\Windows_NT.x64.Release\ ./external/runtime/runtime.depproj
+dotnet msbuild /p:CoreCLROverridePath=d:\git\coreclr\bin\Product\Windows_NT.x64.Release\ ./external/runtime/runtime.depproj
 ```
 
 By convention the project will look for PDBs in a directory under `$(CoreCLROverridePath)/PDB` and if found will also copy them. If not found no PDBs will be copied. If you want to explicitly set the PDB path then you can pass `CoreCLRPDBOverridePath` property to that PDB directory.
@@ -499,4 +495,4 @@ If you prefer, you can use a Debug build of System.Private.CoreLib, but if you d
 
 To collect code coverage that includes types in System.Private.CoreLib.dll, you'll need to follow the above steps, then
 
-`msbuild /p:CoreCLROverridePath=d:\git\coreclr\bin\Product\Windows_NT.x64.Release\ /t:rebuildandtest /p:Coverage=true /p:CodeCoverageAssemblies="System.Private.CoreLib"`
+`dotnet msbuild /p:CoreCLROverridePath="d:\git\coreclr\bin\Product\Windows_NT.x64.Release\" /t:RebuildAndTest /p:Coverage=true /p:CodeCoverageAssemblies="System.Private.CoreLib"`