Initial pass on updating documentation to include MonoVM (dotnet#1863)

* Update documentation to cover also Mono runtime

* Updated requirements for mac and linux to include mono's

* Update System.Private.CoreLib/src/README.md

* Added initial mono building doc

* Added library testing steps for mono

* A bit of rewording based on feedback

* Add some scripts coloring

docs/workflow/README.md

@@ -18,13 +18,13 @@ Before proceeding further, please click on the link above that matches your mach
 
 The runtime repo can be built from a regular, non-administrator command prompt, from the root of the repo, as follows:
 
-For Linux:
-```
+For Linux and macOS
+```bash
 ./build.sh
 ```
 
 For Windows:
-```
+```bat
 build.cmd
 ```
 
@@ -35,9 +35,9 @@ For information about the different options available, supply the argument `--he
 build -h
 ```
 
-On Unix, arguments can be passed in with a single `-` or double hyphen `--`.
+On Unix like systems, arguments can be passed in with a single `-` or double hyphen `--`.
 
-The repository currently consists of three different major parts: the runtime (a.k.a. coreclr), the libraries, and the installer.
+The repository currently consists of different major parts: the runtimes, the libraries, and the installer.
 To build just one part you use the root build script (build.cmd/sh), and you add the `-subsetCategory` flag.
 
 ## Configurations
@@ -46,33 +46,37 @@ You may need to build the tree in a combination of configurations. This section
 
 A quick reminder of some concepts -- see the [glossary](../project/glossary.md) for more on these:
 
-* **Debug configuration** -- Non-optimized code.  Asserts are enabled.
-* **Checked configuration** -- Optimized code. Asserts are enabled.  Only relevant to CoreCLR.
-* **Release configuration** -- Optimized code. Asserts are disabled. Runs at full speed, and suitable for performance profiling. Somewhat poorer debugging experience.
+* **Debug Configuration** -- Non-optimized code.  Asserts are enabled.
+* **Checked Configuration** -- Optimized code. Asserts are enabled.  Only relevant to CoreCLR runtime.
+* **Release Configuration** -- Optimized code. Asserts are disabled. Runs at best speed, and suitable for performance profiling. You will have limited debugging experience.
 
-When we talk about mixing configurations, we're discussing three sub-components:
+When we talk about mixing configurations, we're discussing following sub-components:
 
-* **CoreCLR** (often referred to as the runtime, most code under src/coreclr) -- this is the execution engine for managed code. It is written in C/C++. When built in a debug configuration, it is easier to debug into it, but it executes managed code more slowly - so slowly it will take a long time to run the managed code unit tests.
-* **CoreLib** (also known as System.Private.CoreLib - code under src/coreclr/System.Private.CoreLib) -- this is the lowest level managed library. It has a special relationship with the runtime -- it must be in the matching configuration, e.g., if the runtime you are using was built in a debug configuration, this must be in a debug configuration.
-* **All other libraries** (most code under src/libraries) -- the bulk of the libraries are oblivious to the configuration that CoreCLR/CoreLib were built in. Like most code they are most debuggable when built in a debug configuration, and, happily, they still run sufficiently fast in that configuration that it's acceptable for development work.
+* **Runtime** is the execution engine for managed code and there are two different implementations available. Both are written in C/C++, therefore, easier to debug when built in a Debug configuration.
+    * CoreCLR is comprehensive execution engine which if build in Debug Configuration it executes managed code very slowly. For example, it will take a long time to run the managed code unit tests. The code lives under [src/coreclr](../../src/coreclr).
+    * Mono is portable and also slimmer runtime and it's not that sensitive to Debug Configuration for running managed code. You will still need to build it without optimizations to have good runtime debugging experience though. The code lives under [src/mono](../../src/mono).
+* **CoreLib** (also known as System.Private.CoreLib) is the lowest level managed library. It has a special relationship to the runtimes and therefore it must be built in the matching configuration, e.g., if the runtime you are using was built in a Debug configuration, this must be in a Debug configuration. The runtime agnostic code for this library can be found at [src/libraries/System.Private.CoreLib/src](../../src/libraries/System.Private.CoreLib/src/README.md).
+* **Libraries** is the bulk of the dlls that are oblivious to the configuration that runtimes and CoreLib were built in. They are most debuggable when built in a Debug configuration, and, happily, they still run sufficiently fast in that configuration that it's acceptable for development work. The code lives under [src/libraries](../../src/libraries).
 
 ### What does this mean for me?
 
-At this point you probably know what you are planning to work on first: the runtime or libraries.
+At this point you probably know what you are planning to work on primary: the runtimes or libraries.
 
-* if you're working in CoreCLR proper, you may want to build everything in the debug configuration, depending on how comfortable you are debugging optimized native code.
-* if you're working in most libraries, you will want to use debug libraries with release CoreCLR and CoreLib, because the tests will run faster.
-* if you're working in CoreLib - you probably want to try to get the job done with release CoreCLR and CoreLib, and fall back to debug if you need to. The [Building libraries](building/libraries/README.md) document explains how you'll do this.
+* if you're working in runtimes, you may want to build everything in the Debug configuration, depending on how comfortable you are debugging optimized native code.
+* if you're working in libraries, you will want to use debug libraries with release version of runtime and CoreLib, because the tests will run faster.
+* if you're working in CoreLib - you probably want to try to get the job done with release runtime and CoreLib, and fall back to debug if you need to. The [Building Libraries](building/libraries/README.md) document explains how you'll do this.
 
 Now you know about configurations and how we use them, you will want to read how to build what you plan to work on. Pick one of these:
 
-- [Building coreclr](building/coreclr/README.md)
-- [Building libraries](building/libraries/README.md)
+- [Building CoreCLR runtime](building/coreclr/README.md)
+- [Building Mono runtime](building/mono/README.md)
+- [Building Libraries](building/libraries/README.md)
 
 After that, here's information about how to run tests:
 
-- [Testing coreclr](testing/coreclr/testing.md)
-- [Testing libraries](testing/libraries/testing.md)
+- [Testing CoreCLR runtime](testing/coreclr/testing.md)
+- [Testing Mono runtime](testing/mono/testing.md)
+- [Testing Libraries](testing/libraries/testing.md)
 
 And how to measure performance:
 

docs/workflow/building/libraries/README.md

@@ -4,8 +4,8 @@
 
 Here is one example of a daily workflow for a developer working mainly on the libraries, in this case using Windows:
 
-```
-:: From root in the morning:
+```bat
+:: From root:
 git clean -xdf
 git pull upstream master & git push origin master
 build -subsetCategory coreclr -c Release
@@ -27,10 +27,10 @@ cd tests
 pushd ..\src & dotnet msbuild & popd & dotnet msbuild /t:buildandtest
 ```
 
-The instructions for Linux are essentially the same:
+The instructions for Linux and macOS are essentially the same:
 
-```
-# From root in the morning:
+```bash
+# From root:
 git clean -xdf
 git pull upstream master & git push origin master
 ./build.sh -subsetcategory coreclr -c Release
@@ -53,21 +53,21 @@ The steps above may be all you need to know to make a change. Want more details
 
 ## Building everything
 
-This document explains how to work on libraries. In order to work on library projects or run library tests it is necessary to have built CoreCLR (aka, the "runtime") to give the libraries something to run on. You should normally build CoreCLR in release configuration and libraries in debug configuration. If you haven't already done so, please read [this document](../../README.md#Configurations) to understand configurations.
+This document explains how to work on libraries. In order to work on library projects or run library tests it is necessary to have built the runtime to give the libraries something to run on. You should normally build CoreCLR runtime in release configuration and libraries in debug configuration. If you haven't already done so, please read [this document](../../README.md#Configurations) to understand configurations.
 
 These example commands will build a release CoreCLR (and CoreLib), debug libraries, and debug installer:
 
 For Linux:
-```
+```bash
 ./build.sh -coreclrconfiguration Release
 ```
 
 For Windows:
-```
+```bat
 ./build.cmd -coreclrConfiguration Release
 ```
 
-Detailed information about building and testing CoreCLR and the libraries is in the documents linked below.
+Detailed information about building and testing runtimes and the libraries is in the documents linked below.
 
 ### More details if you need them
 
@@ -90,28 +90,28 @@ By default build only builds the product libraries and none of the tests. If you
 
 **Examples**
 - Building in release mode for platform x64 (restore and build are implicit here as no actions are passed in)
-```
+```bash
 ./build.sh -subsetCategory libraries -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 -subsetCategory libraries -restore -build -buildtests -test
 ```
 
 - Building for different target frameworks (restore and build are implicit again as no action is passed in)
-```
+```bash
 ./build.sh -subsetCategory libraries -framework netcoreapp
 ./build.sh -subsetCategory libraries -framework netfx
 ```
 
 - Build only managed components and skip the native build
-```
+```bash
 ./build.sh -subsetCategory libraries /p:BuildNative=false
 ```
 
 - Clean the entire solution
-```
+```bash
 ./build.sh -subsetCategory libraries -clean
 ```
 
@@ -124,12 +124,12 @@ The libraries build contains some native code. This includes shims over libc, op
 **Examples**
 
 - Building in debug mode for platform x64
-```
+```bash
 ./src/libraries/Native/build-native.sh debug x64
 ```
 
 - The following example shows how you would do an arm cross-compile build.
-```
+```bash
 ./src/libraries/Native/build-native.sh debug arm cross verbose
 ```
 
@@ -143,17 +143,17 @@ Similar to building the entire repo with `build.cmd` or `build.sh` in the root y
 
 - Build all projects for a given library (e.g.: System.Collections) including running the tests
 
-```
+```bash
  ./build.sh -subsetCategory libraries src/libraries/System.Collections
 ```
 
 - Build just the tests for a library project.
-```
+```bash
  ./build.sh -subsetCategory libraries src/libraries/System.Collections/tests
 ```
 
 - All the options listed above like framework and configuration are also supported (note they must be after the directory)
-```
+```bash
  ./build.sh -subsetCategory libraries System.Collections -f netfx -c Release
 ```
 

docs/workflow/building/mono/README.md

@@ -0,0 +1,44 @@
+# Building Mono
+
+To build just Mono runtime, use the `--subsetCategory` flag to the `build.sh` (or `build.cmd`) at the repo root:
+
+```bash
+./build.sh --subsetCategory mono
+```
+or on Windows,
+```bat
+build.cmd --subsetCategory mono
+```
+
+By default, build generates a 'debug' build output, that includes asserts, less code optimizations and is easier for debugging. If you want to make performance measurements, or just want tests to execute more quickly, you can also build the 'release' version which does not have these checks by adding the flag `-configuration Release` (or `-c Release`) and `/p:__BuildType=Release`, for example
+```bash
+./build.sh --subsetCategory mono -configuration Release /p:__BuildType=Release
+```
+
+Product binaries will be dropped in `artifacts\bin\mono\<OS>.<arch>.<flavor>` folder.
+
+To generate nuget packages:
+
+```bash
+./build.sh --subsetCategory mono -pack (with optional release configuration)
+```
+or on Windows,
+```bat
+build.cmd --subsetCategory mono -pack (with optional release configuration)
+```
+
+The following packages will be created under `artifacts\packages\<configuration>\Shipping`:
+
+- `Microsoft.NETCore.Runtime.Mono.<version>-dev.<number>.1.nupkg`
+- `runtime.<OS>.Microsoft.NETCore.Runtime.Mono.<version>-dev.<number>.1.nupkg`
+- `transport.Microsoft.NETCore.Runtime.Mono.<version>-dev.<number>.1.nupkg`
+- `transport.runtime.<OS>.Microsoft.NETCore.Runtime.Mono.<version>-dev.<number>.1.nupkg`
+
+Test binaries are not yet available for mono.
+
+The build places logs in `artifacts\log` and these are useful when the build fails.
+
+The build places all of its output in the `artifacts\obj\mono` directory, so if you remove that directory you can force a
+full rebuild.
+
+The build has a number of options that you can learn about using `build -?`. 

docs/workflow/requirements/linux-requirements.md

@@ -69,6 +69,13 @@ Install the following packages for the toolchain:
 - cmake
 - llvm-9
 - clang-9
+- autoconf
+- automake
+- libtool
+- build-essential
+- python
+- curl
+- git
 - lldb-6.0
 - liblldb-6.0-dev
 - libunwind8
@@ -80,9 +87,8 @@ Install the following packages for the toolchain:
 - libkrb5-dev
 - libnuma-dev (optional, enables numa support)
 
-
 A single line to install all packages above:
 
-    ~$ sudo apt-get install cmake llvm-9 clang-9 lldb-6.0 liblldb-6.0-dev libunwind8 libunwind8-dev gettext libicu-dev liblttng-ust-dev libssl-dev libnuma-dev libkrb5-dev
+    ~$ sudo apt-get install cmake llvm-9 clang-9 autoconf automake libtool build-essential python curl git lldb-6.0 liblldb-6.0-dev libunwind8 libunwind8-dev gettext libicu-dev liblttng-ust-dev libssl-dev libnuma-dev libkrb5-dev
 
 You now have all the required components.

docs/workflow/requirements/macos-requirements.md

@@ -6,41 +6,42 @@ This guide will walk you through the requirements needed to build dotnet/runtime
 Environment
 ===========
 
-These instructions were validated on macOS 10.13 High Sierra.
+These instructions were validated on macOS 10.15 (Catalina).
 
 Xcode
 -----
 
 Install Apple Xcode developer tools from the Mac App Store ([link](https://apps.apple.com/us/app/xcode/id497799835)).
 
-CMake
------
-
-dotnet/runtime has a dependency on CMake 3.15.5 for the build. You can download it from [CMake downloads](http://www.cmake.org/download/).
+Toolchain Setup
+---------------
 
-Alternatively, you can install CMake from [Homebrew](http://brew.sh/).
+Building dotnet/runtime depends on several tools to be installed. You can download them individually or use [Homebrew](http://brew.sh) for easier toolchain setup.
 
-```sh
-brew install cmake
-```
+Install the following packages:
 
-ICU
----
+- cmake 3.15.5 or newer
+- autoconf
+- automake
+- libtool
+- pkg-config
+- python3
+- icu4c
 
-ICU (International Components for Unicode) is also required to build and run. It can be obtained via [Homebrew](http://brew.sh/).
+The lines to install all the packages above using Homebrew.
 
-```sh
-brew install icu4c
+```
+brew install cmake autoconf automake libtool pkg-config python3 icu4c
 brew link --force icu4c
 ```
 
 OpenSSL
 -------
 
-To build the libraries on macOS, you must install and configure links for OpenSSL 1.1, and install `pkg-config` to use it. Using [Homebrew](http://brew.sh/):
+To build the libraries on macOS, you must install and configure links for OpenSSL 1.1.
 
 ```sh
-brew install pkg-config openssl
+brew install openssl
 
 # You might need to "link" pkg-config:
 brew link pkg-config

docs/workflow/testing/mono/testing.md

@@ -0,0 +1,25 @@
+# Running Tests using Mono Runtime
+
+## Running Runtime Tests
+The runtime tests will be available at a later date.
+
+## Running Library Tests
+Running library tests again mono is straightforward regardless of configuration.  Simply run the following commands:
+
+1. Build and set the TestRuntimeFlavor
+
+```bash
+./build.sh /p:TestRuntimeFlavor=mono
+```
+or on Windows
+```bat
+build.cmd /p:TestRuntimeFlavor=mono
+```
+
+2. cd into the test library of your choice (`cd src/libraries/<library>/tests`)
+
+3. Run the tests
+
+```
+dotnet msbuild /t:BuildAndTest /p:TestRuntimeFlavor=mono
+```

src/libraries/System.Private.CoreLib/src/README.md

@@ -1,3 +1,15 @@
 # System.Private.CoreLib Shared Sources
 
-This directory contains the shared sources for System.Private.CoreLib. It represents the majority of the CoreLib implementation.  Each flavor of the runtime (e.g. coreclr, mono) provides a few additional files as part of its build of CoreLib to complement this directory's contents.
+This directory contains the shared sources for System.Private.CoreLib library. It represents the majority of the CoreLib implementation.  Each flavor of the runtime (e.g. coreclr, mono) provides additional files as part of their build of CoreLib to complement this directory's contents.
+
+Runtime specific partial part which have shared part use runtime specific suffix to easy the navigation.
+    * `.CoreCLR.cs` for CoreCLR runtime
+    * `.Mono.cs` for Mono runtime
+
+## System.Private.CoreLib CoreCLR Sources
+
+The CoreCLR specific sources can be found at [src/coreclr/src/System.Private.CoreLib](../../../coreclr/src/System.Private.CoreLib/).
+
+## System.Private.CoreLib Mono Sources
+
+The Mono specific sources can be found at [src/mono/netcore/System.Private.CoreLib](../../../mono/netcore/System.Private.CoreLib/).