Interop With C++ Macros In Jank: A Problem And Solution

Let's dive into the challenges of using C++ macros with interop in Jank. This article explores a specific issue encountered when trying to integrate C++ code, particularly from the Ruby C API, into a Jank project. We'll break down the problem, examine the error messages, and discuss potential solutions to effectively bridge the gap between Jank and C++ macros.

Jank Health Check

Before we delve into the problem, let's ensure our Jank environment is properly configured. The following health check provides an overview of the system, Jank installation, Clang installation, and Jank runtime:

─ system ───────────────────────────────────────────────────────────────────────────────────────────
─ ✅ operating system: linux
─ ✅ default triple: x86_64-unknown-linux-gnu

─ jank install ─────────────────────────────────────────────────────────────────────────────────────
─ ✅ jank version: jank-0.1-6ebd32966e07133861a5734e892a5cfc02bca024
─ ✅ jank resource dir: ../lib/jank/0.1 
─ ✅ jank resolved resource dir: /usr/local/bin/../lib/jank/0.1 (found)
─ ✅ jank user cache dir: /home/mauricio/.cache/jank/x86_64-unknown-linux-gnu-8ef9488056101afe1d0969786e5dc264017e65e64f3b420fe6ba9d169dbf29e9 (found)

─ clang install ────────────────────────────────────────────────────────────────────────────────────
─ ⚠  configured clang path: /home/runner/work/jank/jank/compiler+runtime/build/llvm-install/usr/local/bin/clang++ (not found)
─ ✅ runtime clang path: /usr/local/bin/../lib/jank/0.1/bin/clang++ (found)
─ ⚠  configured clang resource dir: /home/runner/work/jank/jank/compiler+runtime/build/llvm-install/usr/local/lib/clang/22 (not found)
─ ✅ runtime clang resource dir: /usr/local/lib/jank/0.1/lib/clang/22 (found)

─ jank runtime ─────────────────────────────────────────────────────────────────────────────────────
─ ✅ jank runtime initialized
─ ✅ jank pch path: /home/mauricio/.cache/jank/x86_64-unknown-linux-gnu-8ef9488056101afe1d0969786e5dc264017e65e64f3b420fe6ba9d169dbf29e9 (found)
─ ✅ jank can jit compile c++
─ ✅ jank can jit compile llvm ir
─ ✅ jank can aot compile working binaries

This health check confirms that Jank is correctly installed and configured, including the necessary components for JIT and AOT compilation.

Description of the Issue with Reproduction Steps

The core problem lies in the inability to directly use C++ macros within Jank when interfacing with external C++ code. Specifically, the issue arises when trying to call functions that rely on macros for type casting and definition, such as those found in the Ruby C API. Let's examine the code snippet that demonstrates this issue:

(ns types)

(cpp/raw "
#ifndef DUP_CODE
#define DUP_CODE

typedef uintptr_t VALUE;

#define ANYARGS ...

static void rb_define_method(VALUE (*func)(ANYARGS), int arity) {
}

static VALUE some_code(VALUE self, VALUE a) {
  return a;
}

#define RBIMPL_CAST(expr) (expr)

#define RUBY_METHOD_FUNC(func) RBIMPL_CAST((VALUE (*)(ANYARGS))(func))

#endif
 ")

(defn -main [ & args]
  (cpp/rb_define_method (cpp/RUBY_METHOD_FUNC cpp/some_code) (cpp/cast cpp/int  0)))

This code attempts to define a function some_code and then register it using rb_define_method, a function from the Ruby C API. The macro RUBY_METHOD_FUNC is used to cast the function pointer to the correct type. However, Jank fails to recognize the macro, resulting in a compilation error.

The error message clearly indicates the problem:

error: Unable to find 'RUBY_METHOD_FUNC' within the global namespace.

─────┬──────────────────────────────────────────────────────────────────────────────────────────────
     │ types.jank
─────┼──────────────────────────────────────────────────────────────────────────────────────────────
 25  │  ")
 26  │
 27  │ (defn -main [ & args]
     │ ^ Expanded from this macro.
 28  │   (cpp/rb_define_method (cpp/RUBY_METHOD_FUNC cpp/some_code) (cpp/cast cpp/int  0)))
     │                          ^^^^^^^^^^^^^^^^^^^^ Found here.
─────┴──────────────────────────────────────────────────────────────────────────────────────────────

Root Cause Analysis

The fundamental reason for this failure is that Jank's cpp/ interop mechanism does not automatically expand C++ macros. When Jank encounters (cpp/RUBY_METHOD_FUNC cpp/some_code), it attempts to resolve RUBY_METHOD_FUNC as a function or variable within the C++ namespace, which, of course, it is not. It's a macro that should be expanded during the preprocessing stage of compilation.

The Challenge with cpp/raw

While using (cpp/raw "rb_define_method(RUBY_METHOD_FUNC(some_code), 0);") might seem like a workaround, it introduces a significant limitation. You lose the ability to pass parameters defined in Jank to this raw C++ code. In the original problem description, it's mentioned that the actual rb_define_method function accepts more parameters that you would ideally generate from Jank. Directly embedding the macro within cpp/raw bypasses Jank's parameter passing mechanism, making it unsuitable for dynamic interaction between Jank and the C++ code.

Potential Solutions and Workarounds

To address this issue and enable effective interop with C++ macros, consider the following strategies:

1. Macro Expansion via Code Generation

One approach is to generate the C++ code with the macro expansion already performed. This could involve using a separate tool or script to preprocess the C++ code before passing it to Jank. The idea is to replace the macros with their expanded forms, so Jank sees the concrete C++ code directly.

For instance, instead of:

(cpp/rb_define_method (cpp/RUBY_METHOD_FUNC cpp/some_code) (cpp/cast cpp/int  0))

you would generate:

(cpp/rb_define_method (RBIMPL_CAST((VALUE (*)(ANYARGS))(some_code))) (cpp/cast cpp/int  0))

This can be automated using a build script or a custom tool that parses the C++ headers, expands the macros, and generates the corresponding Jank code.

2. Inline Functions Instead of Macros

If feasible, consider replacing the C++ macros with inline functions. Inline functions provide similar performance benefits to macros but are treated as regular functions by the compiler. This allows Jank to interact with them directly without the need for macro expansion.

Instead of:

#define RUBY_METHOD_FUNC(func) RBIMPL_CAST((VALUE (*)(ANYARGS))(func))

Use:

inline VALUE (*RUBY_METHOD_FUNC(VALUE (*func)(ANYARGS)))(ANYARGS) {
  return RBIMPL_CAST((VALUE (*)(ANYARGS))(func));
}

This approach requires modifying the C++ code, which might not always be possible, especially when dealing with external libraries.

3. Custom C++ Wrapper Functions

Create custom C++ wrapper functions that encapsulate the macro usage. These wrapper functions can then be called from Jank, effectively hiding the macros from Jank's direct view. This approach involves writing C++ functions that perform the necessary macro expansions internally and then expose a clean interface to Jank.

For example, define a C++ function like this:

extern "C" {
  void define_ruby_method(VALUE (*func)(ANYARGS), int arity) {
    rb_define_method(RUBY_METHOD_FUNC(func), arity);
  }
}

Then, in Jank, you can call this wrapper function:

(cpp/define_ruby_method cpp/some_code (cpp/cast cpp/int 0))

This method provides a clean separation between the Jank code and the C++ macro usage.

4. Leverage Jank's Code Generation Capabilities

Explore Jank's code generation features to dynamically create the necessary C++ code at runtime. This approach allows you to incorporate the macro expansion logic within your Jank code and generate the appropriate C++ code on the fly. This is an advanced technique, but it offers a high degree of flexibility and control.

5. Conditional Compilation and Feature Detection

Employ conditional compilation techniques to detect whether the code is being compiled within Jank's interop environment. Based on this detection, you can provide alternative implementations that avoid the use of macros when necessary.

#ifdef JANK_INTEROP
// Implementation without macros
#else
// Original implementation with macros
#endif

This approach allows you to maintain compatibility with both Jank and native C++ environments.

Conclusion

Interop with C++ macros in Jank presents unique challenges due to the way Jank handles external C++ code. While direct macro expansion is not supported, several strategies can be employed to overcome this limitation. These include macro expansion via code generation, replacing macros with inline functions, creating custom C++ wrapper functions, leveraging Jank's code generation capabilities, and using conditional compilation. By carefully considering these approaches, you can effectively integrate C++ code with macros into your Jank projects.

For more information on C++ macros and their usage, you can refer to the GCC Preprocessor documentation.