Merge pull request #3869 from dkorpel/readme-source-structure

Add source structure to README

README.md

@@ -49,6 +49,30 @@ The runtime library provides the following:
 * Unit test, coverage, and trace support code.
 * Low-level helpers for compiler-inserted calls.
 
+Source structure
+------
+
+In the `src` directory, there are `core` and `rt` packages.
+
+The `rt` package contains implementations for compiler-inserted calls.
+You may not `import rt.xxx` outside of the `rt` package itself, since its source is not accessible once druntime is compiled;
+it isn't included in the `druntime/import` that ships with compiler releases.
+The compiler assumes these functions have a specific `extern(C)` signature, and expects them to be linked into the final binary.
+See for example: [https://github.com/dlang/dmd/blob/master/src/dmd/backend/drtlsym.d](dmd/backend/drtlsym.d)
+
+The `core` package is shipped with the compiler and has a stable API.
+It contains implementations for D features, but also some D conversions of header files from external libraries:
+- `core/stdc` - C standard library
+- `core/stdcpp` - C++ standard library
+- `core/sys` - operating system API
+
+An exception to the public API is `core.internal`, which contains compiler hooks that are templates.
+Many hooks from `rt` use `TypeInfo` class parameters, providing run-time type information, but they are being replaced by template functions, using static type information:
+[Replace Runtime Hooks with Templates](https://github.com/dlang/projects/issues/25)
+
+Since uninstantiated templates aren't compiled into the druntime binary, they can't be in `rt`.
+Symbols from `core.internal` can be publically imported from other `core` modules, but are not supposed to be imported or otherwise referenced by end user modules.
+
 Issues
 ------