Getting Started
New to FieldWorks development? Start here:
Note: We are migrating documentation from the FwDocumentation wiki into this repository. Some wiki content may be more recent until migration is complete.
Linux and macOS
This repository can be opened on Linux or macOS for editing, code search, documentation, specs, and agent-assisted review.
Builds, tests, installer work, and developer-environment setup are Windows-only and are intentionally disabled on non-Windows hosts.
If you need runnable output, use a Windows machine and run ./build.ps1 or ./test.ps1 there.
Developer Machine Setup
See Contributing.
Building FieldWorks
FieldWorks uses the MSBuild Traversal SDK for declarative, dependency-ordered builds:
Windows (PowerShell):
.\build.ps1 # Debug build
.\build.ps1 -Configuration Release
For detailed build instructions, see .github/instructions/build.instructions.md.
Concurrent worktree builds/tests
build.ps1 and test.ps1 use worktree-aware process cleanup, so running scripted builds/tests in different git worktrees does not kill each other.
Within a single worktree, builds and tests run one at a time: scripts acquire a worktree lock and fail fast if another scripted workflow is active.
You can tag lock ownership for diagnostics with FW_BUILD_STARTED_BY=user|agent (or -StartedBy user|agent).
Building Installers (WiX 3 default, WiX 6 opt-in)
Installer builds default to WiX 3 (legacy batch pipeline) using inputs in FLExInstaller/ and PatchableInstaller/. Use -InstallerToolset Wix6 to opt into the WiX 6 SDK-style path (restored via NuGet; no setup required).
WiX 3.11 setup (required for WiX 3 installer builds)
WiX 3.11 can be installed with Chocolatey:
choco install wixtoolset --version 3.11.2
- Ensure tools (
heat.exe etc.) are available in %WIX%\bin or on the PATH.
- Install the Visual Studio WiX Toolset v3 extension so
Wix.CA.targets is available to MSBuild.
Running installer builds
Installer builds include the additional utilities (UnicodeCharEditor, LCMBrowser, MigrateSqlDbs, etc.).
To skip them, pass -BuildAdditionalApps:$false.
# Build the installer (WiX 3 default)
.\build.ps1 -BuildInstaller
# Build the installer (WiX 6)
.\build.ps1 -BuildInstaller -InstallerToolset Wix6
WiX 3 artifacts are produced under FLExInstaller/bin/x64/<Config>/ (MSI under en-US/).
WiX 6 artifacts are produced under FLExInstaller/wix6/bin/x64/<Config>/ (MSI under en-US/).
For more details, see specs/001-wix-v6-migration/quickstart.md.
Code signing for local installer builds
Signing is optional for local builds. By default, local installer builds do not sign and instead record files to sign later.
To enable signing for a local installer build, pass -SignInstaller to build.ps1.
Required for signing:
- Either
sign (SIL signing tool) or signtool.exe on PATH.
- If using
signtool.exe, set CERTPATH (PFX path) and CERTPASS (password) in the environment.
If you want to control the capture file, set FILESTOSIGNLATER to a file path before building. The build will append files needing signatures to that file.
Model Context Protocol helpers
This repo ships an mcp.json workspace configuration so MCP-aware editors can spin up
the GitHub and Serena servers automatically. See Docs/mcp.md for
requirements and troubleshooting tips.
Agent instruction files
We maintain a shared AGENTS model (AGENTS.md, CLAUDE.md,
.github/AGENTS.md, Src/AGENTS.md, FLExInstaller/AGENTS.md,
openspec/AGENTS.md) and a minimal, requirement-focused guidance model.
GitHub Copilot custom instructions remain under
.github/instructions/*.instructions.md because GitHub requires those paths.
Claude Code workflows live under .claude/skills/.
See .github/AI_GOVERNANCE.md for the documentation taxonomy and “source of truth” rules.
