path: root/
diff options
authorVance Morrison <>2016-10-11 16:10:11 (GMT)
committerGitHub <>2016-10-11 16:10:11 (GMT)
commit7c2cf60715c2aa9eeda16466a225cf77b425df69 (patch)
treeebb66c404f3d1b35eb66496b7c61b98bbf9306b6 /
parentdb89cba9cc24822ed04e97e579f43ef4dcf96f0b (diff)
Update to lead you through basic repo workflow (#7552)
Update to contain much more information about using the repo
Diffstat (limited to '')
1 files changed, 203 insertions, 88 deletions
diff --git a/ b/
index 1b28948..0c77e94 100644
--- a/
+++ b/
@@ -1,107 +1,222 @@
-.NET Core Runtime (CoreCLR)
+.NET Core Common Language Runtime (CoreCLR)
-The CoreCLR repo contains the complete runtime implementation for [.NET Core]( It includes RyuJIT, the .NET GC, native interop and many other components. It is cross-platform, with multiple OS and CPU ports in progress.
+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 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:
+ * Want to **learn more** about .NET Runtime Internals? See the [Documentation on the .NET Core Runtime](Documentation/ page.
+ * Need to **log a issue** or Provide Feedback? See then [Issues and Feedback Page](Documentation/workflow/ page.
+ * Want to **chat** with other members of the CoreCLR community? See the [Chat Section](Documentation/workflow/ page.
+ * Need a **current build** or **test results** of the CoreCLR repository? See the [Official and Daily Builds](Documentation/workflow/ page.
+## What Can you Make from this Repository?
+.NET Core relies heavily on the [Nuget]( package manager
+which is system to package, distribute and version software components. See [](
+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. 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
+In a 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 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 references 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
+ so you can just have your test application's project.json specify the CoreCLR you
+built it will naturally pull anything else it needs from the official location to
+make a complete application. More on this in the [Using Your Build](Documentation/workflow/ 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 at the base of the
+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.
+ * [Windows Build Instructions](Documentation/building/
+ * [Linux Build Instructions](Documentation/building/
+ * [OSX Build Instructions](Documentation/building/
+ * [FreeBSD Build Instructions](Documentation/building/
+ * [NetBSD Build Instructions](Documentation/building/
+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 quit a few tests so this does take a significant amount of time
+that is not necessary if you are just 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
+directory. 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](Documentation/workflow/ 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](Documentation/workflow/ for details on using
+ this technique.
+## 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](Documentation/workflow/ for more.
-Note that the library implementation CoreFX (System.Collections, System.IO, System.Xml and so on) lives in another repo [dotnet/corefx](
+## Contributing to Repository
-Build Status
-| | Debug | Release |
-|**CentOS 7.1**|[![x64 status](](|[![x64 status](](|
-|**Debian 8.4**|[![x64 status](](|[![x64 status](](|
-|**FreeBSD 10.1**|[![x64 status](](|[![x64 status](](|
-|**openSUSE 13.2**|[![x64 status](](|[![x64 status](](|
-|**openSUSE 42.1**|[![x64 status](](|[![x64 status](](|
-|**OS X 10.11**|[![x64 status](](|[![x64 status](](|
-|**Red Hat 7.2**|[![x64 status](](|[![x64 status](](|
-|**Fedora 23**|[![x64 status](](|[![x64 status](](|
-|**Ubuntu 14.04**|[![x64 status](](|[![x64 status](](|
-|**Ubuntu 16.04**|[![x64 status](](|[![x64 status](](|
-|**Ubuntu 16.10**|[![x64 status](](|[![x64 status](](|
-|**Windows 8.1**|[![x64 status](](<br/>[![arm64 status](](|[![x64 status](](<br/>[![arm64 status](](|
-Building the Repo
-|Linux |Windows |Mac OS X |FreeBSD | NetBSD |
-| [Instructions](Documentation/building/ | [Instructions](Documentation/building/ | [Instructions](Documentation/building/ | [Instructions](Documentation/building/ | [Instructions](Documentation/building/ |
-Get .NET Core
-You can get the latest released .NET Core SDK from the [.NET Core Getting started]( page. You can also get the latest development builds of .NET Core and the SDK from the [dotnet/cli repo](
-Chat Room
-Want to chat with other members of the CoreCLR community?
-[![.NET Slack Status](]( [![Join the chat at](](
-Learn about CoreCLR and .NET Core
-The best ways to learn about CoreCLR are to try out the product instructions and to read the "Book of the Runtime" architecture documents that describe the inner workings of the product. New devs to the CLR team are encouraged to read these documents before making substative changes to the product. They are equally useful for open source contributors.
-- [.NET Core Roadmap](
-- [Product instructions](Documentation/
-- [Introduction to the Common Language Runtime](Documentation/botr/
-- [Book of the Runtime](Documentation/
-- [CoreCLR Documents](Documentation)
-.NET Core is part of ASP.NET Core and is a subset of the .NET Framework. You can learn more about .NET Core and how and where you can use it in the [CoreCLR is open source][coreclr blog post] blog post.
-The [.NET Core Libraries][corefx] repo contains the base class libraries, which provides data types and base functionality (ex: String, Collections, HttpClient) on top of CoreCLR. The two repos together make up .NET Core. The [.NET Core is Open Source][.NET Core oss] and [Introducing .NET Core][Introducing .NET Core] blog posts describes our .NET Core OSS strategy and road map in more detail.
-Engage, Contribute and Provide Feedback
-Some of the best ways to contribute are to try things out, file bugs, and join in design conversations. You are encouraged to start a discussion by filing an issue, or starting a thread in the [.NET Foundation forums]( If you are having issues with the Full .NET Framework or .NET Runtime the best ways to file a bug are at [Connect]( or through [Product Support]( if you have a contract.
-Looking for something to work on? The list of [up-for-grabs issues]( is a great place to start.
+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.
* [Contributing Guide](Documentation/project-docs/
* [Developer Guide](Documentation/project-docs/
-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](
-### Reporting security issues and security bugs
+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](
-Security issues and bugs should be reported privately, via email, to the
-Microsoft Security Response Center (MSRC) <>. 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](
+## 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.
-.NET Core (including the coreclr repo) is licensed under the [MIT license](LICENSE.TXT).
+* [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
-.NET Foundation
+## See Also
-.NET Core is a [.NET Foundation]( project.
+* []( is a good place to discover .NET Foundation projects.
+* .NET Core is a [.NET Foundation]( project.
+* [.NET home repo]( links to 100s of .NET projects, from Microsoft and the community.
+* The [.NET Core repo]( links to .NET Core related projects from Microsoft.
+* The [ASP.NET home repo]( is the best place to start learning about ASP.NET Core.
-Related Projects
+## Important Blog Entries
-There are many .NET projects on GitHub.
+* [Announcement of .NET Core Open Source Project](
+* [Introducing .NET Core](
+* [Announcement of CoreCLR](
-- The
-[.NET home repo]( links to 100s of .NET projects, from Microsoft and the community.
-- The [.NET Core repo]( links to .NET Core related projects from Microsoft.
-- The [ASP.NET home repo]( is the best place to start learning about ASP.NET Core.
-- []( is a good place to discover .NET Foundation projects.
+## License
-[.NET Core oss]:
-[Introducing .NET Core]:
-[coreclr blog post]:
+.NET Core (including the coreclr repo) is licensed under the [MIT license](LICENSE.TXT).