Rusty V8 绑定

V8 版本：12.9.202.2

目标

1. 提供高质量 Rust 绑定到 V8 的 C++ API。API 应尽可能接近原始 API。

2. 不引入额外的调用开销。（例如，之前的 Rust V8 绑定强制使用持久句柄。）

3. 不依赖于在 cargo 外部构建的 libv8.a。V8 是一个非常大的项目（超过 60 万行 C++ 代码），通常需要 30 分钟才能编译。此外，V8 依赖于 Chromium 的定制构建系统（gn + ninja），这在外部使用并不容易。因此，许多绑定到 V8 的尝试依赖于单独构建的预构建的二进制文件。虽然这很简单，但它使得升级 V8 变得困难，使得 CI 变得困难，使得生成不同配置的构建变得困难，并且是一个安全问题，因为二进制块可能隐藏恶意代码。因此，我们相信，在 "cargo build" 期间从源代码构建 V8 是至关重要的。

4. 在crates.io上发布crate并允许docs.rs生成文档。由于V8构建的复杂性和大小，这并非易事。例如，为了发布，crate的大小必须保持在10 MiB以下。

二进制构建

V8非常大，编译时间也很长。许多用户更愿意使用V8的预构建版本。我们在Github上为每个版本的rusty v8发布静态库。

默认启用二进制构建：运行cargo build将从Github下载静态库。要禁用此构建，请使用环境变量V8_FROM_SOURCE。

在修改rusty_v8本身时，应通过源代码构建进行测试。CI总是从源代码构建。

V8_FORCE_DEBUG环境变量

默认情况下，rusty_v8将链接到v8的发布版本，如果您想使用v8的调试版本，请设置V8_FORCE_DEBUG=true。

由于性能和CI原因，我们在deno中默认使用v8的发布版本。

RUSTY_V8_MIRROR环境变量

告诉构建脚本从哪里获取二进制构建。理解http://和https:// URL，以及文件路径。默认为https://github.com/denoland/rusty_v8/releases。

基于文件的镜像适合使用缓存的下载。首先，将环境变量指向合适的位置

# you might want to add this to your .bashrc
$ export RUSTY_V8_MIRROR=$HOME/.cache/rusty_v8

然后填充缓存

#!/bin/bash

# see https://github.com/denoland/rusty_v8/releases

for REL in v0.13.0 v0.12.0; do
  mkdir -p $RUSTY_V8_MIRROR/$REL
  for FILE in \
    librusty_v8_debug_x86_64-unknown-linux-gnu.a \
    librusty_v8_release_x86_64-unknown-linux-gnu.a \
  ; do
    if [ ! -f $RUSTY_V8_MIRROR/$REL/$FILE ]; then
      wget -O $RUSTY_V8_MIRROR/$REL/$FILE \
        https://github.com/denoland/rusty_v8/releases/download/$REL/$FILE
    fi
  done
done

RUSTY_V8_ARCHIVE环境变量

告诉构建脚本使用特定的v8库。这可以是URL或路径。这在你有预构建存档时很有用。

export RUSTY_V8_ARCHIVE=/path/to/custom_archive.a
cargo build

从源代码构建V8

使用V8_FROM_SOURCE=1 cargo build -vv来完全从源代码构建crate。

构建脚本需要Python 3可用，作为python3在您的PATH中。如果您想指定要使用的Python的确切二进制文件，您应使用PYTHON环境变量。

构建还需要在您的系统上安装curl。

对于Linux构建：需要安装glib-2.0开发文件，以便pkg-config可以找到它们。在Ubuntu上，运行sudo apt install libglib2.0-dev来安装它们。

对于Windows构建：需要使用64位工具链。不支持32位目标。

对于Mac构建：您需要安装Xcode和Xcode CLT。最新的macOS版本还要求您传递PYTHON=python3，因为macOS不再附带链接到Python 3的python。

对于Android构建：您需要从x86_64主机交叉编译到aarch64或x64 android。您可以使用以下命令

rustup target add aarch64-linux-android  # or x86_64-linux-android
V8_FROM_SOURCE=1 cargo build -vv --target aarch64-linux-android
# or with cross
docker build --build-arg CROSS_BASE_IMAGE=ghcr.io/cross-rs/aarch64-linux-android:0.2.5 -t cross-rusty_v8:aarch64-linux-android .
V8_FROM_SOURCE=1 cross build -vv --target aarch64-linux-android

构建依赖于几个二进制工具：gn、ninja和clang。如果这些工具在环境中未检测到，它们将自动下载。

指定环境变量 $GN 和 $NINJA 可以用来跳过下载 gn 和 ninja。通过将 $CLANG_BASE_PATH 设置为包含 llvm/clang 安装的目录，可以跳过 clang 的下载。由于 V8 依赖于最新的特性，因此建议使用 LLVM v8.0+ 或 Apple clang 11.0+。

可以通过设置环境变量 $GN_ARGS 将参数传递给 gn。

构建源代码时使用的环境变量：SCCACHE、CCACHE、GN、NINJA、CLANG_BASE_PATH、GN_ARGS

常见问题解答

构建 V8 超过 30 分钟，对我来说太慢了。我该怎么办？

安装 sccache 或 ccache。我们的构建脚本将检测并使用它们。如果它们不在您的路径中，请设置 $SCCACHE 或 $CCACHE 环境变量。

所有这些随机的目录如 build 和 buildtools 真的是必要的吗？

为了从源代码构建 V8，我们必须提供 Chromium 的某些 git 子模块的特定目录结构。我们欢迎对代码库进行任何简化，但这是我们在多次失败尝试后找到的一种结构，它谨慎地平衡了 cargo crates 和 GN/Ninja 的需求。

V8 有一个非常大的 API，包含数百个方法。为什么您不自动化生成这个绑定代码呢？

我们实际上已经多次开始走这条路，但是由于 V8 API 的许多异常特性，这并没有证明是成功的。因此，我们现在正在采取一种蛮力方法，首先专注于解决我们声明的目标。我们希望未来能够自动生成绑定。

为什么您要构建这个？

这是为了支持 Deno 项目。我们之前通过一个名为 libdeno 的更简单的 V8 高级 Rust 绑定来完成任务。但随着 Deno 的成熟，我们发现自己在 Rust 中不断需要访问越来越多的 V8 API。

构建时出现未知参数：'-gno-inline-line-tables'

在构建过程中使用 export GN_ARGS="no_inline_line_tables=false"。

我的程序在初始化时崩溃

在启用 PKU 功能的非主线程上初始化 V8 可能会导致崩溃。您可以通过使用 v8::new_unprotected_default_platform 来解决这个问题。

查看https://github.com/denoland/rusty_v8/issues/1381

下载缓存

用于预构建模式链接的v8存档可以被缓存，以避免在切换分支时重新下载存档，否则这些分支会改变当前的rusty_v8版本。

要手动填充缓存，您需要将文件放置在您的.cargo文件夹中的适当位置。运行cargo build -v -v将打印出两行，您可以使用这些行来确定正确的文件和缓存位置

[v8 0.87.0] static lib URL: https://github.com/denoland/rusty_v8/releases/download/v0.87.0/librusty_v8_release_aarch64-apple-darwin.a.gz
[v8 0.87.0] Looking for download in '"/Users/<name>/.cargo/.rusty_v8/https___github_com_denoland_rusty_v8_releases_download_v0_87_0_librusty_v8_release_aarch64_apple_darwin_a_gz"'

curl -L https://github.com/denoland/rusty_v8/releases/download/v0.87.0/librusty_v8_release_aarch64-apple-darwin.a.gz >
  /Users/<name>/.cargo/.rusty_v8/https___github_com_denoland_rusty_v8_releases_download_v0_87_0_librusty_v8_release_aarch64_apple_darwin_a_gz

$ V8_FROM_SOURCE=1 cargo build
$ V8_FROM_SOURCE=1 cargo build --release