Expand description
htl proc macros.
include_tl!("path.tl")->&'static strgenerated Lua, Teal-checked at build timeinclude_tl_bytes!("path.tl")->&'static [u8]stripped Lua 5.4 bytecode, same checkteal_types!()-> thepub mod ... { ... }itemshtl rswrites, fromhtl.toml#[derive(TealRecord)]-> Tealrecord/enum/typedecl +IntoLua/FromLua#[host_module(name = "...")]->UserDataimpl + Teal.d.tlfrom a plainimplblock#[c_export(prefix = "...")]->extern "C"wrappers + C header from the sameimplblock
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 Luatl(the vendored Teal checker) generates frompath.tl, relative toCARGO_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.tlit 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’smodorder — in the same file or another one (#429). A Teal type error, or a warning/lint the project’s policy denies, becomes acompile_error!at this macro’s call site; every.tlthe check reads isinclude_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.tlregeneration, and the same tracking.- teal_
types teal_types!()-> thepub mod ... { ... }itemshtl rswrites, generated atcargo buildfromhtl.toml([rust] modules,exportsand[rust.types]) throughhtl_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 animplblock -> oneextern "C"wrapper perpub fn, the handle lifecycle, and the C header.- host_
module - Turn a plain
implblock into amlua::UserDataimpl, and write its Teal declaration (dts = "scripts/host.d.tl") when the macro expands, so a script seeshost:scale(p: Point, k: number): Pointandhost.Point. Change a Rust signature and the nextcargo buildfails inside the.tlthat relied on it: the declaration is rewritten first, andinclude_tl!/include_bundle!check against it. The breakdown ishtl_core::dts::host_decl, whichhtl dtsruns without building.
Derive Macros§
- Teal
Record - Declare a struct or enum on the Teal side and convert it both ways:
TealRecord::DECL(the.d.tltext),IntoLua/FromLuathat produce and accept exactly what it declares, andhtl_preload. What each Rust shape lowers to is the type table inhtl::dts, which is also whathtl dtsreads; the two cannot disagree.