C++跨平台与跨语言绑定工具：SWIG、Djinni 等选型

本文面向工程落地，按「构建与依赖」和「跨语言绑定」两条主线梳理常用工具，并对 SWIG 与 Djinni 做原理拆解、调用链示意与最小可理解示例 ；辅以表格与 Mermaid 图，便于在桌面、服务端与移动端项目中快速选型与评审。具体命令行、生成文件后缀与目标语言版本以各工具官方文档及本地安装为准。

问题背景
[C++ 跨平台构建与依赖（语言内跨平台）](#C++ 跨平台构建与依赖（语言内跨平台）)
[C++ 跨语言绑定工具总览](#C++ 跨语言绑定工具总览)
SWIG：原理与示例演示
Djinni：原理与示例演示
[SWIG vs Djinni（选型对照）](#SWIG vs Djinni（选型对照）)
快速选型建议
落地注意事项（经验向）
延伸阅读
免责声明

1. 问题背景

当我们说「C++ 跨平台」，通常会混合两类需求：

同一套 C++ 代码在多操作系统构建运行（Windows / Linux / macOS / iOS / Android）。
C++ 与其他语言互调（Python、Java、Swift、C#、Lua、JavaScript 等）。

这两类需求的工具链不同，选型时应拆开看：CMake 解决「在哪编译、链什么库」；SWIG / Djinni / pybind11 等解决「哪一侧发起调用、类型与生命周期怎么过边界」。
跨语言绑定
语言内跨平台
CMake
vcpkg / Conan
SWIG 等
Djinni 等

2. C++ 跨平台构建与依赖（语言内跨平台）

2.1 CMake（主流构建系统）

事实标准，几乎所有现代 C++ 项目都支持。
可生成 Visual Studio、Xcode、Ninja、Makefile 等工程。
适合作为跨平台构建统一入口；胶水代码生成（SWIG）也常在 CMake 里用自定义命令调用。

cmake 复制代码

add_library(mylib STATIC src/mylib.cpp)

2.2 依赖管理：vcpkg / Conan

vcpkg：与 CMake 集成体验好，工程落地快。
Conan：在复杂 CI、私有仓库、多配置场景更灵活。

3. C++ 跨语言绑定工具总览

3.1 按「谁定义边界」分类

类型	代表	边界定义方式	典型场景
从 C++ 头反向生成	SWIG、部分绑定	`.h` + `.i` 或解析头文件	已有大量 C/C++ API，要多语言导出
IDL 正向定义	Djinni、Thrift/Protobuf 等	独立接口描述语言	移动端双端 + C++ 核心，强约束 ABI
头文件内写绑定	pybind11、Boost.Python	C++ 模板/元编程	Python 为主、追求现代 C++ 写法

3.2 Python 方向

pybind11：现代 C++ 风格，当前主流之一。
Boost.Python：模板能力强，但较重。
SIP：Qt 生态常见。
Cython / cppyy：适合不同动态/性能诉求。

3.3 Java / Android 方向

SWIG（生成 JNI 胶水）
JavaCPP
手写 JNI：可控性最高、维护成本最高。

3.4 Lua / JS 方向

Lua：Sol2、LuaBridge、tolua++
JavaScript/Web：Emscripten（C++ → WebAssembly）等

4. SWIG：原理与示例演示

4.1 一句话与官方入口

SWIG（Simplified Wrapper and Interface Generator） ：读 C/C++ 声明 与 .i 接口文件 ，输出 C/C++ 包装编译单元 + 目标语言侧模块 （如 Python 的 .py + *_wrap.cxx），靠 typemap 描述「宿主语言类型 ↔ C++ 类型」的转换规则。文档与版本说明见 SWIG 官网文档。

4.2 在工具链中的位置（图）

工程头文件

*.h / *.hpp
接口文件

*.i
swig 可执行文件
生成的 wrap.cxx / wrap.c
生成的 Python/Java/C#...

绑定层源码
与你原有 C++ 一起链接

成扩展模块或共享库

要点：SWIG 不运行你的业务逻辑 ，它只负责生成「能编译、能链接、能按约定传参」的胶水；业务仍在你的 .cpp 里。

4.3 运行时：一次跨语言调用怎么走（示意）

以 Python 调 C++ 函数 为例（概念上与 Java JNI 生成类似，都是「宿主 → 胶水 → 原生」）：
你的 C++ 实现 C/C++ wrap_* SWIG 生成代理 Python 用户代码你的 C++ 实现 C/C++ wrap_* SWIG 生成代理 Python 用户代码 add(1, 2) 经 Python C API 进入参数已转换后调用 add 返回值包装为 PyObject 等 Python int

4.4 最小示例：头文件 + `.i`（演示用）

mathlib.h（被绑定的真实接口）：

cpp 复制代码

#pragma once
// 演示：保持 C++ 可链接即可；对外暴露给 SWIG 的是声明。
int add(int a, int b);

mathlib.cpp（实现略；与平常 C++ 项目相同。）

mathlib.i（告诉 SWIG：模块名、如何把声明塞进生成的 wrap 里）：

swig 复制代码

%module mathlib

%{
#include "mathlib.h"
%}

int add(int a, int b);

含义简述：

块	作用
`%module mathlib`	生成 Python 时常见 `import mathlib`；其他语言对应各自模块名规则。
`%{ ... %}`	原样复制到生成的 `.cxx` 顶部，用于 `#include` 真实头文件。
最后的 `int add(...)`	告诉 SWIG 要导出的声明（可直接 `%include "mathlib.h"` 代替手写一行行）。

典型生成物 （随 -python / -java 等目标而变，名字仅作示意）：

产物	角色
`mathlib_wrap.cxx`	C++/Python 之间转换、`PyArg_Parse` 一类逻辑多在这里
`mathlib.py`（Python）	用户 `import` 的薄封装，转发到 `_mathlib` 等扩展模块

构建时常见模式：先用 SWIG 生成源码，再把 wrap 与业务 .cpp 一并交给编译器 ，最后产出 .so / .pyd / jni 侧动态库等。

4.5 typemap：跨语言真正的「开关」

当默认映射不满足需求（例如 std::vector<std::string>、自定义智能指针、异常策略）时，在 .i 里写 typemap，显式规定：

in：从 Python 对象取出 C++ 参数；
out：把 C++ 返回值包成 Python 对象；
argout、typecheck` 等：输出参数、重载匹配等高级话题。

示意（语法随版本与目标语言变化，不可直接当生产片段复制）：

swig 复制代码

// 概念示意：把 Python int 转 C++ int 一类的逻辑由 typemap 描述
%typemap(in) int {
  $1 = PyLong_AsLong($input);
}

工程经验：typemap 是 SWIG 能力的上限，也是维护成本的上限------能不用复杂模板暴露接口，就不要把复杂度推到 typemap 里。

4.6 SWIG 常见坑（表）

现象	常见原因	处理方向
模板/重载解析失败	SWIG 子集不支持或需 `%template`	简化对外 API，或显式实例化包装
内存泄漏 / 双重释放	默认所有权与直觉不一致	阅读 doc 中 ownership 、`%newobject` 等
异常穿过边界崩溃	目标语言未配置异常映射	在 C++ 侧 catch 后转错误码，或配置 `%exception`

5. Djinni：原理与示例演示

5.1 定位与项目状态

Djinni ：用 IDL（接口描述语言） 描述 C++ 与 Java / Objective-C（及 Swift 通过 ObjC 桥）之间的接口，生成多端源码 ，在 JNI / ObjC++ 边界上把调用导入你的 C++ 实现。原始项目由 Dropbox 开源，上游 GitHub 已 Archived ，但思路与生成物形态仍是理解「IDL 驱动移动跨端」的经典样本；见 djinni GitHub。

5.2 在移动端架构中的位置（图）

C++ 核心
Djinni 生成层
移动 App
Java / Kotlin

(Android)
ObjC / Swift

(iOS)
JNI 胶水
ObjC++ 桥
你的业务实现

*.cpp

与 SWIG 的直觉差异：Djinni 不解析你现有 C++ 头文件来猜接口 ，而是要求你先在 IDL 里声明契约，再在各端填实现或调用。

5.3 生成与数据流（图）

*.djinni
djinni 生成器
C++ 头/桩代码
Java 接口 + JNI
ObjC 协议 + 桥接

5.4 最小示例：IDL + 各端职责（演示用）

example.djinni（语法为示意，以你所用的生成器版本为准）：

djinni 复制代码

# 演示用伪代码风格；真实项目请对照官方 example

Calculator = interface +c {
    # +c 表示实现放在 C++ 侧，由 Java/ObjC 调用
    add(a: i32, b: i32): i32;
}

Point = record {
    x: i32
    y: i32
}

符号	含义（工程口语）
`interface +c`	C++ 实现接口；Java/ObjC 拿的是「代理 / 句柄」
`record`	类似 POD 结构体，适合跨边界传值

你在 C++ 侧通常会：

继承生成出来的抽象基类（名称以生成器为准）；
实现 add；
由工厂或注册函数把实现对象挂接到 Java/ObjC 持有的接口引用上。

一次调用链（概念）：

text 复制代码

  Java:  calculator.add(1, 2)
      →  JNI 进入 Djinni 生成桩
      →  C++: YourCalculator::add(1,2)
      →  返回值经 JNI 装箱回 int

5.5 ABI 边界：为什么强调 POD、指针与 shared_ptr

Djinni 的设计哲学之一是：JNI/ObjC++ 边界上尽量不直接搬运复杂 C++ 类型 （如随意传 std::string / std::vector 的引用语义），以降低 未定义行为与版本不一致 风险。

常见工程约束（口语化）：

主题	建议
跨边界数据	优先基本类型、`record`、明确所有权句柄
对象生命周期	生成代码常围绕 `std::shared_ptr` 建模，避免悬空引用
异常	少让 C++ 异常直穿 JNI；可映射为错误码或语言侧异常类型

5.6 与 SWIG 同场景对比（Android 调 C++）

步骤	SWIG 思路	Djinni 思路
接口从哪来	从现有 `.h` + `.i` 导出	从 `.djinni` 正向声明
JNI 谁写	SWIG 生成大量通用 glue	Djinni 生成偏「贴合本接口」的 glue
改接口	改头 / 改 `.i`，重新跑 SWIG	改 IDL，全端重新生成
适合谁	已有 C API / 希望多语言一次导出	移动双端 + C++ 核心、强契约

6. SWIG vs Djinni（选型对照）

维度	SWIG	Djinni
输入	C/C++ 头文件 + `.i`	IDL
解析方式	解析 C/C++ 接口（语言子集）	解析自定义 DSL
目标语言范围	很广（Python/Java/C#/Ruby/Go/JS...）	聚焦 Java/ObjC/Swift + C++
生成代码风格	通用 Wrapper，偏「宽」	各端更原生，偏「窄而深」
适配场景	多语言暴露、历史包袱、算法库外抛	移动端 C++ 核心 + 双端 UI
接口边界治理	依赖 typemap + 团队约定	IDL + 生成器强约束
维护形态	`.i` 与模板复杂度可能累积	IDL 变更驱动多端同步

决策树（示意）：
是
是
否
否
Python
多语言或未知
移动端 Android+iOS

共享 C++ 核心?
能接受 IDL 为

接口唯一真相?
Djinni 类方案
SWIG 出 JNI

或手写 JNI/分端胶水
宿主语言以谁为主?
pybind11 优先

老库多语言再考虑 SWIG
SWIG 或分语言评估

7. 快速选型建议

只解决多平台构建：优先 CMake，依赖配 vcpkg/Conan。
C++ → Python：优先 pybind11；老工程或多语言统一可看 SWIG。
C++ → Android + iOS：Djinni 类 IDL 方案在「契约清晰」上占优；若已有大量 C 接口也可 SWIG 出 JNI。
C++ → C#/.NET：优先看 CppSharp（或 SWIG 的 C# 目标）。
极致可控：手写 JNI/ObjC++，但维护成本最高。

8. 落地注意事项（经验向）

先稳 ABI 边界：跨语言层尽量用稳定、简单的数据结构。
减少异常跨边界传播：统一错误码或异常映射策略。
显式生命周期策略：跨语言对象尽量单一所有权模型；SWIG 查 ownership，Djinni 跟生成器对 shared_ptr 的约定。
构建与绑定分层：先跑通纯 C++ 构建，再叠胶水层；CI 中把「生成 → 编译 → 链接」做成显式步骤，避免本地才生成的文件漏提交或误提交。
CI 覆盖双侧测试：不仅测 C++ 单测，也测语言侧调用冒烟。

9. 延伸阅读

SWIG Documentation
dropbox/djinni（Archived）
构建侧可对照：C++ 包管理工具概览、C++ vcpkg：安装、使用、原理与选型

10. 免责声明

本文为技术选型与原理梳理，示例代码为教学裁剪，不保证 可直接复制即通过你当前工具链版本编译。具体生成选项、支持的语言特性与平台约束请以 SWIG / Djinni 官方或 fork 文档 及实际工程验证为准。

C++跨平台与跨语言绑定工具：SWIG、Djinni 等选型