Documentation/workflow/UsingCoreRun.md

   1
   2 # Using corerun To Run .NET Core Application
   3
   4 In page [Using your .NET Core Runtime Build with dotnet cli](UsingDotNetCli.md) gives detailed instructions on using the standard
   5 command line host and SDK, dotnet.exe to run a .NET application with the modified build of the
   6 .NET Core runtime built here.   This is the preferred mechanism for you to officially deploy
   7 your changes to other people since dotnet.exe and Nuget insure that you end up with a consistent
   8 set of DLLs that can work together.
   9
  10 However packing and unpacking the runtime DLLs adds extra steps to the deployment process and when
  11 you are in the tight code-build-debug loop these extra steps are an issue.
  12
  13 For this situation there is an alternative host to dotnet.exe called corerun.exe that is well suited
  14 for this.   It does not know about Nuget at all, and has very simple rules.  It needs to find the
  15 .NET Core runtime (that is coreclr.dll) and additionally any class library DLLs (e.g. System.Runtime.dll  System.IO.dll ...).
  16
  17 It does this by looking at two environment variables.
  18
  19
  20  * `CORE_ROOT` - The directory where to find the runtime DLLs itself (e.g. CoreCLR.dll).
  21  Defaults to be next to the corerun.exe host itself.
  22  * `CORE_LIBRARIES` - A Semicolon separated list of directories to look for DLLS to resolve any assembly references.
  23  It defaults CORE_ROOT if it is not specified.
  24
  25 These simple rules can be used in a number of ways
  26
  27 ## Getting the class library from the shared system-wide runtime
  28
  29 Consider that you already have a .NET application DLL called HelloWorld.dll and wish to run it
  30 (You could make such a DLL by using 'dotnet new' 'dotnet restore' 'dotnet build' in a 'HelloWorld' directory).
  31
  32 If you execute the following
  33 ```bat
  34     set PATH=%PATH%;%CoreCLR%\bin\Product\Windows_NT.x64.Debug
  35     set CORE_LIBRARIES=%ProgramFiles%\dotnet\shared\Microsoft.NETCore.App\1.0.0
  36
  37
  38     corerun HelloWorld.dll
  39 ```
  40
  41 for Linux  use /usr/share for %Program Files%
  42
  43 Where %CoreCLR% is the base of your CoreCLR repository, then it will run your HelloWorld. application.
  44 You can see why this works.  The first line puts build output directory (Your OS, architecture, and buildType
  45 may be different) and thus corerun.exe you just built is on your path.
  46 The second line tells corerun.exe where to find class library files, in this case we tell it
  47 to find them where the installation of dotnet.exe placed its copy.   (Note that version number in the path above may change)
  48
  49 Thus when you run 'corerun HelloWorld.dll' Corerun knows where to get the DLLs it needs.   Notice that once
  50 you set up the path and CORE_LIBRARIES environment, after a rebuild you can simply use corerun to run your
  51 application (you don't have to move DLLs around)
  52
  53 ## Using corerun.exe to Execute a Published  Application
  54
  55 When 'dotnet publish' publishes an application it deploys all the class libraries needed as well.
  56 Thus if you simply change the CORE_LIBRARIES definition in the previous instructions to point at
  57 that publication directory but RUN the corerun from your build output the effect will be that you
  58 run your new runtime getting all the other code needed from that deployed application.   This is
  59 very convenient because you don't need to modify the deployed application in order to test
  60 your new runtime.
  61
  62 ## How CoreCLR Tests use corerun.exe
  63
  64 When you execute 'tests\runTest.cmd' one of the things that it does is set up a directory where it
  65 gathers the CoreCLR that has just been built with the pieces of the class library that tests need.
  66 It places this runtime in the directory
  67 ```bat
  68     bin\Product\<OS>.<Arch>.<BuildType>\test
  69 ```
  70 off the CoreCLR Repository.    The way the tests are expected to work is that you set the environment
  71 variable CORE_ROOT to this directory
  72 (you don't have to set CORE_LIBRARIES) and you can run any tests.  For example after building the tests
  73 (running build-test at the repository base) and running 'test\runtest') you can do the following
  74
  75 ```bat
  76     set PATH=%PATH%;%CoreCLR%\bin\Product\Windows_NT.x64.Debug
  77     set CORE_ROOT=%CoreCLR%\bin\tests\Windows_NT.x64.Debug\Tests\Core_Root
  78 ```
  79 sets you up so that corerun can run any of the test.   For example
  80 ```bat
  81     corerun bin\tests\Windows_NT.X64.Debug\GC\Features\Finalizer\finalizeio\finalizeio\finalizeio.exe
  82 ```
  83 runs the finalizerio test.