|
1 | 1 |
|
2 | | -# Using corerun To Run .NET Application |
| 2 | +# Using `corerun` To Run a .NET Application |
3 | 3 |
|
4 | | -In page [Using your .NET Runtime Build with dotnet cli](../using-dotnet-cli.md) gives detailed instructions on using the standard |
5 | | -command line host and SDK, dotnet.exe to run an application with the modified build of the |
6 | | -.NET 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. |
| 4 | +The page [Using your .NET Runtime Build with dotnet cli](../using-dotnet-cli.md) gives detailed instructions on using the standard |
| 5 | +command line host (that is, `dotnet.exe` or `dotnet`), and SDK to run an application with a local build of the |
| 6 | +.NET Runtime. This is the preferred mechanism for you to officially deploy |
| 7 | +your changes to other people since dotnet.exe and NuGet ensure that you end up with a consistent |
| 8 | +set of binaries that can work together. |
9 | 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. |
| 10 | +However, packing and unpacking the runtime binaries adds extra steps to the deployment process. When |
| 11 | +working in a tight edit-build-debug loop, these extra steps become cumbersome. |
12 | 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 runtime (that is coreclr.dll) and additionally any class library DLLs (e.g. System.Runtime.dll System.IO.dll ...). |
| 13 | +For this tight edit-build-debug loop, there is a simplified alternative to `dotnet` called `corerun` which |
| 14 | +does not know about NuGet at all. It just needs to find the .NET runtime (for example, `coreclr.dll`) |
| 15 | +and any class library assemblies (for example, `System.Runtime.dll`, `System.IO.dll`, etc). |
16 | 16 |
|
17 | | -It does this by looking at two environment variables. |
| 17 | +It does this using heuristics in the following order: |
18 | 18 |
|
| 19 | +1. Check if the user passed the `--clr-path` argument. |
| 20 | +1. Check if the `CORE_ROOT` environment variable is defined. |
| 21 | +1. Check if the .NET runtime binary is in the same directory as the `corerun` binary. |
19 | 22 |
|
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 directory to look for DLLS to resolve any assembly references. |
23 | | - It defaults CORE_ROOT if it is not specified. |
| 23 | +Regardless of which method is used to discover the .NET runtime binary, its location is used to discover |
| 24 | +both the .NET runtime binary and all base class library assemblies. Additional directories can be included |
| 25 | +in the set of class library assemblies by defining the `CORE_LIBRARIES` environment variable. |
24 | 26 |
|
25 | | -These simple rules can be used in a number of ways |
| 27 | +The above heuristics can be used in a number of ways. |
26 | 28 |
|
27 | 29 | ## Getting the class library from the shared system-wide runtime |
28 | 30 |
|
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 | +Consider that you already have a .NET application assembly called `HelloWorld.dll` and wish to run it. |
| 32 | +You could make such an assembly by using an officially installed .NET runtime with `dotnet new` and `dotnet build` in a `HelloWorld` directory. |
31 | 33 |
|
32 | | -If you execute the following |
33 | | -```cmd |
34 | | - set PATH=%PATH%;%CoreCLR%\artifacts\tests\coreclr\windows.x64.Debug\Tests\Core_Root\ |
35 | | - set CORE_LIBRARIES=%ProgramFiles%\dotnet\shared\Microsoft.NETCore.App\1.0.0 |
| 34 | +If you execute the following on Windows, the `HelloWorld` assembly will be run. |
36 | 35 |
|
| 36 | +```cmd |
| 37 | +set PATH=%PATH%;<repo_root>\artifacts\tests\coreclr\windows.x64.Debug\Tests\Core_Root\ |
| 38 | +set CORE_LIBRARIES=%ProgramFiles%\dotnet\shared\Microsoft.NETCore.App\1.0.0 |
37 | 39 |
|
38 | | - corerun HelloWorld.dll |
| 40 | +corerun HelloWorld.dll |
39 | 41 | ``` |
40 | 42 |
|
41 | | -for Linux use /usr/share for %Program Files% |
| 43 | +On non-Windows platforms, setting environment variables is different but the logic is identical. For example, on macOS use `/usr/local/share` for `%ProgramFiles%`. |
42 | 44 |
|
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) |
| 45 | +The `<repo_root>` represents the base of your dotnet/runtime repository. The first line puts the build output directory |
| 46 | +(your OS, architecture, and buildType may be different) and thus the `corerun` binary on your path. |
| 47 | +The second line tells `corerun` where to find class library assemblies. In this case we tell it to find them where |
| 48 | +the installation of `dotnet` placed its copy. The version number in the path may be different depending on what |
| 49 | +is currently installed on your system. |
48 | 50 |
|
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) |
| 51 | +Thus when you run `corerun HelloWorld.dll`, `corerun` knows where to get the assemblies it needs. |
| 52 | +Once you set the path and `CORE_LIBRARIES` environment variable, after a rebuild you can simply use |
| 53 | +`corerun` to run your application – you don't have to move any binaries around. |
52 | 54 |
|
53 | | -## Using corerun.exe to Execute a Published Application |
| 55 | +## Using `corerun` to Execute a Published Application |
54 | 56 |
|
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 |
| 57 | +When `dotnet publish` publishes an application, it deploys all the class libraries needed as well. |
| 58 | +Thus if you simply change the `CORE_LIBRARIES` definition in the previous instructions to point at |
| 59 | +that publication directory, but run the `corerun` from your build output, the effect will be that you |
| 60 | +run your new runtime getting all the other code needed from that deployed application. This is |
59 | 61 | very convenient because you don't need to modify the deployed application in order to test |
60 | 62 | your new runtime. |
61 | 63 |
|
62 | | -## How CoreCLR Tests use corerun.exe |
| 64 | +## How CoreCLR Tests use `corerun` |
63 | 65 |
|
64 | | -When you execute 'runtime/src/tests/build.cmd' one of the things that it does is set up a directory where it |
| 66 | +The test build script (`src/tests/build.cmd` or `src/tests/build.sh`) sets up a directory where it |
65 | 67 | gathers the CoreCLR that has just been built with the pieces of the class library that tests need. |
66 | 68 | It places this runtime in the directory |
67 | | -```cmd |
68 | | - runtime\artifacts\tests\coreclr\<OS>.<Arch>.<BuildType>\Tests\Core_Root |
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 src\tests\build from the repository base) and running 'src\tests\run') you can do the following |
| 69 | +`artifacts\tests\coreclr\<OS>.<Arch>.<BuildType>\Tests\Core_Root` |
| 70 | + starting at the repository root. The way the tests are expected to work is that you can set the environment |
| 71 | +variable `CORE_ROOT` to this directory – you don't have to set `CORE_LIBRARIES` since the test environment has copied all base class libraries assemblies to this `Core_Root` directory – and you can run any test. For example, after building the tests |
| 72 | +(running `src\tests\build` from the repository base), you can do the following on Windows to set up an environment where `corerun` can run any test. |
74 | 73 |
|
75 | 74 | ```cmd |
76 | | - set PATH=%PATH%;%CoreCLR%\artifacts\Product\windows.x64.Debug |
77 | | - set CORE_ROOT=%CoreCLR%\artifacts\tests\coreclr\windows.x64.Debug\Tests\Core_Root |
| 75 | +set PATH=%PATH%;<repo_root>\artifacts\Product\windows.x64.Debug |
| 76 | +set CORE_ROOT=<repo_root>\artifacts\tests\coreclr\windows.x64.Debug\Tests\Core_Root |
78 | 77 | ``` |
79 | | -sets you up so that corerun can run any of the test. For example |
| 78 | +For example, the following runs the finalizerio test on Windows. |
| 79 | + |
80 | 80 | ```cmd |
81 | | - corerun artifacts\tests\coreclr\windows.X64.Debug\GC\Features\Finalizer\finalizeio\finalizeio\finalizeio.exe |
| 81 | +corerun artifacts\tests\coreclr\windows.x64.Debug\GC\Features\Finalizer\finalizeio\finalizeio\finalizeio.dll |
82 | 82 | ``` |
83 | | -runs the finalizerio test. |
| 83 | + |
| 84 | +## Additional `corerun` options |
| 85 | + |
| 86 | +The `corerun` binary is designed to be a platform agnostic tool for quick testing of a locally built .NET runtime. |
| 87 | +This means the `corerun` binary must be able to feasibly exercise any scenario the official `dotnet` binary is capable |
| 88 | +of. It must also be able to help facilitate .NET runtime development and investigation of test failures. |
| 89 | +See `corerun --help` for additional details. |
| 90 | + |
| 91 | +**Options** |
| 92 | + |
| 93 | +`--clr-path <PATH>` - Pass the location of Core Root on the command line. |
| 94 | +- For example, `corerun --clr-path /usr/scratch/private_build HelloWorld.dll` |
| 95 | + |
| 96 | +`--property <PROPERTY>` - Supply a property to pass to the .NET runtime during initialization. |
| 97 | +- For example, `corerun --property System.GC.Concurrent=true HelloWorld.dll` |
| 98 | + |
| 99 | +`--debug` - Wait for a debugger to attach prior to loading the .NET runtime. |
| 100 | +- For example, `corerun --debug HelloWorld.dll` |
0 commit comments