Document project state and goals around platform extension nupkgs

[dagood]

Right now we build platform extension nupkgs out of dotnet/corefx / dotnet/runtime so that downstream repos can use them, but there isn't any clear/recommended way to provide those to users of the source-built SDK. Right now I believe the most usable approach is to get the source-built SDK and then use the nuget.org gallery for further packages (in particular community packages, which may or may not be source-buildable anyway).

---

This also ties into the gradual move from platform extensions => shared framework. There are some packages on nuget.org that appear to be necessary to use .NET Core, but aren't, because they're in the shared framework. It's hard to tell, and I think this is a factor in confusion here.

(It's also confusing for everyone else: sometimes package references are added that aren't necessary at all and it's hard to determine: see https://github.com/dotnet/source-build/blob/c456b3ade5e4a78ca22ced8db34f295c3d9c74ed/patches/cli/0003-Remove-System.Security.Principal.Windows-nupkg-ref.patch for an example of where we had to fix this.)

---

Related: What is the expected usage of source-built assets? #187

[dagood]

Triage notes:
From this issue, the main additions to docs would be: what does source-build produce, and what does it not produce and where would those things come from. There are also some docs in this repo that are about native bootstrapping (where adding a feed is documented to be necessary) and dotnet/runtime build from source that aren't clearly distinguished from distro maintainer docs.

[dagood]

Some monologuing I did in Gitter the doc should probably cover:
https://gitter.im/dotnet/source-build?at=5f3aae7160892e0c6979aa1e

---

Re https://github.com/dotnet/source-build/tree/release/3.1/Documentation#how-to-use-the-produced-runtime:

You shouldn't do that nuget.config bit, that's what I brought up here:

That part of that doc mentioning nuget.config is intended for people who are making tweaks to the runtime and want to build from source and use their own custom runtime--which isn't the main scenario dotnet/source-build is meant for. (Building the .NET SDK from source in a way that's suitable for linux distros and as similar as possible to the one that Microsoft built.)

With those parameters you have to download a runtime pack from nuget.org, you can only build framework-dependent apps without that.
(Tracking some improvements to docs in this area at #1698 )
More about the runtime pack requirement here: #1215

https://docs.microsoft.com/en-us/dotnet/core/deploying/ for more about framework dependence (runtime dependence), in case you're not familiar with each part of that publish command.

Note that if you were to hook up your "portable" runtime pack and make a self-contained app with it, it most likely wouldn't run on all platforms that .NET Core supports--this is because the one we build and put on nuget.org is built with the lowest common denominator glibc version, but yours was built with whatever glibc version is available on your distro. So it'd only run on your distro (or newer).
This is a reason why you probably shouldn't build a portable SDK. 😛 (We do want to make the source-built runtime pack usable, and once we do, it'd break you.)

[crummel]

[Scrub] This is less relevant with the recent and planned changes to portable builds and RIDs in general, as well as the VMR. Closing as obsolete but we should keep bootstrapping instructions in mind for the VMR.