coreclr education

[clrjunkie]

The “Book of the Runtime” provides a good high level overview of various aspects but is insufficient to get up to speed for those who are new to this layer and want to contribute exposing native o/s api’s or debug existing interops.

.NET community needs a more practical code review (preferably 2 – 3 debugging videos) starting by explaining the flow and data-structures (managed and C++) involved in the following scenarios:

Managed to native / Native to managed plumbing (P/Invoke internals)
Native to Managed Thread transitions.

Garbage collection might be interesting further on.. but not high priority.

[shahid-pk]

I think this book needs to be updated Shared Source CLI Essentials for coreclr or something new like that. It was written in the days of the rotor project when ms was distributing .net runtime and its bcl's source code for educational purposes. This book was a great companion to that code.

[mattwarren]

I know the is an old issue, but a blog post I just wrote might help you out?

See 'A Hitchhikers Guide to the CoreCLR Source Code'

[clrjunkie]

Great Job! @mattwarren

Now consider scaling this out by converting the content into Markdown format and submitting it as a pull request for this issue!

That way it would be super easy for CoreCLR team members to review/update/improve the content and will allow the community a simple way to provide feedback, open documentation issues concerning this area and also submit code snippets that illustrate key processing stages.

[mattwarren]

Thanks

Now consider scaling this out by converting the content into Markdown format and submitting it as a pull request for this issue!

@karelz asked asked me about the same thing, so it looks like, one way or the other, it will happen. Fortunately I write my blog posts in Markdown, so the conversion should be easy.

That way it would be super easy for CoreCLR team members to review/update/improve the content and will allow the community a simple way to provide feedback, open documentation issues concerning this area and also submit code snippets that illustrate key processing stages.

That's a good idea, I hadn't thought about it being reviewed/updated/improved in this way.

[karelz]

Yeah, I think contributions to the doc are the key value - it can grow and should be fairly easy to update that way.
The truly hard part is to seed it with good content - which you @mattwarren did in a great way.

IMO the key next steps are to select parts which are stable-ish over time (maybe skip some statistics), break them down into documents, and flip them into markdown. I bet there will be bunch of folks willing to help with the work ...

[mattwarren]

IMO the key next steps are to select parts which are stable-ish over time (maybe skip some statistics), break them down into documents, and flip them into markdown.

Yeah I wasn't planning to submit any of the 'Top 10' lists or even the treemaps, they work in a blog post, but not as project docs

Where should I submit the cleaned up markdown, what's the location in CoreCLR (or elsewhere) that they should go?

[karelz]

@jkotas any suggestion on location in CoreCLR? (sorry, I am not that much familiar with CoreCLR src/docs structure)

[jkotas]

I think that this sort of content should go to https://github.com/dotnet/coreclr/tree/master/Documentation/botr . If it helps, I would not mind renaming "botr" to something more self-explanatory like "architecture".

It would be best to amend the existing documents instead of introducing new ones where appropriate. E.g. The paragraph about JIT may best go to ryujit-overview.md. This document has a list of JIT phases already pretty similar to the one in your blog post. Or the extra details about GC may go to garbage-collection.md.

[danmoseley]

I think this would be a good idea, but nobody has picked it up and I don't think it is that helpful to keep this issue open. Perhaps we will get interest in future.