64 lines
3.1 KiB
Markdown
64 lines
3.1 KiB
Markdown
## Kuroko C API Documentation {#embedding}
|
|
|
|
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](https://launchpad.net/~k-lange/+archive/ubuntu/kuroko/).
|
|
|
|
### Getting Started {#getting-started}
|
|
|
|
```c
|
|
#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.
|