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 | |
| 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')
22 files changed, 912 insertions, 230 deletions
diff --git a/Documentation/README.md b/Documentation/README.md index 7e29013bb2..1a3906b969 100644 --- a/Documentation/README.md +++ b/Documentation/README.md @@ -59,7 +59,7 @@ Book of the Runtime The Book of the Runtime is a set of chapters that go in depth into various interesting aspects of the design of the .NET Framework. -- [Book of the Runtime](botr/_tableOfContents.md) +- [Book of the Runtime](botr/README.md) For your convenience, here are a few quick links to popular chapters: diff --git a/Documentation/botr/_tableOfContents.md b/Documentation/botr/README.md index db4ffc121c..db4ffc121c 100644 --- a/Documentation/botr/_tableOfContents.md +++ b/Documentation/botr/README.md diff --git a/Documentation/botr/clr-abi.md b/Documentation/botr/clr-abi.md index cbd5fc903c..caa5c7add9 100644 --- a/Documentation/botr/clr-abi.md +++ b/Documentation/botr/clr-abi.md @@ -6,6 +6,8 @@ It describes requirements that the Just-In-Time (JIT) compiler imposes on the VM A note on the JIT codebases: JIT32 refers to the original JIT codebase that originally generated x86 code and was later ported to generate ARM code. Later, it was ported and re-architected to generate AMD64 code (making its name something of a confusing misnomer). This work is referred to as RyuJIT. RyuJIT is being ported to generate ARM64 code. JIT64 refers to the legacy codebase that supports AMD64. +CoreRT refers to https://github.com/dotnet/corert runtime that is optimized for AOT. The CoreRT ABI differs in a few details for simplicity and consistency across platforms. + # Getting started Read everything in the documented Windows ABI. @@ -289,6 +291,8 @@ On ARM and ARM64, for all second pass funclets (finally, fault, catch, and filte Catch, Filter, and Filter-handlers also get an Exception object (GC ref) as an argument (`REG_EXCEPTION_OBJECT`). On AMD64 it is the second argument and thus passed in RDX. On ARM and ARM64 this is the first argument and passed in R0. +CoreRT does not use PSPSym. For filter funclets the VM sets the frame register to be the same as the parent function. For second pass funclets the VM restores all non-volatile registers. The same convention is used across all platforms. + (Note that the JIT64 source code contains a comment that says, "The current CLR doesn't always pass the correct establisher frame to the funclet. Funclet may receive establisher frame of funclet when expecting that of original routine." It indicates this is the reason that a PSPSym is required in all funclets as well as the main function, whereas if the establisher frame was correctly reported, the PSPSym could be omitted in some cases.) ## Funclet Return Values @@ -468,7 +472,7 @@ Filters are invoked in the 1st pass of EH processing and as such execution might Duplicated clauses are a special set of entries in the EH tables to assist the VM. Specifically, if handler 'A' is also protected by an outer EH clause 'B', then the JIT must emit a duplicated clause, a duplicate of 'B', that marks the whole handler 'A' (which is now lexically disjoint for the range of code for the corresponding try body 'A') as being protected by the handler for 'B'. -Duplicated clauses are not needed for x86. +Duplicated clauses are not needed for x86 and for CoreRT ABI. During exception dispatch the VM uses these duplicated clauses to know when to skip any frames between the handler and its parent function. After skipping to the parent function, due to a duplicated clause, the VM searches for a regular/non-duplicate clause in the parent function. The order of duplicated clauses is important. They should appear after all of the main function clauses. They should still follow the normal sorting rules (inner-to-outer, top-to-bottom), but because the try-start/try-end will all be the same for a given handler, they should maintain the ordering, regarding inner-to-outer, as the corresponding original clause. diff --git a/Documentation/botr/exceptions.md b/Documentation/botr/exceptions.md index daa684bf8b..8e4b77a051 100644 --- a/Documentation/botr/exceptions.md +++ b/Documentation/botr/exceptions.md @@ -278,10 +278,16 @@ To use the callout filter, instead of this: write this: BOOL OneShot = TRUE; - - PAL_TRY + struct Param { + BSTR* pBSTR; + int length; + }; + struct Param param; + param.pBSTR = pBSTR; + + PAL_TRY(Param*, pParam, ¶m) { - length = SysStringLen(pBSTR); + pParam->length = SysStringLen(pParam->pBSTR); } PAL_EXCEPT_FILTER(CallOutFilter, &OneShot) { diff --git a/Documentation/botr/garbage-collection.md b/Documentation/botr/garbage-collection.md index 9e16131114..789c4e92ff 100644 --- a/Documentation/botr/garbage-collection.md +++ b/Documentation/botr/garbage-collection.md @@ -2,7 +2,7 @@ Garbage Collection Design ========================= Author: Maoni Stephens ([@maoni0](https://github.com/maoni0)) - 2015 -Note: See the The Garbage Collection Handbook referenced in the resources section at the end of this document to learn more about garbage collection topics. +Note: See _The Garbage Collection Handbook_ (referenced in the resources section at the end of this document) to learn more about garbage collection topics. Component Architecture ====================== diff --git a/Documentation/building/crossgen.md b/Documentation/building/crossgen.md index c74a5e680a..bf013e2285 100644 --- a/Documentation/building/crossgen.md +++ b/Documentation/building/crossgen.md @@ -7,7 +7,7 @@ Introduction When you create a .NET assembly using C# compiler, your assembly contains only MSIL code. When the app runs, the JIT compiler translates the MSIL code into native code, before the CPU can execute them. This execution model has some advantages. For example, your assembly code can be portable across all platforms and architectures that support .NET Core. -However, this portability comes with a performance penalty. Your app starts up slower, because the JIT compiler has to spend time to translate the code. +However, this portability comes with a performance cost. Your app starts up more slowly, because the JIT compiler has to spend time to translate the code. To help make your app start up faster, CoreCLR includes a tool called CrossGen, which can pre-compile the MSIL code into native code. @@ -18,7 +18,7 @@ If you build CoreCLR yourself, the CrossGen tool (`crossgen.exe` on Windows, or If you install CoreCLR using a NuGet package, you can find CrossGen in the `tools` folder of the NuGet package. Regardless of how you obtain CrossGen, it is very important that it must match other CoreCLR binaries. -- If you build CrossGen yourself, you should use it with coreclr and mscorlib generated from the same build. Do not attempt to mix CrossGen from one build with binaries generated from another build. +- If you build CrossGen yourself, you should use it with runtime and `System.Private.CoreLib.dll` generated from the same build. Do not attempt to mix CrossGen from one build with binaries generated from another build. - If you install CrossGen from NuGet, make sure you use CrossGen from exactly the same NuGet package as the rest of your CoreCLR binaries. Do not attempt to mix binaries from multiple NuGet packages. If you do not follow the above rules, you are likely to encounter errors while running CrossGen. @@ -26,26 +26,30 @@ If you do not follow the above rules, you are likely to encounter errors while r Using CrossGen -------------- -In most cases, the build script automatically runs CrossGen to create the native image for mscorlib. -When this happens, you will find both `mscorlib.dll` and `mscorlib.ni.dll` in your output directory. -`mscorlib.dll` is the MSIL assembly created by the C# compiler, while `mscorlib.ni.dll` is the native image that contains CPU-specific code. -Once the build is done, you only need `mscorlib.ni.dll` to use CoreCLR. -As a matter of fact, most CoreCLR NuGet packages contain only `mscorlib.ni.dll`, without `mscorlib.dll` +In most cases, the build script automatically runs CrossGen to create the native image for `System.Private.CoreLib.dll` and `mscorlib.dll`. +When this happens, you will find `System.Private.CoreLib.ni.dll` and `mscorlib.ni.dll` in your output directory. +`System.Private.CoreLib.dll` and `mscorlib.dll` are the MSIL assemblies created by the C# compiler, while `System.Private.CoreLib.ni.dll` and `mscorlib.ni.dll` are the native images that contain CPU-specific code. +Once the build is done, you only need `System.Private.CoreLib.ni.dll` and `mscorlib.ni.dll` to use CoreCLR. +The original MSIL assemblies are no longer needed by the runtime. -If for some reason you did not get `mscorlib.ni.dll` with the rest of your CoreCLR, you can easily create it yourself using CrossGen. -First, make sure you have `crossgen.exe` (on Windows) or `crossgen` (other platforms) in the same directory as `mscorlib.dll`. -Then, run one of the following two commands (first command for Windows, second command for other platforms): +If you installed CoreCLR from a NuGet package, `System.Private.CoreLib.ni.dll` and `mscorlib.ni.dll` are included in the package. +If for some reason you did not get `System.Private.CoreLib.dll` or `mscorlib.ni.dll` with the rest of your CoreCLR, you can easily create it yourself using CrossGen. + +If your `System.Private.CoreLib.dll`, `mscorlib.dll` and JIT compiler (`clrjit.dll` on Windows or `libclrjit.*` on other platforms) are all in the same directory as CrossGen itself, you can compile `System.Private.CoreLib.dll` and `mscorlib.dll` with the following commands (first two commands for Windows, next two commands for other platforms): + + .\crossgen.exe System.Private.CoreLib.dll .\crossgen.exe mscorlib.dll + ./crossgen System.Private.CoreLib.dll ./crossgen mscorlib.dll -To create native images for other assemblies, the command line is slightly more complex: +If your files are scattered in different directories, or if you want to create native images for other assemblies, the command line is slightly more complex: - .\crossgen.exe /Platform_Assemblies_Paths "path1;path2;..." assemblyName.dll - ./crossgen /Platform_Assemblies_Paths "path1:path2:..." assemblyName.dll + .\crossgen.exe /JITPath path\clrjit.dll /Platform_Assemblies_Paths "path1;path2;..." path\assemblyName.dll + ./crossgen -JITPath path/libclrjit.so -Platform_Assemblies_Paths "path1:path2:..." path/assemblyName.dll -The /Platform_Assemblies_Paths is used to specify the location of all the dependencies of the input assembly. -You should use full paths for this locations. Relative paths do not always work. +The /Platform_Assemblies_Paths is used to specify the locations of all the dependencies of the input assembly, including the input assembly itself. +You should use full paths for these locations. Relative paths do not always work. If there are multiple paths, separate them with semicolons (`;`) on Windows, or colons (`:`) on non-Windows platforms. It is generally a good idea to enclose the path list in quotes to protect any special characters from the shell. @@ -53,14 +57,13 @@ Using native images ------------------- Running CrossGen on an assembly creates a "native image" file, with the extension of `.ni.dll` or `.ni.exe`. -You should include the native images in your app, at the same location where you normally install the MSIL assemblies. -Once you have included native images, you do not need to include the original MSIL assemblies in your apps. +You should include the native images in your app, either by replacing the original MSIL assmblies with the native images, or by putting the native images next to the MSIL assemblies. +When the native images are present, CoreCLR runtime will automatically use it instead of the original MSIL assemblies. Common errors ------------- The following are some of the command errors while creating or using native images: -- "Could not load file or assembly 'mscorlib.dll' or one of its dependencies. The native image could not be loaded, because it was generated for use by a different version of the runtime. (Exception from HRESULT: 0x80131059)": This error indicates that there is a mismatch between CrossGen and mscorlib.ni.dll. Make sure to use CrossGen and mscorlib.ni.dll from the same build or NuGet package. - "Error: Could not load file or assembly '...' or one of its dependencies. The system cannot find the file specified. (Exception from HRESULT: 0x80070002)": CrossGen wasn't able to find a particular dependency that it needs. Verify that you have the assembly specified in the error message, and make sure its location is included in `/Platform_Assemblies_Paths`. -- CoreCLR unable to initialize: While there are many possible causes of this error, one possibility is a mismatch between mscorlib.ni.dll and coreclr.dll (or libcoreclr.so). Make sure they come from the same build or NuGet package. -- "Unable to load Jit Compiler": Please get a copy of `clrjit.dll` (or `libclrjit.so` or `libclrjit.dylib`, depending on your platform), and place it in the same directory as CrossGen. You can either build `clrjit.dll` yourself, or get it from `Microsoft.NETCore.Jit` NuGet package. To avoid possible issues, please use `clrjit.dll` from the same build as `crossgen.exe` if possible. +- CoreCLR unable to initialize: While there are many possible causes of this error, one possibility is a mismatch between System.Private.CoreLib.ni.dll and coreclr.dll (or libcoreclr.so). Make sure they come from the same build or NuGet package. +- "Unable to load Jit Compiler": Please get a copy of `clrjit.dll` (or `libclrjit.so` or `libclrjit.dylib`, depending on your platform), and place it in the same directory as CrossGen (or use /JITPath option). You can either build `clrjit.dll` yourself, or get it from `Microsoft.NETCore.Jit` NuGet package. To avoid possible issues, please use `clrjit.dll` from the same build as `crossgen.exe` if possible. diff --git a/Documentation/building/linux-instructions.md b/Documentation/building/linux-instructions.md index c948ecde20..ddd4274b83 100644 --- a/Documentation/building/linux-instructions.md +++ b/Documentation/building/linux-instructions.md @@ -47,6 +47,10 @@ ellismg@linux:~$ sudo apt-get install cmake llvm-3.5 clang-3.5 lldb-3.6 lldb-3.6 You now have all the required components. +If you are using Fedora 23 or 24, then you will need to install the following packages: + +`$ sudo dnf install llvm cmake clang lldb-devel libunwind-devel lttng-ust-devel libuuid-devel libicu-devel` + Git Setup --------- @@ -57,6 +61,10 @@ Set the maximum number of file-handles To ensure that your system can allocate enough file-handles for the corefx build run `sysctl fs.file-max`. If it is less than 100000, add `fs.file-max = 100000` to `/etc/sysctl.conf`, and then run `sudo sysctl -p`. +On Fedora 23 or 24: + +`$ sudo dnf install mono-devel` + Build the Runtime and Microsoft Core Library ============================================= diff --git a/Documentation/building/osx-instructions.md b/Documentation/building/osx-instructions.md index 6d3469b2d9..9e6b913675 100644 --- a/Documentation/building/osx-instructions.md +++ b/Documentation/building/osx-instructions.md @@ -51,7 +51,25 @@ The CoreFX cryptography libraries are built on OpenSSL. The version of OpenSSL i ```sh brew install openssl -brew link --force openssl + +# We need to make the runtime libraries discoverable, as well as make +# pkg-config be able to find the headers and current ABI version. +# +# Ensure the paths we will need exist +mkdir -p /usr/local/lib/pkgconfig + +# The rest of these instructions assume a default Homebrew path of +# /usr/local/opt/<module>, with /usr/local being the answer to +# `brew --prefix`. +# +# Runtime dependencies +ln -s /usr/local/opt/openssl/lib/libcrypto.1.0.0.dylib /usr/local/lib/ +ln -s /usr/local/opt/openssl/lib/libssl.1.0.0.dylib /usr/local/lib/ + +# Compile-time dependences (for pkg-config) +ln -s /usr/local/opt/openssl/lib/pkgconfig/libcrypto.pc /usr/local/lib/pkgconfig/ +ln -s /usr/local/opt/openssl/lib/pkgconfig/libssl.pc /usr/local/lib/pkgconfig/ +ln -s /usr/local/opt/openssl/lib/pkgconfig/openssl.pc /usr/local/lib/pkgconfig/ ``` Build the Runtime and Microsoft Core Library diff --git a/Documentation/building/testing-with-corefx.md b/Documentation/building/testing-with-corefx.md index 6609a0aaa7..4f9886f78d 100644 --- a/Documentation/building/testing-with-corefx.md +++ b/Documentation/building/testing-with-corefx.md @@ -7,7 +7,11 @@ It may be valuable to use CoreFX tests to validate your changes to CoreCLR or ms As part of building tests, CoreFX restores a copy of the runtime from myget, in order to update the runtime that is deployed, a special build property `BUILDTOOLS_OVERRIDE_RUNTIME` can be used. If this is set, the CoreFX testing targets will copy all the files in the folder it points to into the test folder, overwriting any files that exist. -To run tests, follow the procedure for [running tests in CoreFX](https://github.com/dotnet/corefx/blob/master/Documentation/building/windows-instructions.md). You can pass `/p:BUILDTOOLS_OVERRIDE_RUNTIME=<path-to-coreclr>\bin\Product\Windows_NT.x64.Release` to build.cmd to set this property. +To run tests, follow the procedure for [running tests in CoreFX](https://github.com/dotnet/corefx/blob/master/Documentation/building/windows-instructions.md). You can pass `/p:BUILDTOOLS_OVERRIDE_RUNTIME=<path-to-coreclr>\bin\Product\Windows_NT.x64.Release` to build.cmd to set this property, e.g. (note the space between the "--" and the "/p" option): + +``` +build.cmd -Release -- /p:BUILDTOOLS_OVERRIDE_RUNTIME=<root of coreclr repo>\bin\Product\Windows_NT.x64.Checked +``` **FreeBSD, Linux, NetBSD, OS X** diff --git a/Documentation/building/viewing-jit-dumps.md b/Documentation/building/viewing-jit-dumps.md index 5303b47626..607c5e63a0 100644 --- a/Documentation/building/viewing-jit-dumps.md +++ b/Documentation/building/viewing-jit-dumps.md @@ -35,7 +35,7 @@ The first thing we want to do is setup the .NET Core app we want to dump. Here a } ``` -You can find a list of RIDs and their corresponding OSes [here](http://dotnet.github.io/docs/core-concepts/rid-catalog.html). +You can find a list of RIDs and their corresponding OSes [here](https://docs.microsoft.com/en-us/dotnet/articles/core/rid-catalog). * Edit `Program.cs`, and call the method(s) you want to dump in there. Make sure they are, directly or indirectly, called from `Main`. In this example, we'll be looking at the disassembly of our custom function `InefficientJoin`: diff --git a/Documentation/building/windows-instructions.md b/Documentation/building/windows-instructions.md index f68ed2c8c7..8ba021bbf9 100644 --- a/Documentation/building/windows-instructions.md +++ b/Documentation/building/windows-instructions.md @@ -1,21 +1,19 @@ Build CoreCLR on Windows ======================== -These instructions will lead you through building CoreCLR and running a "Hello World" demo on Windows. +These instructions will lead you through building CoreCLR. -Environment -=========== +---------------- +#Environment You must install several components to build the CoreCLR and CoreFX repos. These instructions were tested on Windows 7+. -Visual Studio -------------- +## Visual Studio Visual Studio must be installed. Supported versions: +- [Visual Studio 2015](https://www.visualstudio.com/downloads/visual-studio-2015-downloads-vs) (Community, Professional, Enterprise). The community version is completely free. -- [Visual Studio 2015](https://www.visualstudio.com/downloads/visual-studio-2015-downloads-vs) (Community, Professional, Enterprise) - -To debug managed code, ensure you have installed atleast [Visual Studio 2015 Update 3](https://www.visualstudio.com/en-us/news/releasenotes/vs2015-update3-vs). +To debug managed code, ensure you have installed at least [Visual Studio 2015 Update 3](https://www.visualstudio.com/en-us/news/releasenotes/vs2015-update3-vs). Make sure that you install "VC++ Tools". By default, they will not be installed. @@ -23,166 +21,100 @@ To build for Arm32, you need to have [Windows SDK for Windows 10](https://develo Visual Studio Express is not supported. -CMake ------ +##CMake The CoreCLR repo build has been validated using CMake 3.5.2. - Install [CMake](http://www.cmake.org/download) for Windows. -- Add it to the PATH environment variable. +- Add its location (e.g. C:\Program Files (x86)\CMake\bin) to the PATH environment variable. + The installation script has a check box to do this, but you can do it yourself after the fact + following the instructions at [Adding to the Default PATH variable](#adding-to-the-default-path-variable) + + +##Python -Python ---------- Python is used in the build system. We are currently using python 2.7.9, although any recent (2.4+) version of Python should work, including Python 3. - Install [Python](https://www.python.org/downloads/) for Windows. -- Add it to the PATH environment variable. - -PowerShell ----------- -PowerShell is used in the build system. Ensure that it is accessible via the PATH environment variable. Typically this is %SYSTEMROOT%\System32\WindowsPowerShell\v1.0\. +- Add its location (e.g. C:\Python*\) to the PATH environment variable. + The installation script has a check box to do this, but you can do it yourself after the fact + following the instructions at [Adding to the Default PATH variable](#adding-to-the-default-path-variable) -Powershell version must be 3.0 or higher. This should be the case for Windows 8 and later builds. -- Windows 7 SP1 can install Powershell version 4 [here](https://www.microsoft.com/en-us/download/details.aspx?id=40855). +##Git -Git Setup ---------- +For actual user operations, it is often more convinient to use the GIT features built into Visual Studio 2015. +However the CoreCLR and the tests use the GIT command line utilities directly so you need to install them +for these to work properly. You can get it from -Clone the CoreCLR and CoreFX repositories (either upstream or a fork). +- Install [Git For Windows](https://git-for-windows.github.io/) +- Add its location (e.g. C:\Program Files\Git\cmd) to the PATH environment variable. + The installation script has a check box to do this, but you can do it yourself after the fact + following the instructions at [Adding to the Default PATH variable](#adding-to-the-default-path-variable) -```bat -C:\git>git clone https://github.com/dotnet/coreclr -C:\git>git clone https://github.com/dotnet/corefx -``` +##PowerShell +PowerShell is used in the build system. Ensure that it is accessible via the PATH environment variable. +Typically this is %SYSTEMROOT%\System32\WindowsPowerShell\v1.0\. -This guide assumes that you've cloned the CoreCLR and CoreFX repositories into C:\git using the default repo names. If your setup is different, you'll need to pay attention to the commands you run. The guide will always show you the current directory. +Powershell version must be 3.0 or higher. This should be the case for Windows 8 and later builds. +- Windows 7 SP1 can install Powershell version 4 [here](https://www.microsoft.com/en-us/download/details.aspx?id=40855). -The repository is configured to allow Git to make the right decision about handling CRLF. Specifically, if you are working on **Windows**, please ensure that **core.autocrlf** is set to **true**. On **non-Windows** platforms, please set it to **input**. +##DotNet Core SDK +While not strictly needed to build or tests the .NET Core repository, having the .NET Core SDK installed lets +you use the dotnet.exe command to run .NET Core applications in the 'normal' way. We use this in the +[Using Your Build](Documentation/workflow/UsingYourBuild.md) instructions. Visual Studio 2015 (update 3) should have +installed the .NET Core SDK, but in case it did not you can get it from the [Installing the .Net Core SDK](https://www.microsoft.com/net/core) page. -Demo directory --------------- +##Adding to the default PATH variable -In order to keep everything tidy, create a new directory for the files that you will build or acquire. +The commands above need to be on your command lookup path. Some installers will automatically add them to +the path as part of installation, but if not here is how you can do it. -```bat -c:\git>mkdir \coreclr-demo\runtime -c:\git>mkdir \coreclr-demo\ref +You can of course add a directory to the PATH environment variable with the syntax +``` + set PATH=%PATH%;DIRECTORY_TO_ADD_TO_PATH ``` +However the change above will only last until the command windows closes. You can make your change to +the PATH variable persistent by going to Control Panel -> System And Security -> System -> Advanced system settings -> Environment Variables, +and select the 'Path' variable in the 'System variables' (if you want to change it for all users) or 'User variables' (if you only want +to change it for the currnet user). Simply edit the PATH variable's value and add the directory (with a semicolon separator). -Build the Runtime -================= +------------------------------------- +#Building -To build CoreCLR, run `build.cmd` from the root of the coreclr repository. This will do a x64/Debug build of CoreCLR, its native components, mscorlib.dll, and the tests. +Once all the necessary tools are in place, building is trivial. Simply run build build.cmd script that lives at +the base of the repository. - C:\git\coreclr>build -rebuild +```bat + .\build [Lots of build spew] - Repo successfully built. - Product binaries are available at C:\git\coreclr\bin\Product\Windows_NT.x64.debug Test binaries are available at C:\git\coreclr\bin\tests\Windows_NT.x64.debug +``` -**Note:** To avoid building the tests, pass the 'skiptestbuild' option to build. - -**build -?** will list supported parameters. - -Check the build output. +As shown above the product will be placed in - Product binaries will be dropped in `bin\Product\<OS>.<arch>.<flavor>` folder. - A NuGet package, Microsoft.Dotnet.CoreCLR, will be created under `bin\Product\<OS>.<arch>.<flavor>\.nuget` folder. - Test binaries will be dropped under `bin\Tests\<OS>.<arch>.<flavor>` folder -You will see several files. The interesting ones are: - -- `corerun`: The command line host. This program loads and starts the CoreCLR runtime and passes the managed program you want to run to it. -- `coreclr.dll`: The CoreCLR runtime itself. -- `mscorlib.dll`: The core managed library for CoreCLR, which contains all of the fundamental data types and functionality. - -Copy these files into the demo directory. - -```bat -C:\git\coreclr>copy bin\Product\Windows_NT.x64.debug\clrjit.dll \coreclr-demo\runtime -C:\git\coreclr>copy bin\Product\Windows_NT.x64.debug\CoreRun.exe \coreclr-demo\runtime -C:\git\coreclr>copy bin\Product\Windows_NT.x64.debug\coreclr.dll \coreclr-demo\runtime -C:\git\coreclr>copy bin\Product\Windows_NT.x64.debug\mscorlib.dll \coreclr-demo\runtime -C:\git\coreclr>copy bin\Product\Windows_NT.x64.debug\System.Private.CoreLib.dll \coreclr-demo\runtime -``` - -Build the Framework -=================== - -Build the framework out of the corefx directory. +By default build generates a 'Debug' build type, that has extra checking (assert) compiled into it. You can +also build the 'release' version which does not have these checks - c:\git\corefx>build.cmd +The build places logs in `bin\Logs` and these are useful when the build fails. - [Lots of build spew] - - 0 Warning(s) - 0 Error(s) - Time Elapsed 00:03:14.53 - Build Exit Code = 0 - -It's also possible to add -rebuild to build.cmd to force it to delete the previously built assemblies. - -For the purposes of this demo, you need to copy a few required assemblies to the demo folder. - -```bat -C:\git\corefx>copy bin\Windows_NT.AnyCPU.Debug\System.Console\System.Console.dll \coreclr-demo\runtime -C:\git\corefx>copy bin\Windows_NT.AnyCPU.Debug\System.Diagnostics.Debug\System.Diagnostics.Debug.dll \coreclr-demo\runtime -C:\git\corefx>copy bin\AnyOS.AnyCPU.Debug\System.IO\System.IO.dll \coreclr-demo\runtime -C:\git\corefx>copy bin\AnyOS.AnyCPU.Debug\System.IO.FileSystem.Primitives\System.IO.FileSystem.Primitives.dll \coreclr-demo\runtime -C:\git\corefx>copy bin\AnyOS.AnyCPU.Debug\System.Runtime\System.Runtime.dll \coreclr-demo\runtime -C:\git\corefx>copy bin\AnyOS.AnyCPU.Debug\System.Runtime.InteropServices\System.Runtime.InteropServices.dll \coreclr-demo\runtime -C:\git\corefx>copy bin\AnyOS.AnyCPU.Debug\System.Text.Encoding\System.Text.Encoding.dll \coreclr-demo\runtime -C:\git\corefx>copy bin\AnyOS.AnyCPU.Debug\System.Text.Encoding.Extensions\System.Text.Encoding.Extensions.dll \coreclr-demo\runtime -C:\git\corefx>copy bin\AnyOS.AnyCPU.Debug\System.Threading\System.Threading.dll \coreclr-demo\runtime -C:\git\corefx>copy bin\AnyOS.AnyCPU.Debug\System.Threading.Tasks\System.Threading.Tasks.dll \coreclr-demo\runtime -``` - -You also need to copy reference assemblies, which will be used during compilation. - -```bat -C:\git\corefx>copy bin\ref\System.Runtime\4.0.0.0\System.Runtime.dll \coreclr-demo\ref -C:\git\corefx>copy bin\ref\System.Console\4.0.0.0\System.Console.dll \coreclr-demo\ref -``` - -Compile the Demo -================ +The build places all of its output in the `bin` directory, so if you remove that directory you can force a +full rebuild. -Now you need a Hello World application to run. You can write your own, if you'd like. Here's a very simple one: +Build has a number of options that you can learn about using build -?. Some of the more important options are -```C# -using System; + * skiptests - don't build the tests. This can shorten build times quite a bit, but means you can't run tests. + * release - build the 'Release' build type that does not have extra development-time checking compiled in. + * -rebuild - force the build not to be incremental but to recompile everything. + You want this if you are going to do performance testing on your build. -public class Program -{ - public static void Main() - { - Console.WriteLine("Hello, Windows"); - Console.WriteLine("Love from CoreCLR."); - } -} -``` - -Personally, I'm partial to the one on corefxlab which will print a picture for you. Download the [corefxlab demo](https://raw.githubusercontent.com/dotnet/corefxlab/master/demos/CoreClrConsoleApplications/HelloWorld/HelloWorld.cs) to `\coreclr-demo`. - -Then you just need to build it, with csc, the .NET Framework C# compiler. It may be easier to do this step within the "Developer Command Prompt for VS2015", if csc is not in your path. Because you need to compile the app against the .NET Core surface area, you need to pass references to the contract assemblies you restored using NuGet: - -```bat -csc /nostdlib /noconfig /r:ref\System.Runtime.dll /r:ref\System.Console.dll /out:runtime\hello.exe hello.cs -``` - -Run the demo -============ - -You're ready to run Hello World! To do that, run corerun, passing the path to the managed exe, plus any arguments. In this case, no arguments are necessary. - -```bat -C:\coreclr-demo>cd runtime -C:\coreclr-demo\runtime>CoreRun.exe hello.exe -``` +See [Using Your Build](../workflow/UsingYourBuild.md) for instructions on running code with your build. -If `CoreRun.exe` fails for some reason, you will see an empty output. To diagnose the issue, you can use `/v` to switch verbose mode on: `CoreRun.exe /v hello.exe`. +See [Running Tests](../workflow/RunningTests.md) for instructions on running the tests. -Over time, this process will get easier. Thanks for trying out CoreCLR. Feel free to try a more interesting demo. diff --git a/Documentation/coding-guidelines/clr-code-guide.md b/Documentation/coding-guidelines/clr-code-guide.md index 84ba5f2321..c1f69b04d2 100644 --- a/Documentation/coding-guidelines/clr-code-guide.md +++ b/Documentation/coding-guidelines/clr-code-guide.md @@ -27,7 +27,7 @@ Written in 2006, by: * [2.1.10 How to know if a function can trigger a GC](#2.1.10) * [2.1.10.1 GC_NOTRIGGER/TRIGGERSGC on a scope](#2.1.10.1) * [2.2 Are you using holders to track your resources?](#2.2) - * [2.2.1 What are holders and we are they important?](#2.2.1) + * [2.2.1 What are holders and why are they important?](#2.2.1) * [2.2.2 An example of holder usage:](#2.2.2) * [2.2.3 Common Features of Holders](#2.2.3) * [2.2.4 Where do I find a holder?](#2.2.4) @@ -462,7 +462,7 @@ One difference between the standalone TRIGGERSGC and the contract GC_TRIGGERS: t ## <a name="2.2"/>2.2 Are you using holders to track your resources? -### <a name="2.2.1"/>2.2.1 What are holders and we are they important? +### <a name="2.2.1"/>2.2.1 What are holders and why are they important? The CLR team has coined the name **holder** to refer to the infrastructure that encapsulates the common grunt work of writing robust **backout code**. **Backout code** is code that deallocate resources or restore CLR data structure consistency when we abort an operation due to an error or an asynchronous event. Oftentimes, the same backout code will execute in non-error paths for resources allocated for use of a single scope, but error-time backout is still needed even for longer lived resources. @@ -616,6 +616,7 @@ Holders consistently release on destruction – that's their whole purpose. Sadl #### <a name="2.2.8.4"/>2.2.8.4 Critical Section Holder **Wrong:** + pCrst->Enter(); pCrst->Leave(); diff --git a/Documentation/design-docs/multi-reg-call-nodes.md b/Documentation/design-docs/multi-reg-call-nodes.md new file mode 100644 index 0000000000..e89ca2af62 --- /dev/null +++ b/Documentation/design-docs/multi-reg-call-nodes.md @@ -0,0 +1,230 @@ +Support for multiple destination regs, GT_CALL and GT_RETURN nodes that return a value in multiple registers: +============================================================================================================ + +The following targets allow a GT_CALL/GT_RETURN node to return a value in more than one register: + +x64 Unix: +Structs of size betwee 9-16 bytes will be returned in RAX/RDX and/or XMM0/XMM1. + +Arm64: +HFA structs will be returned in 1-4 successive VFP registers s0-s3 or d0-d3. +Structs of size 16-bytes will be returned in two return registers. + +Arm32: +Long type value is returned in two return registers r0 and r1. +HFA structs will be returned in 1-4 successive VFP registers s0-s3 or d0-d3 + +x86: +Long type value is returned in two return registers EDX and EAX. + +Legacy backend used reg-pairs for representing long return value on 32-bit targets, which makes reg allocation and codegen complex. Also this approach doesn't scale well to types that are returned in more than 2 registers. Arm32 HFA support in Legacy backend requires that HFA return value of a call is always stored to local in memory and with the local marked as not promotable. Original implementation of multi-reg return of structs on x64 Unix was similar to Arm32 and further LSRA was not ware of multi-reg call nodes because of which Codegen made some assumptions (e.g. multi-reg return value of a call node is never spilled) that are not always guaranteed. + +This doc proposes new IR forms and an implementation design to support multi-reg call nodes in RyuJIT that is scalable without the limitations/complexity that Legacy backend implementation had. + +Post Importation IR Forms +------------------------- +In importer any call returning a (struct or long type) value in two or more registers is forced to a temp +and temp is used in place of call node subsequently in IR. Note that creation of 'tmp' is avoided if return value of call is getting assigned to a local in IL. + +``` +// tmp = GT_CALL, where tmp is of TYP_STRUCT or TYP_LONG +GT_ASG(TYP_STRUCT or TYP_LONG, tmp, GT_CALL node) +``` + +Similarly importer will force IR of GT_RETURN node returning a value in multiple return registers to be +of the following form if operand of GT_RETURN is anything but a lclVar. + +``` +GT_ASG(TYP_STRUCT or TYP_LONG, tmp, op1) +GT_RETURN(tmp) +``` + +Post struct promotion IR forms +------------------------------ +Before global morph of basic blocks, struct promotion takes place. It will give rise to the following +three cases: + +Case 1: +tmp is not struct promoted or Type Dependently Promoted (P-DEP). + +Case 2: +tmp is Type Independently Promoted (P-INDEP) but its field layout doesn't match the layout of return registers or tmp is P-FULL promoted struct (e.g. SIMD type structs). + +For example, tmp could be a struct of 4 integers. But on x64 unix, two fields of such a struct +will be returned in one 8-byte return register. + +Case 3: +tmp is P-INDEP promoted and its field layout matches the layout of return registers. That is one promoted field will get mapped to a single, un-shared register in the ABI for returning values. +An example is a struct containing two fields of `{TYP_REF, TYP_DOUBLE} `on X64 Unix. + +Post Global Morph, IR forms of tmp=GT_CALL where tmp is of TYP_STRUCT +--------------------------------------------------------------------- +Case 3 is morphed into + + `GT_STORE_MULTI_VAR(TYP_STRUCT, <FieldLcl1, FieldLcl2, FieldLcl3, FieldLcl4>, op1 = GT_CALL)` + + Where FieldLcl[1..4] are lcl numbers of P-INDEP promoted fields of tmp. The limit of 2-4 locals + is statically dependent on target platform/architecture. + + GT_STORE_MULTI_VAR is a new GenTree node to represent the store operation to 2-4 locals + using multi-reg/mem value of a call/lclvar respectively. It also will have additional fields + to store the registers into which FieldLcl[1..4] need to be stored and also a spill mask + to indicate which of the locals needs to be spilled. + + During codegen, return value of call in multiple return registers need to be stored to the + corresponding registers of the locals by properly handling any circular dependencies. + +Case 1 is morphed as + `GT_OBJ(&tmp) = GT_CALL` + + Post rationalization this will get converted to GT_STORE_OBJ/BLK(&tmp, GT_CALL) and + block op codegen will special case for multi-reg call case. This case simpler because, although it is + consuming multiple registers from the call, it doesn't have the complication of multiple + destination registers. + +Case 2 can be handled one of the following two ways + a) Force tmp to memory and morph it as in case 1 above + b) Create 2-4 temp locals matching the type of respective return registers of GT_CALL and + use them to create following IR + +``` +GT_STORE_MULTI_VAR(TYP_STRUCT, <tmpLcl1, tmpLcl2, tmpLcl3, tmpLcl4>, op1 = GT_CALL) +``` + + Example: say on x64 unix, return type is a struct with 3 fields: TYP_INT, TYP_INT and TYP_REF. + First two fields would be combined into a single local of TYP_LONG and third field would + would go into a single local of TYP_REF. + + Additional IR nodes can be created to extract/assemble fields of tmp struct from individual tmpLcls. + +Platform agnostic ReturnTypeDesc on a GT_CALL node +-------------------------------------------------- +Every GT_CALL node will have a light-weight ReturnTypeDesc that provides a platform independent interface to query the following: + - Respective return types of a multi-reg return value + - Respective Return register numbers in which the value is returned. + +ReturnTypeDesc is initialized during importation while creating GenTreeCall node. + +GT_CALL node is augmented with the following additional state: + gtOtherRegs - an array of MAX_RET_REG_COUNT-1 reg numbers of multi-reg return. gtRegNum field + will always be the first return reg. + gtSpillFlags - an array to hold GTF_SPILL/GTF_SPILLED state of each reg. This allows us to + spill/reload individual return registers of a multi-reg call node work. + +Post Global Morph, IR forms of GT_RETURN(tmp) where tmp is of TYP_STRUCT +------------------------------------------------------------------------ +Case 3 is morphed into + +``` + GT_RETURN (TYP_STRUCT, op1 = GT_MULTI_VAR(TYP_STRUCT, <Fieldlcl1, FieldLcl2, FieldLcl3, FieldLcl4>)) +``` + + Where FieldLcl[1..4] are lcl numbers of independently promoted fields of tmp and + GT_MULTI_VAR is a new node that represents 2-4 independent local vars. + +Case 1 remains unchanged + + `GT_RETURN(TYP_STRUCT, op1 = tmp)` + +Case 2 is handled as follows: + a) Force tmp to memory and morph it as in case 1 above + b) Create 2-4 temp locals matching the type of respective return registers of GT_RETURN and + use them to extract individual fields from tmp and morph it as in case 3 above. + + tmpLcl1 = GenTree Nodes to extract first 8-bytes from tmp + tmpLcl2 = GenTree Nodes to extract next 8-bytes from tmp and so on + +``` + GT_RETURN(TYP_STRUCT, op1 = GT_STORE_MULTI_VAR(TYP_STRUCT, <tmpLcl1, tmpLcl2, tmpLcl3, tmpLcl4>, tmp)) +``` + + +Post Lowering, IR forms of GT_CALL node returning TYP_LONG value +---------------------------------------------------------------- +During Lowering, such call nodes are lowered into tmp=GT_CALL if the return value of call node is not already assigned to a local. Further tmp is decomposed into GT_LONG. + +Post IR lowering, GT_CALL will be transformed into + +``` + GT_STORE_LCL_VAR(TYP_LONG, lcl Num of tmp, op1 = GT_CALL) +``` + + where tmp is decomposed into GT_LONG(GT_LCL_VAR(tmpHi), GT_LCL_VAR(tmpLo)) + and finally GT_STORE_LCL_VAR is transformed into + +``` + GT_STORE_MULTI_VAR(TYP_LONG, <tmpHi, tmpLo>, op1=GT_CALL) +``` + + where tmpHi and tmpLo are promoted lcl fields of tmp. + +Post Lowering, IR forms of GT_RETURN(tmp) where tmp is of TYP_LONG +------------------------------------------------------------------ +LclVar tmp will be decomposed into two locals and the resulting IR would be GT_RETURN(GT_LONG) + +Lowering Register specification +-------------------------------- +DstCount of GT_CALL node returning multi-reg return value will be set to 2 or 3 or 4 depending on the number of return registers and its dstCandidates is set to the fixed mask of return registers. + +SrcCount and DstCount of GT_STORE_MULTI_VAR will be set 2 or 3 or 4 depending on the number of locals to which a value is assigned. Note that those locals that do not require a value to be assigned are represented as BAD_VAR_NUM. + +SrcCount of GT_RETURN returning a multi-reg value will be set to 2 or 3 or 4 depending on the number of return registers. + +LSRA Considerations +------------------- +LSRA needs to add support for multi-reg destination GT_CALL, GT_MULTI_VAR and GT_STORE_MULTI_VAR nodes. + +Codegen Considerations +---------------------- +genProduceReg()/genConsumeReg() code paths need to support mullti-reg destination GT_CALL, GT_MULTI_VAR and GT_STORE_MULTI_VAR nodes. + +GT_RETURN(tmp) where tmp is of TYP_STRUCT + - tmp would either be in memory GT_LCL_VAR or GT_MULTI_VAR of TYP_STRUCT + +GT_RETURN(op1) where op1 is of TYP_LONG + - op1 should be always of the form GT_LONG(tmpLclHi, tmpLclLo) + + +Sub work items +-------------- + +The following are the sub work items and against each is indicated its current status: + +1. (Done) Refactor code to abstract structDesc field of GenTreeCall node +ReturnTypeDesc would abstract away existing structDesc (x64 unix) and implement +an API and replace all uses of structDesc of call node with the API. This would be +a pure code refactoring with the addition of ReturnTypeDesc on a GenTreeCall node. + +2. (Done) Get rid of structDesc and replace it with ReturnTypeDesc. +Note that on x64 Unix, we still query structDesc from VM and use it to initialize ReturnTypeDesc. + +3. (Done) Phase 1 Implementation of multi-reg GT_CALL/GT_RETURN node support for x64 Unix + - Importer changes to force IR to be of the form tmp=call always for multi-reg call nodes + - Importer changes to force IR to be of the form GT_RETURN(tmp) always for multi-reg return + - tmp will always be an in memory lcl var. + - Till First class struct support for GT_OBJ/GT_STORE_OBJ comes on-line IR will be of the form + + `GT_STORE_LCL_VAR(tmpLcl, op1 = GT_CALL)` + + where tmpLcl will always be an in memory lcl var of TYP_STRUCT + - Lowering/LSRA/Codegen support to allocate multiple regs to GT_CALL nodes. + - GT_CALL nodes will be governed by a single spill flag i.e. all return registers are spilled together. + - GT_RETURN(tmp) - lowering will mark op1=tmp as contained and generate code as existing code does. + +4. Phase 2 implementation of multi-reg GT_CALL/GT_RETURN node support for x64 unix + - Add new gentree nodes GT_MULTI_VAR and GT_STORE_MULTI_VAR and plumb through rest of JIT phases. + - Global morph code changes to support Case 3 (i.e P-DEP promoted structs) + - Lowering/LSRA/Codegen changes to support GT_MULTI_VAR and GT_STORE_MULTI_VAR + +5. When First class structs support comes on-line, leverage GT_OBJ/GT_STORE_OBJ to store multi-reg +return value of a GT_CALL node to memory cleaning up the code in GT_STORE_LCL_VAR. + +6. (Done) HFA and multi-reg struct return support for Arm64 + +7. (Done) x86 long return support + +8. (Optimization) Phase 3 implementation of multi-reg GT_CALL/GT_RETURN node support for x64 unix + - Global morph code changes to support some of the important Case 2 efficiently + +9. HFA struct and long return support for Arm32 RyuJIT - we should be able to leverage x86 long return and Arm64 HFA struct return work here. + diff --git a/Documentation/project-docs/adding_new_public_apis.md b/Documentation/project-docs/adding_new_public_apis.md index dbf305d542..289ba7de77 100644 --- a/Documentation/project-docs/adding_new_public_apis.md +++ b/Documentation/project-docs/adding_new_public_apis.md @@ -1,26 +1,25 @@ -Adding new public APIs to mscorlib -================================== +Adding new public APIs to System.Private.CoreLib +================================================ -Many of the CoreFX libraries type-forward their public APIs to the implementations in mscorlib. -- The CoreFX build uses published contracts for mscorlib, and the CoreFX test build uses published contracts for some of the CoreFX libraries. -- Some of the CoreFX libraries are not built in the CoreFX repository. For example, System.Runtime.Loader.dll is purely a facade and type-forwards everything to mscorlib. These libraries are built and published through a separate process. -- Hence, when adding a new public API to mscorlib, changes must be staged to ensure that new prerequisites are published before they are used. +Many of the CoreFX libraries type-forward their public APIs to the implementations in System.Private.CoreLib. +- The CoreFX build uses System.Private.CoreLib via Microsoft.TargetingPack.Private.CoreCLR Nuget package. +- Some of the CoreFX libraries are not built in the CoreFX repository. For example, System.Runtime.Loader.dll is purely a facade and type-forwards everything to System.Private.CoreLib. These libraries are built and published through a separate process. +- Hence, when adding a new public API to System.Private.CoreLib, changes must be staged to ensure that new prerequisites are published before they are used. **Staging the changes** -Make the changes to CoreCLR, including mscorlib +Make the changes to CoreCLR, including System.Private.CoreLib - Update `coreclr/src/mscorlib/model.xml` with the new APIs. APIs that are not listed in this file will be stripped out prior to publishing. -- Note that at the moment, merging changes with new public APIs will cause an internal build failure. Please work with your PR reviewer to have these build breaks be fixed soon after merging, otherwise it will block the publishing process. - Merge the changes -- Wait for a new mscorlib contract to be published. Check the latest published version [here](http://myget.org/gallery/dotnet-core). +- Wait for a new System.Private.CoreLib to be published. Check the latest published version [here](https://dotnet.myget.org/feed/dotnet-core/package/nuget/Microsoft.TargetingPack.Private.CoreCLR). -Make the changes to CoreFX consuming the new APIs in mscorlib +Make the changes to CoreFX consuming the new APIs in System.Private.CoreLib - If the changes are to libraries that are built out of the CoreFX repository: - - You will likely see a build failure until a new mscorlib contract is published + - You will likely see a build failure until a new System.Private.CoreLib contract is published - If the changes are to libraries that are **not** built out of the CoreFX repository: - For example, pure facades such as System.Runtime.Loader.dll - There will likely not be a build failure - - But you will still need to wait for the new mscorlib contract to be published before merging the change, otherwise, facade generation will fail + - But you will still need to wait for the new System.Private.CoreLib contract to be published before merging the change, otherwise, facade generation will fail - Merge the changes - Wait for new contracts to be published for libraries with new APIs. Check the latest published versions [here](http://myget.org/gallery/dotnet-core). diff --git a/Documentation/project-docs/ci-trigger-phrases.md b/Documentation/project-docs/ci-trigger-phrases.md index 3652565498..03e071d79d 100644 --- a/Documentation/project-docs/ci-trigger-phrases.md +++ b/Documentation/project-docs/ci-trigger-phrases.md @@ -3,6 +3,8 @@ When submitting a PR to the CoreCLR repo, you may want to run more test suites than are included in the default set of checks run with each PR. In this document you will find a list of all possible jobs to trigger, as well as the phrase that will trigger that job. +You can also ask the CI system to show you all to available trigger phrases by using `@dotnet-bot help`. + These phrases are ordered by OS. They will usually be in the form of "{OS} {Architecture} {Configuration} {Scenario}", so use that format if you are trying to ctrl-f a certain job. To trigger a job, post a comment on your PR with "@dotnet-bot {trigger-phrase}". @@ -79,64 +81,64 @@ To trigger a job, post a comment on your PR with "@dotnet-bot {trigger-phrase}". - **Windows_NT x64 Checked CoreFX JitStressRegs=8 Build & Test:** "test Windows_NT corefx_jitstressregs8" - **Windows_NT x64 Checked CoreFX JitStressRegs=0x10 Build & Test:** "test Windows_NT corefx_jitstressregs0x10" - **Windows_NT x64 Checked CoreFX JitStressRegs=0x80 Build & Test:** "test Windows_NT corefx_jitstressregs0x80" -- **Windows_NT x86 RyuJit Checked Priority 0 Build & Test:** "test Windows_NT x86 ryujit" +- **Windows_NT x86 Checked Priority 0 Build & Test:** "test Windows_NT x86" - **Windows_NT x86 legacy_backend Checked Priority 0 Build & Test:** "test Windows_NT x86 legacy_backend" -- **Windows_NT x86 RyuJit Release Ready-To-Run Priority 0 Build & Test:** "test Windows_NT x86 ryujit Release r2r" +- **Windows_NT x86 Release Ready-To-Run Priority 0 Build & Test:** "test Windows_NT x86 Release r2r" - **Windows_NT x86 legacy_backend Release Ready-To-Run Priority 0 Build & Test:** "test Windows_NT x86 legacy_backend Release r2r" -- **Windows_NT x86 RyuJit Release Ready-To-Run Priority 1 Build & Test:** "test Windows_NT x86 ryujit Release pri1r2r" +- **Windows_NT x86 Release Ready-To-Run Priority 1 Build & Test:** "test Windows_NT x86 Release pri1r2r" - **Windows_NT x86 legacy_backend Release Ready-To-Run Priority 1 Build & Test:** "test Windows_NT x86 legacy_backend Release pri1r2r" -- **Windows_NT x86 RyuJit Release GCStress=15 Ready-To-Run Priority 1 Build & Test:** "test Windows_NT x86 ryujit Release gcstress15_pri1r2r" +- **Windows_NT x86 Release GCStress=15 Ready-To-Run Priority 1 Build & Test:** "test Windows_NT x86 Release gcstress15_pri1r2r" - **Windows_NT x86 legacy_backend Release GCStress=15 Ready-To-Run Priority 1 Build & Test:** "test Windows_NT x86 legacy_backend Release gcstress15_pri1r2r" -- **Windows_NT x86 RyuJit Release jitstress1 R2R Build & Test:** "test Windows_NT x86 ryujit Release jitstress1 R2R" -- **Windows_NT x86 RyuJit Checked jitstress1 R2R Build & Test:** "test Windows_NT x86 ryujit Checked jitstress1 R2R" -- **Windows_NT x86 RyuJit Release jitstress2 R2R Build & Test:** "test Windows_NT x86 ryujit Release jitstress2 R2R" -- **Windows_NT x86 RyuJit Checked jitstress2 R2R Build & Test:** "test Windows_NT x86 ryujit Checked jitstress2 R2R" -- **Windows_NT x86 RyuJit Release jitstressregs1 R2R Build & Test:** "test Windows_NT x86 ryujit Release jitstressregs1 R2R" -- **Windows_NT x86 RyuJit Checked jitstressregs1 R2R Build & Test:** "test Windows_NT x86 ryujit Checked jitstressregs1 R2R" -- **Windows_NT x86 RyuJit Release jitstressregs2 R2R Build & Test:** "test Windows_NT x86 ryujit Release jitstressregs2 R2R" -- **Windows_NT x86 RyuJit Checked jitstressregs2 R2R Build & Test:** "test Windows_NT x86 ryujit Checked jitstressregs2 R2R" -- **Windows_NT x86 RyuJit Release jitstressregs3 R2R Build & Test:** "test Windows_NT x86 ryujit Release jitstressregs3 R2R" -- **Windows_NT x86 RyuJit Checked jitstressregs3 R2R Build & Test:** "test Windows_NT x86 ryujit Checked jitstressregs3 R2R" -- **Windows_NT x86 RyuJit Release jitstressregs4 R2R Build & Test:** "test Windows_NT x86 ryujit Release jitstressregs4 R2R" -- **Windows_NT x86 RyuJit Checked jitstressregs4 R2R Build & Test:** "test Windows_NT x86 ryujit Checked jitstressregs4 R2R" -- **Windows_NT x86 RyuJit Release jitstressregs8 R2R Build & Test:** "test Windows_NT x86 ryujit Release jitstressregs8 R2R" -- **Windows_NT x86 RyuJit Checked jitstressregs8 R2R Build & Test:** "test Windows_NT x86 ryujit Checked jitstressregs8 R2R" -- **Windows_NT x86 RyuJit Release jitstressregsx10 R2R Build & Test:** "test Windows_NT x86 ryujit Release jitstressregsx10 R2R" -- **Windows_NT x86 RyuJit Checked jitstressregsx10 R2R Build & Test:** "test Windows_NT x86 ryujit Checked jitstressregsx10 R2R" -- **Windows_NT x86 RyuJit Release jitstressregsx80 R2R Build & Test:** "test Windows_NT x86 ryujit Release jitstressregsx80 R2R" -- **Windows_NT x86 RyuJit Checked jitstressregsx80 R2R Build & Test:** "test Windows_NT x86 ryujit Checked jitstressregsx80 R2R" -- **Windows_NT x86 RyuJit Release JITMinOpts R2R Build & Test:** "test Windows_NT x86 ryujit Release JITMinOpts R2R" -- **Windows_NT x86 RyuJit Checked JITMinOpts R2R Build & Test:** "test Windows_NT x86 ryujit Checked JITMinOpts R2R" -- **Windows_NT x86 RyuJit Release ForceRelocs R2R Build & Test:** "test Windows_NT x86 ryujit Release ForceRelocs R2R" -- **Windows_NT x86 RyuJit Checked ForceRelocs R2R Build & Test:** "test Windows_NT x86 ryujit Checked ForceRelocs R2R" -- **Windows_NT x86 RyuJit Checked JIT MinOpts Build & Test:** "test Windows_NT x86 ryujit minopts" -- **Windows_NT x86 RyuJit Checked JITStress=1 Build & Test:** "test Windows_NT x86 ryujit jitstress1" -- **Windows_NT x86 RyuJit Checked JITStress=2 Build & Test:** "test Windows_NT x86 ryujit jitstress2" -- **Windows_NT x86 RyuJit Checked Jit ForceRelocs Build & Test:** "test Windows_NT x86 ryujit forcerelocs" -- **Windows_NT x86 RyuJit Checked JITStressRegs=1 Build & Test:** "test Windows_NT x86 ryujit jitstressregs1" -- **Windows_NT x86 RyuJit Checked JITStressRegs=2 Build & Test:** "test Windows_NT x86 ryujit jitstressregs2" -- **Windows_NT x86 RyuJit Checked JITStressRegs=3 Build & Test:** "test Windows_NT x86 ryujit jitstressregs3" -- **Windows_NT x86 RyuJit Checked JITStressRegs=4 Build & Test:** "test Windows_NT x86 ryujit jitstressregs4" -- **Windows_NT x86 RyuJit Checked JITStressRegs=8 Build & Test:** "test Windows_NT x86 ryujit jitstressregs8" -- **Windows_NT x86 RyuJit Checked JITStressRegs=0x10 Build & Test:** "test Windows_NT x86 ryujit jitstressregs0x10" -- **Windows_NT x86 RyuJit Checked JITStressRegs=0x80 Build & Test:** "test Windows_NT x86 ryujit jitstressregs0x80" -- **Windows_NT x86 RyuJit Checked JitStress=2 JITStressRegs=1 Build & Test:** "test Windows_NT x86 ryujit jitstress2_jitstressregs1" -- **Windows_NT x86 RyuJit Checked JitStress=2 JITStressRegs=2 Build & Test:** "test Windows_NT x86 ryujit jitstress2_jitstressregs2" -- **Windows_NT x86 RyuJit Checked JitStress=2 JITStressRegs=3 Build & Test:** "test Windows_NT x86 ryujit jitstress2_jitstressregs3" -- **Windows_NT x86 RyuJit Checked JitStress=2 JITStressRegs=4 Build & Test:** "test Windows_NT x86 ryujit jitstress2_jitstressregs4" -- **Windows_NT x86 RyuJit Checked JitStress=2 JITStressRegs=8 Build & Test:** "test Windows_NT x86 ryujit jitstress2_jitstressregs8" -- **Windows_NT x86 RyuJit Checked JitStress=2 JITStressRegs=0x10 Build & Test:** "test Windows_NT x86 ryujit jitstress2_jitstressregs0x10" -- **Windows_NT x86 RyuJit Checked JitStress=2 JITStressRegs=0x80 Build & Test:** "test Windows_NT x86 ryujit jitstress2_jitstressregs0x80" -- **Windows_NT x86 RyuJit Checked GCStress=0x3 Build & Test:** "test Windows_NT x86 ryujit gcstress0x3" -- **Windows_NT x86 RyuJit Checked GCStress=0xc Build & Test:** "test Windows_NT x86 ryujit gcstress0xc" -- **Windows_NT x86 RyuJit Checked zapdisable Build & Test:** "test Windows_NT x86 ryujit zapdisable" -- **Windows_NT x86 RyuJit Checked Heap Verify 1 Build & Test:** "test Windows_NT x86 ryujit heapverify1" -- **Windows_NT x86 RyuJit Checked GCStress=0xc zapdisable Build & Test:** "test Windows_NT x86 ryujit gcstress0xc_zapdisable" -- **Windows_NT x86 RyuJit Checked GCStress=0xc JitStress=2 zapdisable Build & Test:** "test Windows_NT x86 ryujit gcstress0xc_zapdisable_jitstress2" -- **Windows_NT x86 RyuJit Checked GCStress=0xc zapdisable Heap Verify 1 Build & Test:** "test Windows_NT x86 ryujit gcstress0xc_zapdisable_heapverify1" -- **Windows_NT x86 RyuJit Checked GCStress=0xc JitStress=1 Build & Test:** "test Windows_NT x86 ryujit gcstress0xc_jitstress1" -- **Windows_NT x86 RyuJit Checked GCStress=0xc JitStress=2 Build & Test:** "test Windows_NT x86 ryujit gcstress0xc_jitstress2" -- **Windows_NT x86 RyuJit Checked GCStress=0xc MinOpts Heap Verify 1 Build & Test:** "test Windows_NT x86 ryujit gcstress0xc_minopts_heapverify1" +- **Windows_NT x86 Release jitstress1 R2R Build & Test:** "test Windows_NT x86 Release jitstress1 R2R" +- **Windows_NT x86 Checked jitstress1 R2R Build & Test:** "test Windows_NT x86 Checked jitstress1 R2R" +- **Windows_NT x86 Release jitstress2 R2R Build & Test:** "test Windows_NT x86 Release jitstress2 R2R" +- **Windows_NT x86 Checked jitstress2 R2R Build & Test:** "test Windows_NT x86 Checked jitstress2 R2R" +- **Windows_NT x86 Release jitstressregs1 R2R Build & Test:** "test Windows_NT x86 Release jitstressregs1 R2R" +- **Windows_NT x86 Checked jitstressregs1 R2R Build & Test:** "test Windows_NT x86 Checked jitstressregs1 R2R" +- **Windows_NT x86 Release jitstressregs2 R2R Build & Test:** "test Windows_NT x86 Release jitstressregs2 R2R" +- **Windows_NT x86 Checked jitstressregs2 R2R Build & Test:** "test Windows_NT x86 Checked jitstressregs2 R2R" +- **Windows_NT x86 Release jitstressregs3 R2R Build & Test:** "test Windows_NT x86 Release jitstressregs3 R2R" +- **Windows_NT x86 Checked jitstressregs3 R2R Build & Test:** "test Windows_NT x86 Checked jitstressregs3 R2R" +- **Windows_NT x86 Release jitstressregs4 R2R Build & Test:** "test Windows_NT x86 Release jitstressregs4 R2R" +- **Windows_NT x86 Checked jitstressregs4 R2R Build & Test:** "test Windows_NT x86 Checked jitstressregs4 R2R" +- **Windows_NT x86 Release jitstressregs8 R2R Build & Test:** "test Windows_NT x86 Release jitstressregs8 R2R" +- **Windows_NT x86 Checked jitstressregs8 R2R Build & Test:** "test Windows_NT x86 Checked jitstressregs8 R2R" +- **Windows_NT x86 Release jitstressregsx10 R2R Build & Test:** "test Windows_NT x86 Release jitstressregsx10 R2R" +- **Windows_NT x86 Checked jitstressregsx10 R2R Build & Test:** "test Windows_NT x86 Checked jitstressregsx10 R2R" +- **Windows_NT x86 Release jitstressregsx80 R2R Build & Test:** "test Windows_NT x86 Release jitstressregsx80 R2R" +- **Windows_NT x86 Checked jitstressregsx80 R2R Build & Test:** "test Windows_NT x86 Checked jitstressregsx80 R2R" +- **Windows_NT x86 Release JITMinOpts R2R Build & Test:** "test Windows_NT x86 Release JITMinOpts R2R" +- **Windows_NT x86 Checked JITMinOpts R2R Build & Test:** "test Windows_NT x86 Checked JITMinOpts R2R" +- **Windows_NT x86 Release ForceRelocs R2R Build & Test:** "test Windows_NT x86 Release ForceRelocs R2R" +- **Windows_NT x86 Checked ForceRelocs R2R Build & Test:** "test Windows_NT x86 Checked ForceRelocs R2R" +- **Windows_NT x86 Checked JIT MinOpts Build & Test:** "test Windows_NT x86 minopts" +- **Windows_NT x86 Checked JITStress=1 Build & Test:** "test Windows_NT x86 jitstress1" +- **Windows_NT x86 Checked JITStress=2 Build & Test:** "test Windows_NT x86 jitstress2" +- **Windows_NT x86 Checked Jit ForceRelocs Build & Test:** "test Windows_NT x86 forcerelocs" +- **Windows_NT x86 Checked JITStressRegs=1 Build & Test:** "test Windows_NT x86 jitstressregs1" +- **Windows_NT x86 Checked JITStressRegs=2 Build & Test:** "test Windows_NT x86 jitstressregs2" +- **Windows_NT x86 Checked JITStressRegs=3 Build & Test:** "test Windows_NT x86 jitstressregs3" +- **Windows_NT x86 Checked JITStressRegs=4 Build & Test:** "test Windows_NT x86 jitstressregs4" +- **Windows_NT x86 Checked JITStressRegs=8 Build & Test:** "test Windows_NT x86 jitstressregs8" +- **Windows_NT x86 Checked JITStressRegs=0x10 Build & Test:** "test Windows_NT x86 jitstressregs0x10" +- **Windows_NT x86 Checked JITStressRegs=0x80 Build & Test:** "test Windows_NT x86 jitstressregs0x80" +- **Windows_NT x86 Checked JitStress=2 JITStressRegs=1 Build & Test:** "test Windows_NT x86 jitstress2_jitstressregs1" +- **Windows_NT x86 Checked JitStress=2 JITStressRegs=2 Build & Test:** "test Windows_NT x86 jitstress2_jitstressregs2" +- **Windows_NT x86 Checked JitStress=2 JITStressRegs=3 Build & Test:** "test Windows_NT x86 jitstress2_jitstressregs3" +- **Windows_NT x86 Checked JitStress=2 JITStressRegs=4 Build & Test:** "test Windows_NT x86 jitstress2_jitstressregs4" +- **Windows_NT x86 Checked JitStress=2 JITStressRegs=8 Build & Test:** "test Windows_NT x86 jitstress2_jitstressregs8" +- **Windows_NT x86 Checked JitStress=2 JITStressRegs=0x10 Build & Test:** "test Windows_NT x86 jitstress2_jitstressregs0x10" +- **Windows_NT x86 Checked JitStress=2 JITStressRegs=0x80 Build & Test:** "test Windows_NT x86 jitstress2_jitstressregs0x80" +- **Windows_NT x86 Checked GCStress=0x3 Build & Test:** "test Windows_NT x86 gcstress0x3" +- **Windows_NT x86 Checked GCStress=0xc Build & Test:** "test Windows_NT x86 gcstress0xc" +- **Windows_NT x86 Checked zapdisable Build & Test:** "test Windows_NT x86 zapdisable" +- **Windows_NT x86 Checked Heap Verify 1 Build & Test:** "test Windows_NT x86 heapverify1" +- **Windows_NT x86 Checked GCStress=0xc zapdisable Build & Test:** "test Windows_NT x86 gcstress0xc_zapdisable" +- **Windows_NT x86 Checked GCStress=0xc JitStress=2 zapdisable Build & Test:** "test Windows_NT x86 gcstress0xc_zapdisable_jitstress2" +- **Windows_NT x86 Checked GCStress=0xc zapdisable Heap Verify 1 Build & Test:** "test Windows_NT x86 gcstress0xc_zapdisable_heapverify1" +- **Windows_NT x86 Checked GCStress=0xc JitStress=1 Build & Test:** "test Windows_NT x86 gcstress0xc_jitstress1" +- **Windows_NT x86 Checked GCStress=0xc JitStress=2 Build & Test:** "test Windows_NT x86 gcstress0xc_jitstress2" +- **Windows_NT x86 Checked GCStress=0xc MinOpts Heap Verify 1 Build & Test:** "test Windows_NT x86 gcstress0xc_minopts_heapverify1" - **Windows_NT x86 legacy_backend Release jitstress1 R2R Build & Test:** "test Windows_NT x86 legacy_backend Release jitstress1 R2R" - **Windows_NT x86 legacy_backend Checked jitstress1 R2R Build & Test:** "test Windows_NT x86 legacy_backend Checked jitstress1 R2R" - **Windows_NT x86 legacy_backend Release jitstress2 R2R Build & Test:** "test Windows_NT x86 legacy_backend Release jitstress2 R2R" @@ -159,7 +161,7 @@ To trigger a job, post a comment on your PR with "@dotnet-bot {trigger-phrase}". - **Windows_NT x86 legacy_backend Checked JITMinOpts R2R Build & Test:** "test Windows_NT x86 legacy_backend Checked JITMinOpts R2R" - **Windows_NT x86 legacy_backend Release ForceRelocs R2R Build & Test:** "test Windows_NT x86 legacy_backend Release ForceRelocs R2R" - **Windows_NT x86 legacy_backend Checked ForceRelocs R2R Build & Test:** "test Windows_NT x86 legacy_backend Checked ForceRelocs R2R" -- **Windows_NT x86 RyuJit Release Long-Running GC Build & Test:** "test Windows_NT x86 ryujit Release longgc" +- **Windows_NT x86 Release Long-Running GC Build & Test:** "test Windows_NT x86 Release longgc" - **Windows_NT x86 legacy_backend Release Long-Running GC Build & Test:** "test Windows_NT x86 legacy_backend Release longgc" - **Ubuntu x64 Release Priority 1 Build & Test:** "test Ubuntu pri1" - **Ubuntu x64 Release IL RoundTrip Build & Test:** "test Ubuntu ilrt" diff --git a/Documentation/project-docs/glossary.md b/Documentation/project-docs/glossary.md index 6b13ba82d3..670254ddb6 100644 --- a/Documentation/project-docs/glossary.md +++ b/Documentation/project-docs/glossary.md @@ -15,6 +15,7 @@ As much as possible, we should link to the most authoritative and recent source * JIT: [Just-in-Time](https://github.com/dotnet/coreclr/blob/master/Documentation/botr/ryujit-overview.md) compiler. RyuJIT is the code name for the next generation Just-in-Time(aka "JIT") for the .NET runtime. * LCG: Lightweight Code Generation. An early name for [dynamic methods](https://github.com/dotnet/coreclr/blob/master/src/mscorlib/src/System/Reflection/Emit/DynamicMethod.cs). * NGen: Native Image Generator. +* NYI: Not Yet Implemented * PAL: [Platform Adaptation Layer](http://archive.oreilly.com/pub/a/dotnet/2002/03/04/rotor.html). Provides an abstraction layer between the runtime and the operating system * PE: Portable Executable. * ProjectN: Codename for the first version of [.NET Native for UWP](https://msdn.microsoft.com/en-us/vstudio/dotnetnative.aspx). @@ -22,6 +23,7 @@ As much as possible, we should link to the most authoritative and recent source * Redhawk: Codename for experimental minimal managed code runtime that evolved into [CoreRT](https://github.com/dotnet/corert/). * SOS: [Son of Strike](http://blogs.msdn.com/b/jasonz/archive/2003/10/21/53581.aspx). The debugging extension for DbgEng based debuggers. Uses the DAC as an abstraction layer for its operation. * SVR: The CLR used to be built as two variants, with one called "mscorsvr.dll", to mean the "server" version. In particular, it contained the server GC implementation, which was intended for multi-threaded apps capable of taking advantage of multiple processors. In the .NET Framework 2 release, the two variants were merged into "mscorwks.dll". The WKS version was the default, however the SVR version remained available. +* TPA: Trusted Platform Assemblies used to be a special set of assemblies that comprised the platform assemblies, when it was originally designed. As of today, it is simply the set of assemblies known to constitute the application. * URT: Universal Runtime. Ancient name for what ended up being .NET, is used in the WinError facility name FACILITY_URT. * VSD: [Virtual Stub Dispatch](../botr/virtual-stub-dispatch.md). Technique of using stubs for virtual method invocations instead of the traditional virtual method table. * VM: Virtual machine. 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. |