Embed a virtual machine in a host application.

Embed API

Connect host code to the runtime.

The embedding interface lets a C application create an interpreter, load portable bytecode, execute it, and exchange selected values with the virtual machine. The API is organized around an opaque interpreter handle and packfiles containing bytecode.

Quick start

A minimal host program creates an interpreter, reads a bytecode file, loads it, runs it, and releases the interpreter.

#include <runtime.h>
#include <runtime/embed.h>
#include <runtime/extend.h>

int main(int argc, char *argv[])
{
    Runtime_Interp interp;
    Runtime_PackFile pack;

    interp = Runtime_new(NULL);
    if (!interp) return 1;

    pack = Runtime_readbc(interp, "program.pbc");
    Runtime_loadbc(interp, pack);
    Runtime_runcode(interp, argc, argv);

    Runtime_destroy(interp);
    return 0;
}

Core data types

The public interface uses opaque handles and runtime-defined scalar types. Treat these values as API objects rather than accessing internal members directly.

Interpreter lifecycle

Create the first interpreter with a null parent. Additional interpreters may inherit shared runtime structures from the first instance where supported by the implementation.

Runtime_Interp Runtime_new(Runtime_Interp parent)

Creates an interpreter. Check the return value before using it.

void Runtime_set_run_core(Runtime_Interp interp, Runtime_RunCore core)

Selects an execution core. The default is appropriate when no specialized execution behavior is required.

void Runtime_destroy(Runtime_Interp interp)

Releases interpreter resources according to the runtime version in use.

void Runtime_exit(Runtime_Interp interp, int status)

Runs registered exit handlers and terminates through the runtime’s exit path.

Loading and running bytecode

Bytecode can be read from a path, loaded into the interpreter, and executed with the host process arguments.

Runtime_PackFile Runtime_readbc(Runtime_Interp interp, const char *path)

Reads bytecode or a compatible source representation and returns a packfile handle.

void Runtime_loadbc(Runtime_Interp interp, Runtime_PackFile pack)

Loads the packfile into the interpreter before execution.

void Runtime_runcode(Runtime_Interp interp, int argc, char *argv[])

Runs the loaded code and passes the host arguments to the runtime program.

void Runtime_load_bytecode(Runtime_Interp interp, const char *path)

Loads bytecode or source directly. Some implementations require a prepared dummy packfile first.

Compiler and linker flags

Applications need the runtime headers and libraries, together with any platform dependencies. When the installation provides a package-config file, query it rather than hard-coding installation paths.

pkg-config --modversion runtime
pkg-config --cflags runtime
pkg-config --libs runtime
pkg-config --cflags --libs runtime

cc src/host.c `pkg-config --cflags --libs runtime`

If the package is installed outside standard search paths, set the relevant package-config path before querying the metadata.

Calling a runtime routine

A host application can load a program as a library, locate a named routine, and call it using a compact signature.

Runtime_Interp interp = Runtime_new(NULL);
Runtime_PackFile pack = PackFile_new_dummy(interp, "host-code");
Runtime_String name = string_from_literal(interp, "program.pir");
Runtime_load_bytecode(interp, name);

name = string_from_literal(interp, "entry");
Runtime_PMC routine = Runtime_find_global_cur(interp, name);
Runtime_call_sub(interp, routine, "v");

Runtime_destroy(interp);

Signature symbols describe return and argument categories. A common set includes v for void, I for integer, N for floating point, S for string, and P for a managed value.