Skip to main content

Development setup

Prerequisites​

Use .NET SDK 10.0.400, with rollForward: latestFeature as declared by the code repositories' global.json; PowerShell 7.6+; and Git. The test runner is Microsoft.Testing.Platform. The wiki additionally uses Node 24 and pnpm 11.18.0, pinned by .nvmrc and packageManager.

The independent checkouts are PSLoom, Reed and wiki. Run commands from the repository named in each section. Code repositories keep READMEs; long-form documentation belongs here.

Once the repositories are published and you have access, clone the code from develop and the wiki from main:

git clone --branch develop https://github.com/PSLoom/PSLoom.git
git clone --branch develop https://github.com/PSLoom/Reed.git
git clone --branch main https://github.com/PSLoom/wiki.git

The code repositories preserve main at their initial commit during migration; migration changes live only on develop. main remains their eventual default branch. Use the prepared local checkouts before publication.

Kernel​

The kernel's nuget.config contains nuget.org only. It builds PSLoom.Build from source and does not need GitHub Packages credentials for local development.

dotnet build PSLoom.slnx -c Release
dotnet test --solution PSLoom.slnx -c Release --no-build
pwsh -NoProfile -File ./benchmarks/Measure-Startup.ps1
pwsh -NoProfile -File ./benchmarks/Measure-Startup.ps1 -DraftPath ./benchmarks/drafts/typical.ps1 -AllowHarness Fixture
dotnet run -c Release --project benchmarks/PSLoom.Benchmarks -- --filter '*StyleResolve*' '*HookDispatch*' --exporters json --job short
pwsh -NoProfile -File ./benchmarks/Assert-Budgets.ps1

The kernel owns Fixture startup drafts and hook/style benchmarks. Build first so the module layout exists. To import a source-built module in a fresh session:

$moduleRoot = (Resolve-Path ./artifacts/modules).Path
$env:PSModulePath = $moduleRoot + [IO.Path]::PathSeparator + $env:PSModulePath
Import-Module PSLoom

Token-free local SDK loop​

In the kernel checkout:

pwsh -NoProfile -File ./build/Pack-Local.ps1

The script packs and checks PSLoom.Warp, PSLoom.Build, PSLoom.TestKit and PSLoom, with one version 0.0.0-local.<yyyyMMddHHmmss>, into ~/.psloom/packages. It prints the version last. Use a fresh version each time; NuGet caches packages by version.

In Reed, replace the example timestamp with the printed version:

$sdkVersion = '0.0.0-local.20260916120000'
dotnet build PSLoom.Reed.slnx -c Release "-p:PSLoomVersion=$sdkVersion"
dotnet test --solution PSLoom.Reed.slnx -c Release --no-build "-p:PSLoomVersion=$sdkVersion"

For a 0.0.0-local.* command-line version, Reed conditionally selects nuget.local.config through RestoreConfigFile, clears source mappings, and sets RestoreSources to the local package directory plus nuget.org. It does not contact the private feed and needs no token. For a custom package directory, pass -Output to Pack-Local.ps1 and the matching -p:PSLoomLocalPackageSource=<absolute-directory> to Reed's build/test commands.

Integration projects set RequiresKernelModule and restore the kernel's published module layout into Reed's own artifacts/modules. Do not copy Warp next to Reed manually.

Released SDK packages​

Reed defaults to PSLoomVersion = 0.1.0-alpha.1. Released versions come from https://nuget.pkg.github.com/PSLoom/index.json, alongside public dependencies from nuget.org. This path requires a GitHub personal access token (classic) with read:packages and access to the private packages. Follow GitHub's NuGet registry authentication instructions.

Normal nuget.config uses source mapping: PSLoom and PSLoom.* select the private psloom source, while * selects nuget.org for other packages. This keeps central package management unambiguous and avoids NU1507. Local restore uses the separate mapping-free configuration described above.

Set GITHUB_PACKAGES_TOKEN in your environment; nuget.config reads it without embedding a token in the repository. For example, prompt without writing the token into shell history:

$env:GITHUB_PACKAGES_TOKEN = Read-Host 'GitHub Packages token' -MaskInput
dotnet build PSLoom.Reed.slnx -c Release
dotnet test --solution PSLoom.Reed.slnx -c Release --no-build

The initial package release must exist before this default restore can succeed. CI uses secrets.GITHUB_TOKEN with packages: read; the package settings must grant Reed Actions access to all four packages.

Reed budgets​

After building the whole Reed solution:

pwsh -NoProfile -File ./benchmarks/Measure-Startup.ps1 -DraftPath ./benchmarks/drafts/typical.ps1
dotnet run -c Release --project benchmarks/PSLoom.Reed.Benchmarks -- --filter '*CompletionBenchmarks*' --exporters json --job short
pwsh -NoProfile -File ./benchmarks/Assert-Budgets.ps1

When testing a local SDK, set environment variables before dotnet run so BenchmarkDotNet's generated child projects inherit the SDK selection. Those projects do not inherit the parent command's -p:PSLoomVersion argument. Use the $sdkVersion from the local SDK loop:

$env:PSLoomVersion = $sdkVersion
# Only for packages outside ~/.psloom/packages:
# $env:PSLoomLocalPackageSource = 'D:\psloom\repos\PSLoom\artifacts\packages'
try {
    dotnet run -c Release --project benchmarks/PSLoom.Reed.Benchmarks -- --filter '*CompletionBenchmarks*' --exporters json --job short
} finally {
    Remove-Item Env:PSLoomVersion
    Remove-Item Env:PSLoomLocalPackageSource -ErrorAction SilentlyContinue
}
pwsh -NoProfile -File ./benchmarks/Assert-Budgets.ps1

Remove these environment variables when returning to the pinned release SDK; the example cleans them up after the run. --job short is for a quick local budget check; CI runs the prescribed benchmark jobs. Reed owns the typical draft startup budget and three completion budgets. Its process tests enforce that only the kernel's Warp assembly is loaded.

Wiki​

pnpm install --frozen-lockfile
pnpm start
pnpm typecheck
pnpm build

The production build checks relative Markdown links and generated site links and builds the local search index. See repositories and release flow and harness authoring.