From d932ecf563a8f2bede782e60b3cfacb0285e2be9 Mon Sep 17 00:00:00 2001 From: Mikhail Katychev Date: Sun, 26 Jul 2026 22:13:43 -0500 Subject: [PATCH] doc: update with workspace and other 0.16 changes --- docs/configuration.md | 45 ++++++++++++++++++++++++ docs/manifest.md | 81 ++++++++++++++++++++++++++++++++----------- 2 files changed, 105 insertions(+), 21 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 9967518..0877313 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -138,6 +138,51 @@ default. Set to `"http"` for local test registries. protocol = "https" ``` +### `registry..oci.accept_invalid_certificates` + +- Type: bool, default `false` + +Skip TLS certificate validation. For local self-signed test registries only. + +### `registry..oci.extra_root_certificates` + +- Type: list of inline-tables `{ encoding = "pem" | "der", data = "" }` +- Default: `[]` + +Additional root certificates trusted for TLS. `data` holds the certificate +bytes as a string; use TOML multi-line literals for PEM blocks. Useful when a +private OCI registry is fronted by an internal CA. + +```toml +[[registry."internal.example.com".oci.extra_root_certificates]] +encoding = "pem" +data = """ +-----BEGIN CERTIFICATE----- +MIIB... +-----END CERTIFICATE----- +""" +``` + +### Environment variable authentication + +For OCI registries, an environment variable of the form +`WKG_REGISTRY__AUTH_` overrides any credentials configured +under `[registry."".oci.auth]`. `` is the registry name with +every non-ASCII-alphanumeric character replaced by `_` and upper-cased. +`` is the auth scheme. + +| Registry | Envvar | +| ---------------- | ----------------------------------------- | +| `example.com` | `WKG_REGISTRY_EXAMPLE_COM_AUTH_BEARER` | +| `localhost:8008` | `WKG_REGISTRY_LOCALHOST_8008_AUTH_BEARER` | +| `foo.bar/baz` | `WKG_REGISTRY_FOO_BAR_BAZ_AUTH_BEARER` | + +NOTE: only `BEARER` scheme is currently supported through environmental variables. + +Useful for registries that expect a bearer token rather than a +username/password pair, and for supplying credentials in CI without writing +them to a config file. + ### `registry..local.root` - Type: string (filesystem path) diff --git a/docs/manifest.md b/docs/manifest.md index d1f15d3..bd6b2c9 100644 --- a/docs/manifest.md +++ b/docs/manifest.md @@ -9,20 +9,36 @@ and *is entirely optional*. Projects are not required to use this file. Currently it serves two purposes: adding additional metadata and overriding versions/dependencies. +*NOTE*: A top-level `[workspace]` table is mutually exclusive with top-level +`[overrides]` and `[metadata]`: a workspace root uses `[workspace.metadata]` +instead, and members manifests have their own `[overrides]` / `[metadata]`. + ### Format +Single-package layout: + ```toml [overrides] "my:local-dep" = { path = "../local-dep/wit" } [metadata] -authors = ["WasmPkg "] -categories = ["wasm-pkg"] +authors = "WasmPkg " description = "WASI HTTP interface" license = "Apache-2.0" -documentation = "https://docs.foobar.baz" homepage = "https://foobar.baz" repository = "https://github.com/bytecodealliance/wasm-pkg-tools" +revision = "f00ba4" +``` + +Workspace root layout: + +```toml +[workspace] +members = ["pkg-a", "pkg-b/wit", "examples/*/wit"] + +[workspace.metadata] +authors = "WasmPkg " +license = "Apache-2.0" ``` ### `overrides` @@ -38,18 +54,39 @@ developing two components together. "my:local-dep" = { path = "../local-dep/wit" } ``` -### `metadata.authors` +### `workspace.members` + +- Type: list of strings (paths; gitignore-style globs allowed) -- Type: list of strings +Directories that make up the workspace. Each entry is either a literal path or +a glob (e.g. `"examples/*/wit"`); globs expand relative to the workspace root +and skip entries with no `.wit` files. Used by `wkg fetch --workspace` and +`wkg publish --workspace` to operate on every member in one invocation. +Members share the workspace-level `wkg/deps` and `wkg/config.toml` next to the +root manifest. -Author list. Also consumed by downstream language tooling that reads -`wkg.toml`. +### `workspace.metadata` -### `metadata.categories` +- Type: same shape as [`metadata`](#metadataauthors) below -- Type: list of strings +Workspace-wide package metadata applied to every member. Set here instead of +top-level `[metadata]` when `[workspace]` is present. -Freeform category tags. +### Member declarations + +- Type: `{ workspace = "path/to/root" }` (optional) + +A member `wkg.toml` typically has no `[workspace]` table at all; the root is +discovered by walking ancestor directories for a `wkg.toml` whose +`workspace.members` matches this manifest's path. + + + +### `metadata.authors` + +- Type: string (also accepts the legacy key `author`) + +Author line. Unlike `Cargo.toml`, this is a single string, not a list. ### `metadata.description` @@ -60,15 +97,10 @@ Short description of the package. Emitted as the ### `metadata.license` -- Type: string (SPDX expression) - -License identifier. Emitted as `org.opencontainers.image.licenses`. - -### `metadata.documentation` - -- Type: string (URL) +- Type: string (SPDX expression; serialized as `licenses`) -Documentation URL. Currently informational. +License identifier. Accepts the singular `license` key as an alias. Emitted as +`org.opencontainers.image.licenses`. ### `metadata.homepage` @@ -78,15 +110,22 @@ Project homepage. Emitted as `org.opencontainers.image.url`. ### `metadata.repository` -- Type: string (URL) +- Type: string (URL; serialized as `source`) + +Source repository URL. Accepts `source` or `repository` on input. Emitted as +`org.opencontainers.image.source`. + +### `metadata.revision` + +- Type: string -Source repository. Emitted as `org.opencontainers.image.source`. +Source-control revision (commit hash, tag, etc.) the package was built from. ## OCI annotation mapping When publishing to OCI via `wkg publish`, `wkg` loads the metadata from the wasm binary (which is automatically added to the WIT package with -`wkg wit build` if the metadata is present in the `wkg.toml` file). The +`wkg build` if the metadata is present in the `wkg.toml` file). The metadata is mapped to the following OCI annotations: | `wkg.toml` metadata field | OCI annotation |