Updated build instructions (#5534)

* Updated build instructions

* Adressed reviews

* Reviews

Author: mstfbl

docs/building/assets/process_architecture_run_tests_vs.png

@@ -5,8 +5,8 @@ ML.NET source code files build for .NET Core 3.1 and .NET Standard 2.0. However,
 
 To run tests on .NET Core 3.1, you need to do a few manual steps.
 
-1. Run `.\build.cmd -- /p:Configuration=Release-netcoreapp3_1` or `.\build.cmd -Release-netcoreapp3_1` from the root of the repo.
-2. If you want to build the NuGet packages, `.\build.cmd -buildPackages` after step 1.
+1. Run `.\build.cmd -configuration Debug-netcoreapp3_1` or `.\build.cmd -configuration Release-netcoreapp3_1` from the root of the repo.
+2. If you want to build the NuGet packages, `.\build.cmd -pack` after step 1.
 
 If you are using Visual Studio, you will need to do the following:
 

docs/building/netcoreapp3.1-instructions.md

@@ -48,7 +48,7 @@ On macOS a few components are needed which are not provided by a default develop
 * libomp 7
 * libgdiplus
 * gettext
-* All the requirements necessary to run .NET Core 3.1 applications. To view macOS prerequisites click [here](https://docs.microsoft.com/en-us/dotnet/core/macos-prerequisites?tabs=netcore30).
+* All the requirements necessary to run .NET Core 3.1 applications. To view macOS prerequisites click [here](https://docs.microsoft.com/en-us/dotnet/core/install/macos?tabs=netcore31#dependencies).
 
 One way of obtaining CMake and other required libraries is via [Homebrew](https://brew.sh):
 ```sh

docs/building/unix-instructions.md

@@ -56,21 +56,29 @@ You can use the Developer Command Prompt, Powershell or work in any regular cmd.
 From a (non-admin) Command Prompt window:
 
 - `build.cmd` - builds the assemblies
-- `build.cmd -runTests` - called after a normal "build.cmd" will run all tests
-- `build.cmd -buildPackages` called after a normal “build.cmd” will create the NuGet packages with the assemblies in “bin"
+- `build.cmd -test -integrationTest` - builds the assemblies and runs all tests, including integration tests.
+- `build.cmd -pack` builds the assemblies and generates the corresponding NuGet packages with the assemblies in `artifacts\packages`"
 
 **Note**: Before working on individual projects or test projects you **must** run `build.cmd` from the root once before beginning that work. It is also a good idea to run `build.cmd` whenever you pull a large set of unknown changes into your branch.
 
 ## Running Tests
 
 ### Running tests from Visual Studio
 
-After successfully building, run tests in the Visual Studio Test Explorer window.
+After successfully building, run tests through the Visual Studio Test Explorer window.
+
+Before running tests on Visual Studio, make sure you have selected the correct processor architecture (`x64`, `x86`) for running unit tests that your machine supports and that you have built ML.NET on. To check, click on the settings image in the Test Explorer window, then on "Process Architecture for AnyCPU Projects", and then on the correct architecture type, as demonstrated in the image below:
+
+![Check for unit test process architecture](./assets/process_architecture_run_tests_vs.png)
 
 ### Running tests from the command line
 
-From the root, run `build.cmd` and then `build.cmd -runTests`.
-For more details, or to test an individual project, you can navigate to the test project directory and then use `dotnet test`
+From root, run `build.cmd -test -integrationTest`.
+For more details, or to test an individual project, you can navigate to the test project directory and then use `dotnet test`.
+
+## Running Benchmarks
+
+For more information on running ML.NET benchmarks, please visit the [benchmarking instructions](../../test/Microsoft.ML.PerformanceTests/README.md).
 
 ## Known Issues
 

docs/building/windows-instructions.md

@@ -18,9 +18,9 @@ Developer Workflow
 The dev workflow describes the [development process](https://github.com/dotnet/buildtools/blob/master/Documentation/Dev-workflow.md) to follow. It is divided into specific tasks that are fast, transparent and easy to understand.
 The tasks are represented in scripts (cmd/sh) in the root of the repo.
 
-For more information about the different options that each task has, use the argument `-?` when calling the script.  For example:
+For more information about the different options that each task has, use the argument `-help` when calling the script.  For example:
 ```
-build -?
+build -help
 ```
 
 **Examples**
@@ -33,13 +33,12 @@ git submodule update --init
 
 - Building in release mode for platform x64
 ```
-build.cmd -Release -TargetArchitecture:x64
+build.cmd -configuration Release /p:TargetArchitecture=x64
 ```
 
 - Building the src and then building and running the tests
 ```
-build.cmd
-build.cmd -runTests
+build.cmd -test
 ```
 
 ### Building individual projects
@@ -60,11 +59,19 @@ You can build the tests for Microsoft.MachineLearning.Core.dll by going to
 ### 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.cmd -Release` or `build.cmd -Debug`.
+One can build in Debug or Release mode from the root by doing `build.cmd -configuration Release` or `build.cmd -configuration Debug`.
+
+Currently, the full list of supported configurations are:
+- `Debug`, `Release` (for .NET Core 2.1)
+- `Debug-netcoreapp3_1`, `Release-netcoreapp3_1` (for .NET Core 3.1)
+- `Debug-netfx`, `Release-netfx` (for .NET Framework 4.6.1)
 
 ### Building other Architectures
 
-We only support 64-bit binaries right now.
+We support both 32-bit and 64-bit binaries. To build in 32-bit, use the `TargetArchitecture` flag as below:
+```
+build.cmd -configuration Debug /p:TargetArchitecture=x86
+```
 
 ### Updating manifest and ep-list files
 
@@ -79,6 +86,20 @@ Steps to update `core_manifest.json` and `core_ep-list.tsv`:
 4. Re-enable the skip attribute on the `RegenerateEntryPointCatalog` test.
 5. Commit the updated `core_manifest.json` and `core_ep-list.tsv` files to your branch.
 
+### Running specifics unit tests on CI
+
+It may be necessary to run only specific unit tests on CI, and perhaps even run these tests back to back multiple times. The steps to run one or more unit tests are as follows:
+1. Set `runSpecific: true` and `innerLoop: false` in [.vsts-dotnet-ci.yml](https://github.com/dotnet/machinelearning/blob/master/.vsts-dotnet-ci.yml) per each build you'd like to run the specifics tests on CI.
+2. Import `Microsoft.ML.TestFrameworkCommon.Attributes` in the unit test files that contain specific unit tests to be run.
+3. Add the `[TestCategory("RunSpecificTest")]` to the unit test(s) you'd like to run specifically.
+
+If you would like to run these specific unit test(s) multiple times, do the following for each unit test to run:
+1. Replace the `[Fact]` attribute with `[Theory, IterationData(X)]` where `X` is the number of times to run the unit test.
+2. Add the `int iteration` argument to the unit test you'd like to run multiple times.
+3. Use the `iteration` parameter at least once in the unit test. This may be as simple as printing to console the `iteration` parameter's value.
+
+These steps are demonstrated in this demonstrative [commit](https://github.com/dotnet/machinelearning/commit/2fb5f8cfcd2a81f27bc22ac6749f1ce2045e925b).
+
 ### Running unit tests through VSTest Task & Collecting memory dumps
 
 During development, there may also arise a need to debug hanging tests. In this scenario, it can be beneficial to collect the memory dump while a given test is hanging.