Building

Prerequisites

  • Flutter on PATH (currently 3.47.2 stable).
    • Linux fallback: export PATH="$PATH:~/develop/flutter/bin" (scripts/niman.sh does this itself).
  • Android SDK (Linux): ~/Android/Sdk via gitignored android/local.properties (never commit).
  • First build needs network (the sqlite3 package fetches a prebuilt native binary via Dart build hooks — required on Windows, which ships no sqlite3.dll).

  • Android NDK 29.0.13113456 (required by whisper_ggml).
  • A release APK is arm64-v8a only. armeabi-v7a is excluded at packaging for every build in android/app/build.gradle.kts, and x86_64 for release builds (#1146): the plugins with prebuilt native libraries package every ABI they have, whatever --target-platform asks. A debug build keeps x86_64, so flutter run still installs on an emulator. The scripts and the release workflow pass --target-platform android-arm64, so no x86_64 Dart snapshot is compiled only to be dropped.
  • Linux desktop build: GTK 3 and the plugins’ system libraries — the list CI installs, in check.yml and release.yml alike:

    sudo apt-get install -y clang cmake git ninja-build pkg-config \
      libgtk-3-dev liblzma-dev libstdc++-13-dev \
      libayatana-appindicator3-dev libsecret-1-dev libjsoncpp-dev \
      libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev
    

    Two more are for the checks rather than the build: xvfb, which gives the integration suite the display the GTK bundle needs on a headless host, and hunspell with hunspell-en-us and hunspell-it, without which the live cases of test/unit/spell_check_test.dart skip.

  • Windows desktop build: Visual Studio with the Desktop development with C++ workload. The installer additionally needs Inno Setup 6 — choco install innosetup, as release.yml does.

Helper scripts

Terse output; full logs in /tmp/niman/niman-<cmd>.log (%TEMP%\niman\ on Windows):

./scripts/niman.sh analyze   # flutter analyze --fatal-infos
./scripts/niman.sh test      # flutter test (unit + widget)
./scripts/niman.sh check     # analyze + test; run before every commit
./scripts/niman.sh integration  # integration_test/; run before every commit (issue #241)
./scripts/niman.sh apk       # Android release APK
./scripts/niman.sh apk beta  # Android testing build (issue #106)
./scripts/niman.sh apk frames  # that build in profile mode, with the frame log (#1145)
./scripts/niman.sh linux     # Linux release bundle
./scripts/niman.sh linux beta  # Linux testing build (its own data folder)
scripts\niman.bat check      # Windows equivalent
scripts\niman.bat integration  # the headless integration_test/ files (sync_e2e needs Linux)
scripts\niman.bat apk beta   # Android testing build, from Windows
scripts\niman.bat windows    # Windows build (on a Windows host)
scripts\niman.bat windows beta  # Windows testing build (its own data folder)

Every build the scripts make carries the commit it was cut from (--dart-define=APP_COMMIT=<short hash>, read by lib/src/core/build_identity.dart into the header of an exported debug log, #1135). A tree with uncommitted changes is not that commit, so the hash gets a -dirty suffix (6dad6c8d-dirty) when git status reports anything, untracked files included but for the agents’ own .claude/ folder: a beta built from a worktree in the middle of an edit says so, and a log that names a bare hash can be trusted to be that commit. Both scripts do it the same way; the release workflow builds from a tag and passes the bare hash.

check (.github/workflows/check.yml) runs the formatting gate, analyze, flutter test and the integration files on every pull request, so the suite cannot rot unnoticed again (issue #241). The WebDAV sync flow needs a device (flutter test -d linux), which CI provides on a virtual display, and CI installs hunspell so the live spell-check cases run there instead of skipping (issue #363).

A second job in the same workflow runs the JVM unit tests of the Android app module (android/app/src/test, e.g. LaunchIntentTest, ShareCopyTest) in parallel with the first: flutter build apk --config-only writes the Gradle project (android/gradlew and android/local.properties are not in the repository), then ./gradlew :app:testBetaDebugUnitTest compiles the Kotlin and runs JUnit — no APK, no device (issue #813). Locally: the same two commands, with gradlew.bat on Windows and JAVA_HOME set (Android Studio’s jbr will do).

site (.github/workflows/site.yml) builds the documentation site on every pull request with the deploy’s own steps — the Jekyll build from pages.yml, the step that wraps Niman’s {{…}} template syntax in / included. Publishing runs on main alone (issue #441), so without it a layout, a Liquid tag or a _config.yml key Jekyll refuses would surface when the site deploys, after the merge (issue #470). It deploys nothing: contents: read, no artifact.

The two Android builds (issue #106)

The app ships in two flavors of the channel dimension, so the official app and the testing build install side by side on the same device. Once a flavor dimension has a flavor, AGP drops the no-flavor variant, so the official app is the explicit official flavor — no application ID suffix, no per-flavor manifest, the ID stays dev.niman.niman:

  • ./scripts/niman.sh apk (or scripts\niman.bat apk on a Windows host) builds the official APK: flutter build apk --release --flavor official, artifact build/app/outputs/flutter-apk/app-official-release.apk.
  • flutter run on an Android device needs the flavor too: flutter run --flavor official.

./scripts/niman.sh apk beta (or scripts\niman.bat apk beta on a Windows host) builds the testing build: the release pipeline plus the beta product flavor.

  • Application ID dev.niman.niman.beta (the flavor’s applicationIdSuffix in android/app/build.gradle.kts), launcher label “Niman (Testing)” (per-flavor manifest android/app/src/beta/AndroidManifest.xml).
  • Release-equivalent: same build type, signing, SDK, R8 and desugaring — only the ID and the label differ.
  • The flavor passes --dart-define=APP_CHANNEL=testing; the Dart side (lib/src/core/app_channel.dart) hides the Updates settings section and never starts the update scheduler, whatever the stored auto-update toggle says. A build that forgets the define reads as release and keeps full update behavior.
  • The two installs are fully independent by design: separate storage, separate SQLite indexes, separate MANAGE_EXTERNAL_STORAGE grant (the permission is per application ID, so grant it to the testing install too).
  • AGP forbids flavor names starting with test (reserved for test variants), hence beta.

A local rebuild after a commit uses beta by default; the official artifacts are built only when asked (see AGENTS.md).

./scripts/niman.sh apk frames (scripts iman.bat apk frames) builds the testing app for measuring frames on a device (#1145): the beta flavor in profile mode, with --dart-define=NIMAN_FRAMES=true. That define turns the frame instrumentation on, so an exported debug log splits each action’s frames into build and raster time and carries the app’s memory (#1144); the desktop numbers were taken the same way. It installs beside the release, being the beta flavor, and its artifact is build/app/outputs/flutter-apk/app-beta-profile.apk. Both scripts refuse any other flavor word before the build starts, rather than building the official APK for a typo.

The desktop testing build

On Windows and Linux both builds are one niman executable under one product name, so without help they share one support folder — one settings database, one set of indexes, one single-instance claim. A testing build that migrated the database to a newer schema broke the installed release, which took the version back down and left the next migration to redo what was done (2026-09-22). So the testing build keeps its own folder:

  • scripts\niman.bat windows beta (./scripts/niman.sh linux beta) passes --dart-define=APP_CHANNEL=testing.
  • appSupportDirectory() (lib/src/core/app_channel.dart) answers a sibling of the platform folder, …\dev.niman\niman-testing on Windows, for everything the app keeps: niman.db, indexes/, the log, the single-instance claim. Libraries have to be opened once again in the testing build; the notes themselves are the same files.
  • The window and the tray say “Niman (testing)”, and the two can run at the same time.
  • The settings database refuses to be opened by a build older than the one that last migrated it, rather than let drift stamp it back down.

CI (.github/workflows/release.yml) builds the official APK from every release tag and never the testing flavor: a release page holding both APKs handed the in-app update the testing one (0.0.10; see releasing). Build it where it is wanted, with ./scripts/niman.sh apk beta.

Checks before every commit

  1. dart fix --apply, then dart format lib test tool (both idempotent); CI fails the job on drift (dart format --output=none --set-exit-if-changed lib test tool).
  2. ./scripts/niman.sh check (infos are fatal: flutter analyze --fatal-infos).
  3. flutter test runs test/unit/ + test/widget/; single test: flutter test test/unit/<f>.dart --plain-name "<name>". integration_test/ is E2E, not part of the default run: app_boot and sync_e2e run in CI too (sync_e2e on -d linux, under xvfb); template_backlink is a repro harness and skips unless a library is seeded at /tmp/niman/repro_lib. ./scripts/niman.sh integration runs all three (issue #241).
  4. Windows note: ~20 tests fail on path separators and temp-dir cleanup (pre-existing, green on Linux). Use pwsh scripts/newfail.ps1 — it prints only failures not in scripts/known-failures.txt (exit 1 = something new broke; -Update rewrites the baseline).

Codegen

Two drift databases in lib/src/db/, .g.dart committed:

  • AppDatabase (app_database.dart): settings, long migration chain.
  • IndexDatabase (index_database.dart): one per library, schema 1, no migrations — delete the file to rebuild.

After schema/DAO changes: dart run build_runner build.

Edit this page on GitHub