Merge branch 'master' of /home/vihofer/consolidation/artifacts/core-s…

…etup

docs/installer/building/Running-Tests-In-VisualStudio-IDE.md

@@ -0,0 +1,22 @@
+# Running unit tests within Visual Studio
+
+Sometimes it is convenient to run individual unit tests within the Visual Studio
+IDE. First, build the repo from the command line to create artifacts and set up
+the test environment. Then, use VS Test Explorer to run and debug tests.
+
+## Steps
+
+1. `build.cmd -test`
+2. Open the solution file in the root of the repo.
+3. Open the test explorer window within the Visual Studio IDE.
+4. Select tests and run and/or debug.
+
+## Limitations
+
+* The managed projects load and build, but native and setup projects are not
+  present in the solution and there's no way to trigger a build from inside VS.
+* Rebuilding the native assets alone won't make them used during tests. The
+  tests rely on the setup projects to assemble the native bits into a usable
+  form, and they have to be rebuilt.
+  * With a deep enough understanding of the test layout, you can work around
+    this by copying native build outputs directly into the test layout.

docs/installer/building/local-coreclr-corefx.md

@@ -0,0 +1,29 @@
+# Build Core-Setup with a Local CoreCLR or CoreFX
+
+## Testing with private CoreCLR bits
+
+Generally the Core-Setup build system gets the CoreCLR from a NuGet package which gets pulled down and correctly copied to the various output directories by building `src\pkg\projects\netcoreapp\src\netcoreapp.depproj` which gets built as part of `build.cmd/sh`. For folks that want to do builds and test runs in corefx with a local private build of coreclr you can follow these steps:
+
+1. Build CoreCLR and note your output directory. Ex: `\coreclr\bin\Product\Windows_NT.x64.Release\` Note this will vary based on your OS/Architecture/Flavor and it is generally a good idea to use Release builds for CoreCLR when building Core-Setup and the OS and Architecture should match what you are building in Core-Setup.
+2. Build Core-Setup either passing in the `CoreCLROverridePath` property or setting it as an environment variable:
+
+```batch
+build.cmd /p:CoreCLROverridePath=d:\git\coreclr\bin\Product\Windows_NT.x64.Release
+```
+
+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.
+Once you have updated your CoreCLR you can run tests however you usually do and it should be using your copy of CoreCLR.
+If you prefer, you can use a Debug build of System.Private.CoreLib, but if you do you must also use a Debug build of the native portions of the runtime, e.g. coreclr.dll. Tests with a Debug runtime will execute much more slowly than with Release runtime bits. This override is only enabled for building the NETCoreApp shared framework.
+
+## Testing with private CoreFX bits
+
+Similarly to how Core-Setup consumes CoreCLR, Core-Setup also consumes CoreFX from a NuGet package which gets pulled down and correctly copied to the various output directories by building `src\pkg\projects\netcoreapp\src\netcoreapp.depproj` which gets built as part of `build.cmd/sh`. To test with a local private build of CoreFX, you can follow these steps:
+
+1. Build CoreFX and note your configuration (Ex. Debug, Checked, Release).
+2. Build Core-Setup either passing in the `CoreFXOverridePath` property or setting it as an environment variable (assuming your CoreFX repo is located at `d:\git\corefx`):
+
+```batch
+build.cmd /p:CoreFXOverridePath=d:\git\corefx\artifacts\packages\Debug
+```
+
+The Core-Setup build will resolve the correct libraries to use to build the NETCoreApp shared framework based on the restored packages and will locate the files in the output directory based on the nuspec file of the shared-framework package in the local CoreFX build. This override does not enable using a local CoreFX build when creating the WindowsDesktop shared framework.

docs/installer/building/windows-instructions.md

@@ -0,0 +1,77 @@
+Build Core-Setup on Windows
+========================
+
+These instructions will lead you through building Core-Setup.
+
+----------------
+# Environment
+
+You must install several components to build the Core-Setup repo. These instructions were tested on Windows 10+.
+
+## Visual Studio
+
+Visual Studio must be installed. Supported versions:
+- [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/#2019) (Community, Professional, Enterprise).  The community version is completely free.
+- [Visual Studio 2017](https://visualstudio.microsoft.com/vs/) (Community, Professional, Enterprise).  The community version is completely free.
+
+For Visual Studio:
+* Required installer options that need to be manually enabled:
+  * Universal Windows App Development Tools: Tools and Windows 10 SDK (10.0.14393) + Windows 10 SDK (10.0.10586)
+  * Visual C++
+
+Visual Studio Express is not supported.
+
+## CMake
+
+The Core-Setup repo build requires at least CMake 3.14.
+
+- Install [CMake](http://www.cmake.org/download) for Windows.
+- Add its location (e.g. C:\Program Files (x86)\CMake\bin) to the PATH environment variable.  
+  The installation script has a check box to do this, but you can do it yourself after the fact 
+  following the instructions at [Adding to the Default PATH variable](#adding-to-the-default-path-variable)
+
+
+## Git
+
+For actual user operations, it is often convenient to use the Git features built
+into your editor or IDE. However, Core-Setup and the tests use the Git command
+line utilities directly, so you need to set them up for the build to work
+properly. You can get Git from:
+
+- Install [Git For Windows](https://git-for-windows.github.io/)
+- Add its location (e.g. C:\Program Files\Git\cmd) to the PATH environment variable.  
+  The installation script has a check box to do this, but you can do it yourself after the fact 
+  following the instructions at [Adding to the Default PATH variable](#adding-to-the-default-path-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).
+
+## Adding to the default PATH variable
+
+The commands above need to be on your command lookup path.   Some installers will automatically add them to 
+the path as part of installation, but if not here is how you can do it.  
+
+You can of course add a directory to the PATH environment variable with the syntax
+```
+    set PATH=%PATH%;DIRECTORY_TO_ADD_TO_PATH
+```
+However the change above will only last until the command windows closes.   You can make your change to
+the PATH variable persistent by going to  Control Panel -> System And Security -> System -> Advanced system settings -> Environment Variables, 
+and select the 'Path' variable in the 'System variables' (if you want to change it for all users) or 'User variables' (if you only want
+to change it for the current user).  Simply edit the PATH variable's value and add the directory (with a semicolon separator).
+
+-------------------------------------
+# Building
+
+Once all the necessary tools are in place, building is trivial.  Simply run the
+`build.cmd` script that lives at the base of the repository.
+
+If you want to build a subset of the build because `build.cmd` takes too long,
+try using the `Subset` property. For example, adding `/p:Subset=CoreHost` to
+your build command makes it only build the native project. Read the
+documentation in [Subsets.props](/Subsets.props) and try `/p:Subset=help` for
+more info.