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.json pins 11.0.100-rc.1.26425.128 with rollForward: latestPatch and allowPrerelease: true, so you need that SDK band (a prerelease at the time of writing).
  • Git.
  • PowerShell 7 for the helper scripts (tools/bump_version.ps1 requires 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 with DisableParallelization = 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).

See Also