Rune

Rune Documentation

Rune is the name of the configuration file that is used to configure the behaviour of the runic program. By default runic will load the rune.yml file from the current directory. It is a yaml file so therefore it supports both yaml and json code. Below you can find the documentation for all possible entries of a rune.

Table of Contents

1. Rune entries
2. platforms entry
3. Multi Platform Values
4. to.trim_prefix.enum_type_name entry
5. from.load_all_includes entry
6. to.use_when_else entry

Rune entries

Name	Description	Type	Required	Default
version	Version of the rune configuration. This will be relevant when version 1 is released	int	✅	-
platforms	The platforms for which the from runestone should be generated for. more	array[string]	❌	host
wrapper	Generate a wrapper for functions that do not get exported into the library. more	map	❌	-
from	Configuration for the from language. This can either be paths to different runestone files or a configuration to generate a new one	string / array[string] / map	✅	-
to	Configuration for the to language. This can either be a file path or a configuration to generate bindings	string / map	✅	-

From Language

Name	Description	Type	Required	Default	Multi Platform
from.language	Language of the code that will be parsed	string	✅	-	-
from.shared	Path to the shared (dynamic) library. Can either be a path to a specific file or a file name that gets loaded from the system paths. Either from.shared or from.static should be provided	string	❌	-	✅
from.static	Path to the static library. Can either be a path to a specific file or a file name that gets loaded from the system paths. Either from.shared or from.static should be provided	string	❌	-	✅
from.headers	List of header files to parse when using c language	string / array[string]	(✅)	-	✅
from.packages	List of packages to parse when using odin language	string / array[string]	(✅)	-	✅
from.includedirs	List of include directories to add with the -I flag when parsing c code	string / array[string]	❌	-	✅
from.defines	Map of macros to add with the -D flag when parsing c code	map[string][string]	❌	-	✅
from.flags	List of clang flags that will be appended at the end when parsing c code using libclang	string / array[string]	❌	-	✅
from.enable_host_includes	Wether system headers (e.g. /usr/include) should be visible to libclang when parsing c code. How system include files are handled.	bool	❌	false	✅
from.disable_system_include_gen	By default runic generates empty system header stubs to properly disable missing types when parsing ccode. Using this field this behaviour can be disabled	bool	❌	false	✅
from.disable_stdint_macros	By default runic defines macros for stdint types (e.g. uint32_t = usigned int) when parsing c code. Using this field this behaviour can be disabled	bool	❌	false	✅
from.load_all_includes	Parse all included headers if it was part of the main header (except for extern). more	bool	❌	false	✅
from.forward_decl_type	runic tries to detect forward declarations that are not implemented and adds them as a type. This field controls which type will be used	string	❌	#Opaque	✅
from.overwrite	Here you can overwrite everything that just wont get parsed in a way you want. more	map	❌	-	✅
from.ignore	Using this field you can ignore what you do not want in the generated runestone	map	❌	-	✅
from.extern	If the library references something from an extern source (e.g. header file of another library) you can tell runic here what comes from an extern source. The value of this field depends on the language. When using c this field consists of paths to header files. more	string / array[string]	❌	-	-
from.remaps	Using this field you can change the name of symbols. This is the name with which it will actually be linked to. When generating odin bindings this refers to the link_name	map[string][string]	❌	-	-
from.aliases	Using this field you can add aliases to symbols, so that they can be referenced using multiple names	map[string][string / array[string]]	❌	-	-

Overwrite

Name	Description	Type	Required	Default
from.overwrite.types	Here you can overwrite types. Either all of it or just a part of the types, like certain members of the structs	map[string][string]	❌	-
from.overwrite.functions	Here you can overwrite functions. You can overwrite either complete functions or just parts of it (e.g. param.4.type, param.3.name, return)	map[string][string]	❌	-
from.overwrite.variables	Here you can overwrite the types of variables. You can also just overwrite parts of the type	map[string][string]	❌	-
from.overwrite.constants	Here you can overwrite constants. You can also overwrite the name of a constant	map[string][string]	❌	-

Ignore

Name	Description	Type	Required	Default
from.ignore.constants	Ignore certain constants (which refers to macros when using c)	string / array[string]	❌	-
from.ignore.functions	Ignore certain functions	string / array[string]	❌	-
from.ignore.variables	Ignore certain variables	string / array[string]	❌	-
from.ignore.types	Ignore certain types	string / array[string]	❌	-

Wrapper

Name	Description	Type	Required	Default	Multi Platform
wrapper.language	The programming language for which to generate the wrapper (currently only c is supported)	string	✅	-	-
wrapper.from_compiler_flags	Wether to import the compiler flags from the from section. (defines, includedirs, flags, extern)	bool	❌	true	✅
wrapper.defines	Define macros when parsing the in_headers (corresponds to the -D clang flag). This will be added on top of from_compiler_flags	map[string][string]	❌	-	✅
wrapper.includedirs	Add include search paths when parsing the in_headers (-I clang flag). Will be added to from_compiler_flags	string / array[string]	❌	-	✅
wrapper.flags	Add arbitrary clang compiler flags when parsing the in_headers. Will be added on top of from_compiler_flags	string / array[string]	❌	-	✅
wrapper.load_all_includes	Consider all header files that are included as part of the main file (except for extern)	bool	❌	false	✅
wrapper.extern	Consider some included headers as extern and don't parse them if load_all_includes is enabled. more	string / array[string]	❌	-	✅
wrapper.in_headers	The header files to parse (only c)	string / array[string]	✅	-	✅
wrapper.out_header	The header file that gets generated and contains declarations for the wrapper functions	string	✅	-	-
wrapper.out_source	The c source file that will contain all the definitions for the wrapper functions	string	✅	-	-
wrapper.add_header_to_from	Automatically add the out_header to from.headers	bool	❌	true	-
wrapper.multi_platform	Parse the in_headers for every platform in platforms and create separate files for each platform	bool	❌	true	-

To Language

Name	Description	Type	Required	Default	Multi Platform
to.language	The language for which to generate bindings	string	✅	-	-
to.out	Path to the output file for the bindings. The entire bindings will be written into one file	string	✅	-	-
to.static_switch	A macro which can be used to switch from the shared (dynamic) library to the static one (used in odin)	string	❌	PACKAGE_NAME_STATIC	-
to.trim_prefix	Trim prefixes of types, functions etc. This does not influence the "link_name"	string / array[string] / map	❌	-	-
to.trim_suffix	Trim suffixes of types, functions etc. This does not influence the "link_name"	string / array[string] / map	❌	-	-
to.add_prefix	Add prefixes to types, functions etc. This does not influence the "link_name"	string / array[string] / map	❌	-	-
to.add_suffix	Add suffixes to types, functions etc. This does not influence the "link_name"	string / array[string] / map	❌	-	-
to.ignore_arch	When crossing the runestones (comparing different platforms) ignore the architecture	bool	❌	false	-
to.extern	Declare sources and remaps of extern types. more	map	❌	-	-
to.package	Name of the odin package of the bindings	string	✅	-	-
to.no_build_tag	Wether not to put a build into the first line of the bindings when using odin	bool	❌	false	-
to.use_when_else	Wether to use else when for code of different platforms instead of just using when more	bool	❌	false	-
to.add_libs.shared	Add additional libraries to the foreign import keyword when linking dynamically.	string / array[string]	❌	-	✅
to.add_libs.static	Add additional libraries to the foreign import keyword when linking statically	string / array[string]	❌	-	✅
to.add_libs	Add additional libraries to the foreign import keyword when linking either dynamically or statically. On can only either use the static and shared variants or the general variant, but not all of them at the same time.	string / array[string]	❌	-	✅

Trim and Add Prefixes and Suffixes

Name	Description	Type	Required	Default
to.trim_prefix.types	Trim prefixes of types	string / array[string]	❌	-
to.trim_prefix.functions	Trim prefixes of functions	string / array[string]	❌	-
to.trim_prefix.variables	Trim prefixes of variables	string / array[string]	❌	-
to.trim_prefix.constants	Trim prefixes of constants	string / array[string]	❌	-
to.trim_prefix.enum_type_name	Automatically trim the type name of enums from their entries e.g. Direction :: enum {DIRECTION_UP, ...} -> Direction :: enum {UP, ...}. more	bool	❌	false
to.trim_suffix.types	Trim suffixes of types	string / array[string]	❌	-
to.trim_suffix.functions	Trim suffixes of functions	string / array[string]	❌	-
to.trim_suffix.variables	Trim suffixes of variables	string / array[string]	❌	-
to.trim_suffix.constants	Trim suffixes of constants	string / array[string]	❌	-
to.add_prefix.types	Add prefixes to types	string / array[string]	❌	-
to.add_prefix.functions	Add prefixes to functions	string / array[string]	❌	-
to.add_prefix.variables	Add prefixes to variables	string / array[string]	❌	-
to.add_prefix.constants	Add prefixes to constants	string / array[string]	❌	-
to.add_suffix.types	Add suffixes to types	string / array[string]	❌	-
to.add_suffix.functions	Add suffixes to functions	string / array[string]	❌	-
to.add_suffix.variables	Add suffixes to variables	string / array[string]	❌	-
to.add_suffix.constants	Add suffixes to constants	string / array[string]	❌	-

Extern Sources and Remaps

Name	Description	Type	Required	Default
to.extern.sources	Map the sources of extern types to sources of the to language. e.g. If creating bindings from c to odin the keys would be header files and the values would be package import paths	map[string][string]	❌	-
to.extern.remaps	Change the name of certain extern types to fit the naming in the to language	map[string][string]	❌	-
to.extern.trim_prefix	Wether to apply the prefix trimming of to.trim_prefix to extern types	bool	❌	false
to.extern.trim_suffix	Wether to apply the suffix trimming of to.trim_suffix to extern types	bool	❌	false
to.extern.add_prefix	Wether to add the prefixes of to.add_prefix to extern types	bool	❌	false
to.extern.add_suffix	Wether to add the suffixes of to.add_suffix to extern types	bool	❌	false

platforms entry

Here you can declare multiple platforms for which the runestone or wrapper will be generated. This is to ensure that differences on different platforms are respected e.g.: size_t being different on 32-Bit and 64-Bit. The Platforms need to be specified in the following format: OS ARCHITECTURE. Possible values for OS and ARCHITECTURE include:

• OS
  • Any
  • Linux
  • Windows
  • Macos
  • BSD
• ARCHITECTURE
  • Any
  • x86_64
  • arm64
  • x86
  • arm32

The Any values are equivalent to specifying all the available values. e.g. Linux Any refers to Linux x86_64, Linux arm64, Linux x86, Linux arm32. While Any Any refers to all operating systems and all architectures.

Multi Platform Values

Entries where Multi Platform is set to ✅ can be specified differently for every platform. This is achieved through the following syntax:

from:
  shared.linux.x86_64: "lib/linux/x86_64/libfoo.so"
  static.windows: "lib/windows/foo.lib"

The platform values are the same as in the platforms entry except that they need to be lowercased. Specyfing a value for a specific platform means that this value is used when generating for this specific platform as if it were the only value specified.

to.trim_prefix.enum_type_name entry

If enum entries are prefixed with the type name, this prefix can be trimmed automatically when setting enum_type_name to true. This only works for either screaming snake case entries or entries where the casing is the same as of the type name. e.g.:

// entry names are screaming snake case
enum SlidingDirection {
SLIDING_DIRECTION_UP,
SLIDING_DIRECTION_DOWN,
SLIDING_DIRECTION_LEFT,
SLIDING_DIRECTION_RIGHT
};

// entry names have same casing as the type name
enum SlidingDirection {
SlidingDirectionUp,
SlidingDirectionDown,
SlidingDirectionLeft,
SlidingDirectionRight
};

from.load_all_includes entry

When enabling from.load_all_includes when generating a runestone from c you can load all types from all files that are included in a file specified in from.headers. You can exclude certain files by adding them to from.extern. e.g.:

This is a file specified in from.headers:

#include <cairo.h>

void draw_stuff(cairo_t* cr);

Without adding anything to from.extern every type from cairo.h will be added as if it was part of the file itself. But by changing from.extern like this, this can be avoided:

from:
  extern:
    - "path_that_contains_cairo_h/*"

from.extern accepts glob patterns, but you can only glob files inside of one folder meaning that patterns like foo_library/** will not work. When specifying something in from.extern ideally you also want to specify it in to.extern.sources.

to.use_when_else entry

To explain what this entry does I will use an example. If you would set to.use_when_else to false the generated code could look like this:

when (ODIN_OS == .Linux && ODIN_OS == .Darwin) {
  // Code and stuff ...
}

when (ODIN_OS == .FreeBSD || ODIN_OS == .OpenBSD || ODIN_OS == .NetBSD) {
  // Other code and stuff ...
}

when (ODIN_OS == .Windows) {
  // Weird stuff that windows does ...
}

But when enabling to.use_when_else the code will look like this:

when (ODIN_OS == .Linux && ODIN_OS == .Darwin) {
  // Code and stuff ...
} else when (ODIN_OS == .FreeBSD || ODIN_OS == .OpenBSD || ODIN_OS == .NetBSD) {
  // Other code and stuff ...
} else {
  // Weird stuff that windows does ...
}

This feature is completely relient on the user checking whether the bindings work. Please use with caution.