Contributing
This page explains how to build MonoMod from source, run its tests the way CI does, and find your way around the repository. MonoMod is MIT-licensed (LICENSE).
Prerequisites
- .NET SDK 11.
global.jsonpins11.0.100-rc.1.26425.128withrollForward: latestPatchandallowPrerelease: true, so you need that SDK band (a prerelease at the time of writing). - Git.
- PowerShell 7 for the helper scripts (
tools/bump_version.ps1requires it). - For running tests on older targets: the matching .NET runtimes (the test project targets .NET Core 2.1 through .NET 11) and, on Windows, .NET Framework 4.7.2.
Getting the Source
git clone https://github.com/MonoMod/MonoMod.git
cd MonoMod
The solution file is MonoMod.slnx. The main development branch is reorganize.
Building
The commands CI runs (build.yml):
dotnet restore -bl:restore.binlog -noAutoRsp
dotnet build --no-restore -c Release -p:ContinuousIntegrationBuild=true -bl:build.binlog -clp:NoSummary -noAutoRsp
dotnet pack --no-restore -c Release -p:ContinuousIntegrationBuild=true -bl:pack.binlog -clp:NoSummary -noAutoRsp
For everyday work, dotnet build -c Release is enough. Packages are written under artifacts/package/release/. nuget.config registers that folder as the mm-local package source for MonoMod.* packages, so projects in the repository can consume freshly packed MonoMod packages.
Running Tests
The tests live in src/MonoMod.UnitTest and use xUnit. The project targets net6.0, net5.0, net7.0 through net11.0, net472, netcoreapp2.1, netcoreapp3.0 and netcoreapp3.1. Run one framework and architecture at a time, as CI does:
dotnet test src/MonoMod.UnitTest/MonoMod.UnitTest.csproj -c Release -f net8.0 -a x64
CI (test.yml) runs the built MonoMod.UnitTest.dll for each framework and architecture in a matrix, with crash and hang dumps enabled (--blame-crash-dump-type full --blame-hang-timeout 20m). Mono runs use separate scripts in .github/workflows/ (run-mono-tests.ps1, run-with-dumps.ps1) that collect dumps into DUMPS_PATH.
Note: Tests that apply detours change global process state, which is why most detour tests are in the
[Collection("RuntimeDetour")]xUnit collection, so they do not run in parallel with each other. Some regression tests use their own collection withDisableParallelization = true. Put new detour tests in one of these.
Repository Layout
| Path | Contents |
|---|---|
src/MonoMod.Core |
Low-level detouring (see Architecture). |
src/MonoMod.Utils |
DynamicMethodDefinition, ILCursor, DynamicData, platform detection, switches, logging. |
src/MonoMod.RuntimeDetour |
Hook, ILHook, NativeHook, detour chains. |
src/MonoMod.RuntimeDetour.HookGen |
The HookGen tool. |
src/MonoMod.Patcher |
The Patcher. |
src/MonoMod.DebugIL |
The DebugIL tool. |
src/MonoMod.SourceGen.Internal |
Source generators used to build MonoMod itself. |
src/MonoMod.UnitTest, src/MonoMod.FrameworkTests |
Tests. |
docs/ |
Design notes and articles (for example docs/Core/Architecture.md). |
docfx/ |
The docfx site configuration, built by docs.yml. |
tools/ |
Shared MSBuild props and targets, BannedSymbols.txt, bump_version.ps1. |
build/ |
Build helpers used by CI. |
Versions and Releases
Each packable project has a Version.props with its VersionPrefix (for example src/MonoMod.Core/Version.props). tools/bump_version.ps1 bumps the Major, Minor or Patch component (default Patch) of MonoMod.Core, MonoMod.Utils and MonoMod.RuntimeDetour unless you pass other project names:
./tools/bump_version.ps1 -BumpVersion Minor
Releases are produced by the make_release.yml and upload-packages.yml workflows.
Code Style
.editorconfig sets LF line endings and spaces everywhere, 4-space indentation for C#, and 2 spaces for YAML and MSBuild files. Analyzers run during the build, and tools/BannedSymbols.txt lists APIs that must not be used.
Reporting Issues
Use the issue templates: Bug report / general issue or Feature request. For bugs, include the MonoMod package versions, the runtime and its version, OS and architecture, a minimal reproduction, and the debug log (see Logging).