Kuroko C API Documentation

This documentation covers using Kuroko 1.1 as a scripting language in a host C application and assumes a relatively recent Linux or similarly POSIX-y build environment.

We'll also assume you've already installed Kuroko from a package that includes source headers, such as the PPA.

Getting Started

#include <kuroko/kuroko.h>
#include <kuroko/vm.h>
int main(int argc, char *argv[]) {
krk_interpret("print('hello, world')", "<stdin>");
return 0;
Top-level header with configuration macros.
void krk_freeVM(void)
Release resources from the VM.
Definition: vm.c:992
void krk_initVM(int flags)
Initialize the VM at program startup.
Definition: vm.c:904
Core API for the bytecode virtual machine.
KrkInstance * krk_startModule(const char *name)
Set up a new module object in the current thread.
Definition: vm.c:3219
KrkValue krk_interpret(const char *src, char *fromFile)
Compile and execute a source code input.
Definition: vm.c:3229

Let's start by looking at the example code above.


Kuroko's public API is exposed primarily through the <kuroko/kuroko.h> header.

<kuroko/vm.h> provides internal functions for finer control over how the VM operates.

Other headers provide convenience functions and macros for building C extensions.

Initializing the VM

Our first task in integrating Kuroko into an embedded application is to set up the VM, which we do with krk_initVM(). This function takes one paramater representing the initial global and thread flags, which control debugging features for tracing. In our example code, we do not need to use to use any debug features so we pass 0.

Valid flags to pass to krk_initVM() include:

    Prints instruction traces during execution.
    Prints function bytecode disassembly whenever the compiler is called.
    Halts execution and calls the debugger before every instruction.
    Prints a message each time the garbage collector is run.
    Causes the garbage collector to be called on every allocation (from the main thread).
    Generate tracing data. vm.callgrindFile must be set to a writable stream to store the intermediate data collected by the VM.
    Disables automatic printing of uncaught exception tracebacks. Use krk_dumpTraceback() to print a traceback from the exception in the current thread to stderr.

Be careful when using KRK_GLOBAL_CLEAN_OUTPUT when threading is available; uncaught exceptions from threads will not be automatically printed and are trickier to catch from C code.

Starting a Module

All Kuroko code runs in the context of a module. When we run code directly using krk_interpret(), such as when providing a REPL or calling snippets, or by using krk_runfile() to execute the contents of a file, we need to establish our own module first. krk_startModule() creates a module context and gives it a name. We use the name __main__ as a convention for directly executed code, distinguishing it from imported code.

Calling the Interpreter

We pass C strings containg Kuroko code to krk_interpret() to be run by the interpreter. The second argument to krk_interpret() provides a filename for the source of the code, or representative string to show in tracebacks for code that did not come from a file.

Next up, we'll look at Binding C Functions.