diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 05c82de6..d6e92382 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -46,14 +46,41 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 + - name: Read Linux SDK pin + id: linux-sdk + run: echo "version=$(jq -r '.flutter.version' scripts/appimage-tools.json)" >> "$GITHUB_OUTPUT" - uses: subosito/flutter-action@v2 with: - channel: "stable" + flutter-version: ${{ steps.linux-sdk.outputs.version }} cache: true - name: Install Linux build deps - run: sudo apt-get update && sudo apt-get install -y clang cmake ninja-build pkg-config libgtk-3-dev + run: | + sudo apt-get update + sudo apt-get install -y clang cmake ninja-build pkg-config libgtk-3-dev librsvg2-dev libgirepository1.0-dev libgtk-3-bin libgdk-pixbuf2.0-bin libgdk-pixbuf2.0-dev patchelf file desktop-file-utils xdg-user-dirs shellcheck libssl-dev libunwind-dev libvulkan-dev libgl1-mesa-dev libasound2-dev libsecret-1-dev + - uses: actions/cache@v4 + with: + path: ~/.cache/meshcore-open/appimage + key: linux-appimage-x86_64-${{ hashFiles('scripts/appimage-tools.json') }} + - name: Test packaging contracts + run: | + shellcheck scripts/build_appimage.sh scripts/appimage/*.sh scripts/appimage/AppRun + bash scripts/appimage/test_packaging.sh - run: flutter pub get - run: flutter build linux --release --no-pub + - name: Test AppImage in clean Ubuntu + run: | + docker build --target runtime-test --build-arg "BASE_IMAGE=$(jq -r '.ubuntu' scripts/appimage-tools.json)" -f scripts/appimage/Dockerfile -t meshcore-appimage-runtime scripts + mkdir -p build/appimage-runtime + docker run --rm --user "$(id -u):$(id -g)" --mount "type=bind,source=$PWD/build/linux/x64/release/meshcore-open-x86_64.AppImage,target=/artifact.AppImage,readonly" --mount "type=bind,source=$PWD/scripts/appimage/test_runtime.sh,target=/test_runtime.sh,readonly" --mount "type=bind,source=$PWD/build/appimage-runtime,target=/results" meshcore-appimage-runtime xvfb-run -a bash /test_runtime.sh /artifact.AppImage /results + - uses: actions/upload-artifact@v4 + with: + name: linux-x86_64-appimage + path: | + build/linux/x64/release/meshcore-open-x86_64.AppImage + build/linux/x64/release/appimage-audit.txt + build/linux/x64/release/appimage-tools.json + build/appimage-runtime/ + if-no-files-found: error macos: runs-on: macos-latest diff --git a/CLAUDE.md b/CLAUDE.md index fc69bf60..87d9ceab 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -17,9 +17,14 @@ flutter test flutter build apk --release flutter build ios --release flutter build web --release +flutter build linux --release +MESHCORE_BUILD_APPIMAGE=0 flutter build linux --release +bash scripts/appimage/test_packaging.sh ``` -The versioned web build uses `dart run build_pipe:build` (also `bun run build`). Web deployment pins Flutter 3.41.2; other CI jobs track stable. Read `pubspec.yaml` for current app version and dependencies rather than copying them into this guide. +The versioned web build uses `dart run build_pipe:build` (also `bun run build`). Web deployment pins Flutter 3.41.2; Linux packaging uses the SDK pin in `scripts/appimage-tools.json`; other CI jobs track stable. Read `pubspec.yaml` for current app version and dependencies rather than copying them into this guide. + +Linux Release installs also generate `build/linux/x64/release/meshcore-open-x86_64.AppImage` using linuxdeploy/GTK and an explicit appimagetool invocation. Tools and the runtime download automatically with pinned SHA-256 checksums. `MESHCORE_BUILD_APPIMAGE=0` skips packaging at install time, without a CMake cache reset. Debug/Profile are unchanged. Nix-linked bundles trigger an isolated Ubuntu rebuild through an available Podman/Docker engine; see [Linux AppImage](README.md#linux-appimage) for prerequisites, cache/offline behavior and limitations. Preserve binary/data/lib adjacency and nested native assets when changing packaging. For Linux, use `nix develop`; see [Linux with Nix](README.md#linux-with-nix) for the pinned SDK, native build checks, cache troubleshooting, and Sysprof host prerequisites. diff --git a/README.md b/README.md index de5d2101..7470da2b 100644 --- a/README.md +++ b/README.md @@ -150,6 +150,49 @@ The matrix describes implemented functionality, not a guarantee that every featu flutter run ``` +### Linux AppImage + +`flutter build linux --release` produces both the regular Flutter bundle and +`build/linux/x64/release/meshcore-open-x86_64.AppImage`. Packaging runs after +Flutter installs its assets and native libraries. Debug and Profile builds do +not produce an AppImage. The initial AppImage target is x86_64, with Ubuntu +24.04 as the packaging baseline; older distributions are not guaranteed. + +For a bundle-only build, including other architectures: + +```bash +MESHCORE_BUILD_APPIMAGE=0 flutter build linux --release +``` + +On Ubuntu 24.04, install the packaging prerequisites alongside Flutter's build +dependencies: + +```bash +sudo apt-get install clang cmake ninja-build pkg-config libgtk-3-dev \ + librsvg2-dev libgirepository1.0-dev libgtk-3-bin libgdk-pixbuf2.0-bin \ + libgdk-pixbuf2.0-dev patchelf binutils curl jq file desktop-file-utils xdg-user-dirs +``` + +The build automatically downloads checksum-verified linuxdeploy, its GTK +plugin, appimagetool, and an AppImage runtime. Pins are in +`scripts/appimage-tools.json`; the cache is under +`${XDG_CACHE_HOME:-$HOME/.cache}/meshcore-open/appimage/`. Packaging can reuse +valid cached tools offline, but Flutter dependencies and native-library +downloads must also be available. A packaging failure fails the enabled build, +without publishing a stale image as a new artifact. + +The image includes Flutter assets, native plugins, ONNX Runtime and +redistributable GTK dependencies. It does not include graphics drivers, BlueZ +services, USB permissions, downloaded inference models or user data. The GTK +packaging plugin uses X11, so Wayland sessions need XWayland. The host still +needs compatible glibc and graphics libraries (`libgl1`, `libegl1`, and +`libgles2` on Ubuntu). Launch normally, or without +FUSE by extracting: + +```bash +./build/linux/x64/release/meshcore-open-x86_64.AppImage --appimage-extract-and-run +``` + ### Linux with Nix Enter the development shell from the repository root: @@ -168,6 +211,19 @@ app requires Flutter 3.41.2 or newer. The Linux shell provides wrapped Clang compilers, native headers and libraries, and Sysprof capture development files. Android SDK warnings do not prevent Linux builds. +Release AppImage builds inside `nix develop` require a usable Podman or Docker +engine on the host. The install hook automatically rebuilds in a pinned Ubuntu +container to avoid shipping Nix store dependencies, while keeping the native +Nix bundle intact. The first build downloads a container image and Flutter SDK; +later builds reuse the image and dependency caches. No privileged package +installation is performed on the host. The container uses the SDK pin in +`scripts/appimage-tools.json` and the current source tree, including local +changes and the resolved `pubspec.lock`. Custom Dart defines and build +name/number are forwarded; custom targets, obfuscation and split-debug-info +require a bundle-only build. Use `MESHCORE_BUILD_APPIMAGE=0` to opt out when no +container engine is available. On NixOS, use the distribution's `appimage-run` +support when needed to launch downloaded AppImages. + If an SDK or toolchain update leaves CMake using an old compiler or install prefix, remove the affected generated cache, for example `rm -f build/linux/x64/profile/CMakeCache.txt`, and rebuild. If widget tests diff --git a/documentation/troubleshooting.md b/documentation/troubleshooting.md index 1f94cf3e..886af097 100644 --- a/documentation/troubleshooting.md +++ b/documentation/troubleshooting.md @@ -22,6 +22,32 @@ BLE and TCP retry an unexpected disconnect with exponential backoff; manual disc Companion stats require firmware code 8+, and image channel data requires code 11+. Image inference also needs an enabled, complete model bundle and adequate memory. A missing incoming region label can mean unknown or unavailable metadata, not an unscoped message. See [images](image-messages.md), [regions](regions.md), and [radio stats](radio-statistics.md). +## Linux AppImage build or launch fails + +Linux Release builds package an x86_64 AppImage automatically. Missing +packaging dependencies, failed downloads or checksum mismatches fail the build; +see [Linux AppImage prerequisites](../README.md#linux-appimage). A checksum +mismatch must not be bypassed: remove the named corrupted cache file and retry. +Tools are pinned in `scripts/appimage-tools.json`; cached tools can be reused +offline, but dependency downloads and first-time container setup still need +network access. Use `MESHCORE_BUILD_APPIMAGE=0 flutter build linux --release` +for a bundle-only build, including ARM builds. + +For a Nix build, verify that your user can access Podman or Docker without +interactive privilege escalation. The image is rebuilt in Ubuntu, not made +from the Nix-linked executable. The regular Nix bundle remains available if +packaging fails. Custom targets, obfuscation and split-debug-info are not +supported by the container rebuild. + +The initial compatibility baseline is Ubuntu 24.04. The host must provide +compatible glibc, graphics drivers, and X11/XWayland; Bluetooth still requires +BlueZ and USB still requires device permissions. If FUSE mounting is +unavailable, try the image's `--appimage-extract-and-run` option, or extract +with `--appimage-extract` and launch `squashfs-root/AppRun`. On NixOS, the +distribution's `appimage-run` support may be required. Include +`appimage-audit.txt` and `appimage-tools.json` from the Release output directory +when reporting packaging failures. Never include private message/model data. + ## Useful bug-report details Include app version, OS/device, radio board and firmware version, transport, reproduction steps, expected behavior, and the exact error. Where relevant, include entries from the **Companion Debug Log** in Settings (frame traffic for BLE, TCP, and USB) or the **App Debug Log**. The App Debug Log only records after you enable App Settings → Debug → **App Debug Logging**. Inspect logs before sharing: they can contain message content, identifiers, and location data. diff --git a/flake.nix b/flake.nix index d64b0fb3..528c3d87 100644 --- a/flake.nix +++ b/flake.nix @@ -43,6 +43,9 @@ unzip ] ++ pkgs.lib.optionals pkgs.stdenv.hostPlatform.isLinux [ pkgs.libsysprof-capture + pkgs.jq + pkgs.binutils + pkgs.util-linux ]; shellHook = '' diff --git a/linux/CMakeLists.txt b/linux/CMakeLists.txt index f697e5dc..a3fc95c7 100644 --- a/linux/CMakeLists.txt +++ b/linux/CMakeLists.txt @@ -181,3 +181,7 @@ if(NOT CMAKE_BUILD_TYPE MATCHES "Debug") install(FILES "${AOT_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}" COMPONENT Runtime) endif() + +configure_file("${CMAKE_CURRENT_SOURCE_DIR}/appimage.cmake.in" + "${CMAKE_CURRENT_BINARY_DIR}/appimage.cmake" @ONLY) +install(SCRIPT "${CMAKE_CURRENT_BINARY_DIR}/appimage.cmake" COMPONENT Runtime) diff --git a/linux/appimage.cmake.in b/linux/appimage.cmake.in new file mode 100644 index 00000000..781c3ddf --- /dev/null +++ b/linux/appimage.cmake.in @@ -0,0 +1,25 @@ +if(NOT CMAKE_INSTALL_CONFIG_NAME STREQUAL "Release" OR + "$ENV{MESHCORE_BUILD_APPIMAGE}" STREQUAL "0") + return() +endif() + +function(meshcore_package_appimage) + include("@CMAKE_CURRENT_SOURCE_DIR@/flutter/ephemeral/generated_config.cmake") + set(packaging_environment) + foreach(entry IN LISTS FLUTTER_TOOL_ENVIRONMENT) + if(entry MATCHES "^(FLUTTER_ROOT|FLUTTER_TARGET|DART_DEFINES|DART_OBFUSCATION|SPLIT_DEBUG_INFO|TREE_SHAKE_ICONS)=") + list(APPEND packaging_environment "MESHCORE_APPIMAGE_${entry}") + endif() + endforeach() + execute_process( + COMMAND "@CMAKE_COMMAND@" -E env ${packaging_environment} + bash "@CMAKE_CURRENT_SOURCE_DIR@/../scripts/build_appimage.sh" + "@CMAKE_CURRENT_SOURCE_DIR@/.." "${CMAKE_INSTALL_PREFIX}" + "@CMAKE_CURRENT_BINARY_DIR@" "${CMAKE_INSTALL_CONFIG_NAME}" "@CMAKE_SYSTEM_PROCESSOR@" + RESULT_VARIABLE appimage_result) + if(NOT appimage_result EQUAL 0) + message(FATAL_ERROR "AppImage packaging failed (${appimage_result}). Set MESHCORE_BUILD_APPIMAGE=0 to build only the Flutter bundle.") + endif() +endfunction() + +meshcore_package_appimage() \ No newline at end of file diff --git a/scripts/appimage-tools.json b/scripts/appimage-tools.json new file mode 100644 index 00000000..f8762768 --- /dev/null +++ b/scripts/appimage-tools.json @@ -0,0 +1,26 @@ +{ + "ubuntu": "ubuntu:24.04@sha256:fe81560990fae86dc4743202b2cb4d3df98d0bcf949173cecef15ce1127ef852", + "flutter": { + "version": "3.47.4", + "url": "https://storage.googleapis.com/flutter_infra_release/releases/stable/linux/flutter_linux_3.47.4-stable.tar.xz", + "sha256": "5b45f0ceda99b9bebdc873e7e69f6450aeb4c30f454b505e2e62fc9255a907d3" + }, + "tools": { + "linuxdeploy": { + "url": "https://github.com/linuxdeploy/linuxdeploy/releases/download/1-alpha-20251107-1/linuxdeploy-x86_64.AppImage", + "sha256": "c20cd71e3a4e3b80c3483cef793cda3f4e990aca14014d23c544ca3ce1270b4d" + }, + "appimagetool": { + "url": "https://github.com/AppImage/appimagetool/releases/download/1.9.1/appimagetool-x86_64.AppImage", + "sha256": "ed4ce84f0d9caff66f50bcca6ff6f35aae54ce8135408b3fa33abfc3cb384eb0" + }, + "gtk": { + "url": "https://raw.githubusercontent.com/linuxdeploy/linuxdeploy-plugin-gtk/7a3fbc31a9e5075073ff8790f26effbac5f84453/linuxdeploy-plugin-gtk.sh", + "sha256": "b0f4cbc684a0103a9651f0955b635eaea0096b3a66c0f5a2c2aa337960375171" + }, + "runtime": { + "url": "https://github.com/AppImage/type2-runtime/releases/download/20251108/runtime-x86_64", + "sha256": "2fca8b443c92510f1483a883f60061ad09b46b978b2631c807cd873a47ec260d" + } + } +} \ No newline at end of file diff --git a/scripts/appimage/AppRun b/scripts/appimage/AppRun new file mode 100644 index 00000000..5aaaaece --- /dev/null +++ b/scripts/appimage/AppRun @@ -0,0 +1,10 @@ +#!/usr/bin/env bash +set -eo pipefail + +export APPDIR="${APPDIR:-$(cd "$(dirname "$0")" && pwd)}" +export PATH="$APPDIR/usr/bin:$PATH" +for hook in "$APPDIR"/apprun-hooks/*.sh; do + # shellcheck source=/dev/null + [[ ! -f "$hook" ]] || source "$hook" +done +exec "$APPDIR/usr/bin/meshcore_open" "$@" \ No newline at end of file diff --git a/scripts/appimage/Dockerfile b/scripts/appimage/Dockerfile new file mode 100644 index 00000000..2d9b4106 --- /dev/null +++ b/scripts/appimage/Dockerfile @@ -0,0 +1,27 @@ +ARG BASE_IMAGE=ubuntu:24.04@sha256:fe81560990fae86dc4743202b2cb4d3df98d0bcf949173cecef15ce1127ef852 +FROM ${BASE_IMAGE} AS build + +ENV DEBIAN_FRONTEND=noninteractive +RUN apt-get update && apt-get install -y --no-install-recommends \ + ca-certificates clang cmake ninja-build pkg-config libgtk-3-dev \ + librsvg2-dev libgirepository1.0-dev libgdk-pixbuf-2.0-dev libgtk-3-bin \ + libgdk-pixbuf2.0-bin libgdk-pixbuf2.0-dev binutils patchelf curl jq \ + file desktop-file-utils xdg-user-dirs git rsync unzip xz-utils make g++ \ + libssl-dev libunwind-dev libvulkan-dev libgl1-mesa-dev libglu1-mesa-dev \ + libasound2-dev libsecret-1-dev \ + && rm -rf /var/lib/apt/lists/* + +COPY appimage-tools.json /opt/packaging/ +RUN set -eu; curl --fail --location --retry 3 --connect-timeout 20 --max-time 600 \ + "$(jq -er .flutter.url /opt/packaging/appimage-tools.json)" --output /tmp/flutter.tar.xz \ + && printf '%s /tmp/flutter.tar.xz\n' "$(jq -er .flutter.sha256 /opt/packaging/appimage-tools.json)" | sha256sum --check \ + && tar -xJf /tmp/flutter.tar.xz -C /opt && rm /tmp/flutter.tar.xz \ + && chmod -R a+rwX /opt/flutter +ENV PATH="/opt/flutter/bin:${PATH}" + +FROM ${BASE_IMAGE} AS runtime-test +ENV DEBIAN_FRONTEND=noninteractive +RUN apt-get update && apt-get install -y --no-install-recommends \ + xvfb xauth x11-utils x11-apps xdotool imagemagick dbus-x11 libgl1 libegl1 libgles2 \ + libgl1-mesa-dri fonts-dejavu-core \ + && rm -rf /var/lib/apt/lists/* \ No newline at end of file diff --git a/scripts/appimage/com.meshcore.meshcore_open.desktop b/scripts/appimage/com.meshcore.meshcore_open.desktop new file mode 100644 index 00000000..05d08f4c --- /dev/null +++ b/scripts/appimage/com.meshcore.meshcore_open.desktop @@ -0,0 +1,7 @@ +[Desktop Entry] +Type=Application +Name=MeshCore Open +Exec=meshcore_open +Icon=com.meshcore.meshcore_open +Terminal=false +Categories=Network;InstantMessaging; \ No newline at end of file diff --git a/scripts/appimage/test_packaging.sh b/scripts/appimage/test_packaging.sh new file mode 100644 index 00000000..1e338778 --- /dev/null +++ b/scripts/appimage/test_packaging.sh @@ -0,0 +1,53 @@ +#!/usr/bin/env bash +set -euo pipefail + +project="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" +source "$project/scripts/build_appimage.sh" +temporary="$(mktemp -d)" +trap 'rm -rf "$temporary"' EXIT + +assert_fails() { + if "$@" >"$temporary/error" 2>&1; then + printf 'Expected failure: %s\n' "$*" >&2 + exit 1 + fi +} + +assert_fails packaging_enabled Debug +assert_fails packaging_enabled Profile +packaging_enabled Release +MESHCORE_BUILD_APPIMAGE=0 assert_fails packaging_enabled Release +assert_fails check_bundle "$temporary/missing" + +mkdir -p "$temporary/bundle/lib" "$temporary/bundle/data/flutter_assets" +touch "$temporary/bundle/meshcore_open" "$temporary/bundle/lib/libapp.so" \ + "$temporary/bundle/data/icudtl.dat" +chmod +x "$temporary/bundle/meshcore_open" +check_bundle "$temporary/bundle" +rm "$temporary/bundle/lib/libapp.so" +assert_fails check_bundle "$temporary/bundle" +touch "$temporary/bundle/lib/libapp.so" +MESHCORE_BUILD_APPIMAGE=0 bash "$project/scripts/build_appimage.sh" \ + "$project" /missing "$temporary/output" Release x64 +bash "$project/scripts/build_appimage.sh" "$project" /missing "$temporary/output" Debug x64 +[[ ! -d "$temporary/output" ]] +assert_fails bash "$project/scripts/build_appimage.sh" \ + "$project" /missing "$temporary/output" Release arm64 + +stage_bundle "$project" "$temporary/bundle" "$temporary/AppDir with spaces" +check_bundle "$temporary/AppDir with spaces/usr/bin" +[[ -x "$temporary/AppDir with spaces/AppRun" ]] +[[ -f "$temporary/AppDir with spaces/usr/share/applications/com.meshcore.meshcore_open.desktop" ]] + +printf 'fixture\n' > "$temporary/input" +checksum="$(sha256sum "$temporary/input")" +checksum="${checksum%% *}" +download_verified "file://$temporary/input" "$checksum" "$temporary/cache/tool" +download_verified 'https://invalid.example/offline' "$checksum" "$temporary/cache/tool" +assert_fails download_verified "file://$temporary/input" \ + '0000000000000000000000000000000000000000000000000000000000000000' "$temporary/cache/invalid" +[[ ! -e "$temporary/cache/invalid" ]] +printf 'corruption\n' >> "$temporary/cache/tool" +assert_fails download_verified "file://$temporary/input" "$checksum" "$temporary/cache/tool" + +printf 'AppImage packaging contract tests passed\n' \ No newline at end of file diff --git a/scripts/appimage/test_runtime.sh b/scripts/appimage/test_runtime.sh new file mode 100644 index 00000000..f84a05aa --- /dev/null +++ b/scripts/appimage/test_runtime.sh @@ -0,0 +1,60 @@ +#!/usr/bin/env bash +set -euo pipefail + +image="$(realpath "$1")" +mkdir -p "$2" +output="$(realpath "$2")" +workspace="$(mktemp -d)" +app_pid='' +bus_pid='' +cleanup() { + [[ -z "$app_pid" ]] || kill "$app_pid" 2>/dev/null || true + [[ -z "$bus_pid" ]] || kill "$bus_pid" 2>/dev/null || true + rm -rf "$workspace" +} +trap cleanup EXIT +cd "$workspace" +printf 'AppImage runtime test: extracting image\n' +cp "$image" "$workspace/extractor" +printf '\0\0\0' | dd of="$workspace/extractor" bs=1 seek=8 count=3 conv=notrunc status=none +timeout 60 "$workspace/extractor" --appimage-extract > /dev/null +appdir="$workspace/squashfs-root" +[[ -x "$appdir/AppRun" && -f "$appdir/usr/bin/lib/libapp.so" && \ + -f "$appdir/usr/bin/data/icudtl.dat" && -d "$appdir/usr/bin/data/flutter_assets" ]] +[[ -f "$appdir/usr/bin/lib/libonnxruntime.so.1" && \ + -f "$appdir/usr/share/glib-2.0/schemas/gschemas.compiled" ]] +ldd "$appdir/usr/bin/meshcore_open" > "$output/dependencies.log" 2>&1 +while IFS= read -r -d '' library; do + printf '\n%s\n' "${library#"$appdir/"}" >> "$output/dependencies.log" + ldd "$library" >> "$output/dependencies.log" 2>&1 || true +done < <(find "$appdir/usr/bin/lib" "$appdir/usr/lib" -type f -name '*.so*' -print0) +if grep 'not found' "$output/dependencies.log"; then + printf 'Unresolved AppImage dependencies\n' >&2 + exit 1 +fi +mkdir -p "$workspace/home/Documents" "$workspace/home/config" +printf 'XDG_DOCUMENTS_DIR="%s/Documents"\n' "$workspace/home" > "$workspace/home/config/user-dirs.dirs" +bus_pid="$(dbus-daemon --session --address="unix:path=$workspace/system-bus" --fork --print-pid)" +printf 'AppImage runtime test: launching application\n' +env -u LD_LIBRARY_PATH -u GTK_PATH -u GSETTINGS_SCHEMA_DIR \ + HOME="$workspace/home" XDG_CONFIG_HOME="$workspace/home/config" \ + XDG_DATA_HOME="$workspace/home/data" XDG_CACHE_HOME="$workspace/home/cache" \ + DBUS_SYSTEM_BUS_ADDRESS="unix:path=$workspace/system-bus" \ + dbus-run-session -- "$appdir/AppRun" > "$output/startup.log" 2>&1 & +app_pid=$! +window="$(timeout 60 xdotool search --sync --onlyvisible --limit 1 --name 'MeshCore Open|meshcore_open')" +colors=0 +deadline=$((SECONDS + 60)) +while (( SECONDS < deadline )); do + kill -0 "$app_pid" + xwd -silent -id "$window" -out "$workspace/window.xwd" + convert "$workspace/window.xwd" "$output/startup.png" + colors="$(identify -format '%k' "$output/startup.png")" + (( colors < 20 )) || break +done +(( colors >= 20 )) || { printf 'Application window remained blank\n' >&2; exit 1; } +[[ -s "$output/startup.png" ]] +if grep -Ei 'error while loading shared libraries|cannot open shared object|failed to load asset|unhandled exception' "$output/startup.log"; then + exit 1 +fi +printf 'Extracted AppImage startup passed; screenshot: %s/startup.png\n' "$output" \ No newline at end of file diff --git a/scripts/build_appimage.sh b/scripts/build_appimage.sh new file mode 100644 index 00000000..92063da4 --- /dev/null +++ b/scripts/build_appimage.sh @@ -0,0 +1,293 @@ +#!/usr/bin/env bash +set -euo pipefail + +fail() { + printf 'AppImage: %s\n' "$*" >&2 + return 1 +} + +packaging_enabled() { + [[ "${MESHCORE_BUILD_APPIMAGE:-1}" != 0 && "$1" == Release ]] +} + +check_bundle() { + local bundle="$1" + [[ -x "$bundle/meshcore_open" && -f "$bundle/lib/libapp.so" && \ + -f "$bundle/data/icudtl.dat" && -d "$bundle/data/flutter_assets" ]] || \ + fail "Incomplete release bundle: $bundle" +} + +download_verified() { + local url="$1" checksum="$2" destination="$3" temporary + mkdir -p "$(dirname "$destination")" + if [[ -f "$destination" ]]; then + if printf '%s %s\n' "$checksum" "$destination" | sha256sum --check --status; then + return + fi + fail "Cached tool checksum mismatch: $destination; remove it and retry" + return 1 + fi + temporary="$(mktemp "$destination.download.XXXXXX")" + if ! curl --fail --location --retry 3 --connect-timeout 20 --max-time 600 \ + --output "$temporary" "$url"; then + rm -f "$temporary" + fail "Cannot download $url; populate the verified cache or disable packaging with MESHCORE_BUILD_APPIMAGE=0" + return 1 + fi + if ! printf '%s %s\n' "$checksum" "$temporary" | sha256sum --check --status; then + rm -f "$temporary" + fail "Downloaded tool checksum mismatch: $url" + return 1 + fi + mv "$temporary" "$destination" +} + +require_tools() { + local tool + for tool in "$@"; do + command -v "$tool" >/dev/null || { + fail "Missing $tool; see README Linux AppImage prerequisites or set MESHCORE_BUILD_APPIMAGE=0" + return 1 + } + done +} + +prepare_tools() { + local manifest="$1" cache="$2" tool url checksum + mkdir -p "$cache" + exec {cache_lock}>"$cache/tools.lock" + flock "$cache_lock" + for tool in linuxdeploy appimagetool gtk runtime; do + url="$(jq -er --arg tool "$tool" '.tools[$tool].url' "$manifest")" + checksum="$(jq -er --arg tool "$tool" '.tools[$tool].sha256' "$manifest")" + download_verified "$url" "$checksum" "$cache/$tool" + chmod +x "$cache/$tool" + done + flock -u "$cache_lock" + exec {cache_lock}>&- +} + +extract_tool() { + local tool="$1" destination="$2" + mkdir -p "$destination" + cp "$tool" "$destination/extractor" + printf '\0\0\0' | dd of="$destination/extractor" bs=1 seek=8 count=3 conv=notrunc status=none + (cd "$destination" && ./extractor --appimage-extract >/dev/null) +} + +stage_bundle() { + local project="$1" bundle="$2" appdir="$3" identity=com.meshcore.meshcore_open + mkdir -p "$appdir/usr/bin" "$appdir/usr/share/applications" \ + "$appdir/usr/share/icons/hicolor/256x256/apps" + cp -a "$bundle/." "$appdir/usr/bin/" + install -m 644 "$project/scripts/appimage/$identity.desktop" "$appdir/usr/share/applications/" + install -m 644 "$project/mesh-icon.png" "$appdir/usr/share/icons/hicolor/256x256/apps/$identity.png" + install -m 755 "$project/scripts/appimage/AppRun" "$appdir/AppRun" +} + +audit_appdir() { + local appdir="$1" report="$2" library rpath interpreter needed + : > "$report" + while IFS= read -r -d '' library; do + readelf -h "$library" >/dev/null 2>&1 || continue + rpath="$(patchelf --print-rpath "$library")" + interpreter="$(patchelf --print-interpreter "$library" 2>/dev/null || true)" + needed="$(patchelf --print-needed "$library")" + if [[ "$rpath$interpreter$needed" == *'/nix/store/'* || \ + "$rpath" == *"$appdir"* ]]; then + fail "Non-relocatable ELF: $library" + return 1 + fi + printf '%s\n interpreter: %s\n rpath: %s\n%s\n' \ + "${library#"$appdir/"}" "$interpreter" "$rpath" "$needed" >> "$report" + done < <(find "$appdir" -type f -print0) +} + +package_direct() { + local project="$1" bundle="$2" output="$3" manifest="$4" cache="$5" + local work appdir library relative linuxdeploy appimagetool + local dependencies=() + require_tools curl jq sha256sum flock file readelf patchelf pkg-config \ + desktop-file-validate glib-compile-schemas gdk-pixbuf-thumbnailer xdg-user-dir + pkg-config --exists gtk+-3.0 librsvg-2.0 gobject-introspection-1.0 || \ + { fail 'Missing GTK, librsvg or GObject introspection development files'; return 1; } + prepare_tools "$manifest" "$cache" + work="$(mktemp -d "$output/appimage.XXXXXX")" + # shellcheck disable=SC2064 + trap "rm -rf -- $(printf '%q' "$work")" EXIT + appdir="$work/AppDir" + extract_tool "$cache/linuxdeploy" "$work/linuxdeploy" + extract_tool "$cache/appimagetool" "$work/appimagetool" + linuxdeploy="$work/linuxdeploy/squashfs-root/AppRun" + appimagetool="$work/appimagetool/squashfs-root/AppRun" + install -m 755 "$cache/gtk" "$work/linuxdeploy/squashfs-root/linuxdeploy-plugin-gtk.sh" + export PATH="$work/linuxdeploy/squashfs-root:$PATH" + stage_bundle "$project" "$bundle" "$appdir" + install -m 755 "$(command -v xdg-user-dir)" "$appdir/usr/bin/xdg-user-dir" + gdk-pixbuf-thumbnailer --size 256 "$project/mesh-icon.png" \ + "$appdir/usr/share/icons/hicolor/256x256/apps/com.meshcore.meshcore_open.png" + desktop-file-validate "$appdir/usr/share/applications/com.meshcore.meshcore_open.desktop" + export DEPLOY_GTK_VERSION=3 NO_STRIP=1 + "$linuxdeploy" --appdir "$appdir" --executable "$appdir/usr/bin/meshcore_open" \ + --library "$(pkg-config --variable=libdir harfbuzz)/libharfbuzz.so.0" \ + --library "$(pkg-config --variable=libdir freetype2)/libfreetype.so.6" \ + --library "$(pkg-config --variable=libdir fontconfig)/libfontconfig.so.1" \ + --library "$(pkg-config --variable=libdir fribidi)/libfribidi.so.0" \ + --desktop-file "$appdir/usr/share/applications/com.meshcore.meshcore_open.desktop" \ + --icon-file "$appdir/usr/share/icons/hicolor/256x256/apps/com.meshcore.meshcore_open.png" \ + --plugin gtk + while IFS= read -r -d '' library; do + readelf -h "$library" >/dev/null 2>&1 || continue + dependencies+=(--deploy-deps-only "$library") + done < <(find "$appdir/usr/bin/lib" -type f -print0) + "$linuxdeploy" --appdir "$appdir" "${dependencies[@]}" + while IFS= read -r -d '' library; do + readelf -h "$library" >/dev/null 2>&1 || continue + relative="$(realpath --relative-to="$(dirname "$library")" "$appdir/usr/lib")" + patchelf --set-rpath "\$ORIGIN:\$ORIGIN/lib:\$ORIGIN/$relative" "$library" + done < <(find "$appdir" -type f -print0) + install -m 755 "$project/scripts/appimage/AppRun" "$appdir/AppRun" + mkdir -p "$appdir/usr/share/doc/meshcore-open" + cp "$project/LICENSE" "$appdir/usr/share/doc/meshcore-open/" + while IFS= read -r -d '' library; do + relative="${library#/usr/share/doc/}" + mkdir -p "$appdir/usr/share/doc/meshcore-open/$(dirname "$relative")" + cp -L "$library" "$appdir/usr/share/doc/meshcore-open/$relative" + done < <(find -L /usr/share/doc -name copyright -type f -print0) + while IFS= read -r -d '' library; do + relative="$(realpath --relative-to="$project" "$library")" + mkdir -p "$appdir/usr/share/doc/meshcore-open/build-notices/$(dirname "$relative")" + cp -L "$library" "$appdir/usr/share/doc/meshcore-open/build-notices/$relative" + done < <(find "$(dirname "$bundle")/plugins" -type f \ + \( -iname LICENSE -o -iname NOTICE -o -name ThirdPartyNotices.txt \) -print0) + if [[ -n "${PUB_CACHE:-}" && -d "$PUB_CACHE/hosted" ]]; then + while IFS= read -r -d '' library; do + relative="${library#"$PUB_CACHE/"}" + mkdir -p "$appdir/usr/share/doc/meshcore-open/packages/$(dirname "$relative")" + cp -L "$library" "$appdir/usr/share/doc/meshcore-open/packages/$relative" + done < <(find "$PUB_CACHE/hosted" -maxdepth 4 -type f \ + \( -iname LICENSE -o -iname NOTICE \) -print0) + fi + if [[ -f "${MESHCORE_APPIMAGE_FLUTTER_ROOT:-}/LICENSE" ]]; then + cp "$MESHCORE_APPIMAGE_FLUTTER_ROOT/LICENSE" "$appdir/usr/share/doc/meshcore-open/Flutter-LICENSE" + fi + audit_appdir "$appdir" "$work/audit.txt" + ARCH=x86_64 "$appimagetool" --runtime-file "$cache/runtime" --no-appstream \ + "$appdir" "$work/meshcore-open-x86_64.AppImage" + chmod +x "$work/meshcore-open-x86_64.AppImage" + mv "$work/meshcore-open-x86_64.AppImage" "$output/meshcore-open-x86_64.AppImage" + mv "$work/audit.txt" "$output/appimage-audit.txt" + cp "$manifest" "$output/appimage-tools.json" + rm -rf "$work" + trap - EXIT +} + +container_build() { + local workspace arguments=() definitions=() encoded decoded + workspace="$(mktemp -d /tmp/meshcore-appimage.XXXXXX)" + # shellcheck disable=SC2064 + trap "rm -rf -- $(printf '%q' "$workspace")" EXIT + rsync -aL --exclude '/build' --exclude '/.dart_tool' --exclude '/.git' \ + --exclude '/.pub-cache' --exclude '/.pub' --exclude '/.env' \ + --exclude '/linux/flutter/ephemeral' --exclude '/android' --exclude '/ios' \ + --exclude '/macos' --exclude '/windows' /source/ "$workspace/" + mkdir -p "$HOME" + git config --global --add safe.directory /opt/flutter + flutter config --no-analytics >/dev/null + cd "$workspace" + flutter pub get --enforce-lockfile + IFS=',' read -r -a definitions <<< "${MESHCORE_APPIMAGE_DART_DEFINES:-}" + for encoded in "${definitions[@]}"; do + [[ -n "$encoded" ]] || continue + decoded="$(printf '%s' "$encoded" | base64 --decode)" + case "$decoded" in + FLUTTER_BUILD_NAME=*) arguments+=("--build-name=${decoded#*=}") ;; + FLUTTER_BUILD_NUMBER=*) arguments+=("--build-number=${decoded#*=}") ;; + FLUTTER_VERSION=*|FLUTTER_CHANNEL=*|FLUTTER_GIT_URL=*|FLUTTER_FRAMEWORK_REVISION=*|FLUTTER_ENGINE_REVISION=*|FLUTTER_DART_VERSION=*) ;; + *) arguments+=("--dart-define=$decoded") ;; + esac + done + if [[ "${MESHCORE_APPIMAGE_TREE_SHAKE_ICONS:-true}" == false ]]; then + arguments+=(--no-tree-shake-icons) + fi + flutter build linux --release --no-pub "${arguments[@]}" + cp build/linux/x64/release/meshcore-open-x86_64.AppImage /output/ + cp build/linux/x64/release/appimage-audit.txt /output/ + cp build/linux/x64/release/appimage-tools.json /output/ + rm -rf "$workspace" + trap - EXIT +} + +package_container() { + local project="$1" output="$2" manifest="$3" cache="$4" engine image pin key + [[ "${MESHCORE_APPIMAGE_IN_CONTAINER:-0}" != 1 ]] || \ + { fail 'The container bundle unexpectedly contains Nix-linked executables'; return 1; } + [[ "${MESHCORE_APPIMAGE_FLUTTER_TARGET:-lib/main.dart}" == lib/main.dart && \ + "${MESHCORE_APPIMAGE_DART_OBFUSCATION:-false}" == false && \ + -z "${MESHCORE_APPIMAGE_SPLIT_DEBUG_INFO:-}" ]] || \ + { fail 'Nix AppImage rebuilding supports main.dart without obfuscation/split-debug-info; set MESHCORE_BUILD_APPIMAGE=0 for other builds'; return 1; } + [[ -f "$project/pubspec.lock" ]] || \ + { fail 'The container rebuild requires pubspec.lock from flutter pub get'; return 1; } + engine='' + for key in podman docker; do + if command -v "$key" >/dev/null && "$key" info >/dev/null 2>&1; then + engine="$key" + break + fi + done + [[ -n "$engine" ]] || \ + { fail 'Nix AppImage packaging requires a usable Podman or Docker engine; set MESHCORE_BUILD_APPIMAGE=0 to opt out'; return 1; } + mkdir -p "$cache" "$cache/pub" + pin="$(sha256sum "$manifest" "$project/scripts/appimage/Dockerfile" | sha256sum)" + image="meshcore-open-appimage:${pin:0:16}" + printf 'AppImage: rebuilding in Ubuntu with %s (Flutter %s); native Nix bundle is unchanged\n' \ + "$engine" "$(jq -r '.flutter.version' "$manifest")" + if ! "$engine" image inspect "$image" >/dev/null 2>&1; then + "$engine" build --target build --platform linux/amd64 --tag "$image" \ + --build-arg "BASE_IMAGE=$(jq -er '.ubuntu' "$manifest")" \ + --file "$project/scripts/appimage/Dockerfile" "$project/scripts" + fi + local environment=(--env MESHCORE_APPIMAGE_IN_CONTAINER=1 --env HOME=/tmp/home \ + --env XDG_CACHE_HOME=/cache --env PUB_CACHE=/cache/pub) + for key in FLUTTER_TARGET DART_DEFINES DART_OBFUSCATION SPLIT_DEBUG_INFO TREE_SHAKE_ICONS; do + environment+=(--env "MESHCORE_APPIMAGE_$key") + done + "$engine" run --rm --platform linux/amd64 --user "$(id -u):$(id -g)" \ + "${environment[@]}" --mount "type=bind,source=$(realpath "$project"),target=/source,readonly" \ + --mount "type=bind,source=$output,target=/output" \ + --mount "type=bind,source=$cache,target=/cache" \ + "$image" bash /source/scripts/build_appimage.sh --container-build +} + +main() { + [[ $# == 5 ]] || { fail 'Expected: project bundle output configuration architecture'; return 1; } + local project="$1" bundle="$2" output="$3" configuration="$4" architecture="$5" + packaging_enabled "$configuration" || return 0 + [[ "$architecture" == x64 || "$architecture" == x86_64 ]] || \ + { fail 'Only x86_64 AppImages are supported; set MESHCORE_BUILD_APPIMAGE=0 for other architectures'; return 1; } + mkdir -p "$output" + output="$(realpath "$output")" + exec {output_lock}>"$output/appimage.lock" + flock "$output_lock" + rm -f "$output/meshcore-open-x86_64.AppImage" "$output/appimage-audit.txt" "$output/appimage-tools.json" + check_bundle "$bundle" + require_tools jq readelf sha256sum + local manifest="$project/scripts/appimage-tools.json" pin cache + pin="$(sha256sum "$manifest")" + pin="${pin%% *}" + cache="${XDG_CACHE_HOME:-$HOME/.cache}/meshcore-open/appimage/$pin/x86_64" + if [[ "$(readelf -l "$bundle/meshcore_open")" == *'/nix/store/'* ]]; then + package_container "$project" "$output" "$manifest" "$cache" + else + package_direct "$project" "$bundle" "$output" "$manifest" "$cache" + fi + printf 'AppImage created: %s/meshcore-open-x86_64.AppImage\n' "$output" +} + +if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then + if [[ "${1:-}" == --container-build ]]; then + container_build + else + main "$@" + fi +fi \ No newline at end of file