summaryrefslogtreecommitdiff
path: root/Documentation/workflow
diff options
context:
space:
mode:
authorJiyoung Yun <jy910.yun@samsung.com>2017-04-13 14:17:19 +0900
committerJiyoung Yun <jy910.yun@samsung.com>2017-04-13 14:17:19 +0900
commita56e30c8d33048216567753d9d3fefc2152af8ac (patch)
tree7e5d979695fc4a431740982eb1cfecc2898b23a5 /Documentation/workflow
parent4b11dc566a5bbfa1378d6266525c281b028abcc8 (diff)
downloadcoreclr-a56e30c8d33048216567753d9d3fefc2152af8ac.tar.gz
coreclr-a56e30c8d33048216567753d9d3fefc2152af8ac.tar.bz2
coreclr-a56e30c8d33048216567753d9d3fefc2152af8ac.zip
Imported Upstream version 2.0.0.11353upstream/2.0.0.11353
Diffstat (limited to 'Documentation/workflow')
-rw-r--r--Documentation/workflow/IssuesFeedbackEngagement.md2
-rw-r--r--Documentation/workflow/OfficalAndDailyBuilds.md26
-rw-r--r--Documentation/workflow/RunningTests.md2
-rw-r--r--Documentation/workflow/UsingYourBuild.md290
4 files changed, 171 insertions, 149 deletions
diff --git a/Documentation/workflow/IssuesFeedbackEngagement.md b/Documentation/workflow/IssuesFeedbackEngagement.md
index f83b2b6a89..4346ed90f3 100644
--- a/Documentation/workflow/IssuesFeedbackEngagement.md
+++ b/Documentation/workflow/IssuesFeedbackEngagement.md
@@ -16,7 +16,7 @@ Before you log a new issue, you should try using the search tool on the issue pa
If you want to ask a question, or want wider discussion (to see if others share you issue), we encourage you to start a thread
in the [.NET Foundation forums](http://forums.dotnetfoundation.org/).
-###Chat with the CoreCLR Community
+### Chat with the CoreCLR Community
For more real-time feedback you can also start a chat session by clicking on the icons below.
diff --git a/Documentation/workflow/OfficalAndDailyBuilds.md b/Documentation/workflow/OfficalAndDailyBuilds.md
index d5efb93c04..9d5fcc2bf7 100644
--- a/Documentation/workflow/OfficalAndDailyBuilds.md
+++ b/Documentation/workflow/OfficalAndDailyBuilds.md
@@ -63,17 +63,15 @@ If you click on the images below, you can get more details about the build (incl
and the exact test results (in case your build is failing tests and you are wondering if it is
something affecting all builds).
-| | Debug | Release |
-|---|:-----:|:-------:|
-|**CentOS 7.1**|[![x64 status](https://img.shields.io/jenkins/s/http/dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/debug_centos7.1.svg?label=x64)](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/debug_centos7.1)|[![x64 status](https://img.shields.io/jenkins/s/http/dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/release_centos7.1.svg?label=x64)](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/release_centos7.1)|
-|**Debian 8.4**|[![x64 status](https://img.shields.io/jenkins/s/http/dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/debug_debian8.4.svg?label=x64)](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/debug_debian8.4)|[![x64 status](https://img.shields.io/jenkins/s/http/dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/release_debian8.4.svg?label=x64)](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/release_debian8.4)|
-|**FreeBSD 10.1**|[![x64 status](https://img.shields.io/jenkins/s/http/dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/debug_freebsd.svg?label=x64)](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/debug_freebsd)|[![x64 status](https://img.shields.io/jenkins/s/http/dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/release_freebsd.svg?label=x64)](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/release_freebsd)|
-|**openSUSE 13.2**|[![x64 status](https://img.shields.io/jenkins/s/http/dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/debug_opensuse13.2.svg?label=x64)](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/debug_opensuse13.2)|[![x64 status](https://img.shields.io/jenkins/s/http/dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/release_opensuse13.2.svg?label=x64)](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/release_opensuse13.2)|
-|**openSUSE 42.1**|[![x64 status](https://img.shields.io/jenkins/s/http/dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/debug_opensuse42.1.svg?label=x64)](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/debug_opensuse42.1)|[![x64 status](https://img.shields.io/jenkins/s/http/dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/release_opensuse42.1.svg?label=x64)](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/release_opensuse42.1)|
-|**OS X 10.11**|[![x64 status](https://img.shields.io/jenkins/s/http/dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/debug_osx.svg?label=x64)](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/debug_osx)|[![x64 status](https://img.shields.io/jenkins/s/http/dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/release_osx.svg?label=x64)](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/release_osx)|
-|**Red Hat 7.2**|[![x64 status](https://img.shields.io/jenkins/s/http/dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/debug_rhel7.2.svg?label=x64)](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/debug_rhel7.2)|[![x64 status](https://img.shields.io/jenkins/s/http/dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/release_rhel7.2.svg?label=x64)](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/release_rhel7.2)|
-|**Fedora 23**|[![x64 status](https://img.shields.io/jenkins/s/http/dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/debug_fedora23.svg?label=x64)](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/debug_fedora23)|[![x64 status](https://img.shields.io/jenkins/s/http/dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/release_fedora23.svg?label=x64)](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/release_fedora23)|
-|**Ubuntu 14.04**|[![x64 status](https://img.shields.io/jenkins/s/http/dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/debug_ubuntu.svg?label=x64)](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/debug_ubuntu)|[![x64 status](https://img.shields.io/jenkins/s/http/dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/release_ubuntu.svg?label=x64)](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/release_ubuntu)|
-|**Ubuntu 16.04**|[![x64 status](https://img.shields.io/jenkins/s/http/dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/debug_ubuntu16.04.svg?label=x64)](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/debug_ubuntu16.04)|[![x64 status](https://img.shields.io/jenkins/s/http/dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/release_ubuntu16.04.svg?label=x64)](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/release_ubuntu16.04)|
-|**Ubuntu 16.10**|[![x64 status](https://img.shields.io/jenkins/s/http/dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/debug_ubuntu16.10.svg?label=x64)](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/debug_ubuntu16.10)|[![x64 status](https://img.shields.io/jenkins/s/http/dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/release_ubuntu16.10.svg?label=x64)](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/release_ubuntu16.10)|
-|**Windows 8.1**|[![x64 status](https://img.shields.io/jenkins/s/http/dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/debug_windows_nt.svg?label=x64)](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/debug_windows_nt)<br/>[![arm64 status](https://img.shields.io/jenkins/s/http/dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/arm64_cross_debug_windows_nt.svg?label=arm64)](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/arm64_cross_debug_windows_nt)|[![x64 status](https://img.shields.io/jenkins/s/http/dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/release_windows_nt.svg?label=x64)](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/release_windows_nt)<br/>[![arm64 status](https://img.shields.io/jenkins/s/http/dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/arm64_cross_release_windows_nt.svg?label=arm64)](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/arm64_cross_release_windows_nt)|
+| | X64 Debug | X64 Release | ARM64 Debug | ARM64 Release |
+|---|:-----:|:-------:|:-------:|:-------:|
+|**CentOS 7.1**|[![x64 status](https://ci.dot.net/job/dotnet_coreclr/job/master/job/debug_centos7.1/badge/icon)](http://ci.dot.net/job/dotnet_coreclr/job/master/job/debug_centos7.1)|[![x64 status](https://ci.dot.net/job/dotnet_coreclr/job/master/job/release_centos7.1/badge/icon)](http://ci.dot.net/job/dotnet_coreclr/job/master/job/release_centos7.1)|||
+|**Debian 8.4**|[![x64 status](https://ci.dot.net/job/dotnet_coreclr/job/master/job/debug_debian8.4/badge/icon)](http://ci.dot.net/job/dotnet_coreclr/job/master/job/debug_debian8.4)|[![x64 status](https://ci.dot.net/job/dotnet_coreclr/job/master/job/release_debian8.4/badge/icon)](http://ci.dot.net/job/dotnet_coreclr/job/master/job/release_debian8.4)|||
+|**FreeBSD 10.1**|[![x64 status](https://ci.dot.net/job/dotnet_coreclr/job/master/job/debug_freebsd/badge/icon)](http://ci.dot.net/job/dotnet_coreclr/job/master/job/debug_freebsd)|[![x64 status](https://ci.dot.net/job/dotnet_coreclr/job/master/job/release_freebsd/badge/icon)](http://ci.dot.net/job/dotnet_coreclr/job/master/job/release_freebsd)|||
+|**openSUSE 42.1**|[![x64 status](https://ci.dot.net/job/dotnet_coreclr/job/master/job/debug_opensuse42.1/badge/icon)](http://ci.dot.net/job/dotnet_coreclr/job/master/job/debug_opensuse42.1)|[![x64 status](https://ci.dot.net/job/dotnet_coreclr/job/master/job/release_opensuse42.1/badge/icon)](http://ci.dot.net/job/dotnet_coreclr/job/master/job/release_opensuse42.1)|||
+|**OS X 10.12**|[![x64 status](https://ci.dot.net/job/dotnet_coreclr/job/master/job/debug_osx10.12/badge/icon)](http://ci.dot.net/job/dotnet_coreclr/job/master/job/debug_osx10.12)|[![x64 status](https://ci.dot.net/job/dotnet_coreclr/job/master/job/release_osx10.12/badge/icon)](http://ci.dot.net/job/dotnet_coreclr/job/master/job/release_osx10.12)|||
+|**Red Hat 7.2**|[![x64 status](https://ci.dot.net/job/dotnet_coreclr/job/master/job/debug_rhel7.2/badge/icon)](http://ci.dot.net/job/dotnet_coreclr/job/master/job/debug_rhel7.2)|[![x64 status](https://ci.dot.net/job/dotnet_coreclr/job/master/job/release_rhel7.2/badge/icon)](http://ci.dot.net/job/dotnet_coreclr/job/master/job/release_rhel7.2)|||
+|**Ubuntu 14.04**|[![x64 status](https://ci.dot.net/job/dotnet_coreclr/job/master/job/debug_ubuntu/badge/icon)](http://ci.dot.net/job/dotnet_coreclr/job/master/job/debug_ubuntu)|[![x64 status](https://ci.dot.net/job/dotnet_coreclr/job/master/job/release_ubuntu/badge/icon)](http://ci.dot.net/job/dotnet_coreclr/job/master/job/release_ubuntu)|||
+|**Ubuntu 16.04**|[![x64 status](https://ci.dot.net/job/dotnet_coreclr/job/master/job/debug_ubuntu16.04/badge/icon)](http://ci.dot.net/job/dotnet_coreclr/job/master/job/debug_ubuntu16.04)|[![x64 status](https://ci.dot.net/job/dotnet_coreclr/job/master/job/release_ubuntu16.04/badge/icon)](http://ci.dot.net/job/dotnet_coreclr/job/master/job/release_ubuntu16.04)|||
+|**Ubuntu 16.10**|[![x64 status](https://ci.dot.net/job/dotnet_coreclr/job/master/job/debug_ubuntu16.10/badge/icon)](http://ci.dot.net/job/dotnet_coreclr/job/master/job/debug_ubuntu16.10)|[![x64 status](https://ci.dot.net/job/dotnet_coreclr/job/master/job/release_ubuntu16.10/badge/icon)](http://ci.dot.net/job/dotnet_coreclr/job/master/job/release_ubuntu16.10)|||
+|**Windows 8.1**|[![x64 status](https://ci.dot.net/job/dotnet_coreclr/job/master/job/debug_windows_nt/badge/icon)](http://ci.dot.net/job/dotnet_coreclr/job/master/job/debug_windows_nt)|[![x64 status](https://ci.dot.net/job/dotnet_coreclr/job/master/job/release_windows_nt/badge/icon)](http://ci.dot.net/job/dotnet_coreclr/job/master/job/release_windows_nt)|[![arm64 status](https://ci.dot.net/job/dotnet_coreclr/job/master/job/arm64_cross_debug_windows_nt/badge/icon)](http://ci.dot.net/job/dotnet_coreclr/job/master/job/arm64_cross_debug_windows_nt)|[![arm64 status](https://ci.dot.net/job/dotnet_coreclr/job/master/job/arm64_cross_release_windows_nt/badge/icon)](http://ci.dot.net/job/dotnet_coreclr/job/master/job/arm64_cross_release_windows_nt)|
diff --git a/Documentation/workflow/RunningTests.md b/Documentation/workflow/RunningTests.md
index 0cf84be125..65957f476d 100644
--- a/Documentation/workflow/RunningTests.md
+++ b/Documentation/workflow/RunningTests.md
@@ -1,5 +1,5 @@
-#Running .NET Core Tests
+# Running .NET Core Tests
TODO - Incomplete.
diff --git a/Documentation/workflow/UsingYourBuild.md b/Documentation/workflow/UsingYourBuild.md
index c783dd1e19..dcb24b3ced 100644
--- a/Documentation/workflow/UsingYourBuild.md
+++ b/Documentation/workflow/UsingYourBuild.md
@@ -1,209 +1,233 @@
# Using your .NET Core Runtime Build
-We assume that you have successfully built CoreCLR repository and thus have file of the form
+We assume that you have successfully built CoreCLR repository and thus have files of the form
```
bin\Product\<OS>.<arch>.<flavor>\.nuget\pkg\Microsoft.NETCore.Runtime.CoreCLR.<version>.nupkg
```
And now you wish to try it out. We will be using Windows OS as an example and thus will use \ rather
than / for directory separators and things like Windows_NT instead of Linux but it should be
-pretty obvious how to adapt these instructions for other operating systems.
+pretty obvious how to adapt these instructions for other operating systems.
To run your newly built .NET Core Runtime in addition to the application itself, you will need
a 'host' program that will load the Runtime as well as all the other .NET Core Framework
-code that your application needs. The easiest way to get all this other stuff is to simply use the
+code that your application needs. The easiest way to get all this other stuff is to simply use the
standard 'dotnet' host that installs with .NET Core SDK.
The released version of 'dotnet' tool may not be compatible with the live CoreCLR repository. The following steps
-assume use of unreleased version of 'dotnet' tool that is downloaded as part of the CoreCLR repository
-build at `<repo root>\Tools\dotnetcli`. [Add `Tools\dotnetcli` directory to your path](../building/windows-instructions.md#adding-to-the-default-path-variable)
-and type:
+assume use of a dogfood build of the .NET SDK.
-* dotnet -?
+## Acquire the latest nightly .NET Core 2.0 SDK
-and it prints some help text, you are ready.
+- [Win 64-bit Latest](https://dotnetcli.blob.core.windows.net/dotnet/Sdk/master/dotnet-dev-win-x64.latest.zip)
+- [macOS 64-bit Latest](https://dotnetcli.blob.core.windows.net/dotnet/Sdk/master/dotnet-dev-osx-x64.latest.tar.gz)
+- [Others](https://github.com/dotnet/cli/blob/master/README.md#installers-and-binaries)
-### Step 1: Create a App using the Default Runtime
-At this point you can create a new 'Hello World' program in the standard way.
+To setup the SDK download the zip and extract it somewhere and add the root folder to your [path](../building/windows-instructions.md#adding-to-the-default-path-variable)
+or always fully qualify the path to dotnet in the root of this folder for all the instructions in this document.
+
+After setting up dotnet you can verify you are using the newer version by:
+
+`dotnet --info` -- the version should be greater than 2.0.0-*
+
+For another small walkthrough see [Dogfooding .NET Core 2.0 SDK](https://github.com/dotnet/corefx/blob/master/Documentation/project-docs/dogfooding.md).
+
+## Create sample self-contained application
+
+At this point you can create a new 'Hello World' program in the standard way.
```bat
mkdir HelloWorld
cd HelloWorld
-dotnet new
+dotnet new console
```
-### Step 2: Get the Version number of the CoreCLR package you built.
+### Change project to be self-contained
-This makes a 'standard' hello world application but uses the .NET Core Runtime version that
-came with the dotnet.exe tool. First you need to modify your app to ask for the .NET Core
-you have built, and to do that, we need to know the version number of what you built. Get
-this by simply listing the name of the Microsoft.NETCore.Runtime.CoreCLR you built.
+In order to update with your local changes the application needs to be self-contained, as opposed to running on the
+shared framework. In order to do that you will need to add a `RuntimeIdentifier` to your project.
+
+```
+ <PropertyGroup>
+ ...
+ <RuntimeIdentifier>win7-x64</RuntimeIdentifier>
+ </PropertyGroup>
+```
+
+For windows you will want `win7-x64` but for other OS's you will need to set it to the most appropriate one based
+on what you built. You can generally figure that out by looking at the packages you found in your output. In our
+example you will see there is a package with the name `runtime.win7-x64.Microsoft.NETCore.Runtime.CoreCLR.2.0.0-beta-25023-0.nupkg`
+so you will want to put whatever id is between `runtime.` and `Microsoft.NETCore.Runtime.CoreCLR`.
+
+Next you need to restore and publish. The publish step will also trigger a build but you can iterate on build by calling `dotnet build` as
+needed.
```bat
- dir bin\Product\Windows_NT.x64.Release\.nuget\pkg
+dotnet restore
+dotnet publish
```
-and you will get name of the which looks something like this
+After you publish you will find you all the binaries needed to run your application under `bin\Debug\netcoreapp2.0\win7-x64\publish\`.
+To run the application simply run the EXE that is in this publish directory (it is the name of the app, or specified in the project file).
```
- Microsoft.NETCore.Runtime.CoreCLR.1.2.0-beta-24528-0.nupkg
+.\bin\Debug\netcoreapp2.0\win7-x64\publish\HelloWorld.exe
```
-This gets us the version number, in the above case it is 1.2.0-beta-24528-0. We will
-use this in the next step.
+Thus at this point publication directory directory has NO dependency outside that directory (including dotnet.exe). You can copy this publication
+directory to another machine and run the exe in it and it will 'just work' (assuming you are on the same OS). Note that your managed app's
+code is still in the 'app'.dll file, the 'app'.exe file is actually simply a rename of dotnet.exe.
+
+**NOTE**: Normally you would be able to run the application by calling `dotnet run` however there is currently tooling issues which lead to an error similar
+to `A fatal error was encountered. The library 'hostpolicy.dll' required to execute the application was not found in ...` so to workaround that for
+now you have to manually run the application from the publish directory.
+
+
+## Update CoreCLR from raw binary output
-### Step 3: Modify the Project.json for the App to refer to your Runtime.
+Updating CoreCLR from raw binary output is easier for quick one-off testing which is what this set of instructions
+outline but for consuming in a real .NET Core application you should use the nuget package instructions below.
-Replace the HelloWorld\project.json with [project.json](../../tests/src/Common/netcoreapp/project.json), and update
-`1.2.0-beta-XXXXX-X` version number in the dependencies section with the version number for your build of the runtime.
-This is the line that tells the tools that you want YOUR version of the CoreCLR runtime.
+The 'dotnet publish' step above creates a directory that has all the files necessary to run your app
+including the CoreCLR and the parts of CoreFX that were needed. You can use this fact to skip some steps if
+you wish to update the DLLs. For example typically when you update CoreCLR you end up updating one of two DLLs
+
+* coreclr.dll - Most modifications (with the exception of the JIT compiler and tools) that are C++ code update
+ this DLL.
+* System.Private.CoreLib.dll - If you modified C# it will end up here.
+* System.Private.CoreLib.ni.dll - the native image (code) for System.Private.Corelib. If you modify C# code
+you will want to update both of these together in the target installation.
+
+Thus after making a change and building, you can simply copy the updated binary from the `bin\Product\<OS>.<arch>.<flavor>`
+directory to your publication directory (e.g. `helloWorld\bin\Debug\netcoreapp2.0\win7-x64\publish`) to quickly
+deploy your new bits. In a lot of cases it is easiest to just copy everything from here to your publication directory.
+
+You can build just the .NET Library part of the build by doing (debug, for release add 'release' qualifier)
+(on Linux / OSX us ./build.sh)
+```bat
+ .\build skiptests skipnative
```
- "Microsoft.NETCore.Runtime.CoreCLR": "1.2.0-beta-24528-0"
+Which builds System.Private.CoreLib.dll AND System.Private.CoreLib.ni.dll (you will always want both) if you modify
+C# code. If you wish to only compile the coreclr.dll you can do
+ ```bat
+ .\build skiptests skipmscorlib
```
+Note that this technique does not work on .NET Apps that have not been published (that is you have not created
+a directory with all DLLs needed to run the all) That is because the runtime is either fetched from the system-wide
+location that dotnet.exe installed, OR it is fetched from the local nuget package cache (which is where your
+build was put when you did a 'dotnet restore' and had a dependency on your particular runtime). In theory you
+could update these locations in place, but that is not recommended since they are shared more widely.
-The differences between the project.json generated by the tool and the replacement:
+## Update CoreCLR using runtime nuget package
-- Removed Microsoft.NETCore.App platform dependency (`"type": "platform"`). This tells the build system that you don't want to
-use runtime and libraries that came with the dotnet.exe tool but to fetch the dependencies from the Nuget cache. If you don't do this
-the tools will ignore your request to make the app use an explicitly specified runtime.
-- Added the 'runtimes' line at the top level. The runtime name includes the OS name and the architecture name
-you can find the appropriate name for your OS [here](https://github.com/dotnet/core-docs/blob/master/docs/core/rid-catalog.md).
-This tells the tools exactly which flavor of OS and processor architecture you are running on, so it can find the right
-Nuget package for the runtime.
-- Changed netcoreapp1.0 to netcoreapp1.1. This tells the tools that you want to use the latest .NET Core Framework.
-- Expanded Microsoft.NETCore.App metapackage into explicit list of the .NET Core Framework packages because of there is no good published
-build of Microsoft.NETCore.App metapackage for netcoreapp1.1 yet.
+Updating CoreCLR from raw binary output is easier for quick one-off testing but using the nuget package is better
+for referencing your CoreCLR build in your actual application because of it does not require manual copying of files
+around each time the application is built and plugs into the rest of the tool chain. This set of instructions will cover
+the further steps needed to consume the runtime nuget package.
-### Step 4: Place your build directory and beta .NET Core Framework feed on your Nuget Path
+#### 1 - Get the Version number of the CoreCLR package you built.
-You can do this by creating a file named Nuget.Config in the 'HelloWorld' directory with the following XML
-Obviously **you need to update path in the XML to be the path to output directory for your build**.
-On Windows you also have the alternative of modifying the Nuget.Config
-at %HOMEPATH%\AppData\Roaming\Nuget\Nuget.Config (~/.nuget/NuGet/NuGet.Config on Linux) with the new location.
-This will allow your new
-runtime to be used on any 'dotnet restore' run by the current user.
-Alternatively you can skip creating this file and pass the path to your package directory using
-the -s SOURCE qualifer on the dotnet restore command below. The important part is that somehow
-you have told the tools where to find your new package.
+This makes a 'standard' hello world application but uses the .NET Core Runtime version that
+came with the dotnet.exe tool. First you need to modify your app to ask for the .NET Core
+you have built, and to do that, we need to know the version number of what you built. Get
+this by simply listing the name of the Microsoft.NETCore.Runtime.CoreCLR you built.
-```xml
-<configuration>
- <packageRestore>
- <add key="enabled" value="True" />
- </packageRestore>
- <packageSources>
- <add key="Local CoreCLR" value="C:\Users\User\Source\Repos\coreclr-vancem\bin\Product\Windows_NT.x64.Release\.nuget\pkg" />
- <add key="myget.org dotnet-core" value="https://dotnet.myget.org/F/dotnet-core/api/v3/index.json" />
- </packageSources>
- <activePackageSource>
- <add key="All" value="(Aggregate source)" />
- </activePackageSource>
-</configuration>
+```bat
+ dir bin\Product\Windows_NT.x64.Release\.nuget\pkg
```
-### Step 5: Restore the Nuget Packages for your application
+and you will get name of the which looks something like this
-This consist of simply running the command
```
- dotnet restore
+ Microsoft.NETCore.Runtime.CoreCLR.2.0.0-beta-25023-0.nupkg
```
-which should find the .NET Runtime package in your build output and unpacks it to the local Nuget cache (on windows this is in %HOMEPATH%\.nuget\packages)
+This gets us the version number, in the above case it is 2.0.0-beta-25023-0. We will
+use this in the next step.
-### Step 6: Run your application
+#### 2 - Add a reference to your runtime package
-You can run your 'HelloWorld' applications by simply executing the following in the 'HelloWorld' directory.
+Add the following lines to your project file:
```
- dotnet run
+ <ItemGroup>
+ <PackageReference Include="Microsoft.NETCore.Runtime.CoreCLR" Version="2.0.0-beta-25023-0" />
+ </ItemGroup>
```
-This will compile and run your app. What the command is really doing is building files in helloWorld\bin\Debug\netcoreapp1.1\win7-x64\
-and then running 'dotnet helloWorld\bin\Debug\netcoreapp1.1\win7-x64\HelloWorld.dll' to actually run the app.
-### Step 6: (Optional) Publish your application
+In your project you should also see a `RuntimeFrameworkVersion` property which represents the
+version of Micorosoft.NETCore.App which is used for all the other dependencies. It is possible
+that libraries between your runtime and that package are far enough apart to cause issues, so
+it is best to have the latest version of Microsoft.NETCore.App package if you are working on the
+latest version of the source in coreclr master branch. You can find the latest package by looking
+at https://dotnet.myget.org/feed/dotnet-core/package/nuget/Microsoft.NETCore.App.
-In Step 5 you will notice that the helloWorld\bin\Debug\netcoreapp1.1\win7-x64 directory does NOT actually contain your Runtime code.
-What is going on is that runtime is being loaded directly out of the local Nuget cache (on windows this is in %HOMEPATH%\.nuget\packages).
-The app can find this cache because of the HelloWorld.runtimeconfig.dev.json file which specifies that that this location should be
-added to the list of places to look for dependencies.
+#### 3 - Place your build directory and beta .NET Core Framework feed on your Nuget source list
-This setup fine for development time, but is not a reasonable way of allowing end users to use your new runtime. Instead what
-you want all the necessary code to be gather up so that the app is self-contained. This is what the following command does.
-```
- dotnet publish
-```
-After running this in the 'HelloWorld' directory you will see that the following path
+By default the dogfooding dotnet SDK will create a Nuget.Config file next to your project, if it doesn't
+you can create one. Your config file will need a source for your local coreclr package directory as well
+as a reference to our nightly dotnet-core feed on myget:
-* helloWorld\bin\Debug\netcoreapp1.1\win7-x64\publish
+```xml
+<configuration>
+ <packageSources>
+ <add key="local coreclr" value="D:\git\coreclr\bin\Product\Windows_NT.x64.Debug\.nuget\pkg" />
+ <add key="dotnet-core" value="https://dotnet.myget.org/F/dotnet-core/api/v3/index.json" />
+ </packageSources>
+</configuration>
+
+```
+Obviously **you need to update path in the XML to be the path to output directory for your build**.
-Has all the binaries needed, including the CoreCLR.dll and System.Private.CoreLib.dll that you build locally. To
-run the application simple run the EXE that is in this publish directory (it is the name of the app, or specified
-in the project.json file). Thus at this point this directory has NO dependency outside this publication directory
-(including dotnet.exe). You can copy this publication directory to another machine and run( the exe in it and
-will 'just work'. Note that your managed app's code is still in the 'app'.dll file, the 'app'.exe file is
-actually simply a rename of dotnet.exe.
+On Windows you also have the alternative of modifying the Nuget.Config
+at `%HOMEPATH%\AppData\Roaming\Nuget\Nuget.Config` (`~/.nuget/NuGet/NuGet.Config` on Linux) with the new location.
+This will allow your new runtime to be used on any 'dotnet restore' run by the current user.
+Alternatively you can skip creating this file and pass the path to your package directory using
+the -s SOURCE qualifer on the dotnet restore command below. The important part is that somehow
+you have told the tools where to find your new package.
-### Step 7: (Optional) Confirm that the app used your new runtime
+Once have made these modifications you will need to rerun the restore and publish as such.
-Congratulations, you have successfully used your newly built runtime. To confirm that everything worked, you
-should compare the file creation timestamps for the CoreCLR.dll and System.Private.Runtime.dll in the publishing
-directory and the build output directory. They should be identical. If not, something went wrong and the
-dotnet tool picked up a different version of your runtime.
+```
+dotnet restore
+dotnet publish
+```
+Now your publication directory should contain your local built CoreCLR builds.
-### Step 8: Update BuildNumberMinor Environment Variable!
+#### 4 - Update BuildNumberMinor Environment Variable
One possible problem with the technique above is that Nuget assumes that distinct builds have distinct version numbers.
-Thus if you modify the source and create a new NuGet package you must it a new version number and use that in your
-application's project.json. Otherwise the dotnet.exe tool will assume that the existing version is fine and you
-won't get the updated bits. This is what the Minor Build number is all about. By default it is 0, but you can
-give it a value by setting the BuildNumberMinor environment variable.
+Thus if you modify the source and create a new NuGet package you must it a new version number and use that in your
+application's project. Otherwise the dotnet.exe tool will assume that the existing version is fine and you
+won't get the updated bits. This is what the Minor Build number is all about. By default it is 0, but you can
+give it a value by setting the BuildNumberMinor environment variable.
```bat
set BuildNumberMinor=3
```
-before packaging. You should see this number show up in the version number (e.g. 1.2.0-beta-24521-03).
+before packaging. You should see this number show up in the version number (e.g. 2.0.0-beta-25023-03).
-As an alternative you can delete the existing copy of the package from the Nuget cache. For example on
-windows (on Linux substitute ~/ for %HOMEPATH%) you could delete
+As an alternative you can delete the existing copy of the package from the Nuget cache. For example on
+windows (on Linux substitute ~/ for %HOMEPATH%) you could delete
```bat
- %HOMEPATH%\.nuget\packages\Microsoft.NETCore.Runtime.CoreCLR\1.2.0-beta-24521-02
+ %HOMEPATH%\.nuget\packages\Microsoft.NETCore.Runtime.CoreCLR\2.0.0-beta-25023-02
```
-which should make things work (but is fragile, confirm wile file timestamps that you are getting the version you expect)
-
+which should make things work (but is fragile, confirm file timestamps that you are getting the version you expect)
-## Step 8.1 (Optional) Quick updates in place.
+## (Optional) Confirm that the app used your new runtime
-The 'dotnet publish' step in step 6 above creates a directory that has all the files necessary to run your app
-including the CoreCLR and the parts of CoreFX that were needed. You can use this fact to skip some steps if
-you wish to update the DLLs. For example typically when you update CoreCLR you end up updating one of two DLLs
-
-* coreclr.dll - Most modifications (with the exception of the JIT compiler and tools) that are C++ code update
- this DLL.
-* System.Private.CoreLib.dll - If you modified C# it will end up here.
-* System.Private.CoreLib.ni.dll - the native image (code) for System.Private.Corelib. If you modify C# code
-you will want to update both of these together in the target installation.
+Congratulations, you have successfully used your newly built runtime. To confirm that everything worked, you
+should compare the file creation timestamps for the CoreCLR.dll and System.Private.Runtime.dll in the publishing
+directory and the build output directory. They should be identical. If not, something went wrong and the
+dotnet tool picked up a different version of your runtime.
-Thus after making a change and building, you can simply copy the updated binary from the `bin\Product\<OS>.<arch>.<flavor>`
-directory to your publication directory (e.g. `helloWorld\bin\Debug\netcoreapp1.1\win7-x64\publish`) to quickly
-deploy your new bits. You can build just the .NET Library part of the build by doing (debug, for release add 'release qualifier)
-(on Linux / OSX us ./build.sh)
-```bat
- .\build skiptests skipnative
+As a hint you could adde some code like:
```
-Which builds System.Private.CoreLib.dll AND System.Private.CoreLib.ni.dll (you will always want both) if you modify
-C# code. If you wish to only compile the coreclr.dll you can do
- ```bat
- .\build skiptests skipmscorlib
+ var coreAssemblyInfo = System.Diagnostics.FileVersionInfo.GetVersionInfo(typeof(object).Assembly.Location);
+ Console.WriteLine($"Hello World from Core {coreAssemblyInfo.ProductVersion}");
```
-Note that this technique does not work on .NET Apps that have not been published (that is you have not created
-a directory with all DLLs needed to run the all) That is because the runtime is either fetched from the system-wide
-location that dotnet.exe installed, OR it is fetched from the local nuget package cache (which is where your
-build was put when you did a 'dotnet restore' and had a dependency on your particular runtime). In theory you
-could update these locations in place, but that is not recommended since they are shared more widely.
-
-### Using your Runtime For Real.
+That should tell you the version and which user and machine build the assembly as well as the commit hash of the code
+at the time of building.
-You can see that it is straightforward for anyone to use your runtime. They just need to modify their project.json
-and modify their NuGet search path. This is the expected way of distributing your modified runtime.
--------------------------
## Using CoreRun to run your .NET Core Application
@@ -212,4 +236,4 @@ Generally using dotnet.exe tool to run your .NET Core application is the preferr
However there is a simpler 'host' for .NET Core applications called 'CoreRun' that can also be used. The value
of this host is that it is simpler (in particular it knows nothing about NuGet), but precisely because of this
it can be harder to use (since you are responsible for insuring all the dependencies you need are gather together)
-See [Using CoreRun To Run .NET Core Application](UsingCoreRun.md) for more.
+See [Using CoreRun To Run .NET Core Application](UsingCoreRun.md) for more.