Skip to main content

Crate htl_macros

Crate htl_macros 

Source
Expand description

htl proc macros.

  • include_tl!("path.tl") -> &'static str generated Lua, Teal-checked at build time
  • include_tl_bytes!("path.tl") -> &'static [u8] stripped Lua 5.4 bytecode, same check
  • teal_types!() -> the pub mod ... { ... } items htl rs writes, from htl.toml
  • #[derive(TealRecord)] -> Teal record / enum / type decl + IntoLua / FromLua
  • #[host_module(name = "...")] -> UserData impl + Teal .d.tl from a plain impl block
  • #[c_export(prefix = "...")] -> extern "C" wrappers + C header from the same impl block

Paths are relative to CARGO_MANIFEST_DIR. Teal type errors become compile_error!s, and so do the warnings and lints htl check would fail on — a rule at deny, or any under [lint] strict (htl_core::verdict); the rest are printed and the build goes on. HTL_LINT=deny makes every one fail, HTL_LINT=warn none. HTL_LINTS configures which rules run and at what level, as --lint does for the command; it is read after htl.toml’s [lint], so the environment wins. Every .tl consulted is registered with include_str! so edits trigger a rebuild. Generated code refers to ::htl::..., so use these through the htl umbrella crate.

Declaration text (.d.tl) comes from htl_core::dts, the same code htl dts runs from the CLI, so the files can also be produced before any cargo build.

Before checking, include_tl! / include_tl_bytes! / include_bundle! run the host-module half of that same scan over the whole crate and rewrite every one the scan can see (regenerate_crate), so a build sees each one current whichever of two #[host_module]s — or a #[host_module] and this scan — rustc happens to expand first. Without it, that order follows the crate’s mod declarations, and a module declared after the one doing the include_tl! was checked against yesterday’s declaration (#429). What the scan cannot see, because it reads #[host_module(..)] literally rather than evaluating Rust: the attribute written as #[cfg_attr(.., host_module(..))], an impl a macro_rules! produces rather than one written out, an item reached only through include!, a module whose #[path] leaves src/ / examples/ / tests/ / benches/, and the attribute under another name through use htl::host_module as something_else. Each of those is #[host_module]’s own expansion’s to write, exactly as before this scan existed — this only widens when a declaration it can see lands, never what it writes, and never what it cannot see.

The macros run the checker — htl-core and the vendored Lua that hosts tl — inside the proc macro, under [profile.dev.build-override], whose default opt-level = 0 makes a cargo build that touches a .tl about three times slower than the release-built CLI; htl new --embed writes opt-level = 3 into that section. The .tl edit loop belongs to htl check / htl test in any case — an edit to a leaf module costs a few milliseconds from the cache — and cargo build to the Rust host and the binary.

Macros§

include_bundle
include_bundle!("src/main.tl", host = ["host"], extra = ["modkit"], payload = "source", debug = true)
include_tl
include_tl!("path.tl") -> &'static str: the Lua tl (the vendored Teal checker) generates from path.tl, relative to CARGO_MANIFEST_DIR, Teal-checked at build time against the project’s model and the crate’s #[host_module]s. Before checking, it regenerates every #[host_module]’s .d.tl it can see from the Rust source (regenerate_crate), so the #[host_module] it checks against does not have to be declared before this in the crate’s mod order — in the same file or another one (#429). A Teal type error, or a warning/lint the project’s policy denies, becomes a compile_error! at this macro’s call site; every .tl the check reads is include_str!-tracked, so an edit anywhere in the closure rebuilds. See the module doc for the lint policy and for what the regeneration cannot see.
include_tl_bytes
include_tl!, embedding stripped Lua 5.4 bytecode as &'static [u8] instead of the generated source — the same check, the same .d.tl regeneration, and the same tracking.
teal_types
teal_types!() -> the pub mod ... { ... } items htl rs writes, generated at cargo build from htl.toml ([rust] modules, exports and [rust.types]) through htl_core::rsgen::generate, for a project that does not commit generated Rust.

Attribute Macros§

c_export
#[c_export(prefix = "hello", header = "include/hello.h")] on an impl block -> one extern "C" wrapper per pub fn, the handle lifecycle, and the C header.
host_module
Turn a plain impl block into a mlua::UserData impl, and write its Teal declaration (dts = "scripts/host.d.tl") when the macro expands, so a script sees host:scale(p: Point, k: number): Point and host.Point. Change a Rust signature and the next cargo build fails inside the .tl that relied on it: the declaration is rewritten first, and include_tl! / include_bundle! check against it. The breakdown is htl_core::dts::host_decl, which htl dts runs without building.

Derive Macros§

TealRecord
Declare a struct or enum on the Teal side and convert it both ways: TealRecord::DECL (the .d.tl text), IntoLua / FromLua that produce and accept exactly what it declares, and htl_preload. What each Rust shape lowers to is the type table in htl::dts, which is also what htl dts reads; the two cannot disagree.