Documentation/workflow/UsingYourBuild.md

   1
   2 # Using your .NET Core Runtime Build
   3
   4 We assume that you have successfully built CoreCLR repository and thus have files of the form
   5 ```
   6     bin\Product\<OS>.<arch>.<flavor>\
   7 ```
   8 And now you wish to try it out.  We will be using Windows OS as an example and thus will use \ rather
   9 than / for directory separators and things like Windows_NT instead of Linux but it should be
  10 pretty obvious how to adapt these instructions for other operating systems.
  11
  12 To run your newly built .NET Core Runtime in addition to the application itself, you will need
  13 a 'host' program that will load the Runtime as well as all the other .NET Core Framework
  14 code that your application needs. The easiest way to get all this other stuff is to simply use the
  15 standard 'dotnet' host that installs with .NET Core SDK.
  16
  17 The released version of 'dotnet' tool may not be compatible with the live CoreCLR repository. The following steps
  18 assume use of a dogfood build of the .NET SDK.
  19
  20 ## Acquire the latest nightly .NET Core SDK
  21
  22 - [Win 64-bit Latest](https://dotnetcli.blob.core.windows.net/dotnet/Sdk/master/dotnet-sdk-latest-win-x64.zip)
  23 - [macOS 64-bit Latest](https://dotnetcli.blob.core.windows.net/dotnet/Sdk/master/dotnet-sdk-latest-osx-x64.tar.gz)
  24 - [Others](https://github.com/dotnet/cli/blob/master/README.md#installers-and-binaries)
  25
  26 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)
  27 or always fully qualify the path to dotnet in the root of this folder for all the instructions in this document.
  28
  29 After setting up dotnet you can verify you are using the newer version by:
  30
  31 `dotnet --info` -- the version should be greater than 2.1.0-*
  32
  33 For another small walkthrough see [Dogfooding .NET Core SDK](https://github.com/dotnet/corefx/blob/master/Documentation/project-docs/dogfooding.md).
  34
  35 ## Create sample self-contained application
  36
  37 At this point, you can create a new 'Hello World' program in the standard way.
  38
  39 ```bat
  40 mkdir HelloWorld
  41 cd HelloWorld
  42 dotnet new console
  43 ```
  44
  45 ### Change project to be self-contained
  46
  47 In order to update with your local changes, the application needs to be self-contained, as opposed to running on the
  48 shared framework.  In order to do that you will need to add a `RuntimeIdentifier` to your project.
  49
  50 ```xml
  51 <PropertyGroup>
  52   ...
  53   <RuntimeIdentifier>win-x64</RuntimeIdentifier>
  54 </PropertyGroup>
  55 ```
  56 For Windows you will want `win-x64`, for macOS `osx-x64` and `linux-x64` for Linux.
  57
  58 You might also need to explicitly specify a `PlatformTarget`: it shouldn't be required though, unless for some reason the default `PlatformTarget` on your machine, for that directory, is not `x64`.
  59
  60 ```xml
  61 <PropertyGroup>
  62   ...
  63   <RuntimeIdentifier>win-x64</RuntimeIdentifier>
  64   <PlatformTarget>x64</PlatformTarget>
  65 </PropertyGroup>
  66 ```
  67
  68 ### Publish
  69
  70 Now is the time to publish. The publish step will trigger restore and build. You can iterate on build by calling `dotnet build` as
  71 needed.
  72
  73 ```bat
  74 dotnet publish
  75 ```
  76
  77 **Note:** If publish fails to restore runtime packages you need to configure custom NuGet feed. To do so you have to:
  78
  79 1. run `dotnet new nugetconfig`
  80 2. go to the `NuGet.Config` file and add `<add key="dotnet-core" value="https://dotnet.myget.org/F/dotnet-core/api/v3/index.json" />`
  81
  82 After you publish you will find you all the binaries needed to run your application under `bin\Debug\netcoreapp2.1\win-x64\publish\`.
  83
  84 ```
  85 .\bin\Debug\netcoreapp2.1\win-x64\publish\HelloWorld.exe
  86 ```
  87
  88 **But we are not done yet, you need to replace the published runtime files with the files from your local build!**
  89
  90 ## Update CoreCLR from raw binary output
  91
  92 Updating CoreCLR from raw binary output is easier for quick one-off testing which is what this set of instructions
  93 outline but for consuming in a real .NET Core application you should use the nuget package instructions below.
  94
  95 The 'dotnet publish' step above creates a directory that has all the files necessary to run your app
  96 including the CoreCLR and the parts of CoreFX that were needed. You can use this fact to skip some steps if
  97 you wish to update the DLLs. For example typically when you update CoreCLR you end up updating one of two DLLs
  98
  99 * coreclr.dll - Most modifications (with the exception of the JIT compiler and tools) that are C++ code update
 100   this DLL.
 101 * System.Private.CoreLib.dll - If you modified C# it will end up here.
 102
 103 Thus after making a change and building, you can simply copy the updated binary from the `bin\Product\<OS>.<arch>.<flavor>`
 104 directory to your publication directory (e.g. `helloWorld\bin\Debug\netcoreapp2.1\win-x64\publish`) to quickly
 105 deploy your new bits. In a lot of cases it is easiest to just copy everything from here to your publication directory.
 106
 107 You can build just the .NET Library part of the build by doing (debug, for release add 'release' qualifier)
 108 (on Linux / OSX us ./build.sh)
 109 ```bat
 110     .\build skiptests skipnative
 111 ```
 112 Which builds System.Private.CoreLib.dll if you modify C# code. If you wish to only compile the coreclr.dll you can do
 113  ```bat
 114     .\build skiptests skipmscorlib
 115 ```
 116 Note that this technique does not work on .NET Apps that have not been published (that is you have not created
 117 a directory with all DLLs needed to run the all)  That is because the runtime is either fetched from the system-wide
 118 location that dotnet.exe installed, OR it is fetched from the local nuget package cache (which is where your
 119 build was put when you did a 'dotnet restore' and had a dependency on your particular runtime).    In theory you
 120 could update these locations in place, but that is not recommended since they are shared more widely.
 121
 122 ## (Optional) Confirm that the app used your new runtime
 123
 124 Congratulations, you have successfully used your newly built runtime.
 125
 126 As a hint you could add some code like:
 127 ```
 128 var coreAssemblyInfo = System.Diagnostics.FileVersionInfo.GetVersionInfo(typeof(object).Assembly.Location);
 129 Console.WriteLine($"Hello World from Core {coreAssemblyInfo.ProductVersion}");
 130 Console.WriteLine($"The location is {typeof(object).Assembly.Location}");
 131 ```
 132
 133 That should tell you the version and which user and machine build the assembly as well as the commit hash of the code
 134 at the time of building:
 135
 136 ```
 137 Hello World from Core 4.6.26210.0 @BuiltBy: adsitnik-MININT-O513E3V @SrcCode: https://github.com/dotnet/coreclr/tree/3d6da797d1f7dc47d5934189787a4e8006ab3a04
 138 The location is C:\coreclr\helloWorld\bin\Debug\netcoreapp2.1\win-x64\publish\System.Private.CoreLib.dll
 139 ```
 140
 141 ## Using DotNetCli to run your .NET Core Application
 142
 143 If you don't like the idea of copying files manually you can follow [this instructions](UsingDotNetCli.md) to use dotnet cli to do this for you.
 144 However the steps described here are the simplest and most commonly used by CoreCLR developers for ad-hoc testing.
 145
 146 ## Using CoreRun to run your .NET Core Application
 147
 148 Generally using dotnet.exe tool to run your .NET Core application is the preferred mechanism to run .NET Core Apps.
 149 However there is a simpler 'host' for .NET Core applications called 'CoreRun' that can also be used.   The value
 150 of this host is that it is simpler (in particular it knows nothing about NuGet), but precisely because of this
 151 it can be harder to use (since you are responsible for insuring all the dependencies you need are gather together)
 152 See [Using CoreRun To Run .NET Core Application](UsingCoreRun.md) for more.