Calling a C++ Function from Carbon and Exposing Carbon Types to C++

Desired outcome

Enable a Carbon module to call an existing C++ function (e.g., a math utility) and, if needed, expose Carbon-defined types to C++ callers without rewriting the legacy library.

Prerequisites

• Carbon toolchain installed: clang‑based Carbon compiler, carbon-build, and the Carbon standard library.
• A C++ compiler compatible with the toolchain (GCC 12+ or Clang 15+).
• Bazel available for building mixed‑language targets.
• Basic familiarity with writing .carbon files and Bazel BUILD files.

Procedure

1. Create the C++ header and source.

   // math.h
   #ifndef MATH_H
   #define MATH_H
   int add(int a, int b);
   #endif
   

   // math.cpp
   #include "math.h"
   int add(int a, int b) { return a + b; }
   

   Place these files in your project directory, e.g., ./src/math.h and ./src/math.cpp.
2. Write a Carbon file that imports the C++ declaration.

   // main.carbon
   import "math.h"  // imports the C++ header
   
   fn main() {
       let result: i32 = add(2, 3);
       print(result);
   }
   

   The import directive tells the Carbon compiler to treat the header as a C++ declaration accessible via the extern "C++" ABI.
3. Add any Carbon‑side wrappers (optional). If you need to expose a Carbon struct to C++, define it in a Carbon file and mark it with extern "C++":

   // point.carbon
   extern "C++" struct Point {
       x: f64,
       y: f64,
   };
   
   fn distance(p: Point) -> f64 {
       return (p.x * p.x + p.y * p.y).sqrt();
   }
   

   This generates a C++‑compatible layout for Point.
4. Update the Bazel BUILD file.

   cc_library(
       name = "math_lib",
       srcs = ["src/math.cpp"],
       hdrs = ["src/math.h"],
       visibility = ["//visibility:public"],
   )
   
   carbon_library(
       name = "main_carbon",
       srcs = ["main.carbon"],
       deps = [":math_lib"],
   )
   
   cc_binary(
       name = "demo",
       srcs = [],
       deps = [":main_carbon"],
   )
   

   The carbon_library rule depends on the cc_library so that Bazel builds the C++ code first and links it with the Carbon output.
5. Build and run. From the workspace root run:

   carbon-build build //:demo
   

   Then execute the produced binary:

   bazel-bin/demo
   

   You should see the output 5 printed to the console.

Expected checks

• Compilation finishes without linker errors.
• Running the binary produces the expected result (e.g., 5 for the add example).
• To confirm Carbon‑to‑C++ data flow, inspect symbols: nm bazel-bin/demo | grep add should show a reference to the C++ add symbol.
• If you exposed a Carbon struct, write a small C++ test that includes the generated header and accesses the struct’s fields; the program should compile and run.

Recovery options

• Linking failures. Verify that the C++ library was built with the same ABI as the Carbon compiler expects (Itanium ABI). Rebuild the C++ code with -fPIC and, if exceptions are not needed, add -fno-exceptions to match Carbon’s default.
• Version mismatch. Ensure the Carbon compiler version corresponds to the C++ ABI version used by your toolchain; consult the Carbon release notes for ABI compatibility notes.
• Missing symbols. Run objdump -t bazel-bin/demo or nm to see undefined symbols; check that the cc_library target is correctly listed in the deps of the carbon_library.
• Debugging. Enable debug symbols for both languages (--copt=-g for C++ and --carbon_opt=-g for Carbon) to allow source‑level stepping in a debugger like lldb or gdb.