HTML/CSS/JS 与 C++/Wasm 项目如何组织目录,是否需要 CMake?
现有目录可以作为起点。对于多人协作、计算核心由 C++ 实现的项目,建议将前端源码、C++ 核心、Wasm 接口层和构建产物放在不同目录,并用 CMake 管理 C++ 到 Wasm 的构建。CMake 不是必需的;源文件较少时,也可以直接运行 em++。
这里的 C++ 模块仍运行在浏览器中,项目不需要因为使用 C++ 就额外划分出服务端。
目录应该怎样组织?
可以采用下面的结构,具体名称由团队统一即可:
project/
├── CMakeLists.txt
├── cpp/
│ ├── include/
│ │ └── core.hpp
│ ├── src/
│ │ └── core.cpp
│ └── wasm/
│ └── bindings.cpp
├── web/
│ ├── index.html
│ ├── css/
│ ├── js/
│ │ ├── app.js
│ │ └── wasm-client.js
│ └── assets/
├── tests/
├── build/
├── .gitignore
└── README.md
各目录的职责是:
cpp/include/:计算核心对外提供的头文件;只在内部使用的头文件也可以放在cpp/src/。cpp/src/:计算逻辑,尽量不依赖 DOM 或浏览器交互。cpp/wasm/:向 JavaScript 暴露的接口,以及必要的数据转换。web/:手写的 HTML、CSS、JavaScript 和静态资源。web/js/wasm-client.js:集中处理模块初始化和调用,向 UI 提供普通 JavaScript 函数。build/:CMake 缓存、目标文件和生成的站点文件,通常不提交到版本库。
也可以保留原来位于根目录的 include/ 和 src/。把它们收进 cpp/,主要是为了方便浏览混合语言项目。src/lib/ 建议按具体功能命名;如果存放第三方依赖,应明确区分其来源和管理方式。
对于没有前端构建工具的项目,原来的 public/ 可以继续承担 web/ 的职责。如果以后引入前端工具,应按该工具对 public/ 的约定安排文件。
CMake 负责哪部分构建?
CMake 适合管理 C++ 源文件、头文件路径、依赖库和链接参数;Emscripten 提供编译到 Wasm 的工具链。官方支持通过 emcmake cmake 配置项目,再使用 cmake --build 构建,参见 Emscripten 构建文档。
普通 HTML、CSS 和 JavaScript 可以直接复制到站点输出目录。如果后续需要 JavaScript 打包或 CSS 处理,再增加相应的前端构建步骤即可。
建议将计算核心定义为独立的 CMake target,再让 Wasm 接口 target 链接它。后续添加原生 C++ 测试时,也能复用核心代码。
一个最小的 CMake 与接口示例
下面用“计算平方”演示文件之间的关系,实际项目应替换为自己的计算接口。示例使用 CMake 3.13 及以上版本支持的命令,并选择 C++17;这不代表项目必须使用 C++17。
cpp/include/core.hpp:
#pragma once
double calculate(double value);
cpp/src/core.cpp:
#include "core.hpp"
double calculate(double value) {
return value * value;
}
cpp/wasm/bindings.cpp:
#include "core.hpp"
extern "C" double calculate_value(double value) {
return calculate(value);
}
extern "C" 避免接口名称被 C++ 名字修饰。链接时还需要导出该函数,JavaScript 才能调用它,参见 Emscripten 的 C/C++ 与 JavaScript 交互说明。
根目录的 CMakeLists.txt:
cmake_minimum_required(VERSION 3.13)
project(browser_compute LANGUAGES CXX)
add_library(core STATIC cpp/src/core.cpp)
target_include_directories(core PUBLIC cpp/include)
target_compile_features(core PUBLIC cxx_std_17)
if(EMSCRIPTEN)
add_executable(compute cpp/wasm/bindings.cpp)
target_link_libraries(compute PRIVATE core)
set_target_properties(compute PROPERTIES
SUFFIX ".js"
RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/site/wasm"
)
target_link_options(compute PRIVATE
"--no-entry"
"-sMODULARIZE=1"
"-sEXPORT_ES6=1"
"-sEXPORTED_FUNCTIONS=_calculate_value"
)
endif()
这个接口没有 main(),因此使用 --no-entry。虽然 CMake 中通过 add_executable 定义了链接目标,产物仍是供浏览器加载的 JavaScript 和 Wasm 文件,不是本机可执行程序。
MODULARIZE 和 EXPORT_ES6 使生成的 JavaScript 提供模块工厂函数,前端等待初始化完成后再调用导出函数。加载方式见 Emscripten 模块化输出说明。
前端如何调用并组织构建产物?
在 web/js/wasm-client.js 中集中初始化模块,并复用同一个初始化 Promise:
import createCompute from '../wasm/compute.js';
const modulePromise = createCompute();
export async function calculateValue(value) {
if (!Number.isFinite(value)) {
throw new TypeError('Expected a finite number');
}
const module = await modulePromise;
return module._calculate_value(value);
}
app.js 调用 calculateValue() 并处理结果或异常即可。HTML 入口需要通过 <script type="module"> 加载相应的 JavaScript。
这里的 ../wasm/compute.js 指向构建后的站点目录,源目录 web/ 不必包含生成文件。
假设已经安装并激活 Emscripten,同时安装了 CMake、Ninja 和 Python 3,可以从项目根目录执行:
emcmake cmake -S . -B build/wasm -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build/wasm
cmake -E copy_directory web build/wasm/site
python3 -m http.server 8000 --directory build/wasm/site
然后访问 http://localhost:8000/。示例将前端文件复制到 build/wasm/site/,将 compute.js 和 compute.wasm 放到其中的 wasm/ 目录。修改前端文件后,需要重新执行复制步骤,也可以将复制接入团队的统一构建脚本。
协作时还应约定什么?
先明确跨语言接口的数据类型、错误表示和内存归属。示例只传递一个 double;字符串、数组和 C++ 对象需要额外设计转换方式,不能直接套用这个接口。采用指针和长度传递数据时,还需要明确由谁分配、由谁释放。
生成的 JavaScript 与 Wasm 文件应来自同一次构建,并按加载路径一起部署。通常不应手工修改生成的 compute.js。
如果以后增加本机测试,可以使用 build/native/ 等独立目录,避免与 Emscripten 构建缓存混用。团队还应在 README 中记录工具链版本和构建命令,让新成员能按相同步骤生成站点。
如果计算耗时明显,再评估是否将调用移入 Web Worker。等待 Wasm 初始化的 await 并不会让随后的同步计算自动离开浏览器主线程。
备注:内容仅供参考。
