Skip to content

Organize contributing notes and add WSL testing section #61408

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jcouv merged 2 commits into from
Jun 13, 2022
Merged

Organize contributing notes and add WSL testing section #61408

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e36165a
Organize contributing notes and add WSL testing section
jcouv May 19, 2022
4e5cf5d
Update Building, Debugging, and Testing on Windows.md
jcouv May 19, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 37 additions & 19 deletions docs/contributing/Building, Debugging, and Testing on Windows.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,22 @@ Tests can be run and debugged from the Test Explorer window. For best performanc
2. Use the Search box of Test Explorer to narrow the scope of visible tests to the feature(s) you are working on
3. When you are not actively running tests, set the search query to `__NonExistent__` to hide all tests from the UI

#### Testing in Linux using WSL

Tests can be run and debugged under WSL. This requires a bit of setup the first time. After that, it is as easy as selecting WSL as the active environment in Test Explorer.

1. Install WSL by running `wsl --install` ([details](https://docs.microsoft.com/en-us/windows/wsl/setup/environment#get-started))
2. In the VS installer, install ".NET Debugging with WSL" as an individual component
3. In Test Explorer, go into "Configure Remote Test Environments" (under the gear icon) and uncomment the wsl/Ubuntu environment:
![image](https://user-images.githubusercontent.com/12466233/169365278-485573de-0b14-466e-a96d-b1de5e67e891.png)
![image](https://user-images.githubusercontent.com/12466233/169365165-a2bfc6bc-96ba-45fa-8705-eb8e7997df62.png)
4. Select that test environment from Test Explorer drop-down:
![image](https://user-images.githubusercontent.com/12466233/169365451-681fcbb2-0b21-46f6-bc30-de58ce01bfdc.png)
5. Run a test from Test Explorer test list. This will prompt you to install some dotnet bits into the WSL environment the first time.
6. Debug a test. This will prompt you to install some remote debugging bits into the WSL environment the first time.

[More details](https://docs.microsoft.com/en-us/visualstudio/debugger/debug-dotnet-core-in-wsl-2)

### WPF Test Runner

To debug through tests, you can right click the test project that contains your
Expand All @@ -66,6 +82,13 @@ give it a try.

## Trying Your Changes in Visual Studio

### Deploying with command-line (recommended method)

You can build and deploy with the following command:
`.\Build.cmd -Configuration Release -deployExtensions -launch`.

Then you can launch the `RoslynDev` hive with `devenv /rootSuffix RoslynDev`.

### Deploying with F5

The Rosyln solution is designed to support easy debugging via F5. Several of our
Expand Down Expand Up @@ -140,13 +163,7 @@ your csproj. As shown below, you'll want to (1) add a nuget source pointing to y

![image](https://user-images.githubusercontent.com/12466233/81206129-7fbe8680-8f80-11ea-9438-acc0481a3585.png)


### Deploying with command-line

You can build and deploy with the following command:
`.\Build.cmd -Configuration Release -deployExtensions -launch`.

Then you can launch the `RoslynDev` hive with `devenv /rootSuffix RoslynDev`.
## Various other tips

### Referencing bootstrap compiler

Expand Down Expand Up @@ -185,18 +202,7 @@ Run `build.cmd -testIOperation` which sets the `ROSLYN_TEST_IOPERATION` environm
For running those tests in an IDE, the easiest is to find the `//#define ROSLYN_TEST_IOPERATION` directive and uncomment it.
See more details in the [IOperation test hook](https://github.com/dotnet/roslyn/blob/main/docs/compilers/IOperation%20Test%20Hook.md) doc.

### Running the PublicAPI fixer

1. Install `dotnet-format` as a global tool. It does ship as part of the SDK, but a separate version can be installed as a global tool and invoked with `dotnet-format {options}`.
`C:\Source\roslyn> dotnet tool install -g dotnet-format --version "6.*" --add-source https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet6/nuget/v3/index.json`
2. Restore and build `Compilers.sln`. This is necessary to ensure the source generator project is built and we can load the generator assembly when running `dotnet-format`.
`C:\Source\roslyn> .\restore.cmd`
`C:\Source\roslyn> .\build.cmd`
3. Invoke the `dotnet-format` global tool. Running only the analyzers subcommand and fixing only the "missing Public API signature" diagnostic. We must also pass the `--include-generated` flag to include source generated documents in the analysis.
`C:\Source\roslyn> cd ..`
`C:\Source> dotnet-format analyzers .\roslyn\Compilers.sln --diagnostics=RS0016 --no-restore --include-generated -v diag`

## Replicating Failures in the Used Assemblies leg
### Replicating Failures in the Used Assemblies leg

In order to replicate test failures in that leg, there are a few options:

Expand All @@ -210,6 +216,18 @@ When a test failure is isolated, please add a _dedicated_ test for this (ie. fai
Preferrably, don't replicate the entire original test, just enough to hit the bug to ensure that it's protected against regressions.
Before pushing a relevant fix to CI, you can validate locally using the `-testUsedAssemblies` command-line option for `build.cmd`. For example: `build.cmd -testCoreClr -testCompilerOnly -testUsedAssemblies`.

### Running the PublicAPI fixer

1. Install `dotnet-format` as a global tool. It does ship as part of the SDK, but a separate version can be installed as a global tool and invoked with `dotnet-format {options}`.
`C:\Source\roslyn> dotnet tool install -g dotnet-format --version "6.*" --add-source https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet6/nuget/v3/index.json`
2. Restore and build `Compilers.sln`. This is necessary to ensure the source generator project is built and we can load the generator assembly when running `dotnet-format`.
`C:\Source\roslyn> .\restore.cmd`
`C:\Source\roslyn> .\build.cmd`
3. Invoke the `dotnet-format` global tool. Running only the analyzers subcommand and fixing only the "missing Public API signature" diagnostic. We must also pass the `--include-generated` flag to include source generated documents in the analysis.
`C:\Source\roslyn> cd ..`
`C:\Source> dotnet-format analyzers .\roslyn\Compilers.sln --diagnostics=RS0016 --no-restore --include-generated -v diag`


## Contributing

Please see [Contributing Code](https://github.com/dotnet/roslyn/blob/main/CONTRIBUTING.md) for details on contributing changes back to the code.