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.
3.3 KiB
Marqdo developer entry point
Everything a third party needs starts here. The rule behind this page: depend
only on the released CLI and public protocols, never on Marqdo's private
Rust structures, marqdo-ir internals, inspect --ir, relative paths into the
core checkout, or host memory layout. Adding a new domain function must not
require a core commit.
Product version for these docs: 3.0.0-beta.1 (Linux x86_64 beta).
Protocol versions are independent: Analysis v2, Trace v2, Tool v1, Plugin ABI
v1, Foreign wire v1, Provider manifest v2, lock v4, markdown profile
marqdo.md.v1.
Pick your entry point
| Goal | Use | Deliverable |
|---|---|---|
| AI/math/data/quantum/SKILL libraries, pure algorithms | .mq.md package |
index.mq.md, marqdo.yaml, README, tests |
| Knowledge/Proof/View/IDE/lint/analysis tools | CLI Tool Protocol v1 | standalone executable + tool.json + Analysis/Trace consumer |
| High-performance native callable functions | Callable Plugin ABI v1 | plugin.yaml, host-targeted library, SDK/header |
| New foreign language backend (R/Python/Julia/…) | Foreign Kernel | kernel.json, executable provider, pinned environment |
| Hardware/device/external-stream resources | Resource Provider v2 | provider.json, C ABI library, worker helper |
Change @exec semantics, add keywords/types |
not a third-party extension | core language RFC + migration + full conformance |
Recommended reading order
- quickstart.md — install the archive and run the first project.
- libraries.md — publish a pure
.mq.mdlibrary and consume it through a pinned Git dependency. - tools.md — build an external Tool that consumes Analysis v2 and Trace v2.
- extensions.md — plugins, foreign kernels, resource providers, extension selection and lock v4.
- analysis-trace.md — the public static/dynamic data contracts and digest binding.
- compatibility.md — version axes, platform matrix and the prerelease policy.
- release-limits.md — the honest beta limitations (this
file ships in the archive as
KNOWN_LIMITATIONS.md).
The full worked handbook is
../MARQDO_THIRD_PARTY_INTEGRATION_GUIDE.md.
Normative contracts live in ../../spec/; this directory is a
task-oriented map, not a second specification.
Baseline repository
The current implementation and release entry point is
git.cflmy.cn/cflmy/marqdo-cli. The
earlier cflmy/marqdo repository is a different, incompatible language/product
line; it is not a source of current protocol or syntax truth. See the parent
repository README for the repository split.
Testing against a frozen binary
Any external repository should be testable without rebuilding the CLI:
export MARQDO_BIN=/absolute/path/to/marqdo
# Put marqdo-provider-worker next to it for provider tests, exactly as the
# release archive does.
$MARQDO_BIN --version
Compute the binary SHA-256 before and after your suite; it must not move. The
reference implementation of this gate is
marqdo-extension-conformance
and tools/ci/verify_extension_contracts.py in the core repository.