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
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.
70 lines
3.3 KiB
Markdown
70 lines
3.3 KiB
Markdown
# 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
|
|
|
|
1. [quickstart.md](quickstart.md) — install the archive and run the first
|
|
project.
|
|
2. [libraries.md](libraries.md) — publish a pure `.mq.md` library and consume
|
|
it through a pinned Git dependency.
|
|
3. [tools.md](tools.md) — build an external Tool that consumes Analysis v2 and
|
|
Trace v2.
|
|
4. [extensions.md](extensions.md) — plugins, foreign kernels, resource
|
|
providers, extension selection and lock v4.
|
|
5. [analysis-trace.md](analysis-trace.md) — the public static/dynamic data
|
|
contracts and digest binding.
|
|
6. [compatibility.md](compatibility.md) — version axes, platform matrix and the
|
|
prerelease policy.
|
|
7. [release-limits.md](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`](../MARQDO_THIRD_PARTY_INTEGRATION_GUIDE.md).
|
|
Normative contracts live in [`../../spec/`](../../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`](https://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:
|
|
|
|
```bash
|
|
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`](https://git.cflmy.cn/cflmy/marqdo-extension-conformance)
|
|
and `tools/ci/verify_extension_contracts.py` in the core repository.
|