rust-lang / rust-lang/rust-bindgen

Finegrained control over bindings generation of class members

Open
#3,248 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Rust
Stars
5.3k
Forks
829
Avg merge
1d 1h
Merged PRs (30d)
15

Description

As far as I understand, currently:

  • If bindings are generated for a class, bindings are also generated for all members of the class, as far as this is supported (e.g. no virtual methods).
  • This can be limited very coarsely using --generate. For example, --generate functions,types,vars,constructors,destructors will not generate bindings for any methods.
  • Base objects and fields can be hidden using --opaque-type.

But you can't allowlist or blocklist specific constructors, destructors, methods, and nested types.

A pattern that in my experience often comes up is where most members are suitable for direct bindgen, but a handful require custom glue code to be callable from Rust:

// library.h, third party
#include <string>

class Foo
{
public:
    Foo();
    enum Type { Static, Dynamic };
    void bar(Type);
    void baz(std::string);
};

// glue.cpp, my code
#include <library.h>

void Foo_baz(Foo* self, char const* ptr, std::size_t len)
{
    self->baz(std::string(ptr, len));
}
clang++ -c glue.cpp

# Do not generate bindings for Foo::baz, as it uses std::string which is too complex.
bindgen --allowlist-type Foo|Foo::Type \
        --allowlist-constructor Foo::Foo \
        --allowlist-method Foo::bar \
        --allowlist-function Foo_baz \
        glue.cpp

My current workaround is to just have bindings generated for all members, pass --no-recursive-allowlist, and define manual opaque types that are used in parameters and return types as needed, e.g. #[repr(C)] pub struct std_string([u8; 0]);. :P

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the existing --generate, --allowlist-type, --allowlist-constructor, --allowlist-method, --allowlist-function, and --no-recursive-allowlist entry points. The change should support selecting individual constructors, destructors, methods, and nested types while preserving the glue.cpp example's ability to exclude Foo::baz and include Foo_baz.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp, rust
Domain
devtools
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.