Skip to content

AGENTS.md

Latest commit

 

History

History
105 lines (86 loc) · 5.87 KB

AGENTS.md

File metadata and controls

105 lines (86 loc) · 5.87 KB
Raw

AGENTS: liblcm (LCM)

Summary

liblcm (LCM) is the core FieldWorks Language & Culture Model library for linguistic analyses. It provides the data model, serialization, utilities, and tooling for linguistic, anthropological, and text corpus data. It is a multi-project .NET solution with code generation steps and multi-targeting for legacy .NET Framework and modern .NET.

High-level repo facts

  • Type: .NET solution (multi-project class libraries + build tasks + tools + tests).
  • Languages: C# (.cs), MSBuild (.proj/.csproj/.props/.targets), XML, shell/batch scripts.
  • Target frameworks: net462, netstandard2.0, net8.0 (see .csproj files in src/ and tests/).
  • Build tools: MSBuild, dotnet SDK, GitVersion.MsBuild, NUnit.
  • Output: artifacts/ (NuGet packages and binaries by configuration/TFM).

Build and validation (validated commands and observations)

What CI runs (GitHub Actions)

CI runs on Windows and Ubuntu. See .github/workflows/ci-cd.yml:

  1. Install .NET SDK 8.x.
  2. Ubuntu: install mono-devel and icu-fw packages.
  3. Windows: remove c:\tools\php\icuuc*.dll; install .NET Framework 4.6.1 targeting pack.
  4. Build: dotnet build --configuration Release
  5. Test:
    • Linux: . environ && dotnet test --no-restore --no-build -p:ParallelizeAssembly=false --configuration Release
    • Windows: dotnet test --no-restore --no-build -p:ParallelizeAssembly=false --configuration Release
  6. Pack: dotnet pack --include-symbols --no-restore --no-build -p:SymbolPackageFormat=snupkg --configuration Release

Always mirror this sequence when validating a change locally.

Use dotnet build -m:1 for a cold-start build (a tree with no generated sources yet). Parallel builds race on the generated sources and fail with IdlImp errors. Plain dotnet build is fine once those sources exist.

Tests per README (not validated here)

  • Windows, ReSharper: open LCM.sln and “Run Unit Tests”.
  • Windows, no ReSharper: use MSBuild, then run nunit3-console.exe from artifacts/Debug/net462.
  • Linux terminal: source environ, then run mono with nunit3-console.exe on *Tests.dll in artifacts/Debug/net462.

Commands actually run during onboarding

  • dotnet test .\LCM.sln → FAILED
  • dotnet build --configuration Release → FAILED Failure signature (both commands): GitVersion.MsBuild (netcoreapp3.1 gitversion.dll) exited with code 1. This blocks build/test in this environment. CI uses fetch-depth 0, so ensure a full git history is available. If GitVersion still fails, check GitVersion prerequisites and local .NET runtime compatibility.

Known prerequisites and gotchas

  • GitVersion.MsBuild is used across projects; it requires git metadata. CI checks out with fetch-depth 0.
  • net462 builds on Windows require the .NET Framework 4.6.1 targeting pack (CI installs it).
  • ICU data generation requires ICU binaries (CI installs icu-fw on Ubuntu).
  • Some projects warn on NU1701; treat as warnings unless build breaks.
  • The build prohibits references to System.Windows.Forms (CheckWinForms target).

Project layout and architecture

Key solution and build files

  • LCM.sln: solution entry point.
  • Directory.Build.props / Directory.Build.targets: repo-wide build settings and packaging.
  • Directory.Solution.props / Directory.Solution.targets: solution-level defaults.
  • GitVersion.yml: GitVersion configuration.
  • global.json: SDK roll-forward config.
  • .editorconfig: formatting rules.

Major source projects (src/)

  • src/SIL.LCModel: main LCM library (net462; netstandard2.0).
  • src/SIL.LCModel.Core: core utilities and ICU data generation (netstandard2.0; net462; net8.0).
  • src/SIL.LCModel.Utils: shared utilities (net462; netstandard2.0).
  • src/SIL.LCModel.Build.Tasks: the IdlImp (kernel-interface codegen) and LcmGenerate (single-template rendering, e.g. FieldWorks C++ headers) MSBuild tasks.
  • src/SIL.LCModel.ModelGeneration: the shared NVelocity engine (LcmGenerateImpl + model wrappers) that renders LCM model templates; referenced by both SourceGenerators and Build.Tasks. NVelocity-only dependency.
  • src/SIL.LCModel.SourceGenerators: Roslyn source generator for the LCM domain model (MasterLCModel.xml → Generated*.cs), with the NVelocity templates embedded from its Templates/vm folder.
  • src/SIL.LCModel.FixData: data-fix utilities.
  • src/CSTools: auxiliary tools (pg/lg/Tools).

Code generation to know about:

  • SIL.LCModel: the LcmModelGenerator source generator turns MasterLCModel.xml (with HandGenerated.xml and IntPropTypeOverrides.xml, wired in as AdditionalFiles) into the domain-model Generated*.cs sources at compile time.
  • SIL.LCModel.Core: GenerateKernelCs (IdlImp task), GenerateIcuData.

Tests (tests/)

  • SIL.LCModel.Tests
  • SIL.LCModel.Core.Tests
  • SIL.LCModel.Utils.Tests
  • SIL.LCModel.FixData.Tests
  • TestHelper (support project)

CI/validation checks

  • GitHub Actions: .github/workflows/ci-cd.yml (build, test, pack, publish).
  • Tests run with dotnet test and ParallelizeAssembly=false.
  • Packaging uses dotnet pack with symbol packages.

Dependencies not obvious from layout

  • ICU data and binaries (icu-fw) for Core ICU generation.
  • Mono on Linux for some runtime/test workflows.
  • GitVersion.MsBuild for versioning (requires git metadata).

Repo top-level directories

  • .github/ (GitHub Actions workflow)
  • .vscode/ (VS settings)
  • artifacts/ (build outputs)
  • src/ (production code)
  • tests/ (unit tests)

README highlights (summary)

  • Describes liblcm as FieldWorks model library for linguistic analyses.
  • Build: use dotnet build. Default Debug, optional Release.
  • Debugging: use LOCAL_NUGET_REPO to publish local packages; see NuGet local feeds.
  • Tests: Windows via ReSharper or NUnit console; Linux via mono + NUnit console (requires environ).

Trust these instructions

Follow this file first. Only search the repo if these instructions are incomplete or prove incorrect for your task. If these instructions fail notify the author of the task that they should verify and update the instructions if necessary.