BOTR - The Book of the Runtime


One of those Dev's that like learning about the deep, dark depths of a runtime? Someone who likes to see JUST how something works?

Last week, Scott Hanselman blogged about some .NET Documentation that was new to me, The Book of the Runtime - The internals of the .NET Runtime that you won't find in the documentation, and in checking it out, I thought of you all...

The Book of the Runtime

Welcome to the Book of the Runtime (BOTR) for the .NET Runtime. This contains a collection of articles about the non-trivial internals of the .NET Runtime. Its intended audience are people actually modifying the code or simply wishing to have a deep understanding of the runtime.

Below is a table of contents.

It may be possible that this table is not complete. You can get a complete list by looking at the directory where all the chapters are stored:

[Click through to read it now]

Okay, but what is the BOTR, really?

Book of the Runtime (BotR) FAQ

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.

Each of the BoTR documents were written with a certain perspective, both in terms of the timeframe and the author. We did not think it was right to mutate the documents to make them more "2015". They remain the docs that they were, modulo a few spelling corrections and a conversion to markdown. That said, we'll accept PRs to the docs to improve them.

Who is the main audience of BotR?

  • 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.

What should be in a BotR chapter? ...

How is this different from a design doc? ...

I am a new dev and not familiar with any features yet, how can I contribute? ...

What are the responsibilities of a BotR reviewer? ...

I really don't have time to work on a BotR chapter – it seems like I always have other things to do. What do I do? ...

[Click through to read the rest]

As you've seen, it's all on GitHub,, so you can clone it and do with it what you will!

The Discussion

Conversation locked

This conversation has been locked by the site admins. No new comments can be made.