README.md

   1 .NET Core Common Language Runtime (CoreCLR)
   2 ===========================
   3
   4 This repository contains complete source code the runtime of [.NET Core](http://dotnet.github.io).
   5 If you are new to .NET Core start with the [About .NET](https://docs.microsoft.com/en-us/dotnet/articles/about/)
   6 that quickly points you to [.NET Core Tutorials](https://docs.microsoft.com/en-us/dotnet/articles/core/getting-started)
   7
   8
   9 .NET Core is best thought of as 'agile .NET'.   Generally speaking it is the same as
  10 the [Desktop .NET Framework](https://en.wikipedia.org/wiki/.NET_Framework)
  11 distributed as part of the Windows operating system, but it is a cross platform
  12 (Windows, Linux, macOS) and cross architecture (x86, x64, arm) subset that can be deployed
  13 as part of the application (if desired), and thus can be updated quickly to fix bugs or add features.
  14
  15 ## If You Just Want to Use .NET Core
  16
  17 Most users don't need to build .NET Core from source since there is already a built and tested version for any supported platform.
  18 You can get the latest **released** version of the .NET Core SDK by following the instructions on
  19 the [.NET Core Getting Started](http://dotnet.github.io/getting-started/) page.
  20 If you need the most up to date (daily) version of this .NET Core installer you can get it from the
  21 [latest Installers of .NET Core and .NET Core SDK](https://github.com/dotnet/cli#installers-and-binaries).
  22 If you want one of our official releases, you can get the download from the
  23 [download archive page](https://github.com/dotnet/core/blob/master/release-notes/download-archive.md).
  24
  25 ## Are you Here for Something Besides the Source Code?
  26
  27 In addition to providing the source code, this repository also acts as a useful nexus for things
  28 related to .NET Core including:
  29
  30  * Want to **learn more** about .NET Runtime Internals?  See the [Documentation on the .NET Core Runtime](Documentation/README.md) page.
  31  * Need to **log a issue** or Provide Feedback?   See then [Issues and Feedback Page](Documentation/workflow/IssuesFeedbackEngagement.md) page.
  32  * Want to **chat** with other members of the CoreCLR community?  See the [Chat Section](Documentation/workflow/IssuesFeedbackEngagement.md#Chat-with-the-CoreCLR-community) page.
  33  * Need a **current build** or **test results** of the CoreCLR repository?   See the [Official and Daily Builds](Documentation/workflow/OfficalAndDailyBuilds.md) page.
  34  * If you want powerful search of the source code for both CoreClr and CoreFx see [.NET Source Code Index](https://source.dot.net)
  35
  36 ## What Can you Make from this Repository?
  37
  38 .NET Core relies heavily on the [Nuget](https://en.wikipedia.org/wiki/NuGet) package manager,
  39 which is a system to package, distribute and version software components.  See [https://www.nuget.org/](https://www.nuget.org/)
  40 for more information on Nuget.   For now it is enough to know Nuget is a system that
  41 bundles components into `*.nupkg` files (which are ZIP archives) and these packages can be 'published'
  42 either through a local file system path or by a URL (e.g. https://www.nuget.org/).   There are then tools
  43 (e.g. Nuget.exe, Visual Studio, dotnet.exe) that based on a configuration file (.csproj) know
  44 how to search these publishing locations and pull down consistent set of packages for the
  45 application.
  46
  47 In concrete terms, this repository is best thought of as the source code for the following Nuget package
  48
  49  * **Microsoft.NETCore.Runtime.CoreCLR** - Represents the object allocator, garbage collector (GC), class
  50    loader, type system, interop and the most fundamental parts of the .NET class library (e.g.
  51    System.Object, System.String ...)
  52
  53 It also contains the source code for the following closely related support packages.
  54
  55  * **Microsoft.NETCore.Jit** - The Just In Time (JIT) compiler for the
  56    [.NET Intermediate language (IL)](https://en.wikipedia.org/wiki/Common_Intermediate_Language)
  57  * **Microsoft.NETCore.ILAsm** - An assembler for the
  58    [.NET Intermediate language (IL)](https://en.wikipedia.org/wiki/Common_Intermediate_Language)
  59  * **Microsoft.NETCore.ILDAsm** - A disassembler (Pretty printer) for the
  60    [.NET Intermediate language (IL)](https://en.wikipedia.org/wiki/Common_Intermediate_Language)
  61  * **Microsoft.NETCore.TestHost** - This contains the corehost.exe program, which is a small wrapper
  62    that uses the .NET Runtime to run IL DLLs passed to it on the command line.
  63  * **Microsoft.TargetingPack.Private.CoreCLR** - A set of assemblies that represent the compile time surface
  64    area of the class library implemented by the runtime itself.
  65
  66 ## Relationship with the [CoreFX](https://github.com/dotnet/corefx) Repository
  67
  68 By itself, the `Microsoft.NETCore.Runtime.CoreCLR` package is actually not enough to do much.
  69 One reason for this is that the CoreCLR package tries to minimize the amount of the class library that it implements.
  70 Only types that have a strong dependency on the internal workings of the runtime are included (e.g,
  71 `System.Object`, `System.String`, `System.Thread`, `System.Threading.Tasks.Task` and most foundational interfaces).
  72 Instead most of the class library is implemented as independent Nuget packages that simply use the .NET Core
  73 runtime as a dependency.    Many of the most familiar classes (`System.Collections`, `System.IO`, `System.Xml` and
  74 so on), live in packages defined in the [dotnet/corefx](https://github.com/dotnet/corefx) repository.
  75
  76 But the main reason you can't do much with CoreCLR is that **ALL** of the types in the class library **LOOK**
  77 like they are defined by the CoreFX framework and not CoreCLR.   Any library code defined here
  78 lives in a single DLL called `System.Private.CoreLib.dll` and as its name suggests is private (hidden).
  79 Instead for any particular PUBLIC type defined in CoreCLR, we found the 'right' package in CoreFX where it naturally
  80 belongs and use that package as its **public publishing** point.   That 'facade' package then forwards references
  81 to the (private) implementation in `System.Private.CoreLib.dll` defined here.
  82 For example the *`System.Runtime`* package defined in CoreFX declares the PUBLIC name for types like
  83 `System.Object` and `System.String`.   Thus from an applications point of view these types live in `System.Runtime.dll`.
  84 However, `System.Runtime.dll` (defined in the CoreFX repo) forwards references ultimately to `System.Private.CoreLib.dll`
  85 which is defined here.
  86
  87 Thus in order to run an application, you need BOTH the `Microsoft.NETCore.Runtime.CoreCLR` Nuget package
  88 (defined in this repository) as well as  packages for whatever you actually reference that were defined
  89 in the CoreFX repository (which at a minimum includes the `System.Runtime` package).    You also need some
  90 sort of 'host' executable that loads the CoreCLR package as well as the CoreFX packages and starts your code (typically
  91 you use `dotnet.exe` for this).
  92
  93 These extra pieces are not defined here, however you don't need to build them in order to use the CoreCLR
  94 Nuget package you create here.   There are already versions of the CoreFX packages published on
  95 https://www.nuget.org/ so you can have your test application's project file specify the CoreCLR you
  96 built and it will naturally pull anything else it needs from the official location https://www.nuget.org/ to
  97 make a complete application.  More on this in the [Using Your Build](Documentation/workflow/UsingYourBuild.md) page.
  98
  99 --------------------------
 100 ## Setting up your GIT Clone of the CoreCLR Repository
 101
 102 The first step in making a build of the CoreCLR Repository is to clone it locally.   If you already know
 103 how to do this, just skip this section.  Otherwise if you are developing on windows you can see
 104 [Setting Up A Git Repository In Visual Studio 2017](https://github.com/Microsoft/perfview/blob/master/documentation/SettingUpRepoInVS.md)
 105 for for instructions on setting up.  This link uses a different repository as an example, but the issues (do you fork or not) and
 106 the procedure are equally applicable to this repository.
 107
 108 --------------------------
 109 ## Building the Repository
 110
 111 The build depends on Git, CMake, Python and of course a C++ compiler.  Once these prerequisites are installed
 112 the build is simply a matter of invoking the 'build' script (`build.cmd` or `build.sh`) at the base of the
 113 repository.
 114
 115 The details of installing the components differ depending on the operating system.  See the following
 116 pages based on your OS.  There is no cross-building across OS (only for ARM, which is built on X64).
 117 You have to be on the particular platform to build that platform.
 118
 119  * [Windows Build Instructions](Documentation/building/windows-instructions.md)
 120  * [Linux Build Instructions](Documentation/building/linux-instructions.md)
 121  * [macOS Build Instructions](Documentation/building/osx-instructions.md)
 122  * [FreeBSD Build Instructions](Documentation/building/freebsd-instructions.md)
 123  * [NetBSD Build Instructions](Documentation/building/netbsd-instructions.md)
 124
 125 The build has two main 'buildTypes'
 126
 127  * Debug (default)- This compiles the runtime with additional runtime checks (asserts).  These checks slow
 128    runtime execution but are really valuable for debugging, and is recommended for normal development and testing.
 129  * Release - This compiles without any development time runtime checks.  This is what end users will use but
 130    can be difficult to debug.   Pass 'release' to the build script to select this.
 131
 132 In addition, by default the build will not only create the runtime executables, but it will also
 133 build all the tests.   There are quite a few tests so this does take a significant amount of time
 134 that is not necessary if you want to experiment with changes.   You can skip building
 135 the tests by passing the 'skiptests' argument to the build script.
 136
 137 Thus to get a build as quickly as possible type the following (using `\` as the directory separator, use `/` on Unix machines)
 138 ```bat
 139     .\build skiptests
 140 ```
 141 which will build the Debug flavor which has development time checks (asserts), or
 142 ```bat
 143     .\build release skiptests
 144 ```
 145 to build the release (full speed) flavor.  You can find more build options with build by using the -? or -help qualifier.
 146
 147 ## Using Your Build
 148
 149 The build places all of its generated files under the `bin` directory at the base of the repository.   There
 150 is a `bin\Log` directory that contains log files generated during the build (Most useful when the build fails).
 151 The the actual output is placed in a directory like this
 152
 153 * bin\Product\Windows_NT.x64.Release
 154
 155 Where you can see the operating system and CPU architecture, and the build type are part of the name.   While
 156 the 'raw' output of the build is sometimes useful, normally you are only interested in the Nuget packages
 157 that were built, which are placed in the directory
 158
 159 * bin\Product\Windows_NT.x64.Release\.nuget\pkg
 160
 161 These packages are the 'output' of your build.
 162
 163 There are two basic techniques for using your new runtime.
 164
 165  1. **Use dotnet.exe and Nuget to compose an application**.   See [Using Your Build](Documentation/workflow/UsingYourBuild.md) for
 166  instructions on creating a program that uses
 167  your new runtime by using the NuGet packages you just created and the 'dotnet' command line interface.  This
 168  is the expected way non-runtime developers are likely to consume your new runtime.
 169
 170  2. **Use corerun.exe to run an application using unpackaged Dlls**. This repository also defines a simple host called
 171  corerun.exe that does NOT take any dependency on NuGet.   Basically it has to be told where to get all the
 172  necessary DLLs you actually use, and you have to gather them together 'by hand'.   This is the technique that
 173  all the tests in the repo use, and is useful for quick local 'edit-compile-debug' loop (e.g. preliminary unit testsing).
 174  See [Using corerun To Run .NET Core Application](Documentation/workflow/UsingCoreRun.md) for details on using
 175  this technique.
 176
 177 ## Editing and Debugging
 178
 179 Typically users run through the build and use instructions first with an unmodified build, just to familiarize
 180 themselves with the procedures and to confirm that the instructions work.   After that you will want to actually
 181 make modifications and debug any issues those modifications might cause.   See the following links for more.
 182
 183  * [Editing and Debugging](Documentation/workflow/EditingAndDebugging.md) and
 184  * [Documentation on the .NET Core Runtime](Documentation/README.md)
 185
 186 ## Running Tests
 187
 188 After you have your modification basically working, and want to determine if you have broken anything it is
 189 time to run tests.  See [Running .NET Core Tests](Documentation/workflow/RunningTests.md) for more.
 190
 191 ## Contributing to Repository
 192
 193 Looking for something to work on? The list
 194 of [up-for-grabs issues](https://github.com/dotnet/coreclr/labels/up-for-grabs) is a great place to start.
 195
 196 Please read the following documents to get started.
 197
 198 * [Contributing Guide](Documentation/project-docs/contributing.md)
 199 * [Developer Guide](Documentation/project-docs/developer-guide.md)
 200
 201 This project has adopted the code of conduct defined by the [Contributor Covenant](http://contributor-covenant.org/)
 202 to clarify expected behavior in our community. For more information, see the [.NET Foundation Code of Conduct](http://www.dotnetfoundation.org/code-of-conduct).
 203
 204 -------------------
 205 ## Related Projects
 206
 207 As noted above, the CoreCLR Repository does not contain all the source code that makes up the .NET Core distribution.
 208 Here is a list of the other repositories that complete the picture.
 209
 210 * [dotnet/corefx](https://github.com/dotnet/corefx) - Source for the most common classes in the .NET Framework library.
 211 * [dotnet/core-setup](https://github.com/dotnet/core-setup) - Source code for the dotnet.exe program and the policy logic
 212 to launch basic .NET Core code (hostfxr, hostpolicy) which allow you to say 'dotnet SOME_CORE_CLR_DLL' to run the app.
 213 * [dotnet/cli repo](https://github.com/dotnet/cli) - Source for build time actions supported by dotnet.exe Command line Interface (CLI).
 214 Thus this is the code that runs when you do 'dotnet build', 'dotnet restore' or 'dotnet publish'.
 215 * [dotnet/core-docs](https://github.com/dotnet/core-docs) - Master copy of documentation for
 216 [http://docs.microsoft.com/en-us/dotnet/](https://docs.microsoft.com/en-us/dotnet/)
 217
 218 ## See Also
 219
 220 * [Dotnet.github.io](http://dotnet.github.io) is a good place to discover .NET Foundation projects.
 221 * .NET Core is a [.NET Foundation](http://www.dotnetfoundation.org/projects) project.
 222 * [.NET home repo](https://github.com/Microsoft/dotnet) links to 100s of .NET projects, from Microsoft and the community.
 223 * The [.NET Core repo](https://github.com/dotnet/core) links to .NET Core related projects from Microsoft.
 224 * The [ASP.NET home repo](https://github.com/aspnet/home) is the best place to start learning about ASP.NET Core.
 225
 226 ## Important Blog Entries
 227
 228 * [Announcement of .NET Core Open Source Project](http://blogs.msdn.com/b/dotnet/archive/2014/11/12/net-core-is-open-source.aspx)
 229 * [Introducing .NET Core](http://blogs.msdn.com/b/dotnet/archive/2014/12/04/introducing-net-core.aspx)
 230 * [Announcement of CoreCLR](http://blogs.msdn.com/b/dotnet/archive/2015/02/03/coreclr-is-now-open-source.aspx)
 231
 232 ## License
 233
 234 .NET Core (including the coreclr repo) is licensed under the [MIT license](LICENSE.TXT).