Document Start-ResGen and Start-TypeGen (#2487)

docs/building/internals.md

@@ -1,5 +1,5 @@
 Internals of build process
-=========================================
+==========================
 
 The purpose of this document is to explain build process **internals** with subtle nuances.
 This document is not by any means complete.
@@ -9,7 +9,7 @@ This document assumes that you can successfully build PowerShell from sources fo
 
 
 Top directory
------------
+-------------
 
 We are calling `dotnet` tool build for `$Top` directory
 
@@ -32,3 +32,66 @@ it should be listed as a dependency for FullCLR $Top folder (src\powershell-win-
 
 * If assembly is part of CoreCLR build,
 it should be listed as a dependency for $Top folder (src\powershell-unix or src\powershell-win-core)
+
+Preliminary steps
+-----------------
+
+### ResGen
+
+Until the .NET CLI `dotnet-resgen` tool supports the generation of strongly typed classes,
+we run our own tool C# [ResGen tool](../../src/ResGen).
+While the `Start-PSBuild` command runs this automatically via the `Start-ResGen` function,
+it does *not* require PowerShell.
+The same command can be run manually:
+
+```sh
+dotnet restore
+cd src/ResGen
+dotnet run
+```
+
+Running the program does everything else:
+
+* for each project, given a `resources` folder
+  * creates a `gen` folder
+  * for each `*.resx` file
+    * fills in a strongly typed C# class
+    * writes it out to the corresponding `*.cs` file
+
+These files are *not* automatically updated on each build,
+as the project lacks the ability to detect changes.
+Thus, running it for every build would break incremental recompilation.
+
+If you pull new commits and get an error about missing strings,
+you likely need to delete the `gen` folders and re-run the tool.
+
+### Type Catalog
+
+As a work-around for the lack of `GetAssemblies()`,
+our custom assembly load context takes a pre-generated catalog of C# types
+(for PowerShell type resolution).
+Generating this catalog is a pre-build step that is run via `Start-TypeGen`,
+which `Start-PSBuild` calls.
+Again, however, PowerShell is not required.
+The necessary steps can be run manually:
+
+```sh
+dotnet restore
+cd src/TypeCatalogParser
+dotnet run
+cd ../TypeCatalogGen
+dotnet run ../Microsoft.PowerShell.CoreCLR.AssemblyLoadContext/CorePsTypeCatalog.cs powershell.inc
+```
+
+The [`TypeCatalogParser`](../../src/TypeCatalogParser)
+parses the `src/Microsoft.PowerShell.SDK/project.lock.json` file
+(created by `dotnet restore`),
+which contains the necessary data to resolve the paths to the DLLs of each dependency of PowerShell.
+It produces a list of the location of all the DLLs that have types to be cataloged
+(the output file is `powershell.inc`).
+This list is taken as input to the [`TypeCatalogGen`](../../src/TypeCatalogGen) tool,
+which generates a source file `CorePsTypeCatalog.cs` for the `Microsoft.PowerShell.CoreCLR.AssemblyLoadContext` project.
+
+The error `The name 'InitializeTypeCatalog' does not exist in the current context`
+indicates that the `CorePsTypeCatalog.cs` source file does not exist,
+so follow the steps to generate it.

docs/building/linux.md

@@ -111,6 +111,10 @@ Build manually
 
 The following goes into detail about what `Start-PSBuild` does.
 
+There are two preliminary steps that apply to all operating systems,
+the [ResGen](internals.md#resgen) and [type catalog generation](internals.md#type-catalog),
+documented in [internals of build process](internals.md#preliminary-steps).
+
 Build the native library
 ------------------------