Outils › L’Arche Store

Outils

Cette page n’est pas encore traduite : voici la version anglaise.

The Arche Store

A place to share what you write in arche-lang: whole architectures to reuse or extend, drivers (a component and its code), specifications (requirements, interfaces, ICDs), boards, templates (projects to start from), UI kits (a theme for the product's screens, see below), and libraries of parts and types, and generators (code generators of your own, see generators.md — a script or a command one brings runs only once archec generator approve has recorded it), and plugins (generators, importers and exporters together, see plugins.md). A project takes a package with one command; archec checks it before writing anything. archec new my-project --from owner/name copies a package into a new project instead — yours to change, with derived-from saying where it came from (see new.md).

Taking a package#

archec store search can fd --kind driver
archec add main.arche acme/can-fd@^1.2

The store is the hosted one, https://store.arche-lang.xyz, unless another is named: --store <where>, then ARCHE_STORE, then what archec store use <folder | git URL | https URL> wrote in ~/.arche/config.json. ARCHE_STORE= (set, empty) keeps archec off the hosted store.

archec add takes the newest version in the range that this archec reads, then checks:

  • the archive is the one the store published (its hash);
  • its publisher signed it, with a key the store lists for that owner (Ed25519);
  • its files are the ones signed (their fingerprint);
  • the project accepts its publisher: trust verified takes only verified publishers (board vendors, known projects), trust reviewed also packages a store reviewer read, trust community (the default) any.

Then it unpacks the package into .arche/store/<name>@<version>/, writes uses <name> "^1.2" in the project block, records the store id, version, fingerprint and signing key in arche.lock, and lists the code the package brings. That code reaches firmware through archec gen, so read it. If a check fails, nothing is written.

Commit arche.lock, not .arche/. On a fresh checkout, archec store fetch main.arche takes the locked versions again and checks them against the lock.

archec audit main.arche          # every piece of code, by where it came from
archec store outdated main.arche # newer versions, and yanks
archec store diff acme/can-fd 1.2.0 1.3.0   # what the model gained, lost or changed

Generated files say where their code came from: /* … Its model and code: from store package acme/can-fd 1.2.0 (sha256-…, community). */.

Publishing#

A package is a library folder whose library.arche says what the store needs:

library can-fd "CAN-FD driver for STM32G4" {
  description "FDCAN frames: classic CAN and CAN FD, bit timing from the clock."
  version "1.2.0"
  owner acme
  kind driver
  license "Apache-2.0"
  export-control none
  archec ">=0.10"
  edition "0.12"
  keywords can, stm32, automotive
  derived-from "arche/nucleo-g474re@^0.1"
}
archec store check .       # what would be refused, warned about, or held
archec store card . -o card.html
archec store publish .

--dry-run packs the package and compiles it as the store's validator does (unpacked on its own, what it uses taken from the folder's .arche/store/), and sends nothing. What archec builds at the top of a folder, generated/ and arche-out/, is not part of a package, as dot files are not: a project can be its own package (archec new --kind library).

The first publish makes your signing key in ~/.arche/keys/<owner>.pem and registers the owner with it. Keep that file: it is how the store knows you. A published version never changes. To withdraw one, archec store yank acme/can-fd@1.2.0 --reason "…": it is not taken any more, and projects that have it are told by archec store outdated.

archec store check also says the package's handler language (docs/handlers.md): its project's handlers, else what its code is — a .ts file or a ```ts block is TypeScript, a .py file or a ```python block Python, bodies all in ```arche the action language (which Arche runs as TypeScript). The store records it, the card shows it (Handlers), and the list beside the kind. The validator reads the TypeScript itself (types blanked out, nothing to install) and gives it a badge, typescript: pass or the first line that does not read, as it gives Python one. The Try it page runs TypeScript as it runs the action language, in the visitor's browser, with nothing to load: no Pyodide, no compiler.

What publishing refuses:

  • no owner, license or export-control;
  • anything that could run on install: scripts, binaries, files marked executable, links;
  • a file that does not parse;
  • more than 20 MB.

Export control#

export-control is your statement as publisher: none, ear99, or a control number. Publishing controlled technical data is itself an export. A package whose text reads like defence technology (radar, seeker, guidance, missile, fire control…) is held until a store reviewer releases it, whatever it declares. Technology under ITAR, or that needs an export licence, is not accepted. This is not legal advice.

UI kits#

A package of kind ui-kit holds a theme for a ui { }: the colors its screens are drawn in. The theme is a constant record in the kit's theme.arche, base the theme it starts from (dark or light), the other keys the colors it changes:

// library.arche: library automotive-dark "Automotive dark" { kind ui-kit; owner acme; version "1.0.0"; … }
// theme.arche
/// Dark and high contrast, for a car's cluster.
const AUTOMOTIVE_DARK = { base: "dark", background: "#0b0f14", surface: "#1a2029", primary: "#4fc3f7", onPrimary: "#00131f", warning: "#ffc400" }

A project takes it as any package — archec add main.arche acme/automotive-dark writes its uses — and a ui names it:

ui {
  theme "acme/automotive-dark"     // the kit's theme, by the package's name
  colors { primary "#00e5ff" }     // and changed further, as any theme
  …
}

With the kit's theme.arche included, theme AUTOMOTIVE_DARK names the same constant; a project can declare one of its own the same way. archec checks the theme's contrast as any (ui-a11y). The UI model says where its theme came from (theme.from), and the previews and generators draw it (--target ui-qml). The card of a kit shows each theme with its colors; the card of any package lists the screens of the uis in it.

Not done yet: reusable composite elements (a kit's components whose ui fragments a project's screens would place). A kit is themes only.

Editions and archec releases#

A package states the archec versions it works with (archec ">=0.10") and its edition. Every later archec reads old editions, and archec fmt --edition moves a package to a newer one. Before a release, archec store test <index> --breaks builds every package with the new archec and fails on any package that passed with an earlier one. The badges show the archec versions each package works with.

Running a store#

A store is an index folder. On GitHub it is a repository:

archec store init arche-store      # store.json, README, .github/workflows/store.yml
archec store seed arche-store --license Apache-2.0
cd arche-store && git init && git add . && git commit -m "Arche Store"

Publishing is then a pull request that adds a package (archec store publish <folder> --store <your clone>). The workflow verifies signatures and builds the package with archec. On the main branch, it writes the badges and publishes the pages (archec store site) to GitHub Pages.

The hosted store needs no pull request:

archec store serve arche-store --port 8080
archec store token arche-store acme --org kria-team
archec store token arche-store alice --reviewer

The hosted store adds:

  • accounts: tokens, or GitHub sign-in when GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET are set;
  • private packages for an organisation (archec store publish --private);
  • review of held packages;
  • stars, discussions on each package page, and requests for missing boards or drivers.

archec store seed publishes what archec ships under arche, a verified publisher:

  • the board store, and each board on its own;
  • the standard library;
  • the examples, as architectures (ts-handlers among them: its behaviour in TypeScript);
  • the templates archec new starts from, as kind template;
  • the collections starter and plants (a two-link arm, a cart-pole, a rover and a quadrotor, each a MuJoCo plant with its controller and a test plan run against it: see Plants).

A project started with archec new --from (or --template) says so in its project block, derived-from "arche/rover-esp32@0.1.0". Published, its library carries that line on when its own library.arche has none, and the package page draws the family tree.

archec store import-zephyr <zephyr>/boards -o zephyr-boards writes a board collection from Zephyr's board files (Apache-2.0). Each board gets its processor (hal and chip for STM32, nRF, RP2040 and ESP32), its RAM, and its UART, CAN, SPI and I2C ports with the pins its DTS sets. Publish it as a package with owner added.

Every command is in commands.md.