name: rustq summary: Build readable Elixir↔Rust bridges with RustQ in new NIF projects, ports of existing bindings, and code generators. Use Rusty-Elixir/defrust, inference, Rust source metadata, Elixir macros, and RustQ AST before raw Rust strings.

RustQ Skill

Use this skill when starting a RustQ-powered NIF/bridge, porting existing Rustler bindings, adding generated Rust to an Elixir project, or working on RustQ itself.

RustQ's goal is a readable and maintainable Elixir↔Rust bridge. Generated Rust should be understandable through the Elixir that produced it. Do not turn RustQ projects into cryptic string emitters.

Full guide: https://rustq.hexdocs.pm/using-rustq-well.md

First principles

1. Write bridge behavior as Rusty-Elixir. Prefer defrust functions with real @specs.
2. Let RustQ infer. Do not sprinkle unwrap! everywhere. RustQ can infer many ? propagations from return types, argument types, receiver types, and Rust source callable metadata.
3. Use Elixir metaprogramming. Use ordinary defmacro, quote, unquote, pattern matching, recursion, and schema transforms.
4. Infer from Rust/source schemas. Use RustQ.Syn, rust_sources, rust_packages, and callable_modules instead of hand-copying Rust APIs.
5. Use RustQ AST/builders for generated structure. If a construct is missing, prefer adding RustQ support over writing a large string template.
6. Keep raw Rust strings tiny and local. Macro invocations and unavoidable syntax escapes are fine; large generated functions as strings are not.

Starting point for a new bridge

defmodule MyApp.Native.Generated do
  use RustQ.Meta,
    rust_sources: ["native/my_app_nif/src/helpers.rs"]

  alias RustQ.Type, as: R

  @spec decode_color(R.term()) :: R.nif_result(R.raw(:Color))
  defrust decode_color(term) do
    value = decode_as!(term, R.u32())
    {:ok, Color.from_argb(255, 0, 0, value)}
  end

  @spec draw(R.mut_ref(Canvas.t()), R.term()) :: R.nif_result(R.unit())
  defrust draw(canvas, term) do
    color = decode_color(term)
    canvas.draw_color(color)
    :ok
  end
end

If RustQ knows decode_color/1 returns NifResult<Color> and draw_color/1 expects Color, it can lower the call as decode_color(term)? in the argument position. You do not need to write unwrap! just to force ?.

Prefer inference over unwrap!

unwrap! still exists as an explicit ? escape hatch, but it should not be the default style for every fallible call. Before using it, first make sure RustQ can see the callable metadata that would let it infer propagation.

Prefer this when callable metadata is available:

@spec draw(R.term(), R.slice({R.atom(), R.term()})) :: R.nif_result(R.unit())
defrust draw(term, opts) do
  stroke_paint(decode_color(term), 1.0, opts)
  :ok
end

RustQ can infer propagation from:

• return-position expected wrappers (NifResult<T>, Result<T, E>, Option<T>)
• argument types from local @specs
• argument types from callable_modules
• Rust free functions and impl methods parsed from rust_sources / rust_packages
• receiver method calls when the receiver type is known
• downstream uses of previously-bound locals
• vector pushes and iterator-like argument expectations in supported cases

Before reaching for unwrap!, check:

• Is the callable defined by a local @spec?
• Is it exposed through a callable_modules module?
• Is it parseable from configured rust_sources?
• Is it available from configured rust_packages?
• Is the receiver type known well enough for method lookup?
• Is the expected return or argument type known?

If a fallible call is a method on a Rust type, read the Rust source that defines it and configure metadata before assuming RustQ cannot infer it. Do not use unwrap!, verbose case, or raw Rust wrappers to paper over missing metadata.

Use unwrap! only when you genuinely need to force propagation and metadata/inference cannot express the shape yet:

@spec decode_alpha(R.term()) :: R.nif_result(R.u8())
defrust decode_alpha(term) do
  value = decode_as!(term, R.u32())
  {:ok, cast(value, R.u8())}
end

Use ok_or! for explicit Option<T> to Result/NifResult boundaries:

@spec shader(R.ref(Paint.t())) :: R.nif_result(Shader.t())
defrust shader(paint) do
  ok_or!(paint.shader(), badarg())
end

Use Rust source metadata

Do not retype Rust APIs into Elixir registries when RustQ can read them.

defmodule MyApp.Native.Generated do
  use RustQ.Meta,
    rust_sources: [
      "native/my_app_nif/src/paint.rs",
      "native/my_app_nif/src/generated.rs"
    ],
    rust_packages: [{"skia-safe", manifest_path: "native/my_app_nif/Cargo.toml"}],
    callable_modules: [MyApp.Native.GeneratedEnums]

  alias RustQ.Type, as: R

  @spec run(R.mut_ref(Paint.t()), R.atom()) :: R.nif_result(R.unit())
  defrust run(paint, atom) do
    paint.set_stroke_cap(decode_cap(atom))
    :ok
  end
end

RustQ parses callable signatures and uses them for propagation/argument inference. This is the preferred way to bridge existing Rust libraries.

When a defrust function calls a Rust method such as decoder.read_var_int64(), the correct first move is to expose the Decoder implementation through rust_sources or equivalent callable metadata. Do not duplicate the method signature in an ad hoc Elixir registry or hide missing metadata behind wrappers.

Do not create trivial wrappers for missing metadata

Do not create a new Rust or defrust helper merely to call one Rust method and return Ok(()):

# Bad if the only reason is that RustQ cannot see `Decoder.read_var_int64/0` yet.
@spec kiwi_skip_int64_value(R.mut_ref(R.path(:Decoder, R.lifetime(:_)))) :: R.nif_result(R.unit())
defrust kiwi_skip_int64_value(decoder) do
  unwrap!(decoder.read_var_int64())
  :ok
end

First make RustQ understand the underlying Rust method via rust_sources, rust_packages, or callable_modules, or improve RustQ inference if the metadata is present but unused. Wrappers are fine when they encode real bridge semantics or are required as stable function-pointer targets, but they should not be a workaround for skipped metadata.

Use recursion and reducers instead of return/break-driven product code

RustQ has internal AST nodes for Rust return, loop, break, and continue, but bridge/generator code should usually be written as Elixir-shaped control flow.

Prefer recursion for small state machines:

@spec skip_remaining(R.mut_ref(Decoder.t()), R.u32()) :: R.nif_result(R.unit())
defrust skip_remaining(decoder, remaining) do
  if remaining == 0 do
    :ok
  else
    skip_one(decoder)
    skip_remaining(decoder, remaining - 1)
  end
end

Prefer for ..., reduce: for accumulator loops:

@spec validate_all(R.vec(Item.t())) :: R.nif_result(R.unit())
defrust validate_all(items) do
  for item <- items, reduce: :ok do
    :ok -> validate_item(item)
  end
end

Use return!, break, and continue only when modelling an inherently Rusty low-level primitive or RustQ internals. They should be unusual in downstream product generators.

Use ordinary Elixir macros for reusable Rusty-Elixir

defmacro with_saved_canvas(do: body) do
  quote do
    var!(canvas).save()
    unquote(body)
    var!(canvas).restore()
  end
end

@spec draw(R.ref(Canvas.t())) :: R.nif_result(R.unit())
defrust draw(canvas) do
  with_saved_canvas do
    canvas.translate({1.0, 2.0})
  end

  :ok
end

RustQ expands normal Elixir macros before lowering. Use that power instead of generating Rust strings.

Use the supported Rusty-Elixir surface

Common supported forms include:

• @spec / @type driven function signatures
• ordinary assignments (let) and inferred mutability when later assigned
• case, if, with, guards, tuple patterns, {:ok, value}, {:error, reason}, {:some, value}, :none
• method calls, remote calls, local calls, aliases, pipelines
• decode_as/2 and decode_as!/2 for Rustler term decoding
• ref/1, mut_ref/1, deref/1, cast/2, array/1, index/2, struct_literal/2
• expr!, pat!, stmt!, and arm! for semantic Rust-shaped AST values authored as valid Elixir
• raw_expr!, raw_pat!, raw_stmt!, and raw_arm! only as explicit token escapes

Types: prefer clear specs

Use ordinary Elixir and remote types first:

@spec draw(R.ref(SkiaSafe.Canvas.t()), GeneratedOpts.CircleOpts.t(R.lifetime(:a))) ::
        R.nif_result(R.unit())

Use RustQ.Type (alias RustQ.Type, as: R) for Rust-specific precision:

• R.ref/1, R.mut_ref/1, R.slice/1
• fixed-width numbers: R.u32(), R.i64(), R.f32()
• R.nif_result/1, R.result/2, R.option/1, R.vec/1
• R.lifetime/1
• R.raw/1 and R.path/1,2 as low-level escapes

Do not invent fake Elixir modules solely to spell Rust paths.

AST/builders for generated structure

When generating Rust declarations, prefer RustQ AST/builders:

alias RustQ.Rust
alias RustQ.Rust.AST.Builder, as: A

Rust.ast_item(A.const(:MAX_FIELDS, :usize, A.lit(128), vis: :pub))

If AST/native rendering rejects a shape you need, that is usually a RustQ capability gap. Add the missing node/decoder/rendering support rather than falling back to a giant template.

Raw Rust strings: last resort

RustQ itself still has a few explicit low-level escape boundaries. Treat these as owned exceptions, not examples to copy:

• core renderers/validators that must accept Rust text (RustQ.render/3, splice validation)
• RustQ.Rust.AST.MacroItem, EscapeExpr, and TypeRaw nodes, which are explicit escape nodes
• Rustler helper APIs that accept caller-provided Rust expressions for advanced dispatch/defaults
• unsafe raw NIF_TERM helpers where Rustler exposes only low-level primitives

Anything outside those boundaries should use defrust, RustQ AST, or inferred metadata first.

Acceptable:

Rust.ast_item(A.macro_item("rustler::atoms! { ok, error }"))

Not acceptable as normal style:

Rust.item([
  "fn decode_", name, "(decoder: &mut Decoder<'_>) -> NifResult<()> {\n",
  "    loop { ... }\n",
  "}\n"
])

If a raw escape grows beyond a small syntax boundary, stop and add a semantic RustQ capability.

Porting checklist

When porting existing bindings:

1. Keep clear handwritten Rust as Rust.
2. Move repetitive bridge glue to defrust or AST-backed generation.
3. Configure rust_sources / rust_packages before duplicating Rust signatures.
4. Replace metadata registries with inference from Rust/schema/typespecs.
5. Add rustq.exs, generate checked-in Rust if needed, and enforce mix rustq.gen --check.
6. Run generated Rust through cargo fmt, cargo check, and cargo clippy -- -D warnings. For generator changes that call downstream Rust methods, run the downstream native crate too; Elixir tests alone can miss missing callable metadata or receiver-type drift.

References

Read these in HexDocs/source when working with RustQ:

• RustQ.Meta — defrust, module options, Rusty-Elixir lowering entry point
• RustQ.Type — typespec vocabulary
• RustQ.Rust.AST.Builder — AST constructors
• RustQ.Rust.AST.PatternBuilder and RustQ.Rust.AST.TypeBuilder
• RustQ.Syn and RustQ.Syn.Index — Rust source introspection
• RustQ.Binding.Callable, RustQ.Binding.Source, RustQ.Binding.Index — callable metadata/inference inputs
• RustQ.Rustler and RustQ.Rustler.Schema — Rustler helper generation
• RustQ.Meta.Lower and RustQ.Meta.Inference — current lowering/inference behavior
• guides/using-rustq-well.md — expanded guide with examples

Verification

For non-trivial changes:

• mix ci
• mix rustq.gen --check where applicable
• downstream dogfood CI when changing shared generators
• generated Rust: cargo fmt --check, cargo check, cargo clippy -- -D warnings
• compare generated size after the generator remains readable

Clippy-clean Rust is necessary, not sufficient. RustQ code should also be beautiful at the generator layer.