Skip to content

Latest commit

 

History

History
110 lines (89 loc) · 4.23 KB

README.md

File metadata and controls

110 lines (89 loc) · 4.23 KB
Raw

CHUG: C++ Humanoid Unwrapping Generator

What is CHUG?

CHUG is a replacement for SWIG.

Why CHUG?

What is wrong with SWIG?

  1. SWIG is too complicated, and therefore difficult to debug.
  2. SWIG adds a layer of memory management.

How is CHUG better than SWIG?

  1. CHUG is simpler. CHUG does not parse a C++ header. Instead, it generates the C++ header. The user can then implement it as he sees fit.
  2. CHUG encourages a better memory model. SWIG handles smart-pointers the way it handles all copyable objects: It allocates a copy on the heap and retains (some representation of) a pointer to that new memory in the target language. CHUG has special handling for boost::intrusive_ptr<>, which allows the wrapped object to contain the raw pointer address.

Couldn't a SWIG typemap handle boost:intrusive_ptr<> in a similar way?

Yes, but see #1.

Is it really Humanoid?

Maybe not, but see IMDB.

Architecture of CHUG

CHUG Flowchart

Basic operation

  1. Parse API spec. The 'grammar' is Java. CHUG uses Java reflection to discern the API.
  2. Dump a YAML representation of the API. This CHUY file allows the rest of CHUG to be written in any language.
  3. Parse YAML and ...
    1. Dump a C++ header for the implementation.
      This is the under-layer.
    2. Dump a pure ANSI C (extern "C") version of the API.
      This is the native layer. It is implemented in C++ in terms of the under-layer.
    3. For each target language, dump an implementation of the API.
      These are the over-layers. They use only language-specific features and the C layer.

This multi-step approach makes the whole process easy to debug and customize.

Components

  • HUG
    • Humanoid Unwrapping Generator
    • Given a Java Interface or Abstract class, produce a CHUY file (CHUG/YAML format).
  • PLUG
    • C Plus Plus Under-Layer Generator
    • Given a CHUY file, produce the C++ under-layer.
  • NAG
    • Native API Generator
    • Given a CHUY file, produce the ANSI/ISO C native layer.
  • SWOG
    • Simplified Wrapper Over-layer Generator
    • Given a CHUY file, produce an over-layer for a given target language.

Layers

  • Under-layer: C++
    • Header is generated by PLUG from a CHUG YAML file.
      • Classes derive from a ReferenceCounter (configurable) and extern "C" structs, in addition to the user-defined hierarchy.
      • boost::intrusive_ptr<> is used by default for pass-by-copy.
    • Must be implemented by the user.
      • inline methods are encouraged, through a .i include file.
  • Native layer: ANSI/ISO C
    • Implemented in C++, with extern "C" linkage for its interface.
    • Uses the under-layer, including inline methods.
  • Over-layer: Ruby, Python, C++, Java, etc.
    • Implemented in the target language, using the target language's native API.
      • Java: JNI
      • Python: ctypes
      • Perl: Possibly P5NCI, FFI (which uses libffi), C::DynaLib, or FFI::Raw.
      • Ruby: ?
      • C++: #include native layer API
    • A plug-in architecture allows customization, including the eventual use of more efficient APIs (e.g. Perl XS or Python C API), using either the native layer or the under-layer directly.

WTF? Did you say "C++"?

Yes, we did.

That's crazy talk! Why would I want to generate C++?

Because a well-written C++ library leaves too much exposed, by the nature of C++. A shared library should hide both data members and virtual methods so that minor revisions can be swapped in safely.

License

This work is distributed under the MIT license. See "LICENSE" file.

For more information

See the wiki.