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 ordinary Elixir macros when you want reusable Rusty-Elixir source. They run while compiling the Elixir generator and do not intentionally leave a Rust macro in the output.

For repeated generated bridge code, first use normal Elixir metaprogramming: helper functions that return quoted Rusty-Elixir, defmacro, quote, unquote, unquote_splicing, schema transforms, Enum.map, recursion, and pattern matching. RustQ is designed to lower valid Elixir-shaped Rusty-Elixir; do not invent a separate mini-language or string template when ordinary Elixir can produce the Rusty-Elixir you need.

Use defrustmacro for the different case where repeated generated Rust should call one compact macro_rules! helper while the helper body remains Rusty-Elixir:

defrustmacro field(term, name, type: :ty) do
  decode_as!(required_field(term, name), type)
end

Plain arguments are :expr fragments; annotate type arguments with :ty. Use :ident and :literal when a macro captures Rust identifiers or literal tokens. Do not write Rust syntax in the body. In short: defmacro improves the authoring layer; defrustmacro intentionally changes the generated Rust shape.

defrustmacro can also emit Rust items when the body contains normal Rusty-Elixir defrust. Keep the signature declarative and put the implementation in the inner defrust body:

defrustmacro sparse_message(
  fn: name(:ident),
  env: env(:ident),
  decoder: decoder(:ident),
  module: module_name(:literal),
  capacity: capacity(:literal),
  fields:
    repeat do
      field_id(:literal)
      field_name(:literal)
      field_mode(:ident)
      field_decode(:ident)
    end
) do
  @spec name(R.path(:Env, R.lifetime(:a)), R.mut_ref(R.path(:Decoder))) ::
          R.nif_result(term())
  defrust name(env, decoder) do
    decode_sparse_fields(
      env,
      decoder,
      module_name,
      capacity,
      ref(
        array([
          repeat fields do
            struct_literal(Field,
              id: field_id,
              name: field_name,
              repeated: repeated!(field_mode),
              decode: field_decode
            )
          end
        ])
      )
    )
  end
end

Inside defrustmacro, declared captures such as env, module_name, and field_id lower to Rust macro variables ($env, $module_name, $field_id). repeat fields do ... end is a macro-template repetition, not a runtime loop. Use it only in the documented defrustmacro capture/template positions. If you need to assemble repeated Rusty-Elixir statements or helper bodies, prefer ordinary Elixir quote/unquote_splicing or helper macros at the authoring layer instead of adding new RustQ-specific syntax.

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.

Generate Rust type items from @type

RustQ can emit Rust type declarations from ordinary Elixir @type aliases. Use this before hand-building Rust struct/enum/type-alias strings.

Map types become Rust structs:

@type point :: %{
  required(:x) => R.f32(),
  required(:y) => R.f32()
}

Struct types become Rust structs too:

defmodule Click do
  defstruct [:name]
end

@type click :: %Click{name: String.t()}

Atom unions become Rust enums, and struct unions become tuple enums:

@type mode :: :src_over | :multiply
@type event :: click() | resize() | scroll()

Use R.enum(...) when you need an explicit Rust enum with tuple payloads but do not want to overload ordinary Elixir tuple unions:

@type skip_kind :: R.enum(one: [skip_fn()], repeated: [skip_fn()], bytes: [])

Construct those variants from defrust with enum_variant/2+, not token macros:

defrust kind(repeated, skip) do
  if repeated do
    enum_variant(SkipKind, :repeated, skip)
  else
    enum_variant(SkipKind, :one, skip)
  end
end

Type items are available through __rustq_type_items__/0; use them in generators just like defrust items from __rustq_items__/0 / RustQ.Meta.AST.item/2. This is the preferred path for support structs such as small descriptor records used by generated defrust helpers.

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.