sn-bindgen

Scala 3 Native binding generator to C libraries

SBT plugin

Choosing a different version

Use bindgenVersion to choose another version of bindgen (by default it matches the plugin version)

Overriding path to bindgen binary

bindgenBinary (File)

By default it's resolved from Sonatype for your particular platform.

bindgenBinary := baseDirectory.value / "my-custom-binary"

Different modes of operation

bindgenMode: bindgen.interface.bindgenMode

This parameter controls the way the bindgen is invoked and the location where the generated files will be placed

Source/resource generator mode

Value ResourceGenerator, the default.

In this mode the bindings will be regenerated automatically when the project is compiled or run.

The generated files are put in locations that are usually ignored by VCS (under target).

Manual mode

Value Manual(scalaDir: File, cDir: File).

In this mode you control the location of generated Scala/C files, and you need to manually invoke the generator by calling bindgenGenerateScalaSources and bindgenGenerateCSources.

This mode is useful for bindings you don't intend to modify often, and want to the sources available in checked in code.

For example, the bindings to libclang which underpin this very project are generated using this mode and checked in on Github.

CLI

Passing clang flags

Version 0.2.3 and above

You can pass any clang flags by adding a -- to CLI arguments and passing clang flags after it. Example:

bindgen --package pack --header head.h -- -x c++ -Lfolder -lcurl

In this example, flags -x c++ -Lfolder -lcurl will be passed to clang when analysing the code.

Before version 0.2.3:

--clang bla or --clang-include <folder> to specifically create -I<folder> flag

Full help

Usage: bindgen --package <string> --header <string> [--scala] [--c] [--link-name <string>] [--use-braces] [--c-import <string>]... [--clang-include <string>]... [--clang <string>]... [--quiet] [--trace | --info | --warning | --error] [--llvm-bin <string> | --clang-path <string> | --no-system] [--render.no-constructor <string>] [--render.opaque-structs <string>] [--render.no-comments] [--render.no-location] [--render.external-path <string>]... [--render.external-name <string>]... [--out <string>] [--multi-file] [--export] [--exclude-system-path <string>]... [--flavour <string>]

Generate Scala 3 native bindings from C header files
Version: 0.2.3
Built using Scala 3.3.6 and Scala Native 0.5.7

Options and flags:
    --help
        Display this help text.
    --package <string>
        Package name (Scala) for generated code
    --header <string>
        C header file with definitions you want bindings for
    --scala
        Generate Scala part of the binding
    --c
        Generate C part of the binding
    --link-name <string>
        Library name for linkage (i.e. 'clang' is equivalent to -lclang flag)
    --indentation-size <integer>
        number of spaces used for indentation (default: 2)
    --base-indentation <integer>
        Base indentation of generated Scala code (default: 0)
    --use-braces
        Generate Scala part of the binding with braces or significant whitespace
    --c-import <string>
        List of C imports to add to generated C file (at the very least you will need the header file for the library itself)
    --clang-include <string>
        List of include paths passed to Clang
    --clang <string>
        List of flags to pass directly to Clang
    --quiet
        Don't output the binding to STDOUT (if you are debugging, for example)
    --trace
        Output 'trace' log messages or above
    --info
        Output 'info' log messages or above
    --warning
        Output 'warning' log messages or above (this is the default)
    --error
        Output 'error' log messages or above
    --exclusive-prefix <string>
        When provided, only definitions that start with this prefix will be rendered
    --llvm-bin <string>
        Path to the LLVM installation bin/ folder
        If provided, the clang binary from that folder will be used to
        figure out system headers folders
    --clang-path <string>
        Path to the Clang executable
        If provided, the binary will be used 
        figure out system headers folders
    --no-system
        Do NOT attempt to find clang binary and use it to figure out system headers
        Note that this puts the responsibility of providing paths to common system headers on you
        You can use --clang-include option for that
    --render.no-constructor <string>
        Comma-separated list of names (or wildcards) of structs, for which to NOT render the constructor
        (apply method that takes all the parameters), useful when 
        you see a 'UTF8 string too large while running genBCode'
        examples: 
                    --render.no-constructor _GFileOutputStreamClass,_GFileIface
                    --render.no-constructor 'nk_context,nk_style*'
    --render.opaque-structs <string>
        Comma-separated list of names (or wildcards) of structs, which will be rendered as CArray[...], rather than precise CStruct* - 
        this can be necessary to circumvent the UTF8 string too large issue
        examples: 
                    --render.opaque-struct_GFileOutputStreamClass,_GFileIface
                    --render.opaque-struct 'nk_context,nk_style*'
    --render.no-comments
        Don't render the comment strings from the source
    --render.no-location
        Don't render the header location for each symbol
    --render.external-path <string>
        Render all definitions from a matching path as if they were imported from some package
        example: --render.external-path '*/cairo.h=libcairo'
    --render.external-name <string>
        Render all definitions with matchign names as if they were imported from some package
        example: --render.external-name 'cairo_*=libcairo'
    --out <string>
        Path to file where code will be generated. If not provided, result is sent to STDOUT
    --multi-file
        Produce binding in multiple files, which should improve compilation times if the number of types/functions is large
    --print-files
        (internal use only) Output to stdout the files written by bindgen, 1 per line
    --export
        Generate functions as @exported, so that the generated Scala code can be used as part of a shared/static library
    --temp-dir <string>
        Path where temporary files will be created during clang interrogation (clang needs to be invoked to get the system headers paths
    --exclude-system-path <string>
        List of paths to mark as non-system (helpful if Clang reports some paths you'd rather not ignore)
    --flavour <string>
        Flavour of bindings to generate, all values: scala-native04, scala-native05

Environment Variables:
    LLVM_BIN=<string>
        Path to LLVM installation's bin/ folderIf provided, the clang binary from that folder will be used to
    figure out system headers folders