kuroko/docs/embedding.md

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;
}

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_CALLGRIND
  Generate tracing data. vm.callgrindFile must be set to a writable stream to store the intermediate data collected by the VM.
• 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.

@bsnote{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 @ref c_functions.