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_initVM(0);
krk_startModule("__main__");
krk_interpret("print('hello, world')", "<stdin>");
krk_freeVM();
return 0;
}
kuroko.h
Top-level header with configuration macros.
KrkVM::krk_freeVM
void krk_freeVM(void)
Release resources from the VM.
Definition: vm.c:953
KrkVM::krk_initVM
void krk_initVM(int flags)
Initialize the VM at program startup.
Definition: vm.c:868
vm.h
Core API for the bytecode virtual machine.
krk_interpret
KrkValue krk_interpret(const char *src, const char *fromFile)
Compile and execute a source code input.
Definition: vm.c:3219
krk_startModule
KrkInstance * krk_startModule(const char *name)
Set up a new module object in the current thread.
Definition: vm.c:3209

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

Headers

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:

  • KRK_THREAD_ENABLE_TRACING
    Prints instruction traces during execution.
  • KRK_THREAD_ENABLE_DISASSEMBLY
    Prints function bytecode disassembly whenever the compiler is called.
  • KRK_THREAD_SINGLE_STEP
    Halts execution and calls the debugger before every instruction.
  • KRK_GLOBAL_REPORT_GC_COLLECTS
    Prints a message each time the garbage collector is run.
  • KRK_GLOBAL_ENABLE_STRESS_GC
    Causes the garbage collector to be called on every allocation (from the main thread).
  • KRK_GLOBAL_CLEAN_OUTPUT
    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.