diff --git a/README.md b/README.md index 8deeba5..8170461 100644 --- a/README.md +++ b/README.md @@ -55,6 +55,7 @@ python3 -m unittest discover -s tests - [Browser builds](docs/browser-builds.md) - [Candidate transports](docs/candidate-transports.md) - [Configuration](docs/configuration.md) +- [Desktop vertical](docs/desktop-vertical.md) - [Fixture manifests](docs/fixture-manifests.md) - [Mobile browser](docs/mobile-browser.md) - [Open flow](docs/open-flow.md) diff --git a/docs/architecture.md b/docs/architecture.md index 1079f22..20b9cf3 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -47,6 +47,8 @@ is boring, and generated fixtures from AMPG open without manual proxy setup. Generated backend metadata lives in [generated browser strategy](generated/browser-strategy.md). +The first implementation path is documented in [desktop vertical](desktop-vertical.md). + ## Relationship To AMPG AMPG publishes protocol-specific site variants. AMPB opens those variants with the right diff --git a/docs/browser-builds.md b/docs/browser-builds.md index ec379d1..7a4091e 100644 --- a/docs/browser-builds.md +++ b/docs/browser-builds.md @@ -35,6 +35,33 @@ The script creates: - `/tmp/ampb-browser-build/artifacts` - `/tmp/ampb-browser-build/logs` +## Desktop Build Probe + +Desktop is the first browser proof. The probe uses the current Gecko checkout and writes +its mozconfig, object directory, caches, and logs under `/tmp`. + +Print the desktop build entrypoint help: + +```sh +sh tools/browser-desktop-build-probe.sh +``` + +Run the first desktop configure probe: + +```sh +AMPB_DESKTOP_BUILD_PROBE_MODE=configure sh tools/browser-desktop-build-probe.sh +``` + +The probe writes: + +- `/tmp/ampb-browser-build/mozconfigs/desktop-debug.mozconfig` +- `/tmp/ampb-browser-build/obj/gecko-desktop-debug` +- `/tmp/ampb-browser-build/logs/gecko-desktop-mach-help.log` +- `/tmp/ampb-browser-build/logs/gecko-desktop-mach-configure.log` + +Configure mode may install Mozilla build Python helpers such as `zstandard` into mach +virtualenvs under `/tmp/ampb-browser-build/cache/mozbuild`. + ## Source Plan Print the canonical source targets and paths: @@ -77,7 +104,8 @@ AMPB_INCLUDE_LEGACY_FIREFOX_ANDROID=1 sh tools/browser-source-sync.sh ## Android Build Probe -Run the first Android build-discovery command from the `/tmp` checkout while keeping +Android remains a first-class target, but it follows the desktop proof. Run the first +Android build-discovery command from the `/tmp` checkout while keeping Gradle, pip, Python bytecode, and Mozilla build state in `/tmp`: ```sh diff --git a/docs/desktop-vertical.md b/docs/desktop-vertical.md new file mode 100644 index 0000000..8bdaa61 --- /dev/null +++ b/docs/desktop-vertical.md @@ -0,0 +1,28 @@ +# Desktop Vertical + +> Status: draft | Updated 2026-07-07 | Applies to: AMPB desktop builders + +The first AMPB browser proof is desktop-first with mobile constraints kept in view. The +vertical is a bundled Gecko desktop runtime, AMPB-owned profile state, and a managed Tor +runtime for `.onion` browsing. Android and iOS follow the same routing and transport +contracts after the desktop path is proven. + +## Build Path + +Use the external build workspace: + +```sh +sh tools/browser-build-workspace.sh +sh tools/browser-source-sync.sh +AMPB_DESKTOP_BUILD_PROBE_MODE=configure sh tools/browser-desktop-build-probe.sh +``` + +The desktop probe keeps Gecko source, object files, downloaded toolchains, Python +virtualenvs, pip cache, and logs under `/tmp/ampb-browser-build`. + +## Transport Path + +The first transport target is Tor through an AMPB-owned Arti/Tor runtime. The desktop +vertical is not complete until AMPB can start the runtime, verify the SOCKS endpoint, and +launch the bundled browser profile without clearnet fallback. I2P and Reticulum use the +same route, consent, state, and health-check model after Tor works. diff --git a/tools/browser-desktop-build-probe.sh b/tools/browser-desktop-build-probe.sh new file mode 100644 index 0000000..b859f2b --- /dev/null +++ b/tools/browser-desktop-build-probe.sh @@ -0,0 +1,68 @@ +#!/bin/sh +set -eu + +root="${AMPB_BROWSER_BUILD_ROOT:-/tmp/ampb-browser-build}" +gecko_dir="$root/src/gecko-dev" +mode="${AMPB_DESKTOP_BUILD_PROBE_MODE:-help}" +log="$root/logs/gecko-desktop-mach-${mode}.log" +mozconfig="$root/mozconfigs/desktop-debug.mozconfig" +objdir="$root/obj/gecko-desktop-debug" + +if [ ! -d "$gecko_dir" ]; then + printf 'missing gecko checkout: %s\n' "$gecko_dir" >&2 + exit 1 +fi + +mkdir -p "$root/cache/gradle" +mkdir -p "$root/cache/mozbuild" +mkdir -p "$root/cache/pip" +mkdir -p "$root/cache/pycache" +mkdir -p "$root/logs" +mkdir -p "$root/mozconfigs" +mkdir -p "$objdir" + +cat >"$mozconfig" </dev/null 2>&1; then + continue + fi + PIP_CACHE_DIR="$root/cache/pip" "$python_bin" -m pip install 'zstandard<=0.23.0,>=0.11.1' + done +} + +case "$mode" in + help) + mach_env ./mach build --help >"$log" 2>&1 + ;; + configure) + mach_env ./mach build --help >/dev/null 2>&1 + ensure_zstandard + mach_env ./mach configure >"$log" 2>&1 + ;; + *) + printf 'unsupported AMPB_DESKTOP_BUILD_PROBE_MODE: %s\n' "$mode" >&2 + exit 2 + ;; +esac + +printf 'AMPB_DESKTOP_BUILD_PROBE status=ok mode=%s mozconfig=%s objdir=%s log=%s\n' "$mode" "$mozconfig" "$objdir" "$log" diff --git a/tools/browser-source-plan.sh b/tools/browser-source-plan.sh index 69c9716..7891e3b 100644 --- a/tools/browser-source-plan.sh +++ b/tools/browser-source-plan.sh @@ -16,4 +16,5 @@ printf 'AMPB_TOR_BROWSER_BUILD_REPO=%s\n' "$tor_build_repo" printf 'AMPB_TOR_BROWSER_BUILD_DIR=%s\n' "$root/src/tor-browser-build" printf 'AMPB_GRADLE_USER_HOME=%s\n' "$root/cache/gradle" printf 'AMPB_MOZBUILD_STATE_PATH=%s\n' "$root/cache/mozbuild" -printf 'AMPB_BUILD_LOG=%s\n' "$root/logs/gecko-android-mach-probe.log" +printf 'AMPB_DESKTOP_BUILD_LOG=%s\n' "$root/logs/gecko-desktop-mach-help.log" +printf 'AMPB_ANDROID_BUILD_LOG=%s\n' "$root/logs/gecko-android-mach-probe.log"