Update docs for packaging and other nits (dotnet#40134)

* Update docs for packaging and other nits

docs/coding-guidelines/project-guidelines.md

@@ -1,39 +1,33 @@
 # Build Project Guidelines
-In order to work in dotnet/runtime repo you must first run build.cmd/sh from the root of the repo at least
-once before you can iterate and work on a given library project.
+In order to work in the dotnet/runtime repo you must first run build.cmd/sh from the root of the repo at least once before you can iterate and work on a given library project.
 
 ## Behind the scenes with build.cmd/sh
 
-- Setup tools (currently done in restore in build.cmd/sh)
+- Restore tools
 - Restore external dependencies
  - CoreCLR - Copy to `bin\runtime\$(BuildTargetFramework)-$(TargetOS)-$(Configuration)-$(TargetArchitecture)`
 - Build targeting pack
  - Build src\libraries\ref.proj which builds all references assembly projects. For reference assembly project information see [ref](#ref)
 - Build product
  - Build src\libraries\src.proj which builds all the source library projects. For source library project information see [src](#src).
-- Sign product
- - Build src\sign.proj
 
 # Build Pivots
 Below is a list of all the various options we pivot the project builds on:
 
-- **Target Frameworks:** NetFx (aka Desktop), netstandard (aka dotnet/Portable), NETCoreApp (aka .NET Core)
-- **Platform Runtimes:** NetFx (aka CLR/Desktop), CoreCLR, Mono
+- **Target Frameworks:** .NETFramework, .NETStandard, .NETCoreApp
+- **Platform Runtimes:** .NETFramework (aka CLR/Desktop), CoreCLR, Mono
 - **OS:** Windows_NT, Linux, OSX, FreeBSD, AnyOS
 - **Flavor:** Debug, Release
-- **Architecture:** x86, x64, arm, arm64, AnyCPU
 
 ## Individual build properties
 The following are the properties associated with each build pivot
 
-- `$(BuildTargetFramework) -> Any .NETCoreApp, .NETStandard or .NETFramework TFM, e.g. net5.0`
+- `$(BuildTargetFramework) -> Any .NETCoreApp or .NETFramework TFM, e.g. net5.0`
 - `$(TargetOS) -> Windows | Linux | OSX | FreeBSD | [defaults to running OS when empty]`
 - `$(Configuration) -> Release | [defaults to Debug when empty]`
 - `$(TargetArchitecture) - x86 | x64 | arm | arm64 | [defaults to x64 when empty]`
 - `$(RuntimeOS) - win7 | osx10.10 | ubuntu.14.04 | [any other RID OS+version] | [defaults to running OS when empty]` See [RIDs](https://github.com/dotnet/runtime/tree/master/src/libraries/pkg/Microsoft.NETCore.Platforms) for more info.
 
-For more information on various targets see also [.NET Standard](https://github.com/dotnet/standard/blob/master/docs/versions.md)
-
 ## Aggregate build properties
 Each project will define a set of supported TargetFrameworks
 
@@ -137,44 +131,34 @@ Reference assemblies are required for any library that has more than one impleme
 In the ref directory for the library there should be at most **one** `.csproj` that contains the latest API for the reference assembly for the library. That project can contain multiple entries in its `TargetFrameworks` property. Ref projects should use `<ProjectReference>` for its dependencies.
 
 ### ref output
-The output for the ref project build will be a flat targeting pack folder in the following directory:
-
-`bin\ref\$(TargetFramework)`
+All ref outputs should be under
 
-<BR/>//**CONSIDER**: Do we need a specific BuildTargetFramework version of TargetFramework for this output path to ensure all projects output to same targeting path?
+`bin\$(MSBuildProjectName)\ref\$(TargetFramework)`
 
 ## src
 In the src directory for a library there should be only **one** `.csproj` file that contains any information necessary to build the library in various target frameworks. All supported target frameworks should be listed in the `TargetFrameworks` property.
 
-All libraries should use `<Reference Include="..." />` for all their project references. That will cause them to be resolved against a targeting pack (i.e. `bin\ref\net5.0` or `\bin\ref\netstandard2.0`) based on the project target framework. There should not be any direct project references to other libraries. The only exception to that rule right now is for partial facades which directly reference System.Private.CoreLib and thus need to directly reference other partial facades to avoid type conflicts.
-<BR>//**CONSIDER**: just using Reference and use a reference to System.Private.CoreLib as a trigger to turn the other References into a ProjectReference automatically. That will allow us to have consistency where all projects just use Reference.
+All libraries should use `<Reference Include="..." />` for all their references to libraries that compose the shared framework of the current .NETCoreApp. That will cause them to be resolved against the locally built targeting pack which is located at `artifacts\bin\microsoft.netcore.app.ref`. The only exception to that rule right now is for partial facades which directly reference System.Private.CoreLib and thus need to directly reference other partial facades to avoid type conflicts.
 
-### src output
-The output for the src product build will be a flat runtime folder into the following directory:
+Other target frameworks than .NETCoreApp latest (i.e. `netstandard2.0`, `net461`, `netcoreapp3.0`) should use ProjectReference items to reference dependencies.
 
-`bin\runtime\$(BuildSettings)`
+### src output
+All src outputs are under
 
-Note: The `BuildSettings` is a global property and not the project setting because we need all projects to output to the same runtime directory no matter which compatible target framework we select and build the project with.
-```<BuildSettings>$(BuildTargetFramework)-$(TargetOS)-(Configuration)-(TargetArchitecture)</BuildSettings>```
+`bin\$(MSBuildProjectName)\$(TargetFramework)`
 
 ## pkg
 In the pkg directory for the library there should be only **one** `.pkgproj` for the primary package for the library. If the library has platform-specific implementations those should be split into platform specific projects in a subfolder for each platform. (see [Package projects](./package-projects.md))
 
-TODO: Outline changes needed for pkgprojs
-
 ## tests
 Similar to the src projects tests projects will define a `TargetFrameworks` property so they can list out the set of target frameworks they support.
 
-Tests should not have any `<Reference>` or `<ProjectReference>` items in their project because they will automatically reference everything in the targeting pack based on the TargetFramework they are building in. The only exception to this is a `<ProjectReference>` can be used to reference other test helper libraries or assets.
-
-In order to build and run a test project in a given build target framework a root level build.cmd/sh must have been completed for that build target framework first. Tests will run on the live built runtime at `bin\runtime\$(BuildSettings)`.
-TODO: We need update our test host so that it can run from the shared runtime directory as well as resolve assemblies from the test output directory.
+Tests don't need to reference default references which are part of the targeting packs (i.e. `mscorlib` on .NETFramework or `System.Runtime` on .NETCoreApp). Everything on top of targeting packs should be referenced via ProjectReference items for live built assets.
 
 ### tests output
 All test outputs should be under
 
-`bin\tests\$(MSBuildProjectName)\$(TargetFramework)` or
-`bin\tests\$(MSBuildProjectName)\netstandard2.0`
+`bin\$(MSBuildProjectName)\$(TargetFramework)`
 
 ## Facades
 Facade are unique in that they don't have any code and instead are generated by finding a contract reference assembly with the matching identity and generating type forwards for all the types to where they live in the implementation assemblies (aka facade seeds). There are also partial facades which contain some type forwards as well as some code definitions. All the various build configurations should be contained in the one csproj file per library.

docs/workflow/building/libraries/README.md

@@ -9,7 +9,7 @@ Here is one example of a daily workflow for a developer working mainly on the li
 git clean -xdf
 git pull upstream master & git push origin master
 :: Build Debug libraries on top of Release runtime:
-build -subset clr+libs -runtimeConfiguration Release
+build clr+libs -rc Release
 :: The above you may only perform once in a day, or when you pull down significant new changes.
 
 :: If you use Visual Studio, you might open System.Text.RegularExpressions.sln here.
@@ -33,7 +33,7 @@ The instructions for Linux and macOS are essentially the same:
 git clean -xdf
 git pull upstream master & git push origin master
 # Build Debug libraries on top of Release runtime:
-./build.sh -subset clr+libs -runtimeconfiguration Release
+./build.sh clr+libs -rc Release
 # The above you may only perform once in a day, or when you pull down significant new changes.
 
 # Switch to working on a given library (RegularExpressions in this case)
@@ -56,12 +56,12 @@ These example commands will build a release CoreCLR (and CoreLib), debug librari
 
 For Linux:
 ```bash
-./build.sh -runtimeConfiguration Release
+./build.sh -rc Release
 ```
 
 For Windows:
 ```bat
-./build.cmd -runtimeConfiguration Release
+./build.cmd -rc Release
 ```
 
 Detailed information about building and testing runtimes and the libraries is in the documents linked below.
@@ -83,26 +83,20 @@ For more details on the build settings see [project-guidelines](../../../coding-
 
 If you invoke the `build` script without any actions, the default action chain `-restore -build` is executed.
 
-By default the `build` script only builds the product libraries and none of the tests. If you want to include tests, you want to add the subset `-subset libs.tests`. If you want to run the tests you want to use the `-test` action instead of the `-build`, e.g. `build.cmd/sh -subset libs.tests -test`. To specify just the libraries, use `-subset libs`.
+By default the `build` script only builds the product libraries and none of the tests. If you want to include tests, you want to add the subset `libs.tests`. If you want to run the tests you want to use the `-test` action instead of the `-build`, e.g. `build.cmd/sh libs.tests -test`. To specify just the libraries, use `libs`.
 
 **Examples**
 - Building in release mode for platform x64 (restore and build are implicit here as no actions are passed in)
 ```bash
-./build.sh -subset libs -c Release -arch x64
+./build.sh libs -c Release -arch x64
 ```
 
 - Building the src assemblies and build and run tests (running all tests takes a considerable amount of time!)
 ```bash
-./build.sh -subset libs -test
+./build.sh libs -test
 ```
 
-- Building for different target frameworks (restore and build are implicit again as no action is passed in)
-```bash
-./build.sh -subset libs -framework net5.0
-./build.sh -subset libs -framework net472
-```
-
-- Clean the entire solution
+- Clean the entire artifacts folder
 ```bash
 ./build.sh -clean
 ```
@@ -199,24 +193,24 @@ You can use the same workflow for mono runtime by using `mono.corelib+libs.prete
 By default the libraries will attempt to build using the CoreCLR version of `System.Private.CoreLib.dll`. In order to build against the Mono version you need to use the `/p:RuntimeFlavor=Mono` argument.
 
 ```
-.\build.cmd -subset libs /p:RuntimeFlavor=Mono
+.\build.cmd libs /p:RuntimeFlavor=Mono
 ```
 
 ### Building all for other OSes
 
 By default, building from the root will only build the libraries for the OS you are running on. One can
-build for another OS by specifying `./build.sh -subset libs -os [value]`.
+build for another OS by specifying `./build.sh libs -os [value]`.
 
 Note that you cannot generally build native components for another OS but you can for managed components so if you need to do that you can do it at the individual project level or build all via passing `/p:BuildNative=false`.
 
 ### Building in Release or Debug
 
 By default, building from the root or within a project will build the libraries in Debug mode.
-One can build in Debug or Release mode from the root by doing `./build.sh -subset libs -c Release` or `./build.sh -subset libs -c Debug`.
+One can build in Debug or Release mode from the root by doing `./build.sh libs -c Release` or `./build.sh libs`.
 
 ### Building other Architectures
 
-One can build 32- or 64-bit binaries or for any architecture by specifying in the root `./build.sh -subset libs -arch [value]` or in a project `/p:TargetArchitecture=[value]` after the `dotnet build` command.
+One can build 32- or 64-bit binaries or for any architecture by specifying in the root `./build.sh libs -arch [value]` or in a project `/p:TargetArchitecture=[value]` after the `dotnet build` command.
 
 ## Working in Visual Studio
 
@@ -227,3 +221,17 @@ If you are working on Windows, and use Visual Studio, you can open individual li
 For more details about running tests inside Visual Studio, [go here](../../testing/visualstudio.md).
 
 For more about running tests, read the [running tests](../../testing/libraries/testing.md) document.
+
+## Build packages
+To build a library's package, simply invoke `dotnet pack` on the src project after you successfully built the .NETCoreApp vertical from root:
+
+```
+build libs
+dotnet pack src\libraries\System.Text.Json\src\
+```
+
+Same as for `dotnet build` or `dotnet publish`, you can specify the desired configuration via the `-c` flag:
+
+```
+dotnet pack src\libraries\System.Text.Json\src\ -c Release
+```

docs/workflow/building/libraries/webassembly-instructions.md

@@ -34,12 +34,12 @@ The libraries build contains some native code. This includes shims over libc, op
 
 - Building in debug mode for platform wasm and Browser operating system
 ```bash
-./build.sh --arch wasm --os Browser --subset Libs.Native --configuration Debug
+./build.sh libs.native --arch wasm --os Browser
 ```
 
 - Building in release mode for platform wasm and Browser operating system
 ```bash
-./build.sh --arch wasm --os Browser --subset Libs.Native --configuration Release
+./build.sh libs.native --arch wasm --os Browser -c Release
 ```
 
 ## How to build mono System.Private.CoreLib
@@ -48,20 +48,19 @@ If you are working on core parts of mono libraries you will probably need to bui
 
 
 ```bash
-./build.sh --arch wasm --os Browser --configuration release --subset Mono
+./build.sh mono --arch wasm --os Browser -c Release
 ```
 
 To build just SPC without mono you can use the Mono.CoreLib subset.
 
 ```bash
-./build.sh --arch wasm --os Browser --configuration release --subset Mono.CoreLib
+./build.sh mono.corelib --arch wasm --os Browser -c Release
 ```
 
-
 Building the managed libraries as well:
 
 ```bash
-./build.sh --arch wasm --os Browser --configuration release --subset Mono+Libs
+./build.sh mono+libs --arch wasm --os Browser -c Release
 ```
 
 ## Building individual libraries
@@ -71,16 +70,16 @@ Individual projects and libraries can be build by specifying the build configura
 Building individual libraries
 **Examples**
 
-- Build all projects for a given library (e.g.: System.Net.Http) including running the tests
+- Build all projects for a given library (e.g.: System.Net.Http) including the tests
 
 ```bash
- ./build.sh --arch wasm --os Browser --configuration release --projects src/libraries/System.Net.Http/System.Net.Http.sln
+ ./build.sh --arch wasm --os Browser -c Release --projects src/libraries/System.Net.Http/System.Net.Http.sln
 ```
 
 - Build only the source project of a given library (e.g.: System.Net.Http)
 
 ```bash
- ./build.sh --arch wasm --os Browser --configuration release --projects src/libraries/System.Net.Http/src/System.Net.Http.csproj
+ ./build.sh --arch wasm --os Browser -c Release --projects src/libraries/System.Net.Http/src/System.Net.Http.csproj
 ```
 
 More information and examples can be found in the [libraries](./README.md#building-individual-libraries) document.