From 5696b5e002470e4c3dae619c1f4a1575f9d77b6d Mon Sep 17 00:00:00 2001 From: triton Date: Wed, 29 Aug 2012 21:51:49 +0100 Subject: [PATCH] Added new documentation to the tool. --- Manual.md | 204 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ README | 20 +++++- 2 files changed, 222 insertions(+), 2 deletions(-) create mode 100644 Manual.md diff --git a/Manual.md b/Manual.md new file mode 100644 index 00000000..d9e56b9a --- /dev/null +++ b/Manual.md @@ -0,0 +1,204 @@ +C++ C# interop bridge tool Developer's Manual + + +1. Overview +----------- + +This tool allows you to generate bindinds that wrap C/C++ code allowing +interoperation in another language. This can be useful if you have an +existing native codebase and want to add scripting support, or want to +consume an existing native library in your managed code. + +It differs from most existing C++ binding tools like SWIG in that it +does not generate a C layer to interop with C++, it actually understands +enough of the C++ ABI (application binary interface) to get the job done +without generating extra native code. + + +2. Architecture +--------------- + +The tool is architected in the following layers: + + 1. Parser + +Since writing bindings by hand is tedious and error-prone, an automated +approach is preferred. To do this, we use the open-source Clang parser +that provides us with an AST (Abstract Syntax Tree) of the code, ready +to be consumed by the generator. + +By using a real compiler for parsing the code, we get mature support for +C and C++ features, like a fully-compliant preprocessor and support for +attributes and pragma directives that can affect the behaviour of the +code (ex. custom packing / alignment options). + + 2. Generator (language-specific) + +After parsing is done, a language-specific layer is generated. +Since different target languages provide different features, some C++ +language features are mapped in different ways by different languages. + +Since scripting languages have their own way of expressing certain +patterns, like properties (instead of getters/setters pairs), or +delegates (instead of function pointers) there is support to process +the generated bindings, to rename symbols, create additional helper +methods, map parameters. + +Aditionally some of it can be provided directly in the native source +code, by annotating the declarations with custom attributes. + + 3. Runtime (language-specific) + +This implements the C++ implementation-specific behaviours that allow +the target language to communicate with the native code. It will usually +use an existing FFI that provides support for interacting with C code. + +It needs to know about the object layout, virtual tables, RTTI and +exception low level details, so it can interoperate with the C++ code. + + +3. C/C++ features +------------------- + +In this section we will go through each relevant C / C++ feature and +go over how it is usually implemented and discuss different binding +strategies. + + * Comments + + \brief Doxygen-style C++ comments are currently translated to .NET + XML-style comments. + + * Defines + + Defines can be translated to proper enumerations in C#. This needs + to be a manual operation for now. Other type of defines like strings + are currently not supported. + + * Enumerations + +C/C++ enums are translated to proper enumerations in C#. + +Beware that in the case of anonymous enums inside classes or namespaces, +they need to hoisted to an outer enclosing namespace. In some cases manual +rules need to be written for a good mapping. + + Flags / Bitfields + +Some enums represent bitfields. The generator will try to apply an heuristic +to native enums to check if they represent flags. Most of the time it will +get it right and correctly apply the [Flags] .NET attribute to the wrapper +enum. If it guesses wrong (not enough enum values to make a good guess) +then you will need to make a rule to correct it. + + * Types + + Built in + (Wide) Chars (Unicode?) + Signed / Unsigned Int (8, 16, 32, 64) + Float / Doubles (32, 64) + + Modifiers + Value + Pointers + [C++] References + + * Functions + +Since global scope functions are not supported in C# (though they are +available in CIL) they must be mapped as a static function in a class, +to be consumed by C# code. + + * Bitfields + +Not supported yet. Needs some research to check how to map to C#. + + * Unions + +Not supported yet. Needs some research to check how to map to C#. + + * Type Definitions + +Not supported yet. Needs some research to check how to map to C#. + + * Classes / Structs + +Classes are wrapped in a native .NET class. Support for classes is currently +untested and still experimental. + + POD + Constructors + Destructors + Overloaded Operators + Conversion Operators + Methods + Static Members + Pointers to members + + Inheritance: + + 1. No inheritance + 2. Single inheritance + 3. Multiple inheritance + 4. Virtual inheritance + +* Templates + +Not supported yet. Needs some research to check how to map to C#. + +4. Customization +------------------ + +The generator is extensible and some support for specific C++ features +will appear in the next versions: + + * STL + * Smart Pointers + +5. Target Languages +------------------- + +At the moment the project is C#-specific. + +6. ABI Internals +---------------- + +Each ABI specifies the internal implementation-specific details of how +C++ code works at the machine level, involving things like: + + 1. Class Layout + 2. Symbol Naming + 3. Virtual tables + 4. Exceptions + 5. RTTI (Run-time Type Information) + +There are two major C++ ABIs currently in use: + + 1. Microsoft (VC++ / Clang) + 2. Itanium (GCC / Clang) + +Each implementation differs in a lot of low level details, so we have to +implement specific code for each one. + +The target runtime needs to support calling native methods. +This is usually implemented with an FFI (foreign function interface) in +the target language VM (virtual machine). + +In most cases MSVC lays out classes in the following order: + +1. Pointer to virtual functions table (_vtable_ or _vftable_), added only +when the class has virtual methods and no suitable table from a base class +can be reused. + +2. Base classes + +3. Class members + + +7. Similiar Tools and Inspiration +--------------------------------- + +https://github.com/mono/cxxi +http://code.google.com/p/bridj/ +http://code.google.com/p/jnaerator/ +http://dyncall.org/ diff --git a/README b/README index 80125e62..d5ef0513 100644 --- a/README +++ b/README @@ -1,11 +1,27 @@ +This is my custom fork of Mono.Cxxi that aims to replace the GCC-XML parser +with a Clang-based one, and remove all the C++-ABI specific code for things +like object layout and name mangling from the runtime library while replacing +it with metadata generated by Clang (it already provides all the needed info). + +This is a work-in-progress and is currently unusable for real work. + Directory structure ------------------- +Manual.md + Work-in-progress documentation for this tool. + src/ Mono.Cxxi The runtime library - generator - The binding generator + Bridge + Contains the needed classes to bridge the parser and the generator. + Parser + C++/CLI based wrapper around the C++ Clang libraries. + Generator + The Clang-based binding generator + GCCGenerator + The GCC-XML based binding generator (deprecated) qt Auto generated Qt bindings + test program