fix(ppa): bundle Rust toolchain for noble Cargo.lock v4 builds

Document install channels (PPA/GitHub/CDN); release skill supports
full/cli/ext modes with R2+GitHub ext uploads and manual PPA commands.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
cflmyandCursor committed 2026-09-17 10:18:50 +08:00
1 parent f068b4ab75
commit e31585842d
16 files changed
+347 -213

No files matched your search

+132 -128
View File
@@ -1,16 +1,14 @@
---
name: marqdo-release
description: >-
Run a full Marqdo product release: detect latest version and ask the user for
the next tag, update CHANGELOG/README/skills/public docs, bump Cargo versions,
sync VS Code extension on branch vscode-extension when needed, build or
trigger install assets (Windows CLI + **required Linux native/CLI zips**,
stdlib, ext, public zip, VSIX), push via origin or
https://proxy.cflmy.top/github.com/cflmy/marqdo.git, publish GitHub Release
with detailed notes, and recover from network failures via that proxy or HK
SSH jump (scripts/push-via-hk-jump.py). Use when the user asks to release,
cut a version, publish vX.Y.Z, ship a GitHub release, 发版, 发布新版本, or tag
marqdo.
Run a Marqdo product release: detect latest version and ask the user for the
next tag (or confirm mode), update CHANGELOG/README/skills/public docs, bump
Cargo and/or ext/VERSION, sync VS Code extension when needed, publish GitHub
Release assets, upload extension packs to Cloudflare R2 (ext.marqdo.com) and
GitHub, ship Ubuntu CLI via PPA (scripts/ppa-ship.sh), and print manual
commands when sudo/GPG/network steps need the user. Use when the user asks to
release, cut a version, publish vX.Y.Z, ext-only pack, PPA, 发版, 发布新版本,
or tag marqdo.
---
# Marqdo release
@@ -19,187 +17,193 @@ Canonical release playbook for **cflmy/marqdo**. Read this skill **before** tagg
## Hard rules
1. **Never invent the next version.** Detect current versions → **stop and ask the user** for the next SemVer (`X.Y.Z`). Do not proceed until they confirm.
1. **Never invent the next version.** Detect current versions → **stop and ask the user** for the next SemVer (`X.Y.Z`) and **release mode** if unclear. Do not proceed until they confirm (unless they already stated both in the same message).
2. **Never force-push** `main` / tags. **Never** `--no-verify` unless the user explicitly orders it.
3. **Never commit `vscode-extension/` on `main`** (gitignored). Extension source lives only on branch **`vscode-extension`**. See `doc/design/vscode-extension-commit.md`.
4. **Do not release from a dirty tree** (except intentional release commits you create in this flow).
5. **Tag format** is always `vX.Y.Z` matching root `Cargo.toml` `version = "X.Y.Z"`.
6. Prefer **tag push → GitHub Actions** (`.github/workflows/release.yml`) for **both** Windows and **Linux** install assets. Local packaging is fallback / verification.
7. After network errors: apply [reference.md § Proxy](reference.md). **First try** `https://proxy.cflmy.top/github.com/cflmy/marqdo.git` (this clone’s usual `origin`). Retry; do not silently skip uploads. If the reverse-proxy still drops long pushes, use **HK jump** (`hk.cflmy.de`) via `scripts/push-via-hk-jump.py` — see reference § **Proxy** / **HK SSH jump**.
8. **Do not ship a GitHub Release without the Linux extension/native zip.** Job `linux` must attach `marqdo-VER-native-x86_64-unknown-linux-gnu.zip` (and the Linux CLI bundle). Missing Linux packages = release incomplete.
9. **After publishing GitHub assets that include ext/native zips, upload the same packs to Cloudflare R2** (`https://ext.marqdo.com`) via `scripts/upload-ext-r2.py` so `marqdo ext add` prefers CDN. Credentials live only in `~/.marqdo/r2.env` / CI secrets — **never** commit. See [ext-cdn.md](../../../doc/design/ext-cdn.md).
10. **CLI and extension packs may version independently** (`ext/VERSION` / CDN `latest/VERSION` vs `Cargo.toml`). Ext-only releases use tag `ext-vX.Y.Z` (or attach assets without bumping CLI).
5. **Tag format:** CLI/full → `vX.Y.Z` matching root `Cargo.toml`. Ext-only → `ext-vX.Y.Z` matching `ext/VERSION` (Cargo may stay unchanged).
6. Prefer **tag push → GitHub Actions** (`.github/workflows/release.yml`) for Windows/Linux install assets. Local packaging is fallback / verification.
7. After network errors: apply [reference.md § Proxy](reference.md). **First try** `https://proxy.cflmy.top/github.com/cflmy/marqdo.git`. Retry; do not silently skip uploads. If needed: **HK jump** (`scripts/push-via-hk-jump.py`).
8. **Do not ship a full GitHub Release without the Linux extension/native zip** when the mode includes ext packs. Missing Linux packages = incomplete for that mode.
9. **Extension packs always publish to both** Cloudflare R2 (`https://ext.marqdo.com` via `scripts/upload-ext-r2.py`) **and** GitHub (Release assets / `ext-v*` tag). Credentials only in `~/.marqdo/r2.env` / CI — **never** commit. See [ext-cdn.md](../../../doc/design/ext-cdn.md).
10. **CLI Ubuntu package = PPA** (`ppa:cflmy/marqdo`) via `./scripts/ppa-ship.sh` / `ppa-build-source.sh`. GitHub zips remain for Windows and non-apt Linux.
11. **When a step needs the user** (sudo password, GPG passphrase, Launchpad UI, interactive `dput`): **stop, state what failed, and give the exact commands** to run in their terminal. Do not pretend the step succeeded.
## Defaults (after version is confirmed)
## Release modes
Unless the user overrides, apply these automatically — **do not re-ask**:
Ask (or take from user message) which mode:
| Mode | Bumps | Git tag | GitHub assets | R2 CDN | Ubuntu PPA |
|------|-------|---------|---------------|--------|------------|
| **full** (default) | `Cargo.toml` + `ext/VERSION` (same SemVer) | `vX.Y.Z` | CLI + ext + native + VSIX + … | yes | yes |
| **cli** | `Cargo.toml` only | `vX.Y.Z` | CLI (+ optional attach prior ext) | no (unless user asks) | yes |
| **ext** | `ext/VERSION` only | `ext-vX.Y.Z` (or attach to latest CLI release) | ext.zip + native-*.zip | **required** | no |
Defaults after version+mode confirmed — **do not re-ask**:
| Setting | Default |
|---------|---------|
| Sync / bump `vscode-extension` to same `VER` | **yes** |
| Push `main`, create annotated tag, push tag immediately (trigger CI) | **yes** |
| Release notes language | **中英双语** (Chinese first, then English section, or paired ZH/EN under each heading) |
| Skip VSIX | **no** |
| Docs-only release | **no** (full asset pipeline via CI) |
| Sync / bump `vscode-extension` to same `VER` | **yes** for full/cli; **no** for ext-only |
| Push `main`, create annotated tag, push tag (trigger CI) | **yes** for full/cli |
| Ext packs → R2 **and** GitHub | **yes** whenever ext ships |
| Ubuntu PPA upload after CLI tag | **yes** for full/cli |
| Release notes language | **中英双语** |
| Deploy gh-pages after release | **no** (only if user asks) |
Phase 0 asks **only** for the next version (and optional overrides). Example ask:
Phase 0 ask example:
> 当前最新是 **vA.B.C**。请指定下一个版本号(如 `0.3.2`)。其余按默认:同步扩展、立刻打 tag 发布、中英双语说明。
> 当前最新 CLI **vA.B.C**,扩展包 **E.F.G**。请指定下一个版本号与模式(`full` / `cli` / `ext`,如 `1.0.3 full`)。
## Phase 0 — Detect versions (mandatory stop)
Run in repo root (parallel OK):
```bash
python3 .cursor/skills/marqdo-release/scripts/detect_version.py
# or: rg / git tag / gh release list — see reference.md
```
Report briefly, then **ask only for the next SemVer** (defaults above). Wait for confirmation. Normalize to `VER=X.Y.Z` and `TAG=vX.Y.Z`.
Report briefly, then **ask for SemVer + mode** (unless already given). Normalize `VER` / `TAG`.
## Phase 1 — Preflight
Copy and track:
```
Release progress:
- [ ] Phase 0: version confirmed by user (TAG=…)
- [ ] Phase 0: version + mode confirmed
- [ ] Phase 1: preflight green
- [ ] Phase 2: docs + version bumps committed
- [ ] Phase 3: extension branch (if needed)
- [ ] Phase 3: extension branch (full/cli)
- [ ] Phase 4: main pushed; tag created & pushed
- [ ] Phase 5: CI / assets / release notes verified
- [ ] Phase 6: post-release checks
- [ ] Phase 5: CI / GitHub assets / notes
- [ ] Phase 6: R2 upload (if ext ships)
- [ ] Phase 7: Ubuntu PPA (full/cli)
- [ ] Phase 8: post-release checks
```
Checks:
1. `git status` clean or only release WIP you control.
2. `git checkout main && git pull --ff-only origin main`.
3. Quick gate: `cargo test --test gold structure_hello` (and any release-critical tests the user named). Full gold suite if time allows.
4. `CHANGELOG.md` has meaningful **Unreleased** notes; if empty, draft from `git log vLAST..HEAD --oneline` and confirm with user.
5. Confirm no secrets in the commit (`*.env`, credentials).
Checks: clean tree; `main` ff-only; smoke tests; CHANGELOG Unreleased; no secrets.
## Phase 2 — Docs & version bumps (main)
Bump **in lockstep**:
| File | Change |
|------|--------|
| `Cargo.toml` | `version = "VER"` |
| `crates/marqdo-wasm/Cargo.toml` | same `VER` |
| `CHANGELOG.md` | Move `## Unreleased` → `## vVER — YYYY-MM-DD`; leave fresh empty `## Unreleased` |
| `README.md` | 「现状 / 如何使用最新」version strings, checkout tag, release URL |
| `.cursor/skills/marqdo/SKILL.md` | Version-sensitive bullets if any (WASM/web status); keep rules accurate |
| `public/**` | User-facing tutorials if features shipped (welcome, features/*, extensions). Prefer small factual updates over rewrites |
| `doc/roadmap/*.md` | Mark shipped waves done if this release closes them |
| `.github/workflows/release.yml` | Update **Highlights** body template to this release (CI still uses hardcoded blurb—keep in sync) |
Public HTML: regenerate before packaging / pages deploy:
| File | full | cli | ext |
|------|------|-----|-----|
| `Cargo.toml` + `crates/marqdo-wasm/Cargo.toml` | bump | bump | — |
| `ext/VERSION` | bump | — | bump |
| `CHANGELOG.md` | `## vVER` | `## vVER` | `## Ext pack vVER` |
| `README.md` / `public/**` install + download table | update | update | update ext notes |
| `.cursor/skills/marqdo/SKILL.md` | if surface changed | same | rare |
| `.github/workflows/release.yml` Highlights stub | yes | yes | — |
```bash
./scripts/build-public.sh
# outputs under public/ (gitignored HTML); used by release zip / gh-pages
./scripts/build-public.sh # when public/ sources changed
```
Commit on `main` (HEREDOC message), e.g.:
```text
release: vVER — <one-line highlight>
EOF
```
Push `main` (this repo’s `origin` is usually the reverse proxy):
Commit + push `main` (proxy origin). On push failure → reference § Proxy; if still blocked, **print** for the user:
```bash
# origin typically: https://proxy.cflmy.top/github.com/cflmy/marqdo.git
git push origin main
# one-shot if origin still points at github.com:
git push https://proxy.cflmy.top/github.com/cflmy/marqdo.git HEAD:main
# or: python3 scripts/push-via-hk-jump.py
```
If that times out: [reference § HK SSH jump](reference.md).
## Phase 3 — VS Code / Cursor extension (full/cli only)
## Phase 3 — VS Code / Cursor extension
Default: bump `vscode-extension` package.json to `VER`, compile, push branch `vscode-extension`, return to `main`.
**Default: always** bump extension to `VER` on branch `vscode-extension` (skip only if user said so).
1. `git fetch origin vscode-extension`
2. Work on `vscode-extension` branch (not main):
- Bump `vscode-extension/package.json` `version` to `VER`.
- Update `engines` / CLI version hints in extension README if present.
- `npm ci && npm run compile`
3. Commit & `git push origin vscode-extension`.
4. Return to `main`. **Do not** add `vscode-extension/` to main.
## Phase 4 — Tag & trigger CI
## Phase 4 — Tag & trigger CI (full/cli)
```bash
git tag -a "TAG" -m "TAG"
git push origin "TAG"
git tag -a "vVER" -m "vVER"
git push origin "vVER"
```
This runs `.github/workflows/release.yml`:
Ext-only:
- **windows** — CLI exe/zip, stdlib zip, ext zip, source zip, public zip, VSIX, Windows native zip
- **linux** (`needs: windows`) — **required** Linux native plugins zip + Linux CLI bundle (`ext/` + `native/*.so`)
```bash
git tag -a "ext-vVER" -m "ext-vVER"
git push origin "ext-vVER"
```
If tag push fails: [reference.md § Proxy](reference.md) (`proxy.cflmy.top` first), retry once; then HK jump.
(or build zips locally / via workflow and `gh release upload`).
## Phase 5 — Release notes & assets
If tag push needs the user:
1. Wait for Actions success: `gh run list --workflow=Release --limit 3` / open the run URL. **Both** `windows` and `linux` jobs must be green.
2. Ensure GitHub Release for `TAG` exists with assets (workflow uses `softprops/action-gh-release`).
3. Confirm Linux assets exist: `marqdo-VER-native-x86_64-unknown-linux-gnu.zip` and `marqdo-VER-x86_64-unknown-linux-gnu.zip`. If missing, do **not** call the release done — re-run / upload.
4. **Rewrite release body** (workflow body is a stub) with **中英双语** — see [reference.md § Notes template](reference.md). `gh release edit TAG --notes-file …`.
4. Include: Highlights, Breaking, Install (`ext add`, plugins build), Downloads table, WASM (`marqdo wasm build`), links to CHANGELOG/README, extension branch note.
5. Optional Linux local extras (not required if CI green): `marqdo wasm build` smoke; document in notes that wasm is built from source via CLI.
```bash
git push https://proxy.cflmy.top/github.com/cflmy/marqdo.git vVER
```
Local Windows fallback: `scripts/release-full.ps1 -Tag TAG -Upload` (see script header).
## Phase 5 — GitHub Release notes & assets
## Phase 6 — Post-release
1. Wait for Actions (full/cli): both `windows` and `linux` green when ext natives required.
2. Rewrite release body 中英双语 — [reference.md § Notes](reference.md).
3. Confirm Linux `marqdo-VER-native-x86_64-unknown-linux-gnu.zip` when mode ships ext.
1. `gh release view TAG` — confirm assets + notes.
2. **Upload extension packs to R2 CDN** (required when shipping ext/native zips):
```bash
# credentials: ~/.marqdo/r2.env (never commit) — see doc/design/ext-cdn.md
python3 -m pip install --user boto3
python3 scripts/upload-ext-r2.py --version VER --from-dir dist/
# verify: curl -fsS https://ext.marqdo.com/latest/VERSION
```
Prefer downloading CI artifacts into `dist/` if local build skipped Linux/Windows natives.
3. `git status` clean; `main` synced.
4. Tell user: release URL `https://github.com/cflmy/marqdo/releases/tag/TAG` **and** CDN `https://ext.marqdo.com/vVER/`.
5. Optional: `./scripts/deploy-public.ps1` / pages workflow if user wants user-site refresh.
6. Open fresh `## Unreleased` already done in Phase 2.
## Phase 6 — Extension CDN (R2) — required when ext ships
## Extension-only release (no CLI bump)
```bash
# credentials: ~/.marqdo/r2.env (never commit)
python3 scripts/upload-ext-r2.py --version VER --from-dir dist/
curl -fsS https://ext.marqdo.com/latest/VERSION
```
When only `ext/` / native plugins change:
Also ensure the **same** zips are on GitHub (`vVER` or `ext-vVER`). If R2 credentials missing, **tell the user**:
1. Ask user for **ext pack** SemVer (may differ from `Cargo.toml`).
2. Bump `ext/VERSION`; update CHANGELOG Unreleased → `## Ext pack vVER`.
```bash
# put keys in ~/.marqdo/r2.env then:
python3 scripts/upload-ext-r2.py --version VER --from-dir dist/
```
## Phase 7 — Ubuntu PPA (full/cli)
Linux CLI for apt users. After `Cargo.toml` is at `VER` and `debian/changelog` has a matching `VER-1ppaN` stanza:
```bash
./scripts/ppa-ship.sh noble
```
Packaging notes / noble Cargo.lock v4: [ubuntu-ppa.md](../../../doc/design/ubuntu-ppa.md).
**If the agent cannot sudo / sign / dput**, print exactly:
```bash
cd ~/work/marqdo
./scripts/ppa-ship.sh noble
# or build then upload:
./scripts/ppa-build-source.sh noble
dput ppa:cflmy/marqdo ../build-area/marqdo_*~noble_source.changes
```
Watch: https://launchpad.net/~cflmy/+archive/ubuntu/marqdo/+builds
On Launchpad failure: read the build log, fix `debian/` or bundle script, bump `1ppaN`, re-upload. Tell the user the new `dput` command.
## Phase 8 — Post-release
1. `gh release view TAG` — assets + notes.
2. CDN `https://ext.marqdo.com/vVER/` (if ext shipped).
3. PPA build green (if cli shipped).
4. Tell user URLs: GitHub release, CDN, PPA install one-liner.
5. Optional gh-pages only if asked.
## Extension-only release (mode=ext)
1. User confirms **ext** SemVer (may differ from CLI).
2. Bump `ext/VERSION`; CHANGELOG → `## Ext pack vVER`.
3. Build/package `marqdo-VER-ext.zip` + `marqdo-VER-native-*.zip` (CI or local).
4. Upload to **R2** (`upload-ext-r2.py`) **and** GitHub (tag `ext-vVER` or attach to latest CLI release).
5. Do **not** retag CLI `vX.Y.Z` unless Cargo also bumps.
6. Detail: [ext-cdn.md](../../../doc/design/ext-cdn.md).
4. Upload to **R2 and GitHub** (required both).
5. Do **not** retag CLI / do **not** PPA unless user also asked for cli.
## Failure matrix (short)
| Failure | Action |
|---------|--------|
| `gh` / git TLS or Clash `7890` refused | Unset bad proxy; `required_permissions: ["all"]`; see [reference § Proxy](reference.md) |
| GitHub blocked | **`origin` via proxy.cflmy.top** (see below), then HK jump |
| Tag exists | Stop; ask user to bump or delete tag (no force on shared tags without explicit order) |
| CI red | Fix on main, move tag only if user explicitly allows delete+re-push tag |
| VSIX missing | Fetch `vscode-extension`, build locally, `gh release upload TAG dist/*.vsix` |
| Linux native/CLI zip missing | Incomplete release — fix `linux` job or `gh release upload`; do not skip |
| `gh` / git TLS or Clash `7890` refused | Unset bad proxy; see [reference § Proxy](reference.md) |
| GitHub blocked | proxy.cflmy.top, then HK jump; **print commands** if agent cannot push |
| Tag exists | Stop; ask user |
| CI red | Fix on main; retag only if user allows |
| R2 upload fails | Print `upload-ext-r2.py` command; do not skip silently |
| PPA / sudo / GPG | Print `./scripts/ppa-ship.sh noble` (or `dput …`); do not skip silently |
| Launchpad `Cargo.lock` v4 / old cargo | Ensure bundled `third_party/rust` via current `ppa-build-source.sh`; bump `1ppaN` |
| Linux native zip missing (full/ext) | Incomplete — fix linux job or upload |
## Do not
- Ship without user-confirmed version.
- Hardcode release highlights only in Actions YAML and forget CHANGELOG.
- Commit `target/`, `dist/`, `*.wasm`, or `public/**/*.html` unless project policy changes.
- Ship without user-confirmed version (and mode when ambiguous).
- Ship ext packs to only one of R2 / GitHub.
- Call a full/cli release done without attempting PPA **or** giving the user the PPA commands.
- Commit `target/`, `dist/`, `*.wasm`, `third_party/rust/`, or `public/**/*.html` unless policy changes.
- Merge extension tree into `main`.
+1 -1
View File
@@ -19,7 +19,7 @@ Canonical design (repo): [`markdown-mapping-v0.3.md`](../../doc/design/markdown-
**Authoring / library craft** (GFM-first, no json glue, how to develop Marqdo): use **[marqdo-dev](../marqdo-dev/SKILL.md)** whenever writing or refactoring `.mq.md`, `lib/*`, or `ext/*`.
**Product release** (tag, CHANGELOG, README, public docs, VSIX, GitHub assets): use [marqdo-release](../marqdo-release/SKILL.md) — detect latest version, **ask the user for the next SemVer**, then follow that playbook. Do not invent a version number.
**Product release** (tag, CHANGELOG, README, public docs, VSIX, GitHub assets, **ext → R2+GitHub**, **CLI → Ubuntu PPA**): use [marqdo-release](../marqdo-release/SKILL.md) — detect versions, **ask for SemVer + mode (`full` / `cli` / `ext`)**, then follow that playbook. Ext-only releases are allowed. If sudo/GPG/PPA steps need the user, print the exact commands.
## Hard rules (do not violate)
+4
View File
@@ -78,5 +78,9 @@ plugins/*/tmp/
# Go web plugin c-shared build output (./scripts/build-web-plugin.sh)
/plugins/web/build/
# PPA build: bundled Rust toolchain (packed into .orig by ppa-build-source.sh only)
/third_party/rust/
/third_party/
# ephemeral sqlite / test artifacts
tests/ext/:memory:
+2
View File
@@ -9,9 +9,11 @@
### Fixed
- `ext/` 导入默认搜索 `~/.marqdo/ext`(与 `marqdo ext add` 安装根一致),无需再手动 `export MARQDO_EXT`。
- PPA/noble:捆绑 `third_party/rust`(现代 cargo)以构建 Cargo.lock v4;修复首次 Launchpad 构建失败(distro cargo 1.75)。
### Changed
- 允许 **CLI 与扩展包分开发版**:扩展包 SemVer 可与 `Cargo.toml` 不同(`MARQDO_EXT_VERSION` / `ext/VERSION` / CDN latest)。
- 用户文档(README / `public/00-欢迎` / `features/05-扩展`)标明安装渠道:Ubuntu PPA、GitHub Releases、源码;扩展走 CDN。
## v1.0.2 — 2026-09-16
+12 -2
View File
@@ -122,6 +122,16 @@ marqdo catalog public -o .marqdo
### 如何使用最新 Marqdo(v1.0.2)
**安装解释器(任选其一)**
| 方式 | 适用 | 命令 / 链接 |
|------|------|-------------|
| **Ubuntu PPA** | Ubuntu 24.04+(`noble` 等) | `sudo add-apt-repository ppa:cflmy/marqdo && sudo apt update && sudo apt install marqdo` |
| **GitHub Releases** | Windows / Linux 预编译 zip | https://github.com/cflmy/marqdo/releases |
| **源码** | 需本机 Rust | 见下方 `git clone` + `cargo build --release` |
**安装官方扩展**(与 CLI 可分开发版):`marqdo ext add …` 默认下载顺序为 **CDN** [`https://ext.marqdo.com`](https://ext.marqdo.com) → GitHub Releases → [`proxy.cflmy.top`](https://proxy.cflmy.top) 镜像。
```bash
# 1) 源码安装(跟 tag 或 main)
git clone https://github.com/cflmy/marqdo.git && cd marqdo
@@ -138,7 +148,7 @@ marqdo view public --no-open
marqdo debug public --no-open
marqdo catalog public -o .marqdo
# 3) 安装官方扩展(Release 用户:无需本机 Rust/Go)
# 3) 安装官方扩展(Release / CDN 用户:无需本机 Rust/Go)
marqdo ext add web # 或:网页 — 自动下载 L1 + 预编译 native(Go libweb)
marqdo ext add agent # 或:智能体
marqdo ext add quantum # 或:量子
@@ -171,7 +181,7 @@ cargo run -- view output public -o public
powershell -File ./scripts/build-public.ps1
```
**发布包(GitHub Releases)**:单独二进制 **已内置**官方 `lib/`(`import …:lib/…` 可直接导入)。仍提供带 `lib/` 的 zip 便于覆盖或离线分发。**扩展库**用 `marqdo ext add …` 安装(见 [CHANGELOG](CHANGELOG.md) 与 [ext-cli.md](doc/design/ext-cli.md));原生 `.so`/`.dll` 需本地编译或从带 `native/` 的安装目录解析。
**发布包**:GitHub Releases 的单独二进制 **已内置**官方 `lib/`。Ubuntu 用户优先 **PPA** 装 CLI。**扩展库**用 `marqdo ext add …`(CDN → GitHub);设计见 [ext-cdn.md](doc/design/ext-cdn.md) · [ubuntu-ppa.md](doc/design/ubuntu-ppa.md) · [ext-cli.md](doc/design/ext-cli.md)。
文档:用户站 [public/](public/) · 设计 [doc/](doc/) · OKF / catalog [catalog-cli.md](doc/design/catalog-cli.md) · 调试 [view-debug.md](doc/design/view-debug.md) · 变更 [CHANGELOG.md](CHANGELOG.md)
---
+9 -1
View File
@@ -10,5 +10,13 @@ Official language extensions are not bundled. After install:
Extension packs download from https://ext.marqdo.com (then GitHub / proxy).
Install this package from:
sudo add-apt-repository ppa:cflmy/marqdo
sudo apt update
sudo apt install marqdo
Also available: GitHub Releases (Windows/Linux zips) and building from source.
Documentation: https://github.com/cflmy/marqdo
PPA packaging notes: doc/design/ubuntu-ppa.md in the upstream repository.
PPA notes: doc/design/ubuntu-ppa.md in the upstream repository.
+8
View File
@@ -1,3 +1,11 @@
marqdo (1.0.2-1ppa2) noble; urgency=medium
* Bundle Rust toolchain in orig (third_party/rust) so noble can build
Cargo.lock v4 offline; drop distro cargo/rustc Build-Depends.
* Architecture: amd64 (bundled toolchain is x86_64).
-- cflmy <pingan@cflmy.cn> Thu, 17 Sep 2026 10:20:00 +0800
marqdo (1.0.2-1ppa1) noble; urgency=medium
* Initial Ubuntu PPA packaging for Marqdo 1.0.2.
+6 -3
View File
@@ -4,8 +4,7 @@ Priority: optional
Maintainer: cflmy <pingan@cflmy.cn>
Build-Depends:
debhelper-compat (= 13),
cargo,
rustc,
build-essential,
pkg-config,
libssl-dev,
ca-certificates
@@ -16,7 +15,7 @@ Vcs-Browser: https://github.com/cflmy/marqdo
Rules-Requires-Root: no
Package: marqdo
Architecture: any
Architecture: amd64
Depends: ${shlibs:Depends}, ${misc:Depends}, ca-certificates
Description: Markdown markers as an interpreted programming language
Marqdo treats Markdown markers as executable syntax (code / return /
@@ -24,3 +23,7 @@ Description: Markdown markers as an interpreted programming language
.
Official extensions (web, quantum, …) are installed separately via
"marqdo ext add" and download from https://ext.marqdo.com .
.
Launchpad builds use a bundled Rust toolchain under third_party/rust
(Ubuntu noble cargo is too old for Cargo.lock v4). Rebuilds on newer
series may use distro rustc if cargo ≥ 1.78.
+19 -6
View File
@@ -1,28 +1,41 @@
#!/usr/bin/make -f
export DH_VERBOSE = 1
# Offline builds on Launchpad: use vendored crates when present.
# Offline builds on Launchpad: vendored crates + optional bundled Rust toolchain.
export CARGO_HOME = $(CURDIR)/debian/cargo_home
export CARGO_NET_OFFLINE = true
# Noble (and older) distro cargo cannot read Cargo.lock v4 / modern crates.
# Prefer third_party/rust from the orig tarball when present (see ppa-build-source.sh).
BUNDLED_RUST = $(CURDIR)/third_party/rust
ifneq ($(wildcard $(BUNDLED_RUST)/bin/cargo),)
export PATH := $(BUNDLED_RUST)/bin:$(PATH)
endif
%:
dh $@
override_dh_auto_configure:
mkdir -p debian/cargo_home
@if [ -x "$(BUNDLED_RUST)/bin/cargo" ]; then \
echo "Using bundled Rust: $$($(BUNDLED_RUST)/bin/rustc --version)"; \
else \
echo "Using system Rust: $$(rustc --version 2>/dev/null || echo missing)"; \
fi
@if [ -f "$(CURDIR)/.cargo/config.toml" ] || [ -d "$(CURDIR)/vendor" ]; then \
echo "Using vendored Cargo dependencies"; \
else \
echo "WARNING: no vendor/ — online cargo fetch required (not for Launchpad)"; \
export CARGO_NET_OFFLINE=false; \
fi
override_dh_auto_build:
mkdir -p debian/cargo_home
@command -v cargo >/dev/null || { echo "error: cargo not found (bundle third_party/rust or install rustc/cargo)" >&2; exit 1; }
if [ -d "$(CURDIR)/vendor" ]; then \
CARGO_NET_OFFLINE=true cargo build --release --locked --offline; \
CARGO_NET_OFFLINE=true cargo build --release --locked --offline \
-p marqdo; \
else \
cargo build --release --locked; \
cargo build --release --locked -p marqdo; \
fi
override_dh_auto_test:
@@ -36,5 +49,5 @@ override_dh_auto_install:
override_dh_auto_clean:
dh_auto_clean
rm -rf debian/cargo_home
# keep vendor/ if present (part of source package)
cargo clean || true
# keep vendor/ and third_party/rust (part of source package)
-cargo clean
+28 -40
View File
@@ -2,10 +2,10 @@
| | |
|---|---|
| Status | **Scaffold** — local `debian/` ready; first upload needs Launchpad PPA + vendored crates |
| Status | **Active** — `ppa:cflmy/marqdo`; noble builds need bundled Rust (Cargo.lock v4) |
| Maintainer | cflmy \<pingan@cflmy.cn\> |
| GPG | `505943294D04C803` (fingerprint `52A1…C803`) |
| Suggested PPA | `ppa:cflmy/marqdo` |
| PPA | `ppa:cflmy/marqdo` |
## Goal
@@ -19,77 +19,65 @@ sudo apt install marqdo
CLI and extension packs stay independent: the `.deb` ships the **interpreter**; `marqdo ext add …` still pulls from **https://ext.marqdo.com** (then GitHub / proxy).
## Why bundled Rust?
Ubuntu **noble** ships cargo/rustc **1.75**, which cannot parse **Cargo.lock version 4** (`lock file version 4 requires -Znext-lockfile-bump`). Launchpad builders also have **no network**, so `ppa-build-source.sh` vendors crates **and** installs a modern toolchain into `third_party/rust` inside the `.orig.tar.xz`. `debian/rules` prefers that toolchain over distro cargo.
## One-time Launchpad setup
1. Create PPA: https://launchpad.net/~cflmy/+activate-ppa → name e.g. `marqdo`
2. OpenPGP key already on Launchpad (done)
3. Sign Ubuntu Code of Conduct if Launchpad asks
4. On the build machine:
4. Enable the Ubuntu **series** you upload for (e.g. noble) under PPA → Change details
5. On the build machine:
```bash
sudo apt install build-essential debhelper devscripts dput lintian \
dh-cargo cargo rustc pkg-config
dpkg-dev quilt cargo rustc pkg-config curl xz-utils
```
## Package layout
Debian packaging lives under repo-root `debian/` (this tree).
| File | Role |
|------|------|
| `debian/control` | Package metadata / deps |
| `debian/changelog` | Upload revisions (`dch`) |
| `debian/rules` | `dh` + cargo build |
| `debian/copyright` | Apache-2.0 |
| `debian/source/format` | `3.0 (quilt)` |
| `debian/watch` | Optional upstream tarball watch |
| `scripts/ppa-build-source.sh` | Vendor + `debuild -S` helper |
| `debian/control` | Metadata (amd64; no distro cargo BD) |
| `debian/changelog` | Upload revisions (`1ppaN`) |
| `debian/rules` | `dh` + bundled/system cargo build |
| `scripts/ppa-build-source.sh` | Vendor + bundle Rust + `debuild -S` |
| `scripts/ppa-ship.sh` | apt deps + build + `dput` |
## Versioning
- Upstream SemVer: `Cargo.toml` / git tag `vX.Y.Z`
- Debian revision: `X.Y.Z-1ppa1~SERIES` (SERIES = `noble`, `jammy`, …)
- **Ext pack** SemVer (`ext/VERSION`) is **not** the deb version; bump deb only when CLI/stdlib packaging changes.
- Debian revision: `X.Y.Z-1ppaN~SERIES` (SERIES = `noble`, …) — bump `1ppaN` on packaging-only reuploads
- **Ext pack** SemVer (`ext/VERSION`) is **not** the deb version
## One-shot (recommended)
In a normal terminal (sudo password + GPG passphrase when prompted):
```bash
cd ~/work/marqdo
./scripts/ppa-ship.sh noble # install tools → debuild -S → dput
# ./scripts/ppa-ship.sh resolute # if PPA enabled that series
# ./scripts/ppa-ship.sh noble -n # build only, no upload
./scripts/ppa-ship.sh noble # tools → debuild -S → dput
./scripts/ppa-ship.sh noble -n # build only
```
`sudo ./scripts/ppa-ship.sh …` is OK: apt runs as root; build/sign/upload drop to `$SUDO_USER` so GPG still works.
## Build source package only
If automation cannot enter sudo/GPG, tell the user these commands (do not invent alternatives):
```bash
./scripts/ppa-build-source.sh noble
# → ../build-area/marqdo_X.Y.Z-1ppa1~noble_source.changes
dput ppa:cflmy/marqdo ../build-area/marqdo_*_source.changes
dput ppa:cflmy/marqdo ../build-area/marqdo_*~noble_source.changes
```
The build script vendors Cargo crates into `vendor/` (Launchpad builders have **no network**).
Watch: https://launchpad.net/~cflmy/+archive/ubuntu/marqdo/+builds
Wait for https://launchpad.net/~cflmy/+archive/ubuntu/marqdo/+builds
## Failure notes
## Series strategy
Start with **one** series you use daily (e.g. `noble` 24.04 or `resolute` 26.04). Copy the changelog stanza and rebuild per series, or use `backportpackage` later.
| Symptom | Fix |
|---------|-----|
| `lock file version 4 requires -Znext-lockfile-bump` | Rebuild with current `ppa-build-source.sh` (bundles Rust); bump `1ppaN` |
| Same version rejected by Launchpad | Bump `debian/changelog` (`1ppa2`, …) |
| Wrong series | Enable series on PPA; rebuild with that series name |
## Out of scope (v1 deb)
- Shipping `ext/native/*.so` inside the deb (use CDN `ext add`)
- WASM / VSIX
- Multi-arch cross builds beyond amd64
## Checklist for first upload
- [ ] PPA `marqdo` exists under `~cflmy`
- [ ] `./scripts/ppa-build-source.sh <series>` succeeds
- [ ] `lintian` on `.changes` is acceptable
- [ ] `dput` accepted; amd64 build green on Launchpad
- [ ] Fresh VM: `add-apt-repository` + `apt install marqdo` + `marqdo version`
- WASM / VSIX / non-amd64
+19
View File
@@ -13,6 +13,25 @@ AI already prefers Markdown-shaped output. The idea was: why keep docs and code
The language is still young: structure markers, bilingual core names (`print` / `打印`, …), importable stdlibs (see [`stdlib/`](stdlib/) on this site), local `view`, and static export. Contribute on [GitHub](https://github.com/cflmy/marqdo).
## Install
Pick one way to get the CLI:
| Method | Notes |
|--------|-------|
| Ubuntu PPA | `sudo add-apt-repository ppa:cflmy/marqdo` then `sudo apt install marqdo` |
| GitHub Releases | Prebuilt Windows / Linux zips at [releases](https://github.com/cflmy/marqdo/releases) |
| From source | `cargo build --release` (needs Rust) |
Official extensions version independently of the CLI:
```text
marqdo ext add web
marqdo ext add quantum
```
`ext add` tries CDN https://ext.marqdo.com first, then GitHub, then the proxy mirror. See [`features/05-extensions.mq.md`](features/05-extensions.mq.md).
中文文档请看同目录的 [`00-欢迎.mq.md`](00-欢迎.mq.md)(叙述与内置均用中文)。
A small function to say hello:
+19
View File
@@ -13,6 +13,25 @@ AI 偏爱 Markdown结构的输出。作者的念头是:何必再把文档和
语言仍在起步:结构标记、中英内核双名(`打印` / `print` …)、可导入的标准库(见本站 [`stdlib/`](stdlib/))、本地 `view` 与静态导出。欢迎到 [GitHub](https://github.com/cflmy/marqdo) 一起做。
## 安装
解释器(CLI)任选其一:
| 方式 | 说明 |
|------|------|
| Ubuntu PPA | `sudo add-apt-repository ppa:cflmy/marqdo` 后 `sudo apt install marqdo` |
| GitHub Releases | [releases](https://github.com/cflmy/marqdo/releases) 下载 Windows / Linux 预编译包 |
| 源码 | `cargo build --release`(需本机 Rust) |
官方扩展与 CLI 可分开更新。安装扩展:
```text
marqdo ext add web
marqdo ext add quantum
```
`ext add` 下载顺序:CDN https://ext.marqdo.com → GitHub → proxy 镜像。详见本站 [`features/05-扩展.mq.md`](features/05-扩展.mq.md)。
English docs: [`00-welcome.mq.md`](00-welcome.mq.md) (English prose and English builtins).
用一个小函数打个招呼:
+7 -3
View File
@@ -5,7 +5,7 @@ description: Optional packages — not stdlib
# main
ext/ holds official optional extensions. They are not part of lib/. Resolve via MARQDO_EXT, ./ext, or ext/ next to the binary.
ext/ holds official optional extensions. They are not part of lib/. Resolve via `~/.marqdo/ext`, MARQDO_EXT, ./ext, or ext/ next to the binary.
Install (v0.2+):
@@ -15,14 +15,18 @@ marqdo ext add llm
marqdo ext add agent
marqdo ext add web
marqdo ext add quantum
marqdo ext add linalg
```
For packages with a native plugin, build first then add:
`ext add` downloads L1 sources and prebuilt natives when available. Order: CDN https://ext.marqdo.com → GitHub Releases → proxy mirror. Pack SemVer is `ext/VERSION` and may differ from the CLI.
Rebuild natives locally only when developing plugins:
```text
cargo build --release -p marqdo_plugin_agent
cargo build --release -p marqdo_plugin_web
cargo build --release -p marqdo_plugin_quantum
cargo build --release -p marqdo_plugin_linalg
bash ./scripts/build-web-plugin.sh
marqdo ext add agent
marqdo ext add web
marqdo ext add quantum
+7 -3
View File
@@ -5,7 +5,7 @@ description: 可选包 — 不是标准库
# main
ext/ 存放官方可选扩展,不属于 lib/。解析顺序:MARQDO_EXT、./ext、或可执行文件旁的 ext/。
ext/ 存放官方可选扩展,不属于 lib/。解析顺序:`~/.marqdo/ext`、MARQDO_EXT、./ext、或可执行文件旁的 ext/。
安装(v0.2+):
@@ -15,14 +15,18 @@ marqdo ext add llm
marqdo ext add agent
marqdo ext add web
marqdo ext add quantum
marqdo ext add linalg
```
带原生插件的包需先编译再 add:
`ext add` 会下载 L1 与预编译 native(若有)。下载顺序:CDN https://ext.marqdo.com → GitHub Releases → proxy 镜像。扩展包版本见 `ext/VERSION`,可与 CLI 分开发版。
带原生插件的包若需本地重编:
```text
cargo build --release -p marqdo_plugin_agent
cargo build --release -p marqdo_plugin_web
cargo build --release -p marqdo_plugin_quantum
cargo build --release -p marqdo_plugin_linalg
bash ./scripts/build-web-plugin.sh
marqdo ext add agent
marqdo ext add web
marqdo ext add quantum
+65 -13
View File
@@ -2,6 +2,12 @@
# Build a signed Ubuntu *source* package for Launchpad PPA.
# Usage: ./scripts/ppa-build-source.sh [series]
# Example: ./scripts/ppa-build-source.sh noble
#
# Launchpad builders have no network and noble's cargo (1.75) cannot read
# Cargo.lock v4. This script therefore:
# 1) cargo vendor → vendor/
# 2) installs a modern Rust toolchain into third_party/rust (cached)
# 3) packs both into the .orig.tar.xz for offline debuild on Launchpad
set -euo pipefail
SERIES="${1:-noble}"
@@ -12,16 +18,39 @@ need() { command -v "$1" >/dev/null || { echo "missing tool: $1 (sudo apt instal
need cargo cargo
need debuild devscripts
need dpkg-parsechangelog dpkg-dev
need curl curl
need tar tar
need xz xz-utils
VER="$(sed -n 's/^version = "\(.*\)"/\1/p' Cargo.toml | head -1)"
DEB_VER="${VER}-1ppa1~${SERIES}"
# Debian revision comes from debian/changelog (e.g. 1.0.2-1ppa2); we append ~series.
CHG_VER="$(dpkg-parsechangelog -l debian/changelog -S Version)"
# Strip any previous ~series suffix from changelog version
BASE_DEB_VER="${CHG_VER%%~*}"
# If changelog still has old upstream, prefer Cargo VER for the upstream part
if [[ "$BASE_DEB_VER" != "$VER"-* ]]; then
# keep debian revision suffix after first '-' following VER if possible
REV="${BASE_DEB_VER#*-}"
if [[ "$BASE_DEB_VER" == *"-"* ]]; then
BASE_DEB_VER="${VER}-${REV}"
else
BASE_DEB_VER="${VER}-1ppa1"
fi
fi
DEB_VER="${BASE_DEB_VER}~${SERIES}"
PKG_ROOT="${TMPDIR:-/tmp}/marqdo-ppa/${VER}"
BUILD_AREA="${ROOT}/../build-area"
GPG_KEY="${MARQDO_PPA_GPG_KEY:-505943294D04C803}"
RUST_VER="${MARQDO_PPA_RUST_VERSION:-1.85.0}"
RUST_TRIPLE="${MARQDO_PPA_RUST_TRIPLE:-x86_64-unknown-linux-gnu}"
RUST_NAME="rust-${RUST_VER}-${RUST_TRIPLE}"
RUST_CACHE="${MARQDO_PPA_RUST_CACHE:-${HOME}/.cache/marqdo-ppa}"
RUST_TARBALL="${RUST_CACHE}/${RUST_NAME}.tar.gz"
RUST_URL="${MARQDO_PPA_RUST_URL:-https://static.rust-lang.org/dist/${RUST_NAME}.tar.gz}"
echo "==> upstream ${VER} → debian ${DEB_VER} (${SERIES})"
rm -rf "$PKG_ROOT"
mkdir -p "$PKG_ROOT" "$BUILD_AREA"
mkdir -p "$PKG_ROOT" "$BUILD_AREA" "$RUST_CACHE"
# Clean export of sources (no target/, .git)
if command -v git >/dev/null && git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
@@ -33,9 +62,7 @@ fi
# Ensure debian/ from working tree (may be newer than last commit)
rsync -a "$ROOT/debian/" "$PKG_ROOT/debian/"
# Series-specific changelog entry (rewrite top distribution)
cd "$PKG_ROOT"
# Update changelog top line distribution / version if needed
python3 - <<PY
from pathlib import Path
import re
@@ -55,7 +82,6 @@ PY
echo "==> cargo vendor (Launchpad offline)"
mkdir -p .cargo
cargo vendor --locked vendor >/tmp/marqdo-cargo-vendor.conf
# cargo vendor prints config to stdout; also write known-good offline config
cat > .cargo/config.toml <<'EOF'
[source.crates-io]
replace-with = "vendored-sources"
@@ -64,16 +90,43 @@ replace-with = "vendored-sources"
directory = "vendor"
EOF
# Orig tarball: upstream version without debian/
echo "==> bundle Rust ${RUST_VER} (${RUST_TRIPLE}) for Launchpad"
if [ ! -f "$RUST_TARBALL" ]; then
echo " downloading ${RUST_URL}"
curl -fL --retry 3 --retry-delay 2 -o "${RUST_TARBALL}.partial" "$RUST_URL"
mv "${RUST_TARBALL}.partial" "$RUST_TARBALL"
else
echo " cache hit ${RUST_TARBALL}"
fi
rm -rf third_party/rust
mkdir -p third_party
RUST_EXTRACT="$(mktemp -d "${TMPDIR:-/tmp}/marqdo-rust.XXXXXX")"
tar -xzf "$RUST_TARBALL" -C "$RUST_EXTRACT"
# Official dist tarball contains install.sh
INSTALL_SH="$(find "$RUST_EXTRACT" -maxdepth 2 -name install.sh | head -1)"
if [ -z "$INSTALL_SH" ]; then
echo "error: install.sh not found in ${RUST_TARBALL}" >&2
exit 1
fi
# --disable-ldconfig avoids needing root; strip docs to save space
bash "$INSTALL_SH" \
--prefix="$PKG_ROOT/third_party/rust" \
--without=rust-docs \
--disable-ldconfig
rm -rf "$RUST_EXTRACT"
"$PKG_ROOT/third_party/rust/bin/rustc" --version
"$PKG_ROOT/third_party/rust/bin/cargo" --version
# Always rebuild orig (vendor + rust toolchain change every run)
cd "$(dirname "$PKG_ROOT")"
ORIG="marqdo_${VER}.orig.tar.xz"
if [ ! -f "$BUILD_AREA/$ORIG" ]; then
tar -cJf "$BUILD_AREA/$ORIG" \
--exclude=debian \
-C "$(dirname "$PKG_ROOT")" "$(basename "$PKG_ROOT")"
fi
# debuild expects ../marqdo_VER.orig.tar.xz relative to package dir parent
echo "==> packing ${ORIG} (vendor + third_party/rust)"
rm -f "$BUILD_AREA/$ORIG" "marqdo_${VER}.orig.tar.xz"
tar -cJf "$BUILD_AREA/$ORIG" \
--exclude=debian \
-C "$(dirname "$PKG_ROOT")" "$(basename "$PKG_ROOT")"
ln -sfn "$BUILD_AREA/$ORIG" "marqdo_${VER}.orig.tar.xz"
ls -lh "$BUILD_AREA/$ORIG"
cd "$PKG_ROOT"
echo "==> debuild -S (key ${GPG_KEY})"
@@ -84,7 +137,6 @@ mkdir -p "$BUILD_AREA"
shopt -s nullglob
for f in ../marqdo_"${DEB_VER}"* ../marqdo_"${VER}".orig.tar.*; do
[ -e "$f" ] || continue
# orig may already be a symlink into BUILD_AREA — skip same inode
if [ "$(realpath -m "$f")" = "$(realpath -m "$BUILD_AREA/$(basename "$f")")" ]; then
continue
fi
+9 -13
View File
@@ -73,20 +73,16 @@ echo "==> building source package for series=${SERIES}"
run_user "$ROOT/scripts/ppa-build-source.sh" "$SERIES"
VER="$(sed -n 's/^version = "\(.*\)"/\1/p' "$ROOT/Cargo.toml" | head -1)"
DEB_VER="${VER}-1ppa1~${SERIES}"
BUILD_AREA="$(cd "$ROOT/.." && pwd)/build-area"
CHANGES="${BUILD_AREA}/marqdo_${DEB_VER}_source.changes"
# ppa-build may leave artifacts next to /tmp/marqdo-ppa — copy already done; also scan
if [ ! -f "$CHANGES" ]; then
alt="$(ls -1 "$BUILD_AREA"/marqdo_*_source.changes 2>/dev/null | tail -1 || true)"
if [ -n "${alt:-}" ]; then
CHANGES="$alt"
else
echo "error: no *_source.changes under $BUILD_AREA" >&2
ls -la "$BUILD_AREA" 2>/dev/null || true
exit 1
fi
# Prefer changes matching this series; fall back to newest source.changes
CHANGES="$(ls -1t "$BUILD_AREA"/marqdo_*"~${SERIES}"_source.changes 2>/dev/null | head -1 || true)"
if [ -z "${CHANGES:-}" ]; then
CHANGES="$(ls -1t "$BUILD_AREA"/marqdo_*_source.changes 2>/dev/null | head -1 || true)"
fi
if [ -z "${CHANGES:-}" ] || [ ! -f "$CHANGES" ]; then
echo "error: no *_source.changes under $BUILD_AREA" >&2
ls -la "$BUILD_AREA" 2>/dev/null || true
exit 1
fi
echo "==> artifact: $CHANGES"