Scott Hanselman

The Book of the Runtime - The internals of the .NET Runtime that you won't find in the documentation

September 27, 2017 Comment on this post [6] Posted in DotNetCore
Sponsored By

The Microsoft Docs at are really fantastic lately. All the .NET Docs are on GitHub and you can contribute to them. However, in the world of software engineering (here some a bad, mixed metaphor) there's instructions on how to use a faucet and there's instructions on how to build and design plumbing from scratch.

RyuJIT High level overview

There's additional DEEP docs that don't really belong on the docs site. It's the Book of the Runtime and for now it's on GitHub. Here's the BotR FAQ.

If you're interested in the internals of a system like the .NET Runtime, these docs are a gold mine for you.

The Book of the Runtime is a set of documents that describe components in the CLR and BCL. They are intended to focus more on architecture and invariants and not an annotated description of the codebase.

It was originally created within Microsoft in ~ 2007, including this document. Developers were responsible to document their feature areas. This helped new devs joining the team and also helped share the product architecture across the team.

We realized that the BotR is even more valuable now, with CoreCLR being open source on GitHub. We are publishing BotR chapters to help a new set of CLR developers.

This book likely isn't for you if you're an app developer. Who is it for?

  • Developers who are working on bugs that impinge on an area and need a high level overview of the component.
  • Developers working on new features with dependencies on a component need to know enough about it to ensure the new feature will interact correctly with existing components.
  • New developers need this chapter to maintain a given component.

These aren't design documents, these are docs that were written after features are implemented in order to explain how they work in practice.

Recently Carol Eidt wrote an amazing walkthrough to .NET Core's JIT engine. Perhaps start at the JIT Overview and move to the deeper walkthrough. Both are HUGELY detailed and a fascinating read if you're interested in how .NET makes Dynamic Code Execution near-native speed with the RyuJIT - the next-gen Just in Time compiler.

Here's a few highlights I enjoyed but you should read the whole thing yourself. It covers the high level phases and then digs deeper into the responsibilities of each. You also get a sense of why the RyuJIT is NOT the same JITter from 15+ years ago - both the problem space and processors have changed.

This is the 10,000 foot view of RyuJIT. It takes in MSIL (aka CIL) in the form of byte codes, and the Importer phase transforms these to the intermediate representation used in the JIT. The IR operations are called “GenTrees”, as in “trees for code generation”. This format is preserved across the bulk of the JIT, with some changes in form and invariants along the way. Eventually, the code generator produces a low-level intermediate called InstrDescs, which simply capture the instruction encodings while the final mappings are done to produce the actual native code and associated tables.


This is just one single comprehensive doc in a collection of documents. As for the rest of the Book of the Runtime, here's the ToC as of today, but there may be new docs in the repository as it's a living book.

Check it out!

Sponsor: Check out JetBrains Rider: a new cross-platform .NET IDE. Edit, refactor, test and debug ASP.NET, .NET Framework, .NET Core, Xamarin or Unity applications. Learn more and download a 30-day trial!

About Scott

Scott Hanselman is a former professor, former Chief Architect in finance, now speaker, consultant, father, diabetic, and Microsoft employee. He is a failed stand-up comic, a cornrower, and a book author.

facebook twitter subscribe
About   Newsletter
Hosting By
Hosted in an Azure App Service
September 27, 2017 17:03
Thank you scott, very interesting links to deep dive into how things work.
September 27, 2017 20:10
Awesome post, Scott! I could (and likely will) get lost in the Book of The Runtime for days.
September 28, 2017 3:48
Awesome. Have you been able to read it all? I wonder where do developers get time from in order to do things like this. I cannot... yet.
September 28, 2017 11:38
I've never seen a more apt opportunity to type "tl;dr" :) (referring to the BotR, of course).
October 05, 2017 14:59
Awesome scott!
October 06, 2017 5:05
"This book likely isn't for you if you're an app developer."

Hmmm...perhaps most dotnet devs can get by without this info, but if you want to be the best dev you can be, doesn't it make sense to have at least a basic understanding of how things work in the deep dark recesses of the runtime?

The most helpful book I ever read was Jeff Richter's book about the CLR, way back in the 1.0/1.1 days. So much good info on how a dotnet executable was bootstrapped, how the GC works, etc.

It was maybe not info that I needed to do my work as a dev, but I definitely feel it made me a *better* dev.

Comments are closed.

Disclaimer: The opinions expressed herein are my own personal opinions and do not represent my employer's view in any way.