如何在 Flutter 中使用 QuickJS
01 Nov 2023 / 5 min read
1. QuickJS 介绍
以下内容来自 QuickJS 官方网站。
QuickJS 是一个小型且可嵌入的JavaScript引擎。它支持 ES2020 规范,包括模块、异步生成器、代理和 BigInt。它还可选择性地支持数学扩展,如大十进制浮点数(BigDecimal)、大二进制浮点数(BigFloat)和运算符重载。
主要特点:
- 小巧且易于嵌入:只需几个 C 文件,没有外部依赖,对于一个简单的"Hello World"程序,x86 代码仅占 210 KiB;
- 快速的解释器,启动时间非常短:在桌面 PC 的单核心上,可以在大约 100 秒内运行 ECMAScript 测试套件的 75000 个测试。运行时实例的完整生命周期不到300微秒;
- 几乎完整支持 ES2020,包括模块、异步生成器和完整的附录B支持(用于遗留 Web 兼容性);
- 当选择 ES2020 功能时,通过了接近 100% 的 ECMAScript 测试套件测试。测试概要可在 Test262 报告中找到;
- 可以将 JavaScript 源代码编译为可执行文件,无需外部依赖;
- 使用引用计数进行垃圾回收(以减少内存使用并具有确定性行为),并带有循环删除功能;
- 数学扩展:BigDecimal、BigFloat、运算符重载、bigint 模式、math 模式;
- 具有基本的C库包装的小型内置标准库;
- 带有 JavaScript 实现的命令行解释器,带有上下文着色功能。
2. 了解 Dart 如何与 C 交互
Flutter 应用使用 Dart 开发,与 C 库交互,就得使用 dart:ffi
库。
dart:ffi
是专门用来与原生 C APIs 进行交互的库,FFI 代表 foreign function interface,即外部函数接口。该库的详细使用方式可以参阅 官方文档。
3. 为不同平台编译 QuickJS
Flutter 是跨平台的 UI 框架,要在不同平台使用 QuickJS,就需要为不同平台编译 QuickJS 的动态库。在 Windows 上,需要编译出 .dll
文件;在 Linux 和 Android 上,需要编译出 .so
文件。
编译不同平台的动态库是在 Flutter 中使用 QuickJS 的前期准备,这里主要介绍 Windows 和 Android 平台的编译步骤,编译 Linux 平台的动态库较简单所以省略。
3.1 为 Windows 平台编译 QuickJS 动态库
安装 MYSYS2,编译 QuickJS 需要使用 MYSYS2 中的 MINGW。
安装完成后,运行 MYSYS2 中的 MINGW64(32 位运行 MINGW32),执行下面的命令安装编译所需工具链:
- 如果想要编译 64 位的 QuickJS,则安装
x86_64-toolchain
:
pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-make mingw-w64-x86_64-dlfcn
echo "#! /bin/sh" > /mingw64/bin/make
echo "\"mingw32-make\" \"\$@\"" >> /mingw64/bin/make
- 如果想要编译 32 位的 QuickJS,则安装
i686-toolchain
:
pacman -S mingw-w64-i686-gcc mingw-w64-i686-make mingw-w64-i686-dlfcn
echo "#! /bin/sh" > /mingw32/bin/make
echo "\"mingw32-make\" \"\$@\"" >> /mingw32/bin/make
之后,继续使用 MYSYS2 打开的 MINGW 终端 clone QuickJS 的仓库:
git clone https://github.com/bellard/quickjs.git
切换到 QuickJS 仓库下,执行命令进行编译:
cd quickjs && make
运行完 make
命令后可以得到 libquickjs.a
,此时再运行下面的命令即可得到 libquickjs.dll
:
gcc -shared -o libquickjs.dll -static -s -Wl,--whole-archive libquickjs.a -lm -Wl,--no-whole-archive
3.2 为 Android 平台编译 QuickJS 动态库
Android 中使用 C/C++ 库需要编写一个 CMakeLists.txt
:
cmake_minimum_required(VERSION 3.4.1)
project(quickjs LANGUAGES C)
include_directories(quickjs)
set(QUICK_JS_DIR ${CMAKE_CURRENT_LIST_DIR}/../../../../quickjs)
set(
SOURCE_DIR
${QUICK_JS_DIR}/cutils.c
${QUICK_JS_DIR}/libbf.c
${QUICK_JS_DIR}/libregexp.c
${QUICK_JS_DIR}/libunicode.c
${QUICK_JS_DIR}/quickjs.c
${QUICK_JS_DIR}/quickjs-libc.c
)
file(STRINGS "${QUICK_JS_DIR}/VERSION" CONFIG_VERSION)
add_definitions(-DCONFIG_VERSION="${CONFIG_VERSION}")
add_definitions(-DCONFIG_BIGNUM)
add_definitions(-D_GNU_SOURCE)
add_definitions(-DCONFIG_CC="gcc")
add_definitions(-DCONFIG_PREFIX="/usr/local")
add_library(
${PROJECT_NAME}
SHARED
${SOURCE_DIR}
)
target_include_directories(${PROJECT_NAME} PUBLIC .)
这个 CMakeLists.txt
位于 Flutter 项目目录的 android/src/main/cpp
文件夹下,将 QuickJS 仓库放置于 Flutter 项目根目录,当 Flutter 编译 Android 平台应用时,会自动生成一个 libquickjs.so
并打包进安装包中。
关于 Android 平台集成 C/C++ 的详细介绍,请参阅官方文档。
4. 使用 ffigen 生成函数绑定
要调用 C/C++ 库中的函数,首先要在 Dart 侧进行“声明”,例如在 C 中有这样一个函数:
int add(int a, int b) {
return a + b;
}
那么在 Dart 中,我们就要有一个对应的函数声明,以供 Dart 代码调用这个函数:
import 'dart:ffi' as ffi;
final nativAddFunc = dynamicLibrary.lookup<ffi.NativeFunction<ffi.Int Function(ffi.Int, ffi.Int)>>('add');
这里的 dynamicLibrary.lookup 方法会通过函数名、返回类型、参数类型去查找对应的 C 函数。
在一个编程语言中对另一个编程语言的函数/变量进行声明,专业术语称之为 语言绑定(language bindings)。
那么问题来了,QuickJS 里有那么多函数,每一个都要在 Dart 侧声明一遍吗?
答案是确实如此,虽然我们大多数时候用不到所有函数和变量,但我们也要编写相当多的代码来使用 QuickJS。
然而 Dart 的官方开发人员非常给力,开发了 ffigen
这个库,该库可以通过头文件自动生成 bindings,大大提高了开发效率!
要生成 QuickJS 的 bindings 只需要:
i. 在 Flutter 项目中安装 ffigen
:
flutter pub add ffigen
ii. 配置 pubspecs.yaml
:
...
## 增加下面的配置
ffigen:
name: 'QuickJSBindings'
description: 'generate bindings for quick js'
output: 'lib/bindings.dart'
headers:
entry-points:
- 'quickjs/quickjs.h'
- 'quickjs/quickjs-libc.h'
iii. 运行 dart run ffigen
。
仅需三步,即可生成完整的 bindings(生成前记得将 QuickJS 的仓库放置于项目根目录)。
5. 使用 QuickJS
首先,打开 libquickjs 动态库:
final _lib = DynamicLibrary.open(libquickjs);
final _ = QuickJSBindings(_lib);
然后,创建 JSContext 和 JSRuntime:
final _runtime = _.JS_NewRuntime();
final _context = _.JS_NewContext(_runtime);
最后,调用 JS_Eval 方法执行 JS 代码:
const flag = JS_EVAL_FLAG_STRICT;
final input = code.toNativeUtf8().cast<Char>();
final name = filename.toNativeUtf8().cast<Char>();
final inputLen = _getPtrCharLen(input);
final jsValue = _.JS_Eval(_context, input, inputLen, name, flag);
calloc.free(input);
calloc.free(name);
final result = _js2Dart(_context, jsValue);
_jsStdLoop(_context);
_jsFreeValue(_context, jsValue);
if (result is Exception) {
throw ret;
}
以上便是使用 QuickJS 的方法,当然,还有一些细节问题需要处理,例如如何处理 Promise 类型的返回值,如何创建事件循环等等。但这篇文章主要介绍如何接入 QuickJS,所以在此不再展开叙述(主要还是懒)。