Skip to content

Commit 8bef630

Browse files
hoyosjshoyosjs
authored
Merge branch 'main' into darc-main-d8487f7f-1547-40db-b179-d2f9c0db3159
2 parents db8f783 + fcb028b commit 8bef630

40 files changed

+2424
-729
lines changed

‎.github/workflows/copilot-setup-steps.yml‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
name: "Copilot Setup Steps"
2+
3+
# Allow testing of the setup steps from your repository's "Actions" tab.
4+
on: workflow_dispatch
5+
6+
jobs:
7+
# The job MUST be called `copilot-setup-steps` or it will not be picked up by Copilot.
8+
# See https://docs.github.com/en/copilot/customizing-copilot/customizing-the-development-environment-for-copilot-coding-agent
9+
copilot-setup-steps:
10+
runs-on: 8-core-ubuntu-latest
11+
12+
permissions:
13+
contents: read
14+
15+
# You can define any steps you want, and they will run before the agent starts.
16+
# If you do not check out your code, Copilot will do this for you.
17+
steps:
18+
- uses: actions/checkout@v5
19+
20+
- name: Install Dependencies
21+
run: |
22+
sudo ./eng/common/native/install-dependencies.sh && \
23+
sudo apt-get install -qq -y \
24+
curl
25+
26+
- name: Restore solution
27+
run: ./build.sh -restore
28+
29+
- name: Put dotnet on the path
30+
run: echo "PATH=$PWD/.dotnet:$PATH" >> $GITHUB_ENV
31+
32+
- name: Run dotnet info
33+
run: dotnet --info
34+
35+
- name: Build clr+libs
36+
run: ./build.sh

‎AGENTS.md‎

Lines changed: 285 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,285 @@
1+
# Agent Guidelines for .NET Diagnostics Repository
2+
3+
This document provides standard guidance for AI agents and automated tools working on the .NET Diagnostics repository. Following these guidelines will help ensure consistency and quality across contributions.
4+
5+
## Repository Overview
6+
7+
The .NET Diagnostics repository contains diagnostic tools and libraries for .NET Core, including:
8+
9+
- **SOS**: The Son of Strike debugger extension
10+
- **dotnet-dump**: Dump collection and analysis utility
11+
- **dotnet-gcdump**: Heap analysis tool
12+
- **dotnet-trace**: Event collection tool
13+
- **dotnet-counters**: Performance counter monitoring tool
14+
- **Diagnostic libraries**: Client libraries and services for diagnostics
15+
16+
## Build System
17+
18+
### Building the Repository
19+
20+
The repository uses a cross-platform build system:
21+
22+
**Linux/macOS:**
23+
```bash
24+
./build.sh
25+
```
26+
27+
**Windows:**
28+
```cmd
29+
Build.cmd
30+
```
31+
32+
### Build Scripts Location
33+
- Main build scripts: `build.sh` / `Build.cmd` at repository root
34+
- Actual build logic: `eng/build.sh` / `eng/Build.cmd`
35+
- Build configuration: `build.proj`, `Directory.Build.props`, `Directory.Build.targets`
36+
37+
### Common Build Options
38+
- `-configuration <Debug|Release>`: Build configuration (default: Debug)
39+
- `-architecture <x64|x86|arm|arm64>`: Target architecture
40+
- `-restore`: Restore dependencies before building
41+
- `-build`: Build the repository
42+
- `-rebuild`: Clean and rebuild
43+
- `-test`: Run tests after building
44+
45+
## Testing
46+
47+
### Running Tests
48+
49+
**Linux/macOS:**
50+
```bash
51+
./test.sh
52+
```
53+
54+
**Windows:**
55+
```cmd
56+
Test.cmd
57+
```
58+
59+
The test script runs all tests in the repository. Test projects are located in the `src/tests` directory.
60+
61+
### Test Organization
62+
- Unit tests are typically in `*.Tests` projects
63+
- Integration tests may be in separate test projects
64+
- Test helpers are in `Microsoft.Diagnostics.TestHelpers`
65+
66+
## Project Structure
67+
68+
```
69+
/src
70+
├── Microsoft.Diagnostics.DebugServices # Debug service interfaces
71+
├── Microsoft.Diagnostics.DebugServices.Implementation # Debug service implementations
72+
├── Microsoft.Diagnostics.ExtensionCommands # SOS extension commands
73+
├── Microsoft.Diagnostics.Monitoring # Monitoring libraries
74+
├── Microsoft.Diagnostics.NETCore.Client # Diagnostic client library
75+
├── Microsoft.Diagnostics.Repl # REPL infrastructure
76+
├── Microsoft.FileFormats # File format parsers
77+
├── Microsoft.SymbolStore # Symbol store implementation
78+
├── SOS # SOS debugger extension
79+
├── Tools # Command-line tools (dump, trace, counters, gcdump)
80+
├── tests # Test projects
81+
└── shared # Shared native code
82+
83+
/documentation # Documentation files
84+
/eng # Engineering/build infrastructure
85+
```
86+
87+
## Coding Standards
88+
89+
### C# Code Style
90+
91+
The repository follows standard .NET coding conventions defined in the `.editorconfig` file at the root. This is a **must** for C# code. Ensure your changes conform to these settings:
92+
93+
1. **Indentation**: 4 spaces (no tabs)
94+
2. **Line endings**: LF on Linux/macOS, CRLF on Windows
95+
3. **Braces**: Opening braces on new lines for types, methods, properties, control blocks
96+
4. **Naming**:
97+
- PascalCase for types, methods, properties, public fields
98+
- camelCase for local variables, parameters, private fields
99+
- `_camelCase` for private instance fields (with underscore prefix)
100+
5. **File organization**: One type per file, filename matches type name
101+
6. **Additional EditorConfig rules**:
102+
- Trim trailing whitespace
103+
- Insert final newline
104+
- Follow C# new line and indentation preferences
105+
106+
### Native Code (C/C++)
107+
108+
Native code follows similar conventions:
109+
- 4 spaces for indentation
110+
- Braces on same line for control structures in C++
111+
- Use clear, descriptive names
112+
- Follow existing patterns in the codebase
113+
114+
## Making Changes
115+
116+
### General Guidelines
117+
118+
1. **Surgical changes**: Make the smallest possible changes to address the issue. Focus on solving a single problem without addressing unrelated concerns. Balance minimal code changes with preserving overall code clarity and simplicity
119+
2. **Preserve existing behavior**: Don't break working functionality unless explicitly required
120+
3. **Follow existing patterns**: Match the style and structure of surrounding code
121+
4. **Test thoroughly**: Run builds and tests to verify changes
122+
5. **Update documentation**: If making significant changes, update relevant documentation
123+
124+
### Before Making Changes
125+
126+
1. Run a clean build to ensure the current state is valid:
127+
```bash
128+
./build.sh # or Build.cmd on Windows
129+
```
130+
131+
2. Run tests to understand the baseline:
132+
```bash
133+
./test.sh # or Test.cmd on Windows
134+
```
135+
136+
3. Understand the area you're working on:
137+
- Read related source files
138+
- Review existing tests
139+
- Check documentation in `/documentation`
140+
141+
### After Making Changes
142+
143+
1. **Build**: Ensure your changes compile without errors or new warnings
144+
2. **Test**: Run relevant tests to verify functionality
145+
3. **Code style**: Verify changes match the repository's coding standards
146+
4. **Documentation**: Update if your changes affect public APIs or behavior
147+
148+
## Development Workflow
149+
150+
### Typical Workflow
151+
152+
1. **Create a branch**: Create a feature branch from `main` with a descriptive name
153+
2. **Make changes**: Implement your changes following the coding standards
154+
3. **Build locally**: Run `./build.sh` (or `Build.cmd` on Windows) to ensure the code compiles
155+
4. **Run tests**: Execute `./test.sh` (or `Test.cmd` on Windows) to verify functionality
156+
5. **Commit changes**: Make small, logical commits with clear commit messages
157+
6. **Push to remote**: Push your branch to the remote repository
158+
7. **Create pull request**: Open a PR with a clear description of your changes
159+
8. **Address feedback**: Respond to review comments and make necessary updates
160+
9. **Merge**: Once approved, the PR will be merged to `main`
161+
162+
### Iterative Development
163+
164+
- Make small, incremental changes rather than large, sweeping modifications
165+
- Test frequently to catch issues early
166+
- Commit logical units of work separately
167+
- Keep the build and tests passing at each commit when possible
168+
169+
### Pull Request Guidelines
170+
171+
- **Title**: Use a clear, descriptive title that summarizes the change
172+
- **Description**: Explain what changed, why it changed, and how to test it
173+
- **Link issues**: Reference related issues using "Fixes #1234" or "Addresses #1234"
174+
- **Keep focused**: Each PR should address a single concern or feature
175+
- **Respond promptly**: Address review feedback in a timely manner
176+
177+
## Common Patterns
178+
179+
### Solution Files
180+
181+
The main solution file is `build.sln` at the root. This file is generated from `build.proj` and can be regenerated using:
182+
```bash
183+
./eng/generate-sln.sh
184+
```
185+
186+
### Dependency Management
187+
188+
- NuGet packages: `eng/Versions.props` defines package versions
189+
- Project references: Use relative paths in `.csproj` files
190+
- Native dependencies: Handled through CMake
191+
192+
### Platform-Specific Code
193+
194+
The repository supports multiple platforms (Windows, Linux, macOS, FreeBSD, NetBSD):
195+
- Use conditional compilation (`#if`, `#ifdef`) for platform-specific code
196+
- Leverage .NET's platform detection APIs
197+
- Keep platform-specific code minimal and isolated
198+
199+
## Debugging and Diagnostics
200+
201+
### Loading in IDEs
202+
203+
**Visual Studio Code:**
204+
- Open the repository root folder
205+
- Load `build.sln` for better IntelliSense
206+
- Use the provided launch configurations in `.vscode`
207+
208+
**Visual Studio:**
209+
```cmd
210+
start-vs.cmd
211+
```
212+
213+
### Common Issues
214+
215+
1. **Build failures**: Ensure all prerequisites are installed (see documentation/building/)
216+
2. **Test failures**: Some tests may require specific runtime versions or configurations
217+
3. **Native component issues**: Check CMake output for missing dependencies
218+
219+
## Dependencies and Security
220+
221+
### Adding Dependencies
222+
223+
1. **NuGet packages**: Add to `eng/Versions.props` with appropriate version
224+
2. **Security**: Be mindful of security implications when adding dependencies
225+
3. **Licensing**: Ensure new dependencies are compatible with MIT license
226+
4. **Minimize dependencies**: Only add when necessary
227+
228+
### Security Considerations
229+
230+
- Never commit secrets or credentials
231+
- Follow secure coding practices (input validation, proper error handling)
232+
- Be cautious with native interop and memory management
233+
- Review security implications of changes
234+
235+
## Testing Philosophy
236+
237+
1. **Write tests for new functionality**: New features should include tests
238+
2. **Don't remove existing tests**: Tests verify important functionality
239+
3. **Fix test failures related to your changes**: Don't ignore failing tests
240+
4. **Maintain test quality**: Tests should be clear, focused, and maintainable
241+
242+
## Documentation
243+
244+
### When to Update Documentation
245+
246+
- Adding new tools or features
247+
- Changing public APIs
248+
- Modifying build or test procedures
249+
- Adding new dependencies or requirements
250+
251+
### Documentation Locations
252+
253+
- Tool documentation: `/documentation/*-instructions.md`
254+
- Building instructions: `/documentation/building/`
255+
- Design documents: `/documentation/design-docs/`
256+
- README: `/README.md`
257+
258+
## Git and Version Control
259+
260+
### Branch Strategy
261+
262+
- Main development: `main` branch
263+
- Feature branches: Use descriptive names
264+
- Pull requests: Required for all changes
265+
266+
### Commit Messages
267+
268+
- First line: Brief summary (50 characters or less)
269+
- Blank line, then detailed description if needed
270+
- Reference issues: "Fixes #1234" or "Addresses #1234"
271+
272+
## Resources
273+
274+
- [Building on Linux](documentation/building/linux-instructions.md)
275+
- [Building on Windows](documentation/building/windows-instructions.md)
276+
- [Building on macOS](documentation/building/osx-instructions.md)
277+
- [FAQ](documentation/FAQ.md)
278+
279+
## Questions and Support
280+
281+
If you encounter issues or have questions:
282+
1. Check existing documentation in `/documentation`
283+
2. Review closed issues and pull requests for similar problems
284+
3. Consult the [FAQ](documentation/FAQ.md)
285+
4. Ask in the issue or pull request you're working on

‎Directory.Build.props‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,8 +29,13 @@
2929
$(TargetRid) - the runtime identifier (rid) to against (win-x64, linux-arm64, linux-musl-x64, etc).
3030
$(Configuration) - configuration to test (Debug, Release). Defaults to Debug.
3131
$(ArtifactsBinDir) - artifacts\bin directory
32+
$(ArtifactsDotnetTestDir) - artifacts\dotnet-test directory
3233
-->
3334

35+
<PropertyGroup>
36+
<ArtifactsDotnetTestDir>$([MSBuild]::NormalizeDirectory('$(ArtifactsDir)', 'dotnet-test'))</ArtifactsDotnetTestDir>
37+
</PropertyGroup>
38+
3439
<PropertyGroup Condition="'$(TargetOS)' == ''">
3540
<TargetOS>linux</TargetOS>
3641
<TargetOS Condition="'$([System.Runtime.InteropServices.RuntimeInformation]::IsOSPlatform($([System.Runtime.InteropServices.OSPlatform]::Windows)))' == 'true'">Windows_NT</TargetOS>

‎NuGet.config‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -26,9 +26,5 @@
2626
<!-- Standard feeds -->
2727
<add key="dotnet-public" value="https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-public/nuget/v3/index.json" />
2828
</packageSources>
29-
<auditSources>
30-
<clear />
31-
<add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
32-
</auditSources>
3329
<disabledPackageSources />
3430
</configuration>

‎build.proj‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
<Project Sdk="Microsoft.Build.Traversal">
2+
3+
<ItemGroup >
4+
<ProjectReference Include="src/dirs.proj" />
5+
<ProjectReference Include="src/tests/dirs.proj" Condition="'$(SkipTests)' != 'true'" />
6+
</ItemGroup>
7+
8+
</Project>

0 commit comments

Comments
 (0)