Skip to content

BUILDING.md

Latest commit

 

History

History
521 lines (381 loc) · 14.9 KB

BUILDING.md

File metadata and controls

521 lines (381 loc) · 14.9 KB
Raw

Building Operit2

This file describes how to build, run, and package Operit2 from the repository root.

Rust build warnings are currently expected. Treat command exit status as the signal for build success.

Repository Layout

apps/cli                  Rust CLI/TUI entry
apps/flutter/app          Flutter app entry
core/crates               Shared Rust runtime crates
hosts                     Native host implementations
tools/release             Release build and publish scripts
docs/release-versioning.md Version, tag, channel, and asset naming rules

Requirements

Common tools:

Rust stable toolchain with rustup
Python virtual environment at .venv
Git

Windows desktop CLI builds:

Visual Studio 2022 C++ build tools
MSVC x64 and ARM64 components
LLVM clang at C:\Program Files\LLVM\bin\clang.exe

Linux desktop App builds:

CMake, Ninja, pkg-config, clang, and GTK development headers
GStreamer development headers exposing gstreamer-1.0, gstreamer-app-1.0, and
gstreamer-audio-1.0 through pkg-config
WebKitGTK 4.1 development headers exposing pkg-config package webkit2gtk-4.1

Flutter app builds:

Flutter SDK
apps/flutter/app/android/local.properties with flutter.sdk
tools/release/secrets/android-signing.properties for Android release signing

GitHub publishing:

tools/release/secrets/github.env

Required keys:

GITHUB_TOKEN
GITHUB_API_URL

Rust Targets

Windows CLI release builds use:

rustup target add x86_64-pc-windows-msvc
rustup target add aarch64-pc-windows-msvc

Fedora WSL Linux CLI release builds use these Rust targets:

rustup target add x86_64-unknown-linux-musl
rustup target add aarch64-unknown-linux-gnu
sudo dnf install -y musl-gcc musl-devel musl-libc-static gcc-aarch64-linux-gnu sysroot-aarch64-fc43-glibc

The aarch64 Linux CLI release requires an aarch64-linux-gnu-gcc cross C compiler and the Fedora /usr/aarch64-redhat-linux/sys-root/fc43 sysroot. The build release script injects the sysroot's limits.h while compiling C dependencies because Fedora's cross compiler is built without target headers.

Local CLI Checks

Run from the repository root.

cargo check --manifest-path apps/cli/Cargo.toml
cargo run --manifest-path apps/cli/Cargo.toml --bin operit2 -- cli version

Run the TUI:

cargo run --manifest-path apps/cli/Cargo.toml --bin operit2 -- tui

Run update checks:

cargo run --manifest-path apps/cli/Cargo.toml --bin operit2 -- cli update target
cargo run --manifest-path apps/cli/Cargo.toml --bin operit2 -- cli update check 0.0.0-preview.0
cargo run --manifest-path apps/cli/Cargo.toml --bin operit2 -- tui --update-current-version 0.0.0-preview.0

Build Release Script

Interactive release helper:

.\.venv\Scripts\python.exe tools\release\release_interactive.py

Direct build release script:

.\.venv\Scripts\python.exe tools\release\build_release.py

Environment check only:

.\.venv\Scripts\python.exe tools\build_scripts\build_local.py --products all --cli-arches host --check
.\.venv\Scripts\python.exe tools\release\build_release.py --scope full --cli-arches all --check-environment

Scopes:

.\.venv\Scripts\python.exe tools\release\build_release.py --scope cli
.\.venv\Scripts\python.exe tools\release\build_release.py --scope app
.\.venv\Scripts\python.exe tools\release\build_release.py --scope full
.\.venv\Scripts\python.exe tools\release\build_release.py --scope none --no-wsl

Build only:

.\.venv\Scripts\python.exe tools\release\build_release.py --scope cli

tools/release/dist is the shared staging directory for local, SSH-collected, and GitHub Actions assets. build_release.py keeps existing staged files so platform builds can be composed. Start a new staged set explicitly with:

.\.venv\Scripts\python.exe tools\release\build_release.py --scope cli --clean-dist

Release environment assumptions:

Local Windows build_release.py:
  Builds Android, OpenHarmony, Windows App, Windows CLI, and WSL Linux assets.
  Requires Windows build tools, Android/OpenHarmony signing files, and Fedora WSL
  when WSL Linux assets are selected.

Local build_local.py:
  Builds only the current host App and/or CLI after checking the current host
  requirements. macOS can add unsigned iOS with --include-ios.

GitHub Actions:
  Apple Release Build, macOS Flutter Build, iOS Flutter Build, Windows Release
  Build, Linux Release Build, and Android Flutter Build are manual cloud
  entrypoints. Artifacts downloaded from cloud runs are collected into
  tools/release/dist with download_action_artifacts.py.

Cloud build composition:

1. Trigger the platform workflows needed for this release.
2. Wait for every selected workflow to succeed.
3. Collect every run into tools/release/dist with one --run-id per run.
4. Run publish_dist.py only when the collected files are ready to publish.

Successful App and full builds advance the Flutter build number in apps/flutter/app/pubspec.yaml after their assets are packaged. CLI-only builds do not change it.

CLI architecture selection:

.\.venv\Scripts\python.exe tools\release\build_release.py --scope cli --cli-arches host
.\.venv\Scripts\python.exe tools\release\build_release.py --scope cli --cli-arches all

On Windows, --cli-arches all builds:

operit2-cli-windows-x86_64.zip
operit2-cli-windows-aarch64.zip
operit2-cli-linux-x86_64.tar.gz
operit2-cli-linux-aarch64.tar.gz

Cloud workflows are independent manual workflow_dispatch entrypoints. The Apple aggregate workflow invokes the reusable macOS and iOS workflows; the other workflows build exactly one platform family:

Apple Release Build       macOS App, macOS CLI, and unsigned iOS App
macOS Flutter Build       macOS App and/or CLI
iOS Flutter Build         unsigned iOS App
Windows Release Build     Windows App and/or CLI
Linux Release Build       Linux App and/or CLI
Android Flutter Build     signed Android APKs

Android Flutter Build requires these repository secrets before it can run:

ANDROID_RELEASE_KEYSTORE_BASE64
ANDROID_RELEASE_STORE_PASSWORD
ANDROID_RELEASE_KEY_ALIAS
ANDROID_RELEASE_KEY_PASSWORD

ANDROID_RELEASE_KEYSTORE_BASE64 is the Base64 encoding of the Android release keystore. The workflow writes the signing material only inside its runner.

OpenHarmony has no GitHub Actions workflow yet. Its SDK and command-line tools are not currently distributed from a reproducible URL available to this repository, so a cloud workflow cannot provision a valid toolchain. The local OpenHarmony procedure below remains the supported build path until that SDK distribution source and the signing secrets are supplied.

gh workflow run "Apple Release Build" -f products=all -f include_ios=true -f build_web_assets=false
gh workflow run "macOS Flutter Build" -f products=all -f build_web_assets=false
gh workflow run "iOS Flutter Build" -f build_web_assets=false
gh workflow run "Windows Release Build" -f products=all -f cli_arches=all
gh workflow run "Linux Release Build" -f products=all -f cli_arches=all
gh workflow run "Android Flutter Build"
.\.venv\Scripts\python.exe tools\release\download_action_artifacts.py --run-id <apple-run-id> --run-id <windows-run-id> --run-id <linux-run-id> --run-id <android-run-id>

download_action_artifacts.py accepts only completed successful runs and copies their release archives into the existing tools/release/dist staging directory.

Collaborators can still build the current host locally with one Python command. Run it from the repository root. On Windows, use the project virtual environment. On macOS and Linux, use the active Python 3 environment.

.\.venv\Scripts\python.exe tools\build_scripts\build_local.py --products all --cli-arches host
python3 tools/build_scripts/build_local.py --products all --cli-arches host
python3 tools/build_scripts/build_local.py --products app --include-ios

Local Apple builds require Xcode, Rust, FVM, Node/npm, and Python 3 on the macOS host. Apple outputs include:

operit2-app-macos-universal.zip
operit2-app-ios-arm64.zip
operit2-cli-macos-x86_64.tar.gz
operit2-cli-macos-aarch64.tar.gz

The output directory is:

tools/release/dist

Each CLI archive contains:

operit2 or operit2.exe
install.sh or install.bat
uninstall.sh or uninstall.bat
README.txt

Skip WSL Linux packaging:

.\.venv\Scripts\python.exe tools\release\build_release.py --scope cli --cli-arches all --no-wsl

Publishing

Publish the already-built files in tools/release/dist to GitHub Release:

.\.venv\Scripts\python.exe tools\release\publish_dist.py

Validate the staged files and GitHub credentials without uploading:

.\.venv\Scripts\python.exe tools\release\publish_dist.py --check-only

Publish staged files as a draft:

.\.venv\Scripts\python.exe tools\release\publish_dist.py --draft

The build release script reads versions from:

apps/cli/Cargo.toml
core/crates/operit-runtime/Cargo.toml
apps/flutter/app/pubspec.yaml

Version, tag, build number, and updater asset rules are defined in:

docs/release-versioning.md

Flutter App

The build release script builds app packages through Flutter. Local checks can be run from:

cd apps\flutter\app
fvm install --skip-pub-get
fvm dart pub get --enforce-lockfile

Windows app release build:

fvm flutter build windows --release --no-pub --build-name 2.0.0 --build-number 1

Android release build requires signing values in:

tools/release/secrets/android-signing.properties

Keep the Android release keystore and properties outside git and back them up:

tools/release/secrets/operit2-release.keystore
tools/release/secrets/android-signing.properties

OpenHarmony Flutter App

OpenHarmony builds require the OpenHarmony Flutter SDK maintained at:

https://gitcode.com/openharmony-sig/flutter_flutter.git

The Flutter app is pinned to the OpenHarmony oh-3.41.9-dev branch in apps/flutter/app/.fvmrc. Keep this SDK selected for OpenHarmony development; the standard Flutter SDK is a different toolchain and does not provide the OpenHarmony target.

The user environment must provide:

  • FVM 4.1.2 through the Pub cache bin directory on PATH.
  • dart through a Flutter or Dart SDK bin directory on PATH so the FVM launcher can start.
  • OHOS_SDK_HOME pointing to the OpenHarmony SDK root.
  • The selected OpenHarmony SDK toolchains directory on PATH for hdc.

Restart the terminal or IDE after changing user environment variables so new processes inherit them.

The Windows user environment used for local OpenHarmony builds should keep these values stable:

HOS_SDK_HOME=%USERPROFILE%\harmony-tools\harmonyos-sdk
OHOS_SDK_HOME=%USERPROFILE%\harmony-tools\harmonyos-sdk
DEVECO_SDK_HOME=%USERPROFILE%\harmony-tools\harmonyos-sdk

Add these directories to the user PATH:

%USERPROFILE%\harmony-tools\commandline-tools-2.0.0.2\command-line-tools\bin
%USERPROFILE%\harmony-tools\ohcommandline-tools-2.0.0.2\oh-command-line-tools\bin
%LOCALAPPDATA%\Pub\Cache\bin

The project-local OpenHarmony properties file should point at the same SDK and the FVM-selected Flutter SDK:

apps/flutter/app/ohos/local.properties
hwsdk.dir=<user-home>\\harmony-tools\\harmonyos-sdk
flutter.sdk=<repo-root>\\apps\\flutter\\app\\.fvm\\flutter_sdk

The SDK root must contain a numeric API directory with all build components. The currently validated layout is:

%USERPROFILE%\harmony-tools\harmonyos-sdk\18\ets
%USERPROFILE%\harmony-tools\harmonyos-sdk\18\js
%USERPROFILE%\harmony-tools\harmonyos-sdk\18\native
%USERPROFILE%\harmony-tools\harmonyos-sdk\18\previewer
%USERPROFILE%\harmony-tools\harmonyos-sdk\18\toolchains

Do not point this project at %USERPROFILE%\harmony-tools\openharmony-sdk\9; that older SDK does not match the current OpenHarmony API 18 project files.

The FVM-selected SDK must expose the ohos platform and the hap build command. Verify the selected SDK and DevEco environment from the Flutter app directory:

cd apps\flutter\app
fvm install --skip-pub-get
fvm flutter doctor -v
fvm flutter config

fvm flutter doctor -v must report both Flutter and OpenHarmony toolchains.

Generate the OpenHarmony application module once with the selected SDK:

cd apps\flutter\app
fvm flutter create --platforms ohos .

Build the shared Web Access bundle from the repository root:

.\.venv\Scripts\python.exe tools\build_scripts\build_flutter_web_access.py --base-href /

The remote access bundle is written to apps/web_access/build/bundle and synchronized into the native Flutter assets at:

apps/flutter/app/assets/web_access

The bundle includes a generated web_access_version.json; native launchers use that version to reuse an already materialized Web Access directory.

Build the OpenHarmony HAP with the repository script. The script invokes the same FVM-selected Flutter SDK and the OpenHarmony native toolchain:

The Rust toolchain uses the native OpenHarmony target:

rustup target add aarch64-unknown-linux-ohos

Build the HAP through the repository build script from the repository root:

.\.venv\Scripts\python.exe tools\build_scripts\build_flutter_ohos.py --enforce-lockfile

The build script stages the Rust bridge, copies the OpenHarmony Flutter engine HAR files, patches the embedding HAR for the local API 18 SDK surface, clears the unpacked ohpm embedding package, runs flutter build hap, and signs the unsigned HAP with the project OpenHarmony release signing material in:

tools/release/secrets/ohos-signing/ohos-signing.properties

Keep these OpenHarmony release signing files outside git and back them up:

tools/release/secrets/ohos-signing/operit-ohos-release-app.p12
tools/release/secrets/ohos-signing/operit-ohos-release-app.cer
tools/release/secrets/ohos-signing/operit-ohos-release-profile.p12
tools/release/secrets/ohos-signing/operit-ohos-release-profile.cer
tools/release/secrets/ohos-signing/ohos-signing.properties

The generated per-build profile files are written under:

apps/flutter/app/ohos/signing

That directory is ignored by git and should be treated as local build output.

The signed build output is copied to:

tools/release/dist/operit2-app-ohos-arm64.hap

If the Flutter command reports Can't load Kernel binary, clear stale FVM or Flutter snapshot state for this app, run fvm install --skip-pub-get from apps/flutter/app, and run the OpenHarmony build script again from the repository root.

Useful Cleanup

Remove release output:

Remove-Item -Recurse -Force tools\release\dist, tools\release\work

Remove Rust build output for the CLI:

Remove-Item -Recurse -Force apps\cli\target

Use cleanup commands only for build artifacts.