Skip to main content

Crate layout

Why is a small language split into nine crates? So that each backend library lives in a crate of its own, and a program compiles only the backends it uses. Hypershell is a small shell-scripting language built with Context-Generic Programming (CGP), a Rust library that separates implementations from the code that chooses them. This page lists the crates and what each adds, what a program file imports, and what the workspace needs to build.

One crate per backend​

The syntax, and the interfaces its providers implement, live in one crate that depends only on CGP. Each backend then adds one external library in a crate of its own:

CrateWhat it adds
hypershell-componentsthe syntax, the argument handling, and the control syntax such as Pipe
hypershell-tokio-componentscommands, files, and streams, using Tokio
hypershell-reqwest-componentsHTTP requests, using reqwest
hypershell-json-componentsJSON encoding and decoding, using serde_json
hypershell-hash-componentschecksums, using sha2 and hex
hypershell-tungstenite-componentsWebSockets, using tokio-tungstenite
hypershell-macrothe hypershell! macro
hypershellthe namespace that assembles the language, its error handling, the two ready-made contexts, and the prelude
hypershell-examplesthe runnable examples, and a small extension used by some of them

The split works because providers do not name the context they will run on, or its error type. Those are chosen last, in the hypershell crate. So the Tokio crate builds without reqwest, and the JSON crate builds without Tokio. The HTTP and WebSocket crates do depend on the Tokio crate, because they reuse its stream types.

The hypershell crate does not include the checksum and WebSocket extensions. A program that uses them adds their crates and joins a larger language, as http_checksum_native and bluesky_websocket show.

What a program imports​

A program file needs one import, hypershell::prelude::*. It brings the syntax, the hypershell! macro, the two contexts HypershellCli and HypershellHttp, the anyhow error type as Error, and the CGP names a program uses, the handler traits and their keys among them. Two things are imported separately: HypershellNamespace, from hypershell::namespaces, which a context of your own joins; and ToTokioAsyncRead, from hypershell_tokio_components::dsl, the adapter an HTTP stream needs before StreamToString.

What the workspace needs to build​

The repository pins nightly Rust in its rust-toolchain.toml, and its .cargo/config.toml turns on the compiler's next-generation trait solver with -Z next-solver=globally. The setting matters for the largest programs, the ones that nest whole programs inside others. Checked on stable Rust without it, the two largest examples grew the compiler to about 7 GB of memory before they were stopped; on nightly with the new solver, parallel_compare, one of the two, checked in about 9 seconds and 460 MB. Why the solvers differ so much was not investigated. A crate of your own with large programs should use the same settings, while a small program, such as hello, builds on stable Rust in a crate of its own.

What it costs​

The split keeps each crate's dependencies small, at the price of more crates to depend on: a program using an extension imports from several Hypershell crates and from the library the extension wraps, such as sha2 for checksums. The nightly requirement is the larger cost, because it applies to every crate that builds Hypershell programs that large, not only to Hypershell itself.

Where to go next​


An AI agent wrote this page using the CGP knowledge base. Its content was verified against the project's source. See How AI is used in this project.