Files
marqdo-cli/docs/developers/libraries.md
T
cflmy 2c7c4f31e7
Linux strict security lane (G-C) / strict isolation escape matrix (push) Waiting to run
ci/woodpecker/push/main Pipeline was successful
ci/woodpecker/manual/performance Pipeline was successful
CI / fmt + clippy + test (Linux x86_64) (push) Waiting to run
CI / schema instance validation + consumers (push) Waiting to run
CI / runtime contract (macos-latest) (push) Waiting to run
CI / runtime contract (windows-latest) (push) Waiting to run
release(3.0.0-beta.1): product version migration, beta gates, archive tooling and developer docs
REL-01: workspace/CLI/Analysis product version 3.0.0-beta.1 with updated
Cargo.lock; project.marqdo is enforced against the running core with
package.marqdo_range_invalid/package.marqdo_incompatible fail-closed
diagnostics; Tool SemVer prerelease negotiation tests; init template and
examples use the beta range. Verify init derives the project name from the
target directory instead of falling back to 'example'.

REL-02: beta support matrix is Linux x86_64 only; macOS/Windows are explicitly
experimental/unclaimed; strict policy and G4 Beta-only WARN are documented for
the release evidence.

REL-03: deterministic release packaging (tools/release/package.py) ships the
CLI and provider worker together with SOURCE_SHA, RELEASE_INFO.json,
known-limitations, specs, developer docs, examples incl. built plugin/provider
artifacts and consumers; tools/release/smoke.py cold-install tests the archive.

REL-04: docs/developers entry pages; corrected and self-contained third-party
integration handbook; stale Proposed/native-only/informational spec claims
fixed; release/status/compatibility/changelog/releasing docs updated.

REL-05: release_evidence.py gains an explicit beta profile
(BETA_RELEASE_CANDIDATE) distinct from the stable profile; Woodpecker build
step now packages and smoke-tests the archive on every pipeline.

Adds a runnable Resource Provider v2 example and corrects check --emit to
Analysis v2.
2026-11-22 02:31:32 +08:00

3.6 KiB

Publishing and consuming a pure .mq.md library

A pure library is the preferred extension mechanism: it needs no core change, no C ABI and no rebuild of marqdo. It is ordinary Markdown plus executable sections.

1. Repository layout

marqdo-quantum/
  README.md
  marqdo.yaml
  index.mq.md
  tests/
  examples/

marqdo.yaml:

project:
  name: quantum
  version: 0.1.0
  marqdo: ">=3.0.0-beta.1,<4.0.0"   # enforced against the running core
dependencies: {}

index.mq.md:

# @knowledge 量子数学工具

此包在不修改 Marqdo 内核的情况下向外公开领域函数。

## @exec 加倍

`params(x: Int)`

`return x * 2`

Every exported function is an Exec H2. Its params(...) declaration is the public contract; keep prose documentation in @knowledge sections or paragraphs, which never execute.

2. How a consumer imports it

Pin a full 40/64-character commit; branches and tags are not reproducible:

# consumer/marqdo.yaml
project:
  name: quantum-consumer
  version: 0.1.0
  marqdo: ">=3.0.0-beta.1,<4.0.0"
dependencies:
  quantum:
    git: https://github.com/your-org/marqdo-quantum.git
    rev: 0123456789abcdef0123456789abcdef01234567
---
import:
  quantum: "@quantum"
---

## @exec main

`return quantum.加倍(x=21)`

An @alias import binds the dependency's entry package (its index.mq.md); qualify calls with the alias as above. A project-relative dependency uses path: ./deps/x instead of git/rev. marqdo add <alias> --git <url> --rev <sha> writes the dependency for you.

3. Lock and run

From the consumer project root:

marqdo lock                 # writes marqdo.lock (lock_version: 4)
marqdo sync --locked        # verify cached content and materialize .marqdo/env; no fetch
marqdo check index.mq.md --refs
marqdo call index.mq.md main    # prints 42

Rules that matter for reproducibility:

  • With declared dependencies, check/run/call require marqdo.lock and never fetch or rewrite it.
  • Plain marqdo sync may fetch a pinned Git revision named by the lock; --locked forbids fetching and fails if the verified cache is unavailable. Both modes verify content digests and never silently update the lock.
  • A dependency's content digest, manifest digest, instance id (dep:quantum@0.1.0#<digest>) and alias edges are all recorded. Drift fails with a "run marqdo lock" diagnostic.
  • project.marqdo is enforced; a stale >=0.1,<1 range is a hard package.marqdo_incompatible error, not a warning.

4. Testing your library

Test it with the released binary only:

MARQDO_BIN=/opt/marqdo/marqdo
$MARQDO_BIN check index.mq.md
$MARQDO_BIN call index.mq.md 加倍 --arg x=21

Add a consumer fixture that pins a full SHA and assert the --json values and diagnostics. For negative cases expect hard errors, never prose fallback:

  • wrong arity/type → call.arity / a type diagnostic;
  • unknown function → symbol.unknown;
  • missing lock with dependencies → a run marqdo lock diagnostic;
  • edited dependency content with a stale lock → lock/content-drift error.

5. Publishing checklist

  • README with a minimal runnable example and the exact CLI product range.
  • marqdo.yaml with an enforced project.marqdo range; functions with params(...); all examples migrated to RFC-LANG-0002.
  • Tests pinned to a full commit SHA; no floating branches.
  • State that the package is pure .mq.md and needs no plugin/provider/kernel.
  • Version the package independently of the CLI (0.1.0 here is the package version, not the product version).