diff options
Diffstat (limited to 'Documentation/workflow/UsingYourBuild.md')
| -rw-r--r-- | Documentation/workflow/UsingYourBuild.md | 215 |
1 files changed, 215 insertions, 0 deletions
diff --git a/Documentation/workflow/UsingYourBuild.md b/Documentation/workflow/UsingYourBuild.md new file mode 100644 index 0000000000..c783dd1e19 --- /dev/null +++ b/Documentation/workflow/UsingYourBuild.md @@ -0,0 +1,215 @@ + +# Using your .NET Core Runtime Build + +We assume that you have successfully built CoreCLR repository and thus have file 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. + +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 +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: + +* dotnet -? + +and it prints some help text, you are ready. + +### Step 1: Create a App using the Default Runtime +At this point you can create a new 'Hello World' program in the standard way. + +```bat +mkdir HelloWorld +cd HelloWorld +dotnet new +``` + +### Step 2: Get the Version number of the CoreCLR package you built. + +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. + +```bat + dir bin\Product\Windows_NT.x64.Release\.nuget\pkg +``` + +and you will get name of the which looks something like this + +``` + Microsoft.NETCore.Runtime.CoreCLR.1.2.0-beta-24528-0.nupkg +``` + +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. + +### Step 3: Modify the Project.json for the App to refer to your Runtime. + +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. +``` + "Microsoft.NETCore.Runtime.CoreCLR": "1.2.0-beta-24528-0" +``` + +The differences between the project.json generated by the tool and the replacement: + +- 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. + +### Step 4: Place your build directory and beta .NET Core Framework feed on your Nuget Path + +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. + +```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> +``` + +### Step 5: Restore the Nuget Packages for your application + +This consist of simply running the command +``` + dotnet restore +``` +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) + + +### Step 6: Run your application + +You can run your 'HelloWorld' applications by simply executing the following in the 'HelloWorld' directory. + +``` + dotnet run +``` +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 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. + +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 + +* helloWorld\bin\Debug\netcoreapp1.1\win7-x64\publish + +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. + +### Step 7: (Optional) Confirm that the app used your new runtime + +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. + +### Step 8: 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. +```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). + +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 +``` +which should make things work (but is fragile, confirm wile file timestamps that you are getting the version you expect) + + +## Step 8.1 (Optional) Quick updates in place. + +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. + +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 +``` +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. + +### Using your Runtime For Real. + +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 + +Generally using dotnet.exe tool to run your .NET Core application is the preferred mechanism to run .NET Core Apps. +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. |