Skip to content

Commit 4549956

Browse files
authored
Updated build instructions (#5534)
* Updated build instructions * Adressed reviews * Reviews
1 parent b927a0f commit 4549956

File tree

5 files changed

+44
-15
lines changed

5 files changed

+44
-15
lines changed
Loading

docs/building/netcoreapp3.1-instructions.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,8 @@ ML.NET source code files build for .NET Core 3.1 and .NET Standard 2.0. However,
55

66
To run tests on .NET Core 3.1, you need to do a few manual steps.
77

8-
1. Run `.\build.cmd -- /p:Configuration=Release-netcoreapp3_1` or `.\build.cmd -Release-netcoreapp3_1` from the root of the repo.
9-
2. If you want to build the NuGet packages, `.\build.cmd -buildPackages` after step 1.
8+
1. Run `.\build.cmd -configuration Debug-netcoreapp3_1` or `.\build.cmd -configuration Release-netcoreapp3_1` from the root of the repo.
9+
2. If you want to build the NuGet packages, `.\build.cmd -pack` after step 1.
1010

1111
If you are using Visual Studio, you will need to do the following:
1212

docs/building/unix-instructions.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ On macOS a few components are needed which are not provided by a default develop
4848
* libomp 7
4949
* libgdiplus
5050
* gettext
51-
* 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).
51+
* 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).
5252

5353
One way of obtaining CMake and other required libraries is via [Homebrew](https://brew.sh):
5454
```sh

docs/building/windows-instructions.md

+13-5
Original file line numberDiff line numberDiff line change
@@ -56,21 +56,29 @@ You can use the Developer Command Prompt, Powershell or work in any regular cmd.
5656
From a (non-admin) Command Prompt window:
5757

5858
- `build.cmd` - builds the assemblies
59-
- `build.cmd -runTests` - called after a normal "build.cmd" will run all tests
60-
- `build.cmd -buildPackages` called after a normal “build.cmd” will create the NuGet packages with the assemblies in “bin"
59+
- `build.cmd -test -integrationTest` - builds the assemblies and runs all tests, including integration tests.
60+
- `build.cmd -pack` builds the assemblies and generates the corresponding NuGet packages with the assemblies in `artifacts\packages`"
6161

6262
**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.
6363

6464
## Running Tests
6565

6666
### Running tests from Visual Studio
6767

68-
After successfully building, run tests in the Visual Studio Test Explorer window.
68+
After successfully building, run tests through the Visual Studio Test Explorer window.
69+
70+
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:
71+
72+
![Check for unit test process architecture](./assets/process_architecture_run_tests_vs.png)
6973

7074
### Running tests from the command line
7175

72-
From the root, run `build.cmd` and then `build.cmd -runTests`.
73-
For more details, or to test an individual project, you can navigate to the test project directory and then use `dotnet test`
76+
From root, run `build.cmd -test -integrationTest`.
77+
For more details, or to test an individual project, you can navigate to the test project directory and then use `dotnet test`.
78+
79+
## Running Benchmarks
80+
81+
For more information on running ML.NET benchmarks, please visit the [benchmarking instructions](../../test/Microsoft.ML.PerformanceTests/README.md).
7482

7583
## Known Issues
7684

docs/project-docs/developer-guide.md

+28-7
Original file line numberDiff line numberDiff line change
@@ -18,9 +18,9 @@ Developer Workflow
1818
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.
1919
The tasks are represented in scripts (cmd/sh) in the root of the repo.
2020

21-
For more information about the different options that each task has, use the argument `-?` when calling the script. For example:
21+
For more information about the different options that each task has, use the argument `-help` when calling the script. For example:
2222
```
23-
build -?
23+
build -help
2424
```
2525

2626
**Examples**
@@ -33,13 +33,12 @@ git submodule update --init
3333

3434
- Building in release mode for platform x64
3535
```
36-
build.cmd -Release -TargetArchitecture:x64
36+
build.cmd -configuration Release /p:TargetArchitecture=x64
3737
```
3838

3939
- Building the src and then building and running the tests
4040
```
41-
build.cmd
42-
build.cmd -runTests
41+
build.cmd -test
4342
```
4443

4544
### Building individual projects
@@ -60,11 +59,19 @@ You can build the tests for Microsoft.MachineLearning.Core.dll by going to
6059
### Building in Release or Debug
6160

6261
By default, building from the root or within a project will build the libraries in Debug mode.
63-
One can build in Debug or Release mode from the root by doing `build.cmd -Release` or `build.cmd -Debug`.
62+
One can build in Debug or Release mode from the root by doing `build.cmd -configuration Release` or `build.cmd -configuration Debug`.
63+
64+
Currently, the full list of supported configurations are:
65+
- `Debug`, `Release` (for .NET Core 2.1)
66+
- `Debug-netcoreapp3_1`, `Release-netcoreapp3_1` (for .NET Core 3.1)
67+
- `Debug-netfx`, `Release-netfx` (for .NET Framework 4.6.1)
6468

6569
### Building other Architectures
6670

67-
We only support 64-bit binaries right now.
71+
We support both 32-bit and 64-bit binaries. To build in 32-bit, use the `TargetArchitecture` flag as below:
72+
```
73+
build.cmd -configuration Debug /p:TargetArchitecture=x86
74+
```
6875

6976
### Updating manifest and ep-list files
7077

@@ -79,6 +86,20 @@ Steps to update `core_manifest.json` and `core_ep-list.tsv`:
7986
4. Re-enable the skip attribute on the `RegenerateEntryPointCatalog` test.
8087
5. Commit the updated `core_manifest.json` and `core_ep-list.tsv` files to your branch.
8188

89+
### Running specifics unit tests on CI
90+
91+
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:
92+
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.
93+
2. Import `Microsoft.ML.TestFrameworkCommon.Attributes` in the unit test files that contain specific unit tests to be run.
94+
3. Add the `[TestCategory("RunSpecificTest")]` to the unit test(s) you'd like to run specifically.
95+
96+
If you would like to run these specific unit test(s) multiple times, do the following for each unit test to run:
97+
1. Replace the `[Fact]` attribute with `[Theory, IterationData(X)]` where `X` is the number of times to run the unit test.
98+
2. Add the `int iteration` argument to the unit test you'd like to run multiple times.
99+
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.
100+
101+
These steps are demonstrated in this demonstrative [commit](https://github.com/dotnet/machinelearning/commit/2fb5f8cfcd2a81f27bc22ac6749f1ce2045e925b).
102+
82103
### Running unit tests through VSTest Task & Collecting memory dumps
83104

84105
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.

0 commit comments

Comments
 (0)