bindbc-generate ~main

Bindbc-Generate

The purpose of this repository is to auto generate C bindings based on the bindbc pattern, it has dependencies on:

• Dlang + Dub for compiling D code;

• D++(Dpp).

Dpp is used to translate struct and enum definitions from C to D. The generator may be used without Dpp, but in this case only the function aliases and bind symbols will be generated.

You will also likely need Clang(libclang), as a dependency of D++. See more in their repo.

PR's are welcome.

If you use bindbc-generator in your project, please, link to this repo. If you face an issue when generating bindings, create an issue.

What's New

BindBC Generator now supports plugin programming. Plugins are designed to augment the behavior of the main program, without imposing dependencies on it. They are not compiled into the main program, but loaded and executed at runtime instead.

Currently, the only way to define plugins is to put their source code in a folder with the name of the plugin, within the plugins folder. So, the cimgui plugin would be located at plugins/cimgui.

When you try to use your plugin via the generator, it will try to compile your source files and generate a dll of your plugin as output. Then it would link against that dll.

To write a plugin, create a class that inherits from the Plugin abstract class.

myplugin.d

import plugin;

class MyPlugin : Plugin
{
    // Return the name of the plugin. 
    // It will have to be referenced by this name on the command line.
    override string target(){return "myplugin-behavior";} 

    // The first function called after instantiation.
    // Should return `Plugin.SUCCESS` or `Plugin.ERROR`.
    override int main(string[] args) {}

    // This help string will be shown by the generator when they are passed no arguments
    override string getHelpInformation() {}

    // This function must return the string to be processed by the generator; 
    // Currently only `cppFuncToD` is available
    override string convertToD_Pipe() {}

    // This is the last execution point of your plugin called after binding have been generated.
    // Here, you should any additional files that were not automatically generated by the generator.
    override int onReturnControl(string processedString) {}
    
    // This function is defined in the base class.
    // Use it to return from main, passing a message to the main program.
    final int returnError(string error);
}

// This function will be called by the generator after it loads the dll.
// If you have more plugin classes in the dll, you may define more such functions.
// They will all be executed by the generator.
extern(C) export Plugin exportMyplugin(){return new MyPlugin();}

Now, when executing the program, you will need to pass at least one argument, like below. Unless you pass at least one argument, the plugin won't be executed.

bindbc-generate --load-plugin="myplugin" --plugin-args myplugin-behavior="[arg1, arg2, arg3]"

Just to be clear, --load-plugin loads the code in the plugin folders with that name, while --plugin-args runs the plugin with the given name (target), passing the given arguments.

--load-plugin (or -l) lets you choose which plugins to load. You can pass --load-all instead to load every plugin in the plugins folder.

--plugin-args (or -a) will let you pass arguments to your plugin's main function. Separate the arguments by spaces. Remember to pass the target name, not the plugin name.

WARNING

If no arguments are passed, the plugin execution is skipped. If none of the plugins were given arguments, their help messages are displayed:

bindbc-generate --load-plugins="myplugin" --plugin-args myplugin-behavior="[]"

Options

Bindbc-generator options.
If you find an issue with the content generation, report it at
https://www.github.com/MrcSnm/bindbc-generator

          --dpp-path Path to dpp executable. Searched for in PATH if not specified.
      --plugins-path Path to plugins folder. Default is `plugins`.
         --temp-path Path to temporary directory. Default if `temp`.
-d          --dpparg Arguments to be passed to dpp, --preprocess-only is always included. Pass multiple arguments via comma
-f            --file Target header to get functions and types for generation
-p         --presets
(Presets and custom are mutually exclusive)
Function getter presets:
   cimgui - Preset used for compiling libcimgui -> https://github.com/cimgui/cimgui

-n         --notypes Don't execute Dpp, and don't generate the types file
-c          --custom
Flags m and g are always added, $1 must always match function without exports.
Examples:
    void func(char* str);
    int main();

-u --use-func-prefix
This will be the prefix of your regex.
The postfix will be a predefined one for function format:
    Appends ^(?: at the start(The one which is meant to be ignored)
    Appends )(.+\);)$ at the end (Finish the ignored one and append the function $1 one)

-l    --load-plugins
Loads plugins located in the plugins folder. For the plugin being loaded it must:
    1: Export a function named export(Modulename) which returns a Plugin instance.
    2: Have a compiled .dll or .so following the scheme 'libpluginPLUGIN_FOLDER_NAME'
        2.1: If you need many exports in a single dll, create a package.d with public imports and
        compile it, plugin finding is first folder only, i.e: not recursive.

          --load-all
Loads every plugin located in the plugins folder
-a     --plugin-args
Arguments to pass to a plugin's entry point.
Only the plugins with at least args 1 arg will be executed, pass a null string if you wish
to pass only the current working dir.

Example on multiple args-> --plugin-args myplugin="[arg1, arg2, arg3]"

Reserved arguments are:
    d-conv -> Converts from C to D; every plugin that receives that argument will have its string from convertToD_Pipe() converted to D style

-r       --recompile
Using this option will force a recompilation of the plugins!
             --debug
Compile dynamic libraries with debug symbols enabled
-h            --help This help information.