carton 📦

carton 的主要目标是在为 WebAssembly 开发时提供流畅的零配置体验。它目前通过单独的命令支持以下功能

• 使用 swift run carton dev 监视应用程序的源代码更改并在浏览器中重新加载它。
• 使用 swift run carton test 在完整的 JavaScript/DOM 环境中运行您的 XCTest 套件。
• 使用 swift run carton bundle 优化和打包应用程序以进行分发。

carton 的主要动机来自于在 webpack.js 上遇到足够多的麻烦之后，试图使其配置文件工作，寻找合适的插件。在某个时候，维护者们确信，在 SwiftWasm 项目中必须使用 webpack 可能会限制 SwiftWasm 本身的更广泛采用。希望有了 carton，您可以完全避免使用 webpack。carton 还简化了 SwiftWasm 开发工作流程中的其他一些事情，例如工具链和 SDK 安装。

• Xcode 15.1 或更高版本。
• Swift 5.9.2 或更高版本.

要将 carton 作为 SwiftPM 插件安装，首先将以下行添加到您的 Package.swift 文件中

dependencies: [
    .package(url: "https://github.com/swiftwasm/carton", from: "1.0.0"),
],

swift run carton dev 命令使用 SwiftWasm 工具链构建您的项目，并启动一个 HTTP 服务器，该服务器托管您的 WebAssembly 可执行文件和一个加载它的相应 JavaScript 入口点。该应用程序可在 http://127.0.0.1:8080/ 访问，将在您的默认 Web 浏览器中自动打开。开发服务器使用的端口也可以使用 --port 选项（或简写 -p）进行控制。您可以在您喜欢的编辑器中编辑应用程序源代码并保存，carton 将立即重建应用程序并重新加载所有打开了该应用程序的浏览器选项卡。您还可以传递 --verbose 标志以保持构建过程输出可用，否则默认情况下会从终端屏幕清除过时的输出。如果您有想要在服务时使用的自定义 index.html 页面，请使用 --custom-index-page 选项传递其路径。

swift run carton test 命令在 wasmer、node 或使用您的默认浏览器中运行您的测试套件。您可以使用 --environment 选项在这些之间切换，传递 command、node 或 browser。依赖于 JavaScriptKit 的代码应传递 --environment node 或 --environment browser 选项，具体取决于它是否需要 Web API 才能工作。否则，测试运行将不会成功，因为使用 --environment command 时 JavaScript 环境不可用。如果您想在 CI 上或在没有 GUI 但在浏览器上运行测试套件，则可以传递 --headless 标志。它启用基于 WebDriver 的无头浏览器测试。请注意，您需要在运行测试之前在 PATH 中安装 WebDriver 可执行文件。您可以使用带有预构建测试捆绑包二进制文件的命令，而不是在 carton 中构建它，方法是传递 --prebuilt-test-bundle-path <您的二进制文件路径>。

swift run carton bundle 命令使用 release 配置（尽管您可以传递 --debug 标志来更改它）构建您的项目，并将所有必需的资源复制到 Bundle 目录。然后，您可以使用静态文件托管（例如 GitHub Pages）或任何其他支持静态文件的服务器来部署您的应用程序。除 index.html 之外的所有生成的捆绑文件都按其内容哈希命名，以启用缓存失效。与 swift run carton dev 一样，可以通过 --custom-index-page 选项提供自定义 index.html 页面。您还可以传递 --debug-info 标志以在生成的 .wasm 文件中保留 names 和 DWARF 部分，因为默认情况下这些部分在 release 配置中被剥离。默认情况下，swift run carton bundle 将在生成的 .wasm 二进制文件上运行 wasm-opt，以减小其文件大小。可以通过附加 --wasm-optimizations none 选项来禁用该行为（为了加速构建）。

所有委托给 swift build 和 swiftc 的命令（即 dev、test 和 bundle）都可以传递 -Xswiftc 参数，这等同于 swift build 中的 -Xswiftc。所有 -Xswiftc 参数都将未经修改地传播到 swiftc 本身。

所有这些命令和子命令都可以传递 --help 标志，该标志会打印用法信息和有关所有可用选项的信息。

carton 捆绑了一个 WASI polyfill，这是当前运行任何 SwiftWasm 代码所必需的，以及 JavaScriptKit 运行时，以方便使用。carton 还嵌入了一个 HTTP 服务器，用于直接在浏览器中预览您的 SwiftWasm 应用程序。polyfill 的开发版本与服务器建立辅助 WebSocket 连接，以便在重建的二进制文件可用时重新加载开发浏览器选项卡。这使开发体验更接近 Xcode 实时预览，您可能以前在开发 SwiftUI 应用程序时使用过它。

对于这些基本开发场景，carton 不需要任何配置文件，而将来可能会支持某些配置，例如在需要时支持复杂的资源管道。唯一的要求是您的 Package.swift 至少包含一个可执行产品，当您在 Package.swift 所在的目录中启动 swift run carton dev 时，该产品将被编译为 WebAssembly 并提供服务。

carton 是作为使用 SwiftNIO 的 SwiftPM 插件构建的，并且同时支持 macOS 和 Linux。（非常感谢所有支持和维护这些项目的人！）

默认情况下，swift run carton dev 将在 debug 配置中编译。添加 --release 标志以在 release 配置中编译。

carton 以前嵌入了 JavaScriptKit 库的运行时部分。此运行时允许 Swift 和 JavaScript 代码在 Node.js 和浏览器环境中互操作。由于 JavaScriptKit 运行时的嵌入方式，旧版本的 JavaScriptKit 与不同版本的 carton 不兼容，反之亦然。从 JavaScriptKit 0.15 和 carton 0.15 开始，不同版本之间的这种不兼容性得到了解决。高于这些版本的所有 carton 和 JavaScriptKit 版本组合都彼此兼容。

您仍然必须记住，旧版本的 SwiftWasm 可能与较新的 carton 不兼容。如果您需要使用旧版本，可以参考兼容性矩阵

如果此工具为您节省了任何时间和金钱，请考虑赞助 SwiftWasm 组织。或者，您可以直接在我们的维护人员的个人赞助页面上赞助他们：@carson-katri、@kateinoigakukun 和 @MaxDesiatov。虽然某些赞助级别为您提供优先支持甚至咨询时间，但任何金额都表示感谢，并有助于维护项目。

成为黄金或白金赞助商，并联系维护人员以在我们的 GitHub 上的 README 中添加您的徽标以及指向您网站的链接。

本项目使用 SwiftFormat 和 SwiftLint 来强制执行格式和编码风格。我们鼓励您在存储库的本地克隆中以最适合您的方式手动或自动运行 SwiftFormat，通过 Xcode 扩展、构建阶段 或 git pre-commit hook 等。

为了保证这些工具在您在 macOS 上提交更改之前运行，我们鼓励您运行此命令一次以设置 pre-commit hook

brew bundle # installs SwiftLint, SwiftFormat and pre-commit
pre-commit install # installs pre-commit hook to run checks before you commit

有关更多详细信息和其他平台的安装说明，请参阅 pre-commit 文档页面。

SwiftFormat 和 SwiftLint 也在 CI 上为每个 PR 运行，因此 CI 构建可能会因格式或风格不一致而失败。我们要求 CI 构建在合并之前对所有 PR 都通过。

本项目遵守“贡献者盟约行为准则”。参与即表示您需要遵守此准则。请将不可接受的行为报告给 hello@swiftwasm.org。