Prerequisites
- Flutter 3.50.0. CI pins this version (
FLUTTER_VERSIONinpr-test.ymlandrelease.yml), so use the same one locally. Runflutter doctorand fix what it reports. - A platform toolchain:
- macOS: Xcode.
- Windows: Visual Studio with the Desktop development with C++ workload.
- Linux:
clang,cmake,ninja-build,pkg-configandlibgtk-3-dev. The CI job also installsliblzma-dev,libsecret-1-dev,libjsoncpp-dev,libkeybinder-3.0-devandlibnotify-dev. - Android: JDK 17 and the Android SDK.
- A Rust toolchain, only if you want RDP or VNC (see below).
Run in development
flutter run) uses its own CLI endpoint and run directory, so it never takes over an installed YourSSH. See the CLI notes in CLAUDE.md.
Build a release
Native RDP and VNC libraries
RDP and VNC are Rust crates (packages/yourssh_rdp, packages/yourssh_vnc). The compiled libraries (.dylib, .so, .dll) are not tracked in git. Build them once after cloning, and again after you change the Rust code:
packages/<crate>/assets/native/. In development the app loads it from there; in a release build it is bundled next to the app. Without the library, the app runs normally and only RDP or VNC connections fail.
Run the crate’s own tests without Flutter:
The Android build is SSH only and builds no Rust libraries.
JavaScript plugin runtime
JavaScript plugins run on QuickJS through a small C bridge inpackages/yourssh_script_engine/native/. Only the macOS arm64 libqjsbridge.dylib is prebuilt and committed. After you change the C bridge, rebuild it with:
Analyze, test and lint
flutter test (or dart test for yourssh_cli) inside the package directory.
From the repository root, run the UI lint gate:
--no-fatal-infos is deliberate. On Flutter 3.50, a few hundred infos are deprecations of package:flutter/material.dart that a separate migration will clear. Warnings and errors still fail the build.Android toolchain
Each Flutter release raises the minimum Gradle, Android Gradle Plugin (AGP) and Kotlin versions that its Gradle plugin accepts, and the Android build fails below them. When you bump Flutter, bump the Android toolchain with it. The versions live inapp/android/gradle/wrapper/gradle-wrapper.properties and the plugins {} block of app/android/settings.gradle.kts. The android job in pr-test.yml (a debug APK build) is the check.
Regenerate the docs screenshots
The screenshots in this documentation come from an isolated journey that drives the real app against local demo servers. It needs macOS and Docker.setup generates a throwaway client key (outside the repository), builds a demo SSH image and starts five containers: a demo server, a bastion, an internal database host behind the bastion, an RDP desktop and a VNC desktop. all builds the integration-test app once, then launches it with a temporary HOME, so your real settings, hosts and ~/.yourssh are never touched. It runs a desktop pass and a mobile pass and writes the PNGs and an INDEX.md to screenshots/docs/. Set SECTIONS="01,02" to limit sections or DOCS_OUT to change the output directory.
CI workflows
Both workflows are in.github/workflows/.
pr-test.yml runs on pull requests to develop and master:
release.yml runs when a commit lands on master. It runs analyze and tests first, then builds every platform in parallel:
- macOS: universal build, signed with a Developer ID certificate, notarized and stapled, shipped as a DMG and a ZIP.
- Windows: portable ZIP and an Inno Setup installer, for x64 and ARM64.
- Linux:
.debpackage and portabletar.gz, for x86_64 and arm64. - Android: a release APK.
release job, the only one with a write token, creates the GitHub release and attaches the artifacts.
Next steps
- Architecture to learn the codebase.
- Contributing for the pull request workflow.