diff options
| author | Jiyoung Yun <jy910.yun@samsung.com> | 2016-12-27 16:46:08 +0900 |
|---|---|---|
| committer | Jiyoung Yun <jy910.yun@samsung.com> | 2016-12-27 16:46:08 +0900 |
| commit | db20f3f1bb8595633a7e16c8900fd401a453a6b5 (patch) | |
| tree | e5435159cd1bf0519276363a6fe1663d1721bed3 /Documentation/workflow | |
| parent | 4b4aad7217d3292650e77eec2cf4c198ea9c3b4b (diff) | |
| download | coreclr-db20f3f1bb8595633a7e16c8900fd401a453a6b5.tar.gz coreclr-db20f3f1bb8595633a7e16c8900fd401a453a6b5.tar.bz2 coreclr-db20f3f1bb8595633a7e16c8900fd401a453a6b5.zip | |
Imported Upstream version 1.0.0.9127upstream/1.0.0.9127
Diffstat (limited to 'Documentation/workflow')
| -rw-r--r-- | Documentation/workflow/EditingAndDebugging.md | 49 | ||||
| -rw-r--r-- | Documentation/workflow/IssuesFeedbackEngagement.md | 37 | ||||
| -rw-r--r-- | Documentation/workflow/OfficalAndDailyBuilds.md | 79 | ||||
| -rw-r--r-- | Documentation/workflow/RunningTests.md | 10 | ||||
| -rw-r--r-- | Documentation/workflow/UsingCoreRun.md | 83 | ||||
| -rw-r--r-- | Documentation/workflow/UsingYourBuild.md | 215 |
6 files changed, 473 insertions, 0 deletions
diff --git a/Documentation/workflow/EditingAndDebugging.md b/Documentation/workflow/EditingAndDebugging.md new file mode 100644 index 0000000000..66b4d4fcfd --- /dev/null +++ b/Documentation/workflow/EditingAndDebugging.md @@ -0,0 +1,49 @@ + +# Editing and Debugging + +If you are editing on the Windows Operating system, Using Visual Studio 2015 is a good option for editing +the code in this repository. You can of course also use the editor of your choice. One further option +is to use [VSCode](https://code.visualstudio.com/) which is a light weight, cross-platform tool that like +Visual Studio, is optimized for development workflow (code editing and debugging) but works on more platforms +(in particular OSX and Linux) + +[VSCode](https://code.visualstudio.com/) has built-in support for syntax highlighting and previewing +markdown (`*.md`) files that GIT repositories like this one use for documentation. If you want to modify +the docs, VSCode is a good choice. See [Markdown and VSCOde](https://code.visualstudio.com/Docs/languages/markdown) +for more on VSCode support and [Mastering Markdown](https://guides.github.com/features/mastering-markdown/) for +more on Markdown in general. + +# Visual Studio Solutions + +The repository has a number of Visual Studio Solutions files (`*.sln`) that are useful for editing parts of +what are in the repository. In particular + + * `src\mscorlib\System.Private.CorLib.sln` - This solution is for all managed (C#) code that is defined + in the runtime itself. This is all class library support of one form or another. + * `bin\obj\Windows_NT.<Arch>.<BuildType>\CoreCLR.sln` - this solution contains most native (C++) projects + associated with the repository, including + * `coreclr` - This is the main runtime DLL (the GC, class loader, interop are all here) + * `corjit` - This is the Just In Time (JIT) compiler that compiles .NET Intermediate language to native code. + * `corerun` - This is the simple host program that can load the CLR and run a .NET Core application + * `crossgen` - This is the host program that runs the JIT compiler and produces .NET Native images (`*.ni.dll`) + for C# code. + +Thus opening one of these two solution files (double clicking on them in Explorer) is typically all you need +to do most editing. + +Notice that the CoreCLR solution is under the 'bin' directory. This is because it is created as part of the build. +Thus you can only launch this solution after you have built at least once. + +* See [Debugging](../building/debugging-instructions.md) + +### Interacting with GIT in Visual Studio + +Most interactions with GIT can be done from within Visual Studio. See the following for more details. +* [Setting up with a fork with Visual Studio 2015](https://github.com/Microsoft/perfview/blob/master/documentation/OpenSourceGitWorkflow.md) + +# See Also + +Before you make modifications, you probably want to learn more about the general architecture of .NET Core. +See the following docs for more. + + * [Documentation on the .NET Core Runtime](../README.md) diff --git a/Documentation/workflow/IssuesFeedbackEngagement.md b/Documentation/workflow/IssuesFeedbackEngagement.md new file mode 100644 index 0000000000..a6c0550e08 --- /dev/null +++ b/Documentation/workflow/IssuesFeedbackEngagement.md @@ -0,0 +1,37 @@ + +# Engage, Log Issues and Provide Feedback + +## Reporting Problems (Bugs) + +We track bugs, feature requests and other issues [in this repo](https://github.com/dotnet/coreclr/issues). +If you have a problem and believe that the issue is in the native runtime you should log it there. If in the managed code log it in the [CoreFX repo](https://github.com/dotnet/corefx/issues) _even if the code is in this CoreCLR repo_ (ie., in mscorlib/System.Private.Corelib). The reason for this is we sometimes move managed types between the two and it makes sense to keep all the issues together. + +Before you log a new issue, you should try using the search tool on the issue page on a few keywords to see if the issue was already logged. + +### NET Forums +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 + +For more real-time feedback you can also start a chat session by clicking on the icons below. + +[](http://tattoocoder.com/aspnet-slack-sign-up/) [](https://gitter.im/dotnet/coreclr?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) + +### Security issues + +To avoid tipping off malicious users wishing to exploit a vulnerability, +security issues and bugs should be reported privately, via email, to the +Microsoft Security Response Center (MSRC) <secure@microsoft.com>. You should +receive a response within 24 hours. If for some reason you do not, please follow +up via email to ensure we received your original message. Further information, +including the MSRC PGP key, can be found in the +[Security TechCenter](https://technet.microsoft.com/en-us/security/ff852094.aspx) + +### Issues with the .NET Desktop runtime + +The .NET Core repository is not an appropriate place to log issues for the 'Desktop' .NET Framework built into the Windows +operating system. If you are having issues with the Full .NET Framework or .NET Runtime the best ways to file a bug +are at [Connect](http://connect.microsoft.com/VisualStudio) or through +[Product Support](https://support.microsoft.com/en-us/contactus?ws=support) if you have a contract. + diff --git a/Documentation/workflow/OfficalAndDailyBuilds.md b/Documentation/workflow/OfficalAndDailyBuilds.md new file mode 100644 index 0000000000..5a36af6f46 --- /dev/null +++ b/Documentation/workflow/OfficalAndDailyBuilds.md @@ -0,0 +1,79 @@ +# Official Releases and Daily Builds of CoreCLR and CoreFX components + +If you are not planning on actually making bug fixes or experimenting with new features, then you probably +don't need to don't need build CoreCLR yourself, as the .NET Runtime team routinely does this for you. + +Roughly every three months, the .NET Runtime team publishes a new version of .NET Core to Nuget. .NET Core's +official home on NuGet is + + * <https://www.nuget.org/packages/Microsoft.NETCore.Runtime.CoreCLR/> + +and you can expect to see new versions roughly three months. However it is also the case that the .NET +Team publishes **daily builds** of all sorts of packages including those built by the CoreCLR and CoreFX +repositories. You can see what is available from + + * <https://dotnet.myget.org/gallery/dotnet-core>, and in particular you can see the builds of CoreCLR at + * <https://dotnet.myget.org/feed/dotnet-core/package/nuget/Microsoft.NETCore.Runtime.CoreCLR>. + +Thus if your goal is just to get the latest bug fixes and features, you don't need to build CoreCLR yourself you +can simply add <https://dotnet.myget.org/F/dotnet-core/api/v3/index.json> to your Nuget Feed list. + +## Package Version Numbers + +Version numbers for Nuget packages look like the following +``` + 1.0.24214.01 +``` +Which have the form +``` + <major>.<minor>.<buildNumberMajor>.<buildNumberMinor> +``` + +* The major version number represents a compatibility band. If the next release of the package is not + backward compatible (most apps that run on version N-1 will run on version N) then this number is increased. + This number is not likely to change (we care about compatibility alot) + +* The minor number is increased every time interesting new features are added (not just minor bug fixes). + For CoreCLR we tend to update this every time we create a public release (every 3 months). + +* The Major Build Number is a number that represents a daily build. The last 2 digits of this build number + is the **day of the month** of the GIT commit that is being built. Thus we know in the example above this + build's last commit to GIT happened on the 14th day of the month. The most significant digits represents + the month count since April 1996. In the example above 242 represents Jun 2016. + +* The Minor Build number is something that disambiguates different builds that share the same + commit (or the different commits on the same day). It is a sequential number and is typically 1 for + official builds, and 0 for developer builds. (You can set the environment variable BuildNumberMinor if + you wish to set it for your own builds). + + + +See the [Package and File Versioning](https://github.com/dotnet/corefx/blob/master/Documentation/building/versioning.md) page +for more details on how the build version number is generated. + + + +# Build/Test Status of the repository + +As mentioned we build the CoreCLR repository daily, and as part of that build we also run all +the tests associted with this repository. Below is a table of the most recent results for all +the different operating systems and architectures that we routinely build. + +If you click on the images below, you can get more details about the build (including the binaries) +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**|[](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/debug_centos7.1)|[](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/release_centos7.1)| +|**Debian 8.4**|[](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/debug_debian8.4)|[](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/release_debian8.4)| +|**FreeBSD 10.1**|[](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/debug_freebsd)|[](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/release_freebsd)| +|**openSUSE 13.2**|[](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/debug_opensuse13.2)|[](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/release_opensuse13.2)| +|**openSUSE 42.1**|[](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/debug_opensuse42.1)|[](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/release_opensuse42.1)| +|**OS X 10.11**|[](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/debug_osx)|[](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/release_osx)| +|**Red Hat 7.2**|[](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/debug_rhel7.2)|[](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/release_rhel7.2)| +|**Fedora 23**|[](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/debug_fedora23)|[](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/release_fedora23)| +|**Ubuntu 14.04**|[](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/debug_ubuntu)|[](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/release_ubuntu)| +|**Ubuntu 16.04**|[](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/debug_ubuntu16.04)|[](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/release_ubuntu16.04)| +|**Ubuntu 16.10**|[](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/debug_ubuntu16.10)|[](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/release_ubuntu16.10)| +|**Windows 8.1**|[](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/debug_windows_nt)<br/>[](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/arm64_cross_debug_windows_nt)|[](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/release_windows_nt)<br/>[](http://dotnet-ci.cloudapp.net/job/dotnet_coreclr/job/master/job/arm64_cross_release_windows_nt)| diff --git a/Documentation/workflow/RunningTests.md b/Documentation/workflow/RunningTests.md new file mode 100644 index 0000000000..0cf84be125 --- /dev/null +++ b/Documentation/workflow/RunningTests.md @@ -0,0 +1,10 @@ + +#Running .NET Core Tests + +TODO - Incomplete. + +See [Windows Instructions](../building/windows-test-instructions.md) +See [Unix Instructions](../building/unix-test-instructions.md) + + + diff --git a/Documentation/workflow/UsingCoreRun.md b/Documentation/workflow/UsingCoreRun.md new file mode 100644 index 0000000000..3979f135b0 --- /dev/null +++ b/Documentation/workflow/UsingCoreRun.md @@ -0,0 +1,83 @@ + +# Using corerun To Run .NET Core Application + +In page [Using Your Build](UsingYourBuild.md) gives detailed instructions on using the standard +command line host and SDK, dotnet.exe to run a .NET application with the modified build of the +.NET Core runtime built here. This is the preferred mechanism for you to officially deploy +your changes to other people since dotnet.exe and Nuget insure that you end up with a consistent +set of DLLs that can work together. + +However packing and unpacking the runtime DLLs adds extra steps to the deployment process and when +you are in the tight code-build-debug loop these extra steps are an issue. + +For this situation there is an alternative host to dotnet.exe called corerun.exe that is well suited +for this. It does not know about Nuget at all, and has very simple rules. It needs to find the +.NET Core runtime (that is coreclr.dll) and additionally any class library DLLs (e.g. System.Runtime.dll System.IO.dll ...). + +It does this by looking at two environment variables. + + + * `CORE_ROOT` - The directory where to find the runtime DLLs itself (e.g. CoreCLR.dll). + Defaults to be next to the corerun.exe host itself. + * `CORE_LIBRARIES` - A Semicolon separated list of directories to look for DLLS to resolve any assembly references. + It defaults CORE_ROOT if it is not specified. + +These simple rules can be used in a number of ways + +## Getting the class library from the shared system-wide runtime + +Consider that you already have a .NET application DLL called HelloWorld.dll and wish to run it +(You could make such a DLL by using 'dotnet new' 'dotnet restore' 'dotnet build' in a 'HelloWorld' directory). + +If you execute the following +```bat + set PATH=%PATH%;%CoreCLR%\bin\Product\Windows_NT.x64.Debug + set CORE_LIBRARIES=%ProgramFiles%\dotnet\shared\Microsoft.NETCore.App\1.0.0 + + + corerun HelloWorld.dll +``` + +for Linux use /usr/share for %Program Files% + +Where %CoreCLR% is the base of your CoreCLR repository, then it will run your HelloWorld. application. +You can see why this works. The first line puts build output directory (Your OS, architecture, and buildType +may be different) and thus corerun.exe you just built is on your path. +The second line tells corerun.exe where to find class library files, in this case we tell it +to find them where the installation of dotnet.exe placed its copy. (Note that version number in the path above may change) + +Thus when you run 'corerun HelloWorld.dll' Corerun knows where to get the DLLs it needs. Notice that once +you set up the path and CORE_LIBRARIES environment, after a rebuild you can simply use corerun to run your +application (you don't have to move DLLs around) + +## Using corerun.exe to Execute a Published Application + +When 'dotnet publish' publishes an application it deploys all the class libraries needed as well. +Thus if you simply change the CORE_LIBRARIES definition in the previous instructions to point at +that publication directory but RUN the corerun from your build output the effect will be that you +run your new runtime getting all the other code needed from that deployed application. This is +very convenient because you don't need to modify the deployed application in order to test +your new runtime. + +## How CoreCLR Tests use corerun.exe + +When you execute 'tests\runTest.cmd' one of the things that it does is set up a directory where it +gathers the CoreCLR that has just been built with the pieces of the class library that tests need. +It places this runtime in the directory +```bat + bin\Product\<OS>.<Arch>.<BuildType>\test +``` +off the CoreCLR Repository. The way the tests are expected to work is that you set the environment +variable CORE_ROOT to this directory +(you don't have to set CORE_LIBRARIES) and you can run any tests. For example after building the tests +(running build-test at the repository base) and running 'test\runtest') you can do the following + +```bat + set PATH=%PATH%;%CoreCLR%\bin\Product\Windows_NT.x64.Debug + set CORE_ROOT=%CoreCLR%\bin\tests\Windows_NT.x64.Debug\Tests\Core_Root +``` +sets you up so that corerun can run any of the test. For example +```bat + corerun bin\tests\Windows_NT.X64.Debug\GC\Features\Finalizer\finalizeio\finalizeio\finalizeio.exe +``` +runs the finalizerio test.
\ No newline at end of file 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. |