voice-cat/docs/building.md

# Building and testing

## Prerequisites

- .NET SDK selected by `dotnet/global.json`
- CMake and a C compiler for the Opus/RNNoise shim
- PowerShell for the cross-platform build scripts
- Xcode plus the pinned .NET macOS/iOS workloads for Apple clients

Dependencies and NuGet lock files are committed. GPL/LGPL dependencies are forbidden.

## Managed core, server, CLI, and tests

From the repository root:

```bash
./dotnet/build-native.ps1
dotnet restore dotnet/VoiceCat.slnx --locked-mode
dotnet build dotnet/VoiceCat.slnx -c Release --no-restore
dotnet test dotnet/VoiceCat.slnx -c Release --no-build
./dotnet/check-licenses.ps1
```

The native script builds `native/media`, fetches checksum-pinned Opus 1.5.2, compiles vendored
RNNoise, and stages the resulting library and notices in `dotnet/artifacts/native`.

Equivalent direct native build:

```bash
cmake -S native/media -B dotnet/artifacts/native-build -DCMAKE_BUILD_TYPE=Release
cmake --build dotnet/artifacts/native-build --target voicecat_media --parallel 2
cmake --install dotnet/artifacts/native-build --component DotnetMedia \
  --prefix dotnet/artifacts/native
```

## Run locally

```bash
dotnet run --project dotnet/src/VoiceCat.Server -- --data-dir ./voicecat-data
dotnet run --project dotnet/src/VoiceCat.Cli -- \
  --host 127.0.0.1 --port 8384 --nickname Alice --trust-first
```

Both commands support `--help`. The CLI also supports deterministic two-process text and tone
checks used by the managed test suite.

## Windows client

```powershell
./dotnet/build-native.ps1
dotnet restore clients/windows/VoiceCat.slnx --locked-mode
dotnet build clients/windows/VoiceCat.slnx -c Release --no-restore
./clients/windows/publish-client.ps1
```

The supported app references `VoiceCat.Managed` and the managed core. Published output must
contain `voicecat_media.dll` and must not contain the retired `voicecat.dll`.

## Apple clients

On Apple Silicon with the SDK/workload versions documented in
`clients/apple/dotnet/README.md`:

```bash
./dotnet/build-native.ps1
./dotnet/build-native-ios.sh
dotnet restore clients/apple/dotnet/VoiceCat.Apple.slnx
dotnet build clients/apple/dotnet/VoiceCat.Apple.slnx -c Debug --no-restore
```

The iOS build invokes the standalone project in `native/apple/broadcast` and embeds its appex.
Use `clients/apple/dotnet/build-ios-device.sh` and `deploy-ios-device.sh` for signed device
builds. Use `clients/apple/dotnet/publish-macos.sh --dry-run` for an ad-hoc validated macOS
bundle; its environment variables enable Developer ID signing and notarization.

## Server publishing

`dotnet/publish-server.ps1` produces locked self-contained Windows and Linux artifacts in one
command. Pass `-Runtime win-x64` or `-Runtime linux-x64` to publish only one target.
`Dockerfile`, Compose configuration, and systemd packaging use the managed server. Validate a
published binary with its TLS `--health-check`, preferably including `--expect-fingerprint`.

## CI and release expectations

CI builds the native shim, managed solution, tests, licenses, and managed Apple clients. The
old C++ implementation is not a conformance target. Release validation additionally includes
real devices, screen readers, sustained calls, signing/notarization, container execution, and
a server soak; see `roadmap.md`.