QuickStart

Welcome to gentool quick start!

Let's start using the tool with creating the project.

It is still under development so let's take project file from one of the tests, for example tests/basic_cpp01/basic.json

{
    "$schema": "./config-schema.json",
    "version": 1,
    "input": {
        "std": "c++11",
        "paths": ["../cpp"],
        "includes": ["../cpp/"],
        "system": [],
        "defines": [],
        "cflags": []
    },
    "output": {
        "path": "generated.d",
        "target": "dlang",
        "attr-nogc": false,
    }
}

At the moment of writting all document sections are required, however as you can see the minimum required is input language standard and paths, and output path and target language.

Paths section decribes what you would like to see in produced bindings, in other words everything that is not on the paths will be ignored.

It is possible to use environment variables in paths in form $(PATH_VAR_NAME)

If variable is an array only the first value is used.

{
    ...
    "paths": ["$(MY_PATH)/include"],
    "includes": ["$(OTHER_PATH)/build/include"]
    ...
}

Now suppose we want to generate bindings for someLib, all you have to do is:

• Put required macro defines (compiler -D switch)
• Fill in where to search for headers (including system/STL)
• (Optionally) compiler flags

For most cases it is ok to ignore compiler flags, unless the project makes use of them for code generation or conditional compilation.

Note: Code will be generated for the same archtecture as the gentool binary itself, it is possible to add -m32 or -m64 switch to cflags to override the architecture.

Assume that we saved the library at /home/usr/cpp/mylib, and it has include and source folders and doesn't have other dependencies.

So what we have after these steps

project.json:

{
    "$schema": "./config-schema.json",
    "version": 1,
    "input": {
        "std": "c++11",
        "paths": ["/home/usr/cpp/mylib/include"],
        "includes": ["/home/usr/cpp/mylib/include"],
        "system": [],
        "defines": [],
        "cflags": []
    },
    "output": {
        "path": "mylib_generated.d",
        "target": "dlang",
        "attr-nogc": false,
        "no-param-refs": false,
        "skip-bodies": false,
        "mangle-all": false
    }
}

The first thing is that it does includes itself, this is important because 'paths' is only used by the tool, and not the "compilation" process.

Also note that system and includes sections handled identically, it is safe to ignore system headers section and in fact in future it might be deprecated.

Now after we fill up the required paths and defines let's generate the bindings.

gentool ./project.json

And that's it, it should produce our fresh new bindings.

Please note though it is still under development, so there might be some quirks, issues, bugs, errors and just not yet finished language constructs. In this case it is up to the user to clean up the produced code

Available output options

attr-nogc - This serves the purpose of marking every function with @nogc on D side. However one can easily do so on module scope level or block level

@nogc:
    // .. the rest of the file

@nogc
{
    // here comes @nogc functions
}

no-param-refs - Used to strip ref from function parameters that have body available, the reason behind this option is to allow structs and primitives to be used without much PITA until relevant DIP for rvalue refs is implemented.

skip-bodies - Skip inlined functions bodies. Might be useful as code conversion is not yet completed, which means there will always be some manual work after conversion.

mangle-all - Writes mangled names to every function. Might be useful as D name mangling interop is not 100% accurate, and in some cases will result in unresolved symbols on link stage.

One can refer to Known issues and clean-ups section for more info.