Skip to content

Commit e2b497a

Browse files
RaymondHuyRaymondHuy
authored
Merge branch 'main' into issue-81376
2 parents f2e73e2 + 5f3e1ff commit e2b497a

File tree

2,459 files changed

+93741
-129716
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

2,459 files changed

+93741
-129716
lines changed

‎.config/dotnet-tools.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121
]
2222
},
2323
"microsoft.visualstudio.slngen.tool": {
24-
"version": "11.1.0",
24+
"version": "12.0.15",
2525
"commands": [
2626
"slngen"
2727
]

‎.github/copilot-instructions.md

Lines changed: 290 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,290 @@
1+
**Any code you commit SHOULD compile, and new and existing tests related to the change SHOULD pass.**
2+
3+
You MUST make your best effort to ensure your changes satisfy those criteria before committing. If for any reason you were unable to build or test the changes, you MUST report that. You MUST NOT claim success unless all builds and tests pass as described above.
4+
5+
You MUST refer to the [Building & Testing in dotnet/runtime](#building--testing-in-dotnetruntime) instructions and use the commands and approaches specified there before attempting your own suggestions.
6+
7+
You MUST follow all code-formatting and naming conventions defined in [`.editorconfig`](/.editorconfig).
8+
9+
In addition to the rules enforced by `.editorconfig`, you SHOULD:
10+
11+
- Prefer file-scoped namespace declarations and single-line using directives.
12+
- Ensure that the final return statement of a method is on its own line.
13+
- Use pattern matching and switch expressions wherever possible.
14+
- Use `nameof` instead of string literals when referring to member names.
15+
- Always use `is null` or `is not null` instead of `== null` or `!= null`.
16+
- Trust the C# null annotations and don't add null checks when the type system says a value cannot be null.
17+
- Prefer `?.` if applicable (e.g. `scope?.Dispose()`).
18+
- Use `ObjectDisposedException.ThrowIf` where applicable.
19+
- When writing tests, do not emit "Act", "Arrange" or "Assert" comments.
20+
21+
---
22+
23+
# Building & Testing in dotnet/runtime
24+
25+
- [1. Prerequisites](#1-prerequisites)
26+
- [1.1. Determine Affected Components](#11-determine-affected-components)
27+
- [1.2. Baseline Setup](#12-baseline-setup)
28+
- [2. Iterative Build and Test Strategy](#2-iterative-build-and-test-strategy)
29+
- [2.1. Success Criteria](#21-success-criteria)
30+
- [3. CoreCLR (CLR) Workflow](#3-coreclr-clr-workflow)
31+
- [4. Mono Runtime Workflow](#4-mono-runtime-workflow)
32+
- [5. Libraries Workflow](#5-libraries-workflow)
33+
- [5.1. How To: Identify Affected Libraries](#51-how-to-identify-affected-libraries)
34+
- [5.2. How To: Build and Test Specific Library](#52-how-to-build-and-test-specific-library)
35+
- [6. WebAssembly (WASM) Libraries Workflow](#6-webassembly-wasm-libraries-workflow)
36+
- [7. Additional Notes](#7-additional-notes)
37+
- [7.1. Troubleshooting](#71-troubleshooting)
38+
- [7.2. Windows Command Equivalents](#72-windows-command-equivalents)
39+
- [7.3. References](#73-references)
40+
41+
## 1. Prerequisites
42+
43+
These steps need to be done **before** applying any changes.
44+
45+
### 1.1. Determine Affected Components
46+
47+
Identify which components will be impacted by the changes. If in doubt, analyze the paths of the files to be updated:
48+
49+
- **CoreCLR (CLR):** Changes in `src/coreclr/` or `src/tests/`
50+
- **Mono Runtime:** Changes in `src/mono/`
51+
- **Libraries:** Changes in `src/libraries/`
52+
- **WASM/WASI Libraries:** Changes in `src/libraries/` *and* the affected library targets WASM or WASI *and* the changes are included for the target (see below for details).
53+
- If none above apply, it is most possibly an infra-only or a docs-only change. Skip build and test steps.
54+
55+
**WASM/WASI Library Change Detection**
56+
57+
A change is considered WASM/WASI-relevant if:
58+
59+
- The relevant `.csproj` contains explicit Browser/WASM or WASI targets (look for `<TargetFrameworks>`, `$(TargetPlatformIdentifier)`, or `Condition` attributes referencing `browser` or `wasi`, as well as `TARGET_BROWSER` or `TARGET_WASI` constants), **and**
60+
- The changed file is not excluded from the build for that platform in any way with a `Condition` attribute on `<ItemGroup>` or `<Compile>`.
61+
62+
---
63+
64+
### 1.2. Baseline Setup
65+
66+
Before applying any changes, ensure you have a full successful build of the needed runtime+libraries as a baseline.
67+
68+
1. Checkout `main` branch
69+
70+
2. From the repository root, run the build depending on the affected component. If multiple components are affected, subsequently run and verify the builds for all of them.
71+
- **CoreCLR (CLR):** `./build.sh clr+libs+host`
72+
- **Mono Runtime:** `./build.sh mono+libs`
73+
- **Libraries:** `./build.sh clr+libs -rc release`
74+
- **WASM/WASI Libraries:** `./build.sh mono+libs -os browser`
75+
76+
3. Verify the build completed without error.
77+
- _If the baseline build failed, report the failure and don't proceed with the changes._
78+
79+
4. From the repository root:
80+
- Configure PATH: `export PATH="$(pwd)/.dotnet:$PATH"`
81+
- Verify SDK Version: `dotnet --version` should match `sdk.version` in `global.json`.
82+
83+
5. Switch back to the working branch.
84+
85+
---
86+
87+
## 2. Iterative Build and Test Strategy
88+
89+
1. Apply the intended changes
90+
91+
2. **Attempt Build.** If the build fails, attempt to fix and retry the step (up to 5 attempts).
92+
93+
3. **Attempt Test.**
94+
- If a test _build_ fails, attempt to fix and retry the step (up to 5 attempts).
95+
- If a test _run_ fails,
96+
- Determine if the problem is in the test or in the source
97+
- If the problem is in the test, attempt to fix and retry the step (up to 5 attempts).
98+
- If the problem is in the source, reconsider the full changeset, attempt to fix and repeat the workflow.
99+
100+
4. **Workflow Iteration:**
101+
- Repeat build and test up to 5 cycles.
102+
- If issues persist after 5 workflow cycles, report failure.
103+
- If the same error persists after each fix attempt, do not repeat the same fix. Instead, escalate or report with full logs.
104+
105+
When retrying, attempt different fixes and adjust based on the build/test results.
106+
107+
### 2.1. Success Criteria
108+
109+
- **Build:**
110+
- Completes without errors.
111+
- Any non-zero exit code from build commands is considered a failure.
112+
113+
- **Tests:**
114+
- All tests must pass (zero failures).
115+
- Any non-zero exit code from test commands is considered a failure.
116+
117+
- **Workflow:**
118+
- On success: Report completion
119+
- Otherwise: Report error(s) with logs for diagnostics.
120+
- Collect logs from `artifacts/log/` and the console output for both build and test steps.
121+
- Attach relevant log files or error snippets when reporting failures.
122+
123+
---
124+
125+
## 3. CoreCLR (CLR) Workflow
126+
127+
From the repository root:
128+
129+
- Build:
130+
`./build.sh clr`
131+
132+
- Run tests:
133+
`cd src/tests && ./build.sh && ./run.sh`
134+
135+
- More info can be found in the dedicated workflow docs:
136+
- [Building CoreCLR Guide](/docs/workflow/building/coreclr/README.md)
137+
- [Building and Running CoreCLR Tests](/docs/workflow/testing/coreclr/testing.md)
138+
139+
---
140+
141+
## 4. Mono Runtime Workflow
142+
143+
From the repository root:
144+
145+
- Build:
146+
`./build.sh mono+libs`
147+
148+
- Run tests:
149+
150+
```bash
151+
./build.sh clr.host
152+
cd src/tests
153+
./build.sh mono debug /p:LibrariesConfiguration=debug
154+
./run.sh
155+
```
156+
157+
- More info can be found in the dedicated workflow docs:
158+
- [Building Mono](/docs/workflow/building/mono/README.md)
159+
- [Running test suites using Mono](/docs/workflow/testing/mono/testing.md)
160+
161+
---
162+
163+
## 5. Libraries Workflow
164+
165+
From the repository root:
166+
167+
- Build all libraries:
168+
`./build.sh libs -rc release`
169+
170+
- Run all tests for libraries:
171+
`./build.sh libs.tests -test -rc release`
172+
173+
- Build a specific library:
174+
- Refer to the section [5.2. How To: Build and Test Specific Library](#52-how-to-build-and-test-specific-library) below.
175+
176+
- Test a specific library:
177+
- Refer to the sections [5.1. How To: Identify Affected Libraries](#51-how-to-identify-affected-libraries) and [5.2. How To: Build and Test Specific Library](#52-how-to-build-and-test-specific-library) below.
178+
179+
- More info can be found in the dedicated workflow docs:
180+
- [Build Libraries](/docs/workflow/building/libraries/README.md)
181+
- [Testing Libraries](/docs/workflow/testing/libraries/testing.md)
182+
183+
### 5.1. How To: Identify Affected Libraries
184+
185+
For each changed file under `src/libraries/`, find the matching library and its test project(s).
186+
Most libraries use:
187+
188+
- Source: `src/libraries/<LibraryName>/src/<LibraryName>.csproj`
189+
190+
- Tests (single):
191+
- `src/libraries/<LibraryName>/tests/<LibraryName>.Tests.csproj`
192+
- OR `src/libraries/<LibraryName>/tests/<LibraryName>.Tests/<LibraryName>.Tests.csproj`
193+
194+
- Tests (multiple types):
195+
- `src/libraries/<LibraryName>/tests/FunctionalTests/<LibraryName>.Functional.Tests.csproj`
196+
- `src/libraries/<LibraryName>/tests/UnitTests/<LibraryName>.Unit.Tests.csproj`
197+
- Or similar.
198+
199+
---
200+
201+
### 5.2. How To: Build and Test Specific Library
202+
203+
If only one library is affected:
204+
205+
1. **Navigate to the library directory:**
206+
`cd src/libraries/<LibraryName>`
207+
208+
2. **Build the library:**
209+
`dotnet build`
210+
211+
3. **Build and run all test projects:**
212+
213+
- For each discovered `*.Tests.csproj` in the `tests` subdirectory:
214+
`dotnet build /t:test ./tests/<TestProject>.csproj`
215+
216+
- *Adjust path as needed. If in doubt, search with `find tests -name '*.csproj'`.*
217+
218+
- `dotnet build /t:test` is generally preferred over `dotnet test`
219+
220+
---
221+
222+
## 6. WebAssembly (WASM) Libraries Workflow
223+
224+
From the repository root:
225+
226+
- Build:
227+
`./build.sh libs -os browser`
228+
229+
- Run tests:
230+
`./build.sh libs.tests -test -os browser`
231+
232+
- More info can be found in the dedicated workflow docs:
233+
- [Build libraries for WebAssembly](/docs/workflow/building/libraries/webassembly-instructions.md)
234+
- [Testing Libraries on WebAssembly](/docs/workflow/testing/libraries/testing-wasm.md)
235+
236+
---
237+
238+
## 7. Additional Notes
239+
240+
### 7.1. Troubleshooting
241+
242+
- **Shared Framework Missing**
243+
244+
- If the build fails with an error "The shared framework must be built before the local targeting pack can be consumed.", build both the runtime (clr or mono) and the libs.
245+
E.g., from the repo root, run `./build.sh clr+libs -rc release` if working on Libraries on CoreCLR. To find the applicable command, refer to the section [1.2. Baseline Setup](#12-baseline-setup).
246+
247+
- **Testhost Is Missing**
248+
249+
- If a test run fails with errors indicating a missing testhost, such as:
250+
- "Failed to launch testhost with error: System.IO.FileNotFoundException", or
251+
- "artifacts/bin/testhost/... No such file or directory",
252+
that means some of the prerequisites were not built.
253+
254+
- To resolve, build both the appropriate runtime (clr or mono) and the libs as a single command before running tests.
255+
E.g., from the repo root, run `./build.sh clr+libs -rc release` before testing Libraries on CoreCLR. To find the applicable command, refer to the section [1.2. Baseline Setup](#12-baseline-setup).
256+
257+
- **Build Timeout**
258+
259+
- Do not fail or cancel initial `./build.sh` builds due to timeout unless at least 40 minutes have elapsed.
260+
A full `clr+libs` build from scratch can take up to 32 minutes or more on some systems.
261+
262+
- Only wait for long-running `./build.sh` commands if they continue to produce output.
263+
If there is no output for 5 minutes, assume the build is stuck and fail early.
264+
265+
- **Target Does Not Exist**
266+
267+
- Avoid specifying a target framework when building unless explicitly asked.
268+
Build should identify and select the appropriate `$(NetCoreAppCurrent)` automatically.
269+
270+
---
271+
272+
### 7.2. Windows Command Equivalents
273+
274+
- Use `build.cmd` instead of `build.sh` on Windows.
275+
- Set PATH: `set PATH=%CD%\.dotnet;%PATH%`
276+
- All other commands are similar unless otherwise noted.
277+
278+
---
279+
280+
### 7.3. References
281+
282+
- [`.editorconfig`](/.editorconfig)
283+
- [Building CoreCLR Guide](/docs/workflow/building/coreclr/README.md)
284+
- [Building and Running CoreCLR Tests](/docs/workflow/testing/coreclr/testing.md)
285+
- [Building Mono](/docs/workflow/building/mono/README.md)
286+
- [Running test suites using Mono](/docs/workflow/testing/mono/testing.md)
287+
- [Build Libraries](/docs/workflow/building/libraries/README.md)
288+
- [Testing Libraries](/docs/workflow/testing/libraries/testing.md)
289+
- [Build libraries for WebAssembly](/docs/workflow/building/libraries/webassembly-instructions.md)
290+
- [Testing Libraries on WebAssembly](/docs/workflow/testing/libraries/testing-wasm.md)

0 commit comments

Comments
 (0)