This repo contains the .NET Core runtime, called CoreCLR, and the base library, called mscorlib. It includes the garbage collector, JIT compiler, base .NET data types and many low-level classes.
C# C++ C Smalltalk Assembly Objective-C Other
Latest commit 4fc4d2a Jan 25, 2017 @AndyAyersMS AndyAyersMS committed on GitHub Merge pull request #9096 from AndyAyersMS/RevComplement
Add BenchmarkGames revcomp benchmark
Permalink
Failed to load latest commit information.
Documentation Fix runtest.sh build of Coreoverlay to account for new directory stru… Jan 24, 2017
cross Fix armel toolchain setting (#8961) Jan 17, 2017
src Document jumpStub usage in Codeman.cpp Jan 24, 2017
tests Merge pull request #9096 from AndyAyersMS/RevComplement Jan 25, 2017
.editorconfig Disable the 'trim_trailing_whitespace' fixes issue 225 Feb 12, 2015
.gitattributes Add BenchmarkGames revcomp benchmark Jan 24, 2017
.gitignore Stop build from leaving localpkg cache in src Jan 13, 2017
.gitmirrorselective Rename gitmirrorfile Nov 11, 2016
BuildToolsVersion.txt Enable PInvoke analyzer for S.P.CoreLib.dll Jan 9, 2017
CMakeLists.txt [Local GC] Provide an implementation of GCToOSInterface for Unix-like… Jan 24, 2017
CODE_OWNERS.TXT Start using CODE_OWNERS.TXT (#5027) May 17, 2016
CONTRIBUTING.md Create CONTRIBUTING.md (#6386) Jul 22, 2016
DotnetCLIVersion.txt Update CLI to 1.0.0-preview2-1-003182, BuildTools to 1.0.27-prereleas… Jan 6, 2017
LICENSE.TXT Update copyright for .NET Core and update file header guidance Jan 27, 2016
PATENTS.TXT Add additional data to PATENTS.TXT Nov 18, 2015
README.md Fix typos and grammer in coreclr README.md (#8561) Dec 10, 2016
THIRD-PARTY-NOTICES Fix #6125 (#6432) Jul 23, 2016
UpdatePublishedVersions.ps1 Use versions repo tooling from BuildTools. Aug 22, 2016
all.locproj Initial commit to populate CoreCLR repo Jan 30, 2015
build-packages.cmd Merge pull request #6613 from wtgodbe/packagebuilds Oct 17, 2016
build-packages.sh Update build-packages.sh to support portableLinux Dec 19, 2016
build-test.cmd Add support for running CoreCLR Tests in Helix Jan 24, 2017
build.cmd [Local GC] Provide an implementation of GCToOSInterface for Unix-like… Jan 24, 2017
build.proj Create SOS SymbolReader managed project and change SOS to use it. (#6783 Aug 19, 2016
build.sh [Local GC] Provide an implementation of GCToOSInterface for Unix-like… Jan 24, 2017
clean.cmd Standardize on _echo name (#7532) Oct 8, 2016
clean.sh Fix lexicographical compares of numeric values. Jul 21, 2016
clr.coreclr.props Disable and remove FEATURE_APPDOMAIN_RESOURCE_MONITORING. This is a b… Jan 23, 2017
clr.defines.targets Remove disabled FEATURE_APTCA Jan 23, 2017
clr.native.targets Initial commit to populate CoreCLR repo Jan 30, 2015
clr.props Remove desktop props Jan 23, 2017
clr.targets Initial commit to populate CoreCLR repo Jan 30, 2015
clrdefinitions.cmake [Local GC] Provide an implementation of GCToOSInterface for Unix-like… Jan 24, 2017
cmake.definitions Change to Generate nuget packages for Windows Arm64 builds. Jun 25, 2016
compileoptions.cmake [x86/Linux] Implement libunwind-based unwindLazyStack (#8686) Dec 20, 2016
config.json Add support for running CoreCLR Tests in Helix Jan 24, 2017
crosscomponents.cmake [ARM32/Linx] cross-architecture build: restrict build project list (#… Jan 17, 2017
crossgen.cmake Keep FEATURE_MERGE_JIT_AND_ENGINE with refactored approach Apr 26, 2016
dac.cmake Enabling profiling on Unix/OS X. Jan 31, 2016
dac.props Initial commit to populate CoreCLR repo Jan 30, 2015
definitionsconsistencycheck.cmake Move intermediate file into intermediate dir (#5981) Jun 28, 2016
dependencies.props Update CoreClr, CoreFx to beta-24924-01, beta-24924-02, respectively Jan 24, 2017
dir.props Add support for running CoreCLR Tests in Helix Jan 24, 2017
dir.targets update version of buildtools Jan 29, 2016
dir.traversal.targets Initial commit to populate CoreCLR repo Jan 30, 2015
enablesanitizers.sh Reduce clr startup noise when using Clang sanitizers Jan 21, 2016
functions.cmake [Linux] Fix cross-architecture component build configuration for ARM3… Dec 23, 2016
generateexportedsymbols.awk Extend the Unix hosting API Jul 16, 2015
generateversionscript.awk Handle mscorwks_unixexports.src with better regexp operator for compa… Apr 5, 2016
global.json Using full versions, update CoreFX dependencies to beta-24328-05. Jul 29, 2016
init-tools.cmd Update CLI to 1.0.0-preview2-1-003182, BuildTools to 1.0.27-prereleas… Jan 6, 2017
init-tools.sh Update CLI to 1.0.0-preview2-1-003182, BuildTools to 1.0.27-prereleas… Jan 6, 2017
netci.groovy Fix runtest.sh build of Coreoverlay to account for new directory stru… Jan 24, 2017
oacr.cfg Initial commit to populate CoreCLR repo Jan 30, 2015
partition.settings.targets Initial commit to populate CoreCLR repo Jan 30, 2015
perf.groovy Fix pull request title automation Jan 12, 2017
pgosupport.cmake Add PGO GENPROFILE support to coreclr and clrjit (#7423) Oct 4, 2016
publish-packages.cmd Build tests against packages & produce Core_Root for arbitrary OS Oct 17, 2016
publish-packages.sh Build tests against packages & produce Core_Root for arbitrary OS Oct 17, 2016
run-cppcheck.sh NetBSD: Add support for retrieving the number of available CPUs Jan 21, 2016
run.cmd Standardize on _echo name (#7532) Oct 8, 2016
run.sh Remove the dependency of using config.json in cwd (#7330) Sep 23, 2016
sanitizerblacklist.txt Reduce clr startup noise when using Clang sanitizers Jan 21, 2016
sync.cmd Build tests against packages & produce Core_Root for arbitrary OS Oct 17, 2016
sync.sh Use run tool in coreclr dev workflow. Jul 30, 2016
verify-so.sh Fix shared library dependencies verification on some platforms (#8349) Nov 29, 2016

README.md

.NET Core Common Language Runtime (CoreCLR)

This repository contains complete source code the runtime of .NET Core. If you are new to .NET Core start with the About .NET that quickly points you to .NET Core Tutorials

.NET Core is best thought of as 'agile .NET'. Generally speaking it is the same as the Desktop .NET Framework distributed as part of the Windows operating system, but it is a cross platform (Windows, Linux, OSX) and cross architecture (x86, x64, arm) subset that can be deployed as part of the application (if desired), and thus can be updated quickly to fix bugs or add features.

If You Just Want to Use .NET Core

Most users don't need to build .NET Core from source since there is already an built and tested version for any supported platform. You can get the latest released version of the .NET Core SDK by following the instructions on the .NET Core Getting Started page. If you need the most up to date (daily) version of this .NET Core installer you can get it from the latest Installers of .NET Core and .NET Core SDK.

Are you Here for Something Besides the Source Code?

In addition to providing the source code, this repository also acts as a useful nexus for things related to .NET Core including:

What Can you Make from this Repository?

.NET Core relies heavily on the Nuget package manager, which is a system to package, distribute and version software components. See https://www.nuget.org/ for more information on Nuget. For now it is enough to know Nuget is a system that bundles components into *.nupkg files (which are ZIP archives) and these packages can be 'published' either through a local file system path or by a URL (e.g. https://www.nuget.org/). There are then tools (e.g. Nuget.exe, Visual Studio, dotnet.exe) that based on a configuration file (project.json) know how to search these publishing locations and pull down consistent set of packages for the application.

In concrete terms, this repository is best thought of as the source code for the following Nuget package

  • Microsoft.NETCore.Runtime.CoreCLR - Represents the object allocator, garbage collector (GC), class loader, type system, interop and the most fundamental parts of the .NET class library (e.g. System.Object, System.String ...)

It also contains the source code for the following closely related support packages.

  • Microsoft.NETCore.Jit - The Just In Time (JIT) compiler for the .NET Intermediate language (IL)
  • Microsoft.NETCore.ILAsm - An assembler for the .NET Intermediate language (IL)
  • Microsoft.NETCore.ILDAsm - A disassembler (Pretty printer) for the .NET Intermediate language (IL)
  • Microsoft.NETCore.TestHost - This contains the corehost.exe program, which is a small wrapper that uses the .NET Runtime to run IL DLLs passed to it on the command line.
  • Microsoft.TargetingPack.Private.CoreCLR - A set of assemblies that represent the compile time surface area of the class library implemented by the runtime itself.

Relationship with the CoreFX Repository

By itself, the Microsoft.NETCore.Runtime.CoreCLR package is actually not enough to do much. One reason for this is that the CoreCLR package tries to minimize the amount of the class library that it implements. Only types that have a strong dependency on the internal workings of the runtime are included (e.g, System.Object, System.String System.Thread, System.Threading.Tasks.Task and most foundational interfaces). Instead most of the class library is implemented as independent Nuget packages that simply use the .NET Core runtime as a dependency. Many of the most familiar classes (System.Collections, System.IO, System.Xml and so on), live in packages defined in the dotnet/corefx repository.

But the main reason you can't do much with CoreCLR is that ALL of the types in the class library LOOK like they are defined by the CoreFX framework and not CoreCLR. Any library code defined here lives in a single DLL called System.Private.CoreLib.dll and as its name suggests is private (hidden). Instead for any particular PUBLIC type defined in CoreCLR, we found the 'right' package in CoreFX where it naturally belongs and use that package as its public publishing point. That 'facade' package then forwards references to the (private) implementation in System.Private.CoreLib.dll defined here. For example the System.Runtime package defined in CoreFX declares the PUBLIC name for types like System.Object and System.String. Thus from an applications point of view these types live in System.Runtime.dll. However, System.Runtime.dll (defined in the CoreFX repo) forwards references ultimately to System.Private.CoreLib.dll which is defined here.

Thus in order to run an application, you need BOTH the Microsoft.NETCore.Runtime.CoreCLR Nuget package (defined in this repository) as well as packages for whatever you actually reference that were defined in the CoreFX repository (which at a minimum includes the System.Runtime package). You also need some sort of 'host' executable that loads the CoreCLR package as well as the CoreFX packages and starts your code (typically you use dotnet.exe for this).

These extra pieces are not defined here, however you don't need to build them in order to use the CoreCLR Nuget package you create here. There are already versions of the CoreFX packages published on https://www.nuget.org/ so you can have your test application's project.json specify the CoreCLR you built and it will naturally pull anything else it needs from the official location https://www.nuget.org/ to make a complete application. More on this in the Using Your Build page.


Setting up your GIT Clone of the CoreCLR Repository

The first step in making a build of the CoreCLR Repository is to clone it locally. If you already know how to do this, just skip this section. Otherwise if you are developing on windows you can see Setting Up A Git Repository In Visual Studio 2015 for for instructions on setting up. This link uses a different repository as an example, but the issues (do you fork or not) and the procedure are equally applicable to this repository.


Building the Repository

The build depends on GIT, CMAKE, Python and of course a C++ compiler. Once these prerequisites are installed the build is simply a matter of invoking the 'Build' script (Build.cmd or build.sh) at the base of the repository.

The details of installing the components differ depending on the operating system. See the following pages based on your OS. There is no cross-building across OS (only for ARM, which is built on X64).
You have to be on the particular platform to build that platform.

The build has two main 'buildTypes'

  • Debug (default)- This compiles the runtime with additional runtime checks (asserts). These checks slow runtime execution but are really valuable for debugging, and is recommended for normal development and testing.
  • Release - This compiles without any development time runtime checks. This is what end users will use but can be difficult to debug. Passing 'release' to the build script select this.

In addition, by default the build will not only create the runtime executables, but it will also build all the tests. There are quite a few tests so this does take a significant amount of time that is not necessary if you want to experiment with changes. You can submit the building of the tests with the 'skiptests' argument to the build script.

Thus to get a build as quickly as possible type the following (using \ as the directory separator, use / on Unix machines)

    .\build skiptests 

which will build the Debug flavor which has development time checks (asserts), or

    .\build release skiptests

to build the release (full speed) flavor. You can find more build options with build by using the -? or -help qualifier.

Using Your Build

The build places all of its generated files under the 'bin' directory at the base of the repository. There is a 'bin\Log' directory that contains log files generated during the build (Most useful when the build fails). The the actual output is placed in a directory like this

  • bin\Product\Windows_NT.x64.Release

Where you can see the operating system and CPU architecture, and the build type are part of the name. While the 'raw' output of the build is sometimes useful, normally you are only interested in the Nuget packages that were built, which are placed in the directory

  • bin\Product\Windows_NT.x64.Release.nuget\pkg

These packages are the 'output' of your build.

There are two basic techniques for using your new runtime.

  1. Use dotnet.exe and Nuget to compose an application. See Using Your Build for instructions on creating a program that uses your new runtime by using the NuGet packages you just created and the'dotnet' command line interface. This is the expected way non-runtime developers are likely to consume your new runtime.

  2. Use corerun.exe to run an application using unpackaged Dlls. This repository also defines a simple host called corerun.exe that does NOT take any dependency on NuGet. Basically it has to be told where to get all the necessary DLLs you actually use, and you have to gather them together 'by hand'. This is the technique that all the tests in the repo use, and is useful for quick local 'edit-compile-debug' loop (e.g. preliminary unit testsing). See Executing .NET Core Apps with CoreRun.exe for details on using this technique.

Editing and Debugging

Typically users run through the build and use instructions first with an unmodified build, just to familiarize themselves with the procedures and to confirm that the instructions work. After that you will want to actually make modifications and debug any issues those modifications might cause. See the following links for more.

Running Tests

After you have your modification basically working, and want to determine if you have broken anything it is time to runt tests. See Running .NET Core Tests for more.

Contributing to Repository

Looking for something to work on? The list of up-for-grabs issues is a great place to start.

Please read the following documents to get started.

This project has adopted the code of conduct defined by the Contributor Covenant to clarify expected behavior in our community. For more information, see the .NET Foundation Code of Conduct.


Related Projects

As noted above, the CoreCLR Repository does not contain all the source code that makes up the .NET Core distribution. Here is a list of the other repositories that complete the picture.

  • dotnet/corefx - Source for the most common classes in the .NET Framework library.
  • dotnet/core-setup - Source code for the dotnet.exe program and the policy logic to launch basic .NET Core code (hostfxr, hostpolicy) which allow you to say 'dotnet SOME_CORE_CLR_DLL' to run the app.
  • dotnet/cli repo - Source for build time actions supported by dotnet.exe Command line Interface (CLI). Thus this is the code that runs when you do 'dotnet build', 'dotnet restore' or 'dotnet publish'.
  • dotnet/core-docs - Master copy of documentation for http://docs.microsoft.com/en-us/dotnet/

See Also

Important Blog Entries

License

.NET Core (including the coreclr repo) is licensed under the MIT license.