Skip to content

Commit 5a64c5d

Browse files
mamoreau-devolutionsmamoreau-devolutions
authored
Add AGENTS.md for AI agents (#165)
Adds repository-specific guidance for any AI agent (build steps, repo layout, safe-change rules, and packaging notes).
1 parent df015e3 commit 5a64c5d

1 file changed

Lines changed: 146 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
# AGENTS.md
2+
3+
This file contains repo-specific guidance for *any* AI agent (Copilot, Claude, Cursor, etc.) working in this repository.
4+
5+
## What this repo is
6+
7+
**MsRdpEx** (“Microsoft RDP Extensions”) is a Windows-focused project that:
8+
9+
- Builds a native hooking DLL: `MsRdpEx.dll` (Detours-based)
10+
- Builds launcher EXEs: `mstscex.exe`, `msrdcex.exe`, `vmconnectex.exe`
11+
- Includes an optional .NET package: `Devolutions.MsRdpEx` (NuGet)
12+
- Includes an MSI installer built with WiX v4
13+
14+
Key folders:
15+
16+
- `dll/`: native DLL implementation
17+
- `exe/`: native launcher EXEs
18+
- `channels/`: DVC-related code (e.g., `DvcServer`)
19+
- `dotnet/`: C# projects + NuGet packaging
20+
- `installer/`: WiX v4 project + sources
21+
- `dependencies/detours/`: **prebuilt** Detours package used by CMake
22+
- `scripts/`: PowerShell build helpers (notably Detours regeneration)
23+
24+
## Agent operating rules (keep diffs safe)
25+
26+
- Prefer **small, targeted** changes. Avoid mass reformatting or mechanical renames.
27+
- Don’t change packaging/versioning unless the task explicitly asks for it.
28+
- Treat any credential-like strings as secrets:
29+
- Do not add logging that could capture passwords/tokens.
30+
- The `.RDP` options `ClearTextPassword`/`GatewayPassword` are “testing only”; avoid persisting them.
31+
- Avoid editing `.github/workflows/*` unless explicitly requested (they’re owned by DevOps).
32+
- Keep Windows compatibility in mind (this is not a cross-platform repo).
33+
34+
## Build prerequisites (local)
35+
36+
Typical local prerequisites:
37+
38+
- Windows 10/11
39+
- Visual Studio 2022 (MSVC v143) or newer with “Desktop development with C++”
40+
- CMake (Visual Studio generator)
41+
- PowerShell 7 (`pwsh`) for scripts
42+
- For managed builds: .NET SDK 8.x (and .NET Framework targeting packs if building `net48`)
43+
44+
## Build: native (DLL + EXEs)
45+
46+
CMake expects a **prebuilt Detours package** in `dependencies/detours/`.
47+
48+
Example x64 build:
49+
50+
```powershell
51+
cmake -G "Visual Studio 17 2022" -A x64 -DWITH_DOTNET=OFF -B build-x64
52+
cmake --build build-x64 --config Release
53+
```
54+
55+
Outputs are placed under the build directory (e.g. `build-x64/Release/`).
56+
57+
Architectures:
58+
59+
- `-A Win32` (x86)
60+
- `-A x64`
61+
- `-A ARM64`
62+
63+
## Detours dependency (important)
64+
65+
This repo *commits* a prebuilt Detours layout under `dependencies/detours/` and ignores other `dependencies/*` content.
66+
67+
- `dependencies/*` is ignored by `.gitignore`
68+
- `dependencies/detours/` is explicitly **not** ignored (it’s meant to be present)
69+
- `dependencies/sources/` is ignored (Detours source clone lives here)
70+
71+
If Detours is missing or needs updating, regenerate it from the repo root:
72+
73+
```powershell
74+
pwsh -ExecutionPolicy Bypass -File .\scripts\detours-all.ps1
75+
```
76+
77+
Notes:
78+
79+
- `scripts/detours.ps1` expects a Visual Studio developer environment (via `VSCMD_ARG_TGT_ARCH`).
80+
- `scripts/detours-all.ps1` can optionally install `VsDevShell` for the current user (`-InstallVsDevShell`).
81+
82+
## Build: managed (NuGet package)
83+
84+
The .NET build is wired through CMake as *external MSBuild projects*.
85+
86+
Managed-only CMake build (used by CI):
87+
88+
```powershell
89+
cmake -G "Visual Studio 17 2022" -A x64 -DWITH_DOTNET=ON -DWITH_NATIVE=OFF -B build-dotnet
90+
cmake --build build-dotnet --config Release
91+
dotnet pack .\dotnet\Devolutions.MsRdpEx -o package
92+
```
93+
94+
Packaging note:
95+
96+
- The NuGet package includes native `MsRdpEx.dll` for `win-x86`, `win-x64`, `win-arm64` from `dependencies/MsRdpEx/<arch>/MsRdpEx.dll`.
97+
- If you’re producing a NuGet package locally, ensure those native binaries are present (CI populates them by building native per-arch first).
98+
99+
## Build: MSI installer (WiX v4)
100+
101+
The MSI build consumes the native binaries from `dependencies/MsRdpEx/<arch>/` and is driven by `installer/MsRdpEx.sln`.
102+
103+
CI-style build (per arch):
104+
105+
```powershell
106+
# x64 example
107+
$platform = 'x64' # Win32, x64, ARM64
108+
dotnet build /p:Configuration=Release /p:Platform=$platform installer/MsRdpEx.sln
109+
```
110+
111+
The workflow also rewrites `installer/Variables.wxi` to set `ProductVersion` (MSI short version) during packaging. Avoid manual edits unless asked.
112+
113+
## Versioning (very important)
114+
115+
- The canonical version is `dotnet/Devolutions.MsRdpEx/Devolutions.MsRdpEx.csproj` `<Version>`.
116+
- The top-level `CMakeLists.txt` parses that `<Version>` to define `MSRDPEX_VERSION`.
117+
- CI may rewrite `<Version>` during release packaging.
118+
119+
Guideline for agents: **don’t bump `<Version>`** unless the task explicitly requests it.
120+
121+
## COM interop / generated artifacts
122+
123+
The `com/` folder contains generated artifacts related to `mstscax.dll` / `rdclientax.dll` interop.
124+
125+
- Follow `com/README.md` if you need to regenerate `.tlh/.tli`, `mstscax.idl`, or C# interop assemblies.
126+
- Prefer not to hand-edit generated outputs unless regeneration is part of the task.
127+
128+
## Debugging / runtime notes
129+
130+
Extended logging is controlled via environment variables (examples):
131+
132+
```powershell
133+
$Env:MSRDPEX_LOG_ENABLED="1"
134+
$Env:MSRDPEX_LOG_LEVEL="DEBUG" # TRACE is extremely verbose
135+
```
136+
137+
Default log location is under `%LocalAppData%\MsRdpEx\MsRdpEx.log` unless overridden.
138+
139+
## If you change build/packaging behavior
140+
141+
When a task touches build logic, try to validate locally:
142+
143+
- Native: `cmake --build <builddir> --config Release`
144+
- Managed: `dotnet pack .\dotnet\Devolutions.MsRdpEx -o package`
145+
146+
If you can’t run a full build (missing toolchain), keep the changes minimal and explain what should be validated by a human (arch matrix, MSI packaging, etc.).

0 commit comments

Comments
 (0)