The cxxbridge-cmd is not ideal:

1. The cxxbridge-cmd version might be different from cxx version, which can cause problems
2. It's hard to track file changes outside rust project, i.e. determine the best time to re-generate the header/source file

I used the side-effect from cxx_build::bridge(...) to generate the necessary files https://github.com/XiangpengHao/cxx-cmake-example/blob/27dfab58ff4888d4ede71fdad45a7d112640d2b0/rust_part/build.rs#L2 and then copy those files to desired locations https://github.com/XiangpengHao/cxx-cmake-example/blob/27dfab58ff4888d4ede71fdad45a7d112640d2b0/rust_part/CMakeLists.txt#L20

It would be great if we have some ways to explictly write the ouput file, maybe something like

// build.rs
fn main() {
    cxx_build::bridge("src/lib.rs").header("/path/lib.rs.h").source("/path/lib.rs.cpp");

    println!("cargo:rerun-if-changed=src/lib.rs");
}

The cxx help says:

It would be reasonable to build a higher level bindgen-like tool on top of CXX which consumes a C++ header ... as source of truth and generates the cxx::bridge, eliminating the repetition while leveraging the static analysis safety guarantees of CXX.

It is looking to me like that's exactly the model we may need in order to get permission to use Rust within the large codebase in which I work.

Could we use this issue to speculate about how this might work? It's not something I'm about to start hacking together, but it's conceivable that we could dedicate significant effort in the medium term, if we can become convinced of a solid plan.

Here are my early thoughts.

Note that C++ remains the undisputed ruler in our codebase, so all of this is based around avoiding any C++ changes whatsoever. That might not be practical.

Bits of cxx to keep unchanged

• Built-in types (notably, which objects can be passed by reference/pointer/etc.... a major concern about Rust/C++ interop in my organisation is that C++ objects often have internal pointers; the fact that you can't pass them by value into Rust within cxx neatly sidesteps that concern)
• C++-side and Rust-side shim generation
• Magical emergent behavior where an unsafe keyword is only used if you're doing something that actually is a bit iffy with C++ object lifetimes
• Declaration of any Rust functions which C++ should be able to call (for now). This proposal only talks about calls from Rust into C++.
• The fact that the wrapper shims should work nicely with cross-language LTO inlining and thus (in the optimal case where there are no type conversions) shrink down to nothing
• cxxbridge tool.

Bits where we'll need to do something different

• No cxx::bridge section. Instead, declarations are read from C++ headers. A simple include_cpp! macro instead. ("Simple" in the user's sense, very much not in the implementation sense, where we'd need to replicate much of bindgen)
• Generation of C++ wrapper functions only for those which are actually used. An include_cpp! macro may pull in hundreds of header files with thousands of functions. The cxxbridge C++-generation tool would have to work incredibly hard for every .rs file if it generated wrappers for each one. So, instead, the call sites into C++ from Rust would probably need to be recognizable by that tool such that it could generate the minimum number of shims. (Procedural macro in statement position? cpp_call!?)
• Perhaps some way to avoid duplication of cxxbridge effort if hundreds of .rs files use the same include_cpp! macro(s). This might be purely a build-system thing; I haven't thought it through.
• If such a function call refers to a struct which can be represented in cxx::bridge (e.g. because it contains only unique_ptrs and ints) then said struct is fully defined such that it's accessible to both Rust and C++. If a struct is not representable in cxx then it is declared in the virtual cxx::bridge as an opaque type (and thus can only be referenced from unique_ptrs etc.)
• Passing the C++ include paths and #defines into rustc. I can't think of a better way to do this than to rely on the env! macro. Ugh.
• If Rust code calls a C++ function which can't be translated, a compile-time error occurs with information about why cxx can't handle it (e.g. C++ object passed by value). Ideally this could (in future) be improved by C++ annotations that tell Rust users where and how to use a wrapper function that may already have been defined (input to clippy/rust-analyzer/etc. in future? Highly ambitious.)
• This involves a possible mindset shift. At the moment, we're using cxx in localized places where it wraps up C++ function calls with an idiomatic Rust wrapper. This proposal involves instead allowing production Rust code to freely call C++ classes and functions. There may be some major leaps here to make this practical, which I might not have thought of (as I say, these are early thoughts...)
• A few things orthogonal to this feature and beyond the scope of this issue: class method calls, enums, extensible support for our shared pointer types, etc.

Next steps our side

• We need to list out the sorts of C++ function calls and class accesses which typical Rust code would need to do in our codebase. We then need to analyze the types involved and find out if this plan is actually practical for our codebase. If we find a significant proportion of likely function calls involve passing C++ types by value that can't be represented by cxx, we're in trouble. My hope is that this isn't the case, but work is required to figure this out.

Meanwhile though I wanted to raise this to find out if this is the sort of thing you were thinking, when you wrote that comment in the docs!

It's not a real PR, more like a question about the demo code in demo-cxx/ and demo-rs/.

The setup is an existing C++ CMake project, the goal is to be able to add Rust code to it. The C++ project is internally structured as a main application and shared libraries. In this demo we will have a main C++ application and a shared library. The shared library will be entirely in Rust except for the interface, the FFI will provide the C++ interface so the main application could link to it as to a regular C++ shared library.

I haven't found any main.cpp in the demo-cxx/ or demo-rs/, so there is probably a space for this kind of demo.

The first step is creating the demo-cmake/ dir, dumping the cmake-cargo into it, fixing workspace errors. Then testing their build:

mkdir ../build
cd ../build
cmake ../cxx/demo-cmake
make -j

The application of interest is demo-cmake/test/rust2cpp, it does the C-like variation of what we want. So the second step is adding parts of demo-cxx/ and demo-rs/ to that application (main.rs turns into lib.rs, demo.h turns into a pure-C++ interface for the library).

There are minor things such as: hardcoded include paths in demo.cc and build.rs, hardcoded cxx dependency path, cxxbridge complaining about the "target path" that has to end with "target" but instead ends with "out". I'm currently looking into this error that occurs while building the library:

src/lib.rs:1:1: error[E0658]: custom attributes cannot be applied to modules

So it doesn't compile yet. I suppose most of the work that is left is related to the Rust/cxx build system side.

Suggestions welcome. Maybe I've missed an obvious solution or maybe somebody has already done such an integration.

I've hacked in some preliminary std::vector<T> support to allow passing C++ vectors to Rust.

https://github.com/myronahn/cxx/tree/master

Right now it works for std::vector<uint8_t> since that was my primary need but it would be very easy to add in support for all the basic types.

Adding support for general types is a bit harder as the orphan rule is keeping me from defining macro-expanded trait impls for both the Vector class and the UniquePtr class. I'm currently wondering what the best workaround would be for this.

It would be great to get a once-over from you if you have any spare time to take a look. Is it worth continuing work on this, or are you in the middle of implementing something bigger/better?

Thanks in advance.

Hello to everybody. Is it possible to define shared structs in a separate file?

Use case: I have generated Rust structs from a Protobuf definition and would like to expose them as shared structs in my bridge definition. From what I can tell, the fields on the generated structs are supported (except Option, but I saw its WIP). As a workaround, I tried to use the include! Macro in the bridge definition, Unfortunately, it doesn't work.

another question Until the Option enum becomes supported, is there a temporary solution I can use to move Option in a shared struct?

I've been working on introducing cxx to Fuchsia as a safer, better way for us to write Rust/C++ FFIs. As part of this, I'd like to provide a library or two with some common types for others to reuse in their own FFIs.

For example, see the handle types from #274; these would be a bridge between our C++ and Rust handle wrappers. These are important to write once and reuse because there's a lot of ways to implement them in a way that would cause resource leaks. Another example is a reusable Result type; we don't use exceptions and panicking on every error result is undesirable.

To do this, I'd like to be able to reuse shared types defined in one bridge module in another bridge module without having to treat them as opaque Rust types in the using module (so that they can be passed by value without boxing). Today these seem to just be recognized as unsupported types. For example:

// handle.rs
#[cxx::bridge(namespace = zx::ffi)]
mod ffi {
    struct Process {
        raw: u32,
    }

    struct Job {
        raw: u32,
    }

    // ... and so on
}

impl Drop for ffi::Process { ... }
impl Drop for ffi::Job { ... }
// ... and so on, From impls to convert, etc.

// usage.rs
#[cxx::bridge(namespace = my_usage::ffi)]
mod ffi {
    extern "Rust" {
        fn create_process(name: &CxxString, job: &handle::ffi::Job) -> handle::ffi::Process;
    }
}

Hello! I'm trying to generate rust bindings for the autodesk fbx c++ library to be able to use the fbx functionalities inside a rust application. The fbx library is comprised of precompiled dynamic libraries and header files and it's publicly available. I created a build.rs file like this:

fn main() {
    println!("cargo:rustc-link-search=/path/to/lib/gcc/x64/release/"); // path to the compiled fbx library
    println!("cargo:rustc-link-lib=fbxsdk");

    cxx_build::bridge("src/main.rs")
        .flag_if_supported("-std=c++11")
        .include("/path/to/lib/include")  // path to the fbx headers files
        .compile("cxxbridge-demo");
    println!("cargo:rerun-if-changed=src/main.rs");
    println!("cargo:rerun-if-changed=src/shim.h");
}

My main.rs file is like this:

#[cxx::bridge]
mod ffi {
    unsafe extern "C++" {
        include!("testcxx/lib/include/fbxsdk.h");
        include!("testcxx/src/shim.h");

        type FbxManager;

        fn FbxManager_Create() -> UniquePtr<FbxManager>;
    }
}
fn main() {
    let mgr = ffi::FbxManager_Create();
}

In shim.h I tried to create a shim for the FbxManager::Create() static method which is usually the first method called to initilaize the library. This is shim.h

#pragma once
#include <fbxsdk.h>
#include <memory>

std::unique_ptr<FbxManager> FbxManager_Create() {
    return std::unique_ptr<FbxManager>(FbxManager::Create());
}

When I run cargo build with this situation I get an ld error that says:

path/to/testcxx/target/debug/build/testcxx-59666266ff383069/out/libcxxbridge-demo.a(main.rs.o): in function `FbxManager_Create()':
          /path/to/testcxx/target/debug/build/testcxx-59666266ff383069/out/cxxbridge/crate/testcxx/src/shim.h:6: undefined reference to `fbxsdk::FbxManager::Create()'
          collect2: error: ld returned 1 exit status

I would like to ask help for this specific case but also how in general I should behave when trying to bind to c++ static methods and creating instances of c++ classes. Many thanks, Frank

Moved from https://github.com/dtolnay/cxx/pull/927#issuecomment-911138782.

It looks like the target-features don't flow from the top crate down to the crates it consumes, at least not if it's scoped to the package's own .cargo/config.toml. If I only set this in my project's .cargo/config.toml, when it builds cxx, the flag is missing and it's not listed in the CARGO_CFG_TARGET_FEATURE output for cxx, but it is used in my project.

It turns out cc also has support for this already by default 😄, but because it's not flowing from the top-level package config.toml down to its dependencies and their dependencies, it doesn't kick in. It does work if you set the RUSTFLAGS environment variable before running cargo, and it works for user-wide ~/.cargo/config.toml as well, but this would let a consumer handle it automatically with feature flags in the Cargo.toml.

        unsafe impl cxx::ExternType for bindgen::Bob {
            type Id = cxx::type_id!("Bob");
        }
        mod bindgen {
            #[repr(C)]
            pub struct Bob {
                pub a: u32,
                pub b: u32,
            }
        }
        #[cxx::bridge]
        pub mod cxxbridge {
            extern "C" {
                include!("input.h");
                pub fn give_bob() -> Bob;
                type Bob = super::bindgen::Bob;
            }
        }

doesn't work because we can't return ExternTypes by value.

Each extern type may be one of three fundamental categories of type:

• An alias to another cxx::bridge type (in which case it's a simple alias and we don't do anything in the current instantiation)
• A type which is_trivially_move_constructible && is_trivially_destructible. If so, we allow allow it to be passed by value into/our of cxx types, and we check this with static_asserts as discussed in #280. ("trivial" types for short henceforth)
• A type which isn't trivially move constructable/destructable. In these cases we don't allow use by value but we do allow generation of UniquePtr traits etc. as per #312.

This distinction is implied by #280 but this could be done as a pre-requisite step first. I also feel it would be desirable to pin this down before finalizing design for #312.

The question is, for a given ExternType, how does cxx know which of these three categories of type it is? What's your plan there? Is it to require the developer to implement an extra trait for trivial types which is then checked for safety using static_assert? Or did you plan to do something funky to auto-detect trivial types at build time?

(NB for this last category of types, my higher-level code generator plans to create shims which allow us to call pre-existing C++ APIs that take a T by instead passing a UniquePtr<T>. I have yet to do this bit. It makes superficial sense that "complicated" types need to be entirely allocated, accessed, and managed within C++ but can still be owned by Rust. Figuring out whether this is ergonomic in practice is arguably the entire point of my https://github.com/google/autocxx experiments... if this doesn't work out it's back to the drawing board!)

This is still a WIP but the core of this is working now. Two main things to do:

• Figure out how to handle both bridges trying to emit the Vec/Box functions, and how to make usage in UniquePtr/CxxVector work if the remote bridge doesn't use the shared type in that way
• Clean up TODOs about adding ui tests

My other PR (#298) will also need to rebased on this or vice versa. The first 4 commits here are duplicated between them.

Fixes #297

This commit reworks how files are placed so that anyone who overrides CARGO_TARGET_DIR or the associated cargo config setting will be able to use the crate. It is a breaking change because the cargo manifest directory is now included by default, not the directory that is the parent of the target directory. It also places the rust/cxx.h file in $OUT_DIR/cxxbridge instead of inside of $TARGET_DIR/cxxbridge. This also removes the need to symlink it.

Proof of concept to support the rust type char which is mapped to rust::Char.

This should be seen as the rust counterpart to https://github.com/dtolnay/cxx/pull/725, and address the other part of https://github.com/dtolnay/cxx/issues/592.

If this is approved, next steps/questions I can think of:

• [ ] Can we use the rust's char::from_u32 to validate the unicode value? (currently it's a copy of it)
• [ ] Can cpp's rust::Char be made a POD?
• [ ] What should be the scope of the API of cpp rust::Char? Currently intentionally minimal
• [ ] More tests (at least for each supported type in do_typecheck)
• [ ] Documentation

I couldn't see this discussed before (?), sorry if it has been.

Would it be accepted to add some helper methods to cxx_gen (or elsewhere?) for higher level code generators ? (If such methods would be accepted I would be happy to help contribute code to do this.)

In CXX-Qt we have a few places where it'd be useful for reuse some of the code from CXX itself rather than our fragile reimplementation of things, and other code generators using CXX may find this useful (eg maybe autocxx?). Furthermore this prevents breakage if CXX changes what it generates or adds support for more types.

Some of the possible scenarios we have come across so far that would be useful (note that API are just examples and could be different).

Retrieving the C++ name for a Rust type

This is useful when we are generating extra C++ code for Rust CXX bridges and need to match the type names for parameters or return types.

For a given syn::Type or syn::ReturnType it would be useful if there was a cxx_gen method to retrieve the corresponding C++ type name.

Note that this would also have to consider any namespaces and cxx_name attributes from the bridge.

For example with the following extern C++ block

#[namespace = "my_namespace"]
unsafe extern "C++" {
  #[cxx_name = "B"]
  type A;
}

If A is used as a type within a method, we need to have generation code to go from A to ::my_namespace::B. (and any other conversions need to occur like for UniquePtr or function pointers etc).

Would something like the following in cxx_gen be accepted?

pub fn syn_type_to_cxx_type(ty: &syn::Type, cxx_name_map: &BTreeMap<String, String>, namespace_map: &BTreeMap<String, String>) -> String {
    // calculates ::my_namespace::B from
    //  - reads syn::Type A
    //  - cxx_name_map with A -> B
    //  - namespace_map of A -> my_namespace
}

There would also likely need to be a similar method for syn::ReturnType as Result<T> can be used just in returns from my understanding (?).

Determining if the type is unsafe for CXX bridges

If certain types are used in CXX bridge functions the method needs to be marked as unsafe, eg if you use *mut T. Being able to determine by asking CXX which of it's supported types are unsafe would be much better than having to chase any new types.

Would something like the following in cxx_gen be accepted?

pub fn syn_type_is_cxx_bridge_unsafe(ty: &syn::Type) -> bool {
   // determine if syn::Type is unsafe
}

Retrieving the C++ bridge method name for a Rust method

In more advanced cases we need to friend the CXX bridge method (this is so that we can call protected methods from a C++ base class from Rust) it would be good if there was a helper to provide us the method name.

For example with the following CXX block

#[namespace = "my_namespace"]
unsafe extern "C++" {
    #[cxx_name = "B"]
    type A;
    fn method(self: &A);
}

CXX generates internal method names such as my_namespace$cxxbridge1$B$method.

Would something like the following in cxx_gen be accepted?

pub fn method_to_cxx_bridge_function_name(method: &syn::Ident, self_ty: Option<&syn::Type>, cxx_name_map: &BTreeMap<String, String>, namespace_map: &BTreeMap<String, String>) -> String {
    // calculates my_namespace$cxxbridge1$B$method from
    //  - reads the method ident "method"
    //  - reads the syn::Type Some(&A)
    //  - cxx_name_map with A -> B
    //  - namespace_map of method -> my_namespace
}

When I add another mod to the code in the demo, and reusing existing bingding types. I use the cxxbrdge command to generate the header file, the following error will be reported

Hi

I have a question, how can I use constructor C++ class with this library ?

#[cxx::bridge(namespace = "svglib")]
mod ffi {
    struct Fill {
        fill: String
    }

    struct Stroke {
        stroke: String,
        stroke_width: f32
    }

    //struct Circle {
    //    properties: SvgProperties
    //}

    unsafe extern "C++" {
        include!("../../../Sources/svglib/include/svglib.h");
        type Circle;
        pub fn Circle(fill: Fill, stroke: Stroke) -> Circle;
        pub fn generate(x: f32, y: f32, r: f32) -> String;
    }
}

With this code I have:

error: needs a cxx::ExternType impl in order to be used as a return value of `Circle`

When I add:

    struct Circle {
        properties: SvgProperties
    }

error: linking with `cc` failed: exit status: 1
   = note: Undefined symbols for architecture x86_64:
            "svglib::Circle::generate(double, double, double)", referenced from:
                _theme_astral_svg in libsweinterfacelib.a(SweInterface.o)
            "svglib::Circle::Circle(svglib::Fill, svglib::Stroke)", referenced from:
                _theme_astral_svg in libsweinterfacelib.a(SweInterface.o)
          ld: symbol(s) not found for architecture x86_64
          clang: error: linker command failed with exit code 1 (use -v to see invocation)

I am quite close to the finish line.. of wrapping a 3rd party C++ library with CXX so I can stop coding C++ and join the Rust hype train.. I am seeing the following error.. it feels like this is just my ignorance of C++ .. that my function signature is not quite matching .. any advice is appreciated

Main.RS

#[cxx::bridge(namespace = "com::enserio")]
mod ffi {
    unsafe extern "C++" {
        include!("twsapi_grpc_server/include/twsapi-client.h");
        include!("twsapi_grpc_server/include/AvailableAlgoParams.h");
        include!("twsapi_grpc_server/include/AccountSummaryTags.h");
        include!("twsapi_grpc_server/include/Utils.h");

        type TWSApiClient;

        fn new_twsapi_client() -> UniquePtr<TWSApiClient>;
        fn connect(self: Pin<&mut TWSApiClient>, port: i32, client_id: i32) -> bool;
    }
}

fn main() {
    let client = ffi::new_twsapi_client();
    client.connect(4002, 333);
}

The Error

error[E0599]: no method named `connect` found for struct `UniquePtr<TWSApiClient>` in the current scope
  --> src/main.rs:21:12
   |
21 |     client.connect(4002, 333);
   |            ^^^^^^^ method not found in `UniquePtr<TWSApiClient>`

For more information about this error, try `rustc --explain E0599`.
error: could not compile `twsapi_grpc_server` due to previous error

TWSAPIClient.cc

...

class TWSApiClient::impl {
    friend TWSApiClient;
};

TWSApiClient::TWSApiClient() : impl(new class TWSApiClient::impl)
        , m_osSignal(2000)//2-seconds timeout
        , m_pClient(new EClientSocket(this, &m_osSignal))
        , m_state(ST_CONNECT) // starts at m_state = 0
        , m_sleepDeadline(0)
        , m_orderId(0)
        , m_extraAuth(false) {}

TWSApiClient::~TWSApiClient()
{
    if( m_pReader ){
        m_pReader.reset();
    }
    delete m_pClient;
}

/**
*  Connect - This part of the client deals with connection to IB Gateway
*
*  See: https://interactivebrokers.github.io/tws-api/classIBApi_1_1EClientSocket.html
*/
    bool TWSApiClient::connect(int port, int clientId) {...}{
    ...

  std::unique_ptr<TWSApiClient> new_twsapi_client() {
    return std::make_unique<TWSApiClient>();
  }

TWSAPIClien.h

class TWSApiClient : public EWrapper {

public:
    #include "EWrapper_prototypes.h"

    TWSApiClient();
    ~TWSApiClient();

    bool connect(int port, int client_id);
    <and many other functions, but first want to just test connecting>

private:
     class impl;
    std::shared_ptr<impl> impl;
    EReaderOSSignal m_osSignal;
    EClientSocket * const m_pClient;
    State m_state;
    time_t m_sleepDeadline;
    OrderId m_orderId;
    std::unique_ptr<EReader> m_pReader;
    bool m_extraAuth;
    std::string m_bboExchange;
    int client_id;
};

std::unique_ptr<TWSApiClient> new_twsapi_client();

OVERVIEW:

This patch adds experimental support for us to use slices in a nostd/freestanding environment, aim is to run c++ <=> cxx-rs <=> rust on a baremental target environment and use slices, with the intention of supporting more features later.

CFG

In the application Cargo.toml file, the following feature cfgs are required:

[dependencies]
cxx = { ... , default-features = false }

[build-dependencies]
cxx-build = { ... , default-features = false }

Then build with:

RUSTFLAGS='--cfg cxx_experimental_no_alloc' cargo build

Build Notes

and in the particular .cpp file you may need to declare the following

void __assert_func (const char *__a, int, const char *__b, const char *__c) {
	while (true) {}
}

void *__gxx_personality_v0;

FUNCTIONALITY:

Currently, this only supports slices (outside of trivial features).

TESTING:

Tested by compiling:

• cargo test (run existing tests)

• cxx/demo/ running it.

• compiling with a arm toolchain setup with cmake/corrosion and running the binary on QEMU arm with basic logic assertions [1].

Current testing has been done in the direction of C++ -> Rust with a simple callback test to C++. A simple test setup can be seen here [2].

TODO:

• Get features such as Results<Ok, Err> working.

• When we build for the none std case (no default-features), instead of creating a symlink to the original cxx.h file, we copy it over and define the macro to disable stdlib dependencies. Perhaps there's a better way to do this?

NOTES:

By default, all the standard features are enabled gaurded by the #ifndef CXXBRIDGE1_RUST_STD, so this shoudn't break anything.

[1] https://github.com/twilfredo/qemu_misc/tree/master/bm_arm [2] https://github.com/twilfredo/qemu_misc/blob/master/bm_arm/main.cpp

Signed-off-by: Wilfred Mallawa [email protected]