Motif

Motif provides a command-line tool and a desktop application for working with FieldWorks language projects. Both front ends use the same typed command handlers, and the current project boundaries are summarized in the architecture overview.

Get started

Install the .NET 10 SDK, then build and check the repository from its root:

./build.ps1
./test.ps1

build.ps1 runs the comment and design-token checks before compiling. test.ps1 runs that build gate before the full suite. All Motif projects target net10.0.

On Ubuntu, local LibLCM builds need SIL's icu-fw package; on macOS they need icu4c with its library directory on DYLD_LIBRARY_PATH. The Linux and macOS workflows show the current setup. Windows development uses the bundled SIL ICU dependencies.

Run from the build

After ./build.ps1, run the CLI and App from bin/<Configuration>:

./bin/Debug/motif.exe help                 # Windows
./bin/Debug/SIL.Motif.App.exe              # Windows
./bin/Debug/motif help                     # Linux or macOS
./bin/Debug/SIL.Motif.App                  # Linux or macOS

Use Release in place of Debug for a release build. Windows apphosts use .exe; Linux and macOS apphosts have no extension. See the build output layout.

PanGloss is optional for opening the App and required for parsing. Motif pins release artifacts by version and SHA-256 in pangloss-release.json (currently v0.5.2) and bundles the matching executable in release packages. For a local parser, set MOTIF_PANGLOSS_EXE to its path; that override is authoritative, and a missing configured file stops discovery. Otherwise a repository build searches the sibling ../PanGloss/dist/*/ and ../PanGloss/rust/target/release/ locations, then the Motif executable directory. The error message gives the local cargo build --release -p pg-cli command when no parser is found.

To stage a self-contained release payload, install the pinned Velopack CLI and run the package script. It verifies the pinned PanGloss file before packaging:

dotnet tool install --global vpk --version 1.2.158
./tools/package-release.ps1 -ProductVersion 0.1.0

The package workflow creates Windows per-user Setup, Linux AppImage, and macOS portable ZIP artifacts. The Install Guide describes the supported Windows setup; Unix packaging and native ICU inputs are documented by the workflow and pinned ICU payload manifest.

For builds against a local LibPalaso checkout, see the opt-in NuGet override instructions. The override is off by default; package-cache settings and the package source remain separate.

Documentation site

The CLI, App and site share authored user Help owned by src/SIL.Motif.Help/Content/. SIL.Motif.Help embeds these files with logical resource names beginning help/, preserving the runtime names help/<locale>/....

Build the CLI first, export the shared Help catalog, then run the site's sync tests and production build with Node 22.12 or later:

./bin/Debug/motif.exe help --all --json > bin/help-export.json # Windows
# On Linux or macOS use: ./bin/Debug/motif help --all --json > bin/help-export.json
Push-Location site
npm ci
$env:MOTIF_HELP_EXPORT = (Resolve-Path ../bin/help-export.json).Path
npm test
npm run build
Pop-Location

The site reads the exported Help rather than maintaining a second authored copy. Refresh the export after Help changes, and provide current Walkthrough media through MOTIF_WALKTHROUGH_OUTPUT; otherwise site sync uses the checked-in fixtures for those inputs. npm test covers the sync script, and npm run build runs the sync before building. This site workflow is separate from ./build.ps1 and ./test.ps1.

To generate the publishable website, manually run the CI workflow with publish_website enabled (or use gh workflow run ci.yml -f publish_website=true). Ordinary pushes, pull requests and manual runs with the flag disabled skip the documentation job. An opted-in run validates the pinned PanGloss release, integration tests, current Help, images and release videos before building and uploading the documentation-site artifact. Any validation, site build or artifact upload failure fails that job. This prepares the website artifact; it does not deploy it to a hosting service.

./tools/Build-Media.ps1 generates media without building the site by default. The site step remains available through an explicit -Only selection for local site development.

Read next

• Current architecture — project references, command sharing, process coordination, cache ownership and Help content location.
• CLI and command API — where current command usage and Guides are maintained.
• Semantic change contract and Proposal lifecycle — normative change and workflow details.
• Shared Help and agent Guides — user-facing Guides owned by SIL.Motif.Help.
• Assessment scope and parser handoff — parser evidence and integration details.
• Repository instructions — build, test, vocabulary and contribution rules.

The former architecture documents remain available as historical plans: Plan A, product architecture plan, and architecture proposal. The current overview is the guide to the implementation that exists now.