🥮 mooncakes.io

    dynlib

    Checked dynamic library loading for MoonBit native targets.

    moonbit
    native
    wasm
    dynamic-library
    ffi
    Download zip
    Version
    0.2.1
    License
    Apache-2.0
    Repository
    Last updated
    11 hours ago
    Downloads
    361

    #dynlib

    Nanaloveyuki/dynlib is a MoonBit package for loading dynamic libraries on native targets. The package also compiles for js, wasm, and wasm-gc; those targets return UnsupportedTarget because their runtime does not provide the native dynamic-library loader used by this API.

    #Install

    Add the package to your moon.mod:

    import {
      "Nanaloveyuki/dynlib@0.2.1",
    }

    Build the consuming package for a native target to load libraries. Cross-target builds remain available when the package is part of a shared library.

    #Load, Resolve, and Read an Address

    Load a platform library name or an absolute library path, resolve a symbol, then obtain its address:

    let library = match @dynlib.load("example-library") {
      Ok(value) => value
      Err(error) => abort("load failed: \{error}")
    }

    let symbol = match library.resolve("example_symbol") {
      Ok(value) => value
      Err(error) => abort("symbol missing: \{error}")
    }

    let address = match symbol.address() {
      Ok(value) => value
      Err(error) => abort("library was closed: \{error}")
    }

    // Use address only with an explicit, ABI-correct native binding.
    ignore(address)

    dynlib does not invoke resolved symbols. The consuming package owns the FFI signature and calling convention.

    DynlibError does not include operating-system diagnostic strings or requested paths. Handle InvalidLibraryPath, InvalidSymbolName, LoadFailed, ResolveFailed, SymbolNotFound, OutOfMemory, InvalidUtf8, and UnsupportedTarget explicitly when the distinction matters.

    #Close

    Close each loaded library at a deterministic shutdown point:

    ignore(library.close())

    Library::close is idempotent. After it succeeds, Library::resolve and Symbol::address return Closed; do not retain or use a previously returned address. Do not call resolve, address, or close concurrently for the same library; the package does not provide a synchronization or symbol lease API.

    DynlibError

    source
    pub(all) enum DynlibError {
      UnsupportedTarget
      InvalidLibraryPath
      InvalidSymbolName
      InvalidUtf8
      OutOfMemory
      LoadFailed
      ResolveFailed
      SymbolNotFound(String)
      InvalidHandle
      CloseFailed
      Closed
    } derive(Eq, 
    Debug    )

    A failure produced while loading, resolving, or closing a dynamic library.

    DynlibError::equal

    source
    fn DynlibError::equal(DynlibError, DynlibError) -> Bool

    Library

    source
    pub struct Library {
      // private fields
    }

    An explicitly owned native dynamic-library handle.

    Call close when the library is no longer needed. Closing is idempotent.

    Library::close

    source
    fn Library::close(self : Library) -> Result[Unit, DynlibError]

    Unloads the library. Calling close again returns success without touching the operating system handle.

    Library::is_open

    source
    fn Library::is_open(self : Library) -> Bool

    Returns whether this library remains open.

    Library::resolve

    source
    fn Library::resolve(self : Library, name : String) -> Result[Symbol, DynlibError]

    Resolves a native symbol without invoking it.

    Dynamic function calls are deliberately outside this package's API because calling conventions and signatures must be modeled by the consuming FFI.

    Symbol

    source
    pub struct Symbol {
      // private fields
    }

    A resolved symbol tied to the library that produced it.

    The address cannot be obtained after the source library is closed.

    Symbol::address

    source
    fn Symbol::address(self : Symbol) -> Result[UInt64, DynlibError]

    Returns a raw symbol address while its source library remains open.

    The caller must not retain or invoke the address after Library::close.

    load

    source
    fn load(path : String) -> Result[Library, DynlibError]

    Loads a dynamic library by absolute path or platform loader name.

    Paths are encoded as UTF-8. On Windows they are converted to UTF-16 before calling the operating system loader.

    Source Files

    Powered by MoonBit

    Site sourceReport issuePackagesBuild queueSkillsStatistics

    © 2026 mooncakes.io