Skip to content

Use Generated Code

Java / JNI / C++ Project

Includes & Build target

The following headers / code will be generated for each defined type:

Type C++ header C++ source Java JNI header JNI source
Enum/Flags my_enum.hpp NativeMyEnum.hpp NativeMyEnum.cpp
Record my_record[_base].hpp my_record[_base].cpp (+) MyRecord[Base].java NativeMyRecord.hpp NativeMyRecord.cpp
Interface my_interface.hpp my_interface.cpp (+) NativeMyInterface.hpp NativeMyInterface.cpp

(+) Generated only for types that contain constants.

Additionally djinni_jni_main.cpp is generated to provide a default implementation for JNI_OnLoad and JNI_OnUnload, if --jni-generate-main=true.

Add all generated source files to your build target, and link the C++ code against the djinni-support-lib.

Our JNI approach

JNI stands for Java Native Interface, an extension of the Java language to allow interop with native (C/C++) code or libraries.

For each type, built-in (list, string, etc.) or user-defined, Djinni produces a translator class with a toJava and fromJava function to translate back and forth.

Application code is responsible for the initial load of the JNI library. Add a static block somewhere in your code:

class Main {
    static {
      // The name  of the library is specified in / build.gradle / Makefile / CMakeLists.txt, 
      // depending on your build system.

If you package your native library in a jar, you can also use the NativeLibLoader to help unpack and load your lib(s).

Any library loaded from Java should provide the functions JNI_OnLoad and JNI_OnUnload. They are called by JNI when the library is loaded/unloaded.

Djinni uses these functions to initialize & cleanup internal structures. The generated file djinni_jni_main.cpp includes a default implementation of JNI_Onload and JNI_OnUnload functions provided by the support library.

If you are building a library that does not use JNI except through Djinni, this default should work well for you. If want to provide your own implementation of JNI_Onload and JNI_OnUnload, the generation of djinni_jni_main.cpp can be disabled by setting --jni-generate-main=false.

Objective-C / C++ Project

Includes & Build Target

Generated files for Objective-C / C++ are as follows (assuming prefix is DB):

Type C++ header C++ source Objective-C files Objective-C++ files
Enum/Flags my_enum.hpp DBMyEnum.h
Record my_record[_base].hpp my_record[_base].cpp 1⃣ DBMyRecord[Base].h DBMyRecord[Base]+Private.h
DBMyRecord[Base].mm 2⃣ DBMyRecord[Base]
Interface my_interface.hpp my_interface.cpp 1⃣ DBMyInterface.h DBMyInterface+Private.h
  • 1⃣ Generated only for types that contain constants.
  • 2⃣ Generated only for types with derived operations and/or constants. These have .mm extensions to allow non-trivial constants.

Add all generated files to your build target, and link against the djinni-support-lib.

Note that +Private files can only be used with ObjC++ source (other headers are pure ObjC) and are not required by Objective-C users of your interface.

Python / C++ Project (Experimental)

Python support in Djinni is experimental, but ready to try out. It can generate code for bridging C++ with Python 3.

For more information, you can check out the talk from CppCon 2015. Slides and video are available online.

Includes & Build Target

When bridging to Python, Djinni generates 4 types of output:

  • python Generated Python classes and proxies for interacting with C++ via CFFI.
  • cffi Python code run at build time to create a Python extension out of the C++ code.
  • cwrapper A C interface implemented in C++ to allowing Python to interact with C++ classes.
  • cpp The same C++ classes generated for all other Djinni languages.

Generated files for Python / C++ are as follows:

Type C++ header C++ source Python files CFFI C Wrapper
Enum/Flags my_enum.hpp dh__my_enum.cpp
Record my_record[_base].hpp my_record[_base].cpp 1⃣ my_record[_base].py dh__my_record.cpp
Interface my_interface.hpp my_interface.cpp 1⃣ cw__my_interface.cpp
  • 1⃣ Generated only for types that contain constants.

Additional C Wrapper files are generated for data structures; their names are encoded as:


See the in the table below a few examples:

Type C Wrapper
list<i32> dh__list_int32_t.{cpp,h,hpp}
set<string> dh__set_string.{cpp,h,hpp}
map<i32, set<string>> dh__map_int32_t_set_string.{cpp,h,hpp}

Add all generated C and C++ source files to your build target, and link it against the djinni-support-lib.

Compile the Python extension module (CFFI) by executing while providing all C Wrapper header files (.h) as arguments. The resulting shared library will enable Python to access your C++ library through the CFFI bridge.

Known limitations of the generator

  • External types defined in YAML are not yet supported.
  • Use of non-nullable pointers is not yet supported.

C++/CLI / C++ Project

C++/CLI is a technology by Microsoft that provides interoperability of C++ with Microsoft .NET languages such as C#. It is only supported on Windows.

Djinni generates a shallow C++/CLI wrapper around the C++ interfaces. Once compiled to a shared library, the resulting dll just needs to be added to your C# project as reference, and you can call your Djinni interfaces from C# like any other .NET library.

Includes & Build target

The following code will be generated for each defined type:

Type C++ header C++ source C++/CLI header/sources
Enum/Flags my_enum.hpp MyEnum.hpp, MyEnum.cpp
Record my_record.hpp my_record.cpp MyRecord.hpp, MyRecord.cpp
Interface my_interface.hpp my_interface.cpp (+) MyInterface.hpp, MyInterface.cpp

Add all generated files to your build target, and link against the djinni-support-lib.

C++/CLI sources have to be compiled with MSVC and the /clr (Common Language Runtime Compilation) option.

Last update: May 7, 2021