RustQ.Native (rustq v1.0.0-rc.19)

Copy Markdown View Source

Builds and loads a Rustler NIF crate generated entirely from Rusty-Elixir.

use RustQ.Native makes the current module a native compilation unit and imports RustQ.Meta. Public entrypoints use defnif; generated helper functions use defrust or defrustp.

defmodule MyApp.Native do
  use RustQ.Native

  @spec add(integer(), integer()) :: integer()
  defnif add(left, right), do: left + right
end

RustQ generates the crate under the Mix build directory, compiles it with Cargo, copies the native library into the application's priv/native directory, and injects the NIF loader. No checked-in Rust or Cargo files are required for this path.

Genuine native policy remains explicit. Use :otp_app, :crate, :mode, :cargo, or :crates only when their inferred defaults are not appropriate. Generated crates are formatted before compilation. Existing RustQ.Meta options such as :rust_sources, :rust_packages, and :callable_modules may be passed alongside them.

Existing and precompiled crates can use RustQ as an item generator without transferring build or loading ownership:

use RustQ.Native, build: false, load: false

RustQ.Native.items/1 then returns ABI-prepared functions, codecs, and resource implementations for splicing into the externally-owned crate.

Summary

Functions

Called by RustQ.Meta before a native module compiles: prepares its items for the NIF boundary, defines __rustq_native_items__/0 and __rustq_native_source__/0, and, when the module builds its crate, compiles it and adds the loader.

Makes the calling module a native compilation unit: validates the native options, prepares the generated crate's Cargo.toml so its crates' metadata can be read, and passes the remaining options to use RustQ.Meta.

Returns ABI-prepared Rust items from a RustQ.Native module.

Returns ABI-prepared Rust source without crate imports or initialization.

Functions

__compile_native__(env, values, opts, exports)

Called by RustQ.Meta before a native module compiles: prepares its items for the NIF boundary, defines __rustq_native_items__/0 and __rustq_native_source__/0, and, when the module builds its crate, compiles it and adds the loader.

__using__(opts)

(macro)

Makes the calling module a native compilation unit: validates the native options, prepares the generated crate's Cargo.toml so its crates' metadata can be read, and passes the remaining options to use RustQ.Meta.

items(module)

@spec items(module()) :: [RustQ.Rust.AST.item()]

Returns ABI-prepared Rust items from a RustQ.Native module.

source(module)

@spec source(module()) :: String.t()

Returns ABI-prepared Rust source without crate imports or initialization.