Add Emscripten/WebAssembly build and worker

lzray-universe · lzray-universe · commit 2b7f2b9ca045 · 2026-03-20T20:27:15.000+08:00
Add Emscripten (wasm) build support: CI matrix &amp; steps to install emsdk, configure and build with emcmake/emcc, and package wasm artifacts. Update CMakeLists to set emscripten-specific compile/link options, include pre-js, copy the worker stub, and use a static library variant for EMSCRIPTEN. Add README documentation and examples for building and using lunar.js/lunar.wasm and the browser Worker, and ignore build_wasm in .gitignore. Add two runtime helpers: src/emscripten/lunar_pre.js (node FS mounting and path rewriting) and src/emscripten/lunar_worker.js (Worker interface to run the CLI in browsers).
diff --git a/.github/workflows/Release.yml b/.github/workflows/Release.yml
@@ -46,6 +46,11 @@ jobs:
             kind: native
             cmake_args: '-DCMAKE_OSX_ARCHITECTURES="x86_64;arm64"'
 
+          - os: ubuntu-latest
+            name: wasm-emscripten
+            kind: emscripten
+            emsdk_version: 5.0.3
+
     runs-on: ${{ matrix.os }}
 
     steps:
@@ -60,6 +65,34 @@ jobs:
         if: matrix.kind == 'native'
         run: cmake --build build --config Release -j
 
+      - name: Setup Emscripten
+        if: matrix.kind == 'emscripten'
+        shell: bash
+        run: |
+          set -euxo pipefail
+          git clone https://github.com/emscripten-core/emsdk.git "$RUNNER_TEMP/emsdk"
+          "$RUNNER_TEMP/emsdk/emsdk" install ${{ matrix.emsdk_version }}
+          "$RUNNER_TEMP/emsdk/emsdk" activate ${{ matrix.emsdk_version }}
+
+      - name: Configure (emscripten)
+        if: matrix.kind == 'emscripten'
+        shell: bash
+        run: |
+          set -euxo pipefail
+          source "$RUNNER_TEMP/emsdk/emsdk_env.sh"
+          emcmake cmake -S . -B build \
+            -DCMAKE_BUILD_TYPE=Release \
+            -DLUNAR_ENABLE_SERIES_FALLBACK=ON \
+            -DLUNAR_BUILD_TESTS=OFF
+
+      - name: Build (emscripten)
+        if: matrix.kind == 'emscripten'
+        shell: bash
+        run: |
+          set -euxo pipefail
+          source "$RUNNER_TEMP/emsdk/emsdk_env.sh"
+          cmake --build build -j
+
       
       - name: Setup Zig (musl)
         if: matrix.kind == 'musl'
@@ -115,16 +148,24 @@ jobs:
           mkdir -p package
           cp README.md package/
           cp LICENSE package/
-          cp -R vsop87a package/
-          cp -R elpmpp02 package/
 
-          if [ "${{ runner.os }}" = "Windows" ]; then
+          if [ "${{ matrix.kind }}" = "emscripten" ]; then
+            cp build/lunar.js package/
+            cp build/lunar.wasm package/
+            cp build/lunar_worker.js package/
+            cd package
+            tar -czvf ../lunar-${{ matrix.name }}.tar.gz *
+          elif [ "${{ runner.os }}" = "Windows" ]; then
+            cp -R vsop87a package/
+            cp -R elpmpp02 package/
             cp build/Release/lunar.exe package/
             cp build/Release/lunar.dll package/ || true
             cp build/Release/lunar.lib package/ || true
             cd package
             7z a ../lunar-${{ matrix.name }}.zip *
           else
+            cp -R vsop87a package/
+            cp -R elpmpp02 package/
             cp build/lunar package/
             cp build/liblunar.so package/ 2>/dev/null || true
             cp build/liblunar.dylib package/ 2>/dev/null || true
diff --git a/.gitignore b/.gitignore
@@ -10,6 +10,7 @@ Thumbs.db
 # CMake out-of-source builds
 /build/
 /build-*/
+/build_wasm/
 /cmake-build-*/
 /out/
 /package/
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -12,6 +12,28 @@ option(LUNAR_ENABLE_DIMENSION_TYPES "Enable compile-time tagged physical vectors
 option(LUNAR_ENABLE_SERIES_FALLBACK "Enable VSOP87A/ELPMPP02 fallback when BSP is unavailable" ON)
 option(LUNAR_BUILD_TESTS "Build GoogleTest-based test targets" ${BUILD_TESTING})
 
+if(EMSCRIPTEN)
+    set(LUNAR_EMSCRIPTEN_COMPILE_OPTIONS
+        -fexceptions
+    )
+    set(LUNAR_EMSCRIPTEN_LINK_OPTIONS
+        -fexceptions
+        -lnodefs.js
+        -lworkerfs.js
+        "SHELL:-sALLOW_MEMORY_GROWTH=1"
+        "SHELL:-sFORCE_FILESYSTEM=1"
+        "SHELL:-sEXIT_RUNTIME=1"
+        "SHELL:-sENVIRONMENT=node,web,worker"
+        "SHELL:-sEXPORTED_RUNTIME_METHODS=['FS','callMain']"
+        "SHELL:--pre-js ${CMAKE_CURRENT_SOURCE_DIR}/src/emscripten/lunar_pre.js"
+    )
+    configure_file(
+        ${CMAKE_CURRENT_SOURCE_DIR}/src/emscripten/lunar_worker.js
+        ${CMAKE_CURRENT_BINARY_DIR}/lunar_worker.js
+        COPYONLY
+    )
+endif()
+
 set(LUNAR_SERIES_SOURCES
     vsop87a/vsop87a.cpp
     vsop87a/vsop87a_ear.cpp
@@ -100,6 +122,11 @@ target_compile_definitions(lunar_core PUBLIC
     LUNAR_ENABLE_DIMENSION_TYPES=$<BOOL:${LUNAR_ENABLE_DIMENSION_TYPES}>
     LUNAR_ENABLE_SERIES_FALLBACK=$<BOOL:${LUNAR_ENABLE_SERIES_FALLBACK}>
 )
+if(EMSCRIPTEN)
+    target_compile_options(lunar_core PUBLIC
+        ${LUNAR_EMSCRIPTEN_COMPILE_OPTIONS}
+    )
+endif()
 if(MSVC)
     target_compile_options(lunar_core PRIVATE /utf-8)
 endif()
@@ -115,8 +142,19 @@ target_include_directories(lunar PRIVATE
 if(MSVC)
     target_compile_options(lunar PRIVATE /utf-8)
 endif()
+if(EMSCRIPTEN)
+    target_link_options(lunar PRIVATE
+        ${LUNAR_EMSCRIPTEN_LINK_OPTIONS}
+    )
+endif()
+
+if(EMSCRIPTEN)
+    set(LUNAR_DLL_LIBRARY_TYPE STATIC)
+else()
+    set(LUNAR_DLL_LIBRARY_TYPE SHARED)
+endif()
 
-add_library(lunar_dll SHARED
+add_library(lunar_dll ${LUNAR_DLL_LIBRARY_TYPE}
     src/c_api.cpp
 )
 target_link_libraries(lunar_dll PRIVATE lunar_core)
diff --git a/README.md b/README.md
@@ -49,13 +49,78 @@ cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
 cmake --build build -j
 ```
 
-### 2.4 产物
+### 2.4 WebAssembly（Emscripten）
+
+```powershell
+git clone https://github.com/emscripten-core/emsdk.git D:\tools\emsdk
+D:\tools\emsdk\emsdk install latest
+D:\tools\emsdk\emsdk activate latest
+cmd /c "call D:\tools\emsdk\emsdk_env.bat && D:\tools\emsdk\upstream\emscripten\emcmake.bat cmake -S . -B build_wasm -G Ninja -DLUNAR_BUILD_TESTS=OFF -DCMAKE_BUILD_TYPE=Release"
+cmd /c "call D:\tools\emsdk\emsdk_env.bat && cmake --build build_wasm --parallel"
+```
+
+说明：
+
+- 产物为 `build_wasm/lunar.js` 与 `build_wasm/lunar.wasm`
+- 兼容包装还会生成 `build_wasm/lunar_worker.js`
+- 保留现有 CLI 入口；Node 下可直接执行 `node build_wasm/lunar.js --version`
+- wasm 构建默认启用异常支持、文件系统支持、`FS`/`callMain` 导出与内存增长
+- Node 下会自动把当前工作目录挂载到 wasm 虚拟文件系统，当前目录内相对 `.bsp` 路径可直接使用
+- Windows 下会自动兼容 `D:\path\to\file.bsp` 这类盘符绝对路径
+- 浏览器 Worker 下可直接使用 `lunar_worker.js`，按 CLI 的 `argv` 方式调用
+- Worker 支持两种输入：`files` 写入内存文件，或 `mounts` 通过 `WORKERFS` 挂载 `File`/`Blob`
+- `lunar_worker.js` 保持 CLI 语义：单次执行后自动退出；下一条命令请新建 Worker
+- 若不需要 BSP，可继续使用 `@series`
+
+浏览器 Worker 示例：
+
+```js
+const worker=new Worker('./lunar_worker.js');
+
+worker.onmessage=({data})=>{
+  if(data.type==='ready'){
+    worker.postMessage({
+      argv:[
+        'day','2025-06-01',
+        '--bsp','/ephem/'+spkFile.name,
+        '--format','txt'
+      ],
+      mounts:[
+        {path:'/ephem',files:[spkFile]}
+      ]
+    });
+    return;
+  }
+  if(data.type==='result'){
+    console.log(data.exit_code);
+    console.log(data.stdout);
+    console.error(data.stderr);
+  }
+};
+```
+
+浏览器 Worker 也可先写入内存文件：
+
+```js
+worker.postMessage({
+  argv:[
+    'day','2025-06-01',
+    '--bsp','/ephem/de442s.bsp',
+    '--format','txt'
+  ],
+  files:[
+    {path:'/ephem/de442s.bsp',data:spkArrayBuffer}
+  ]
+});
+```
+
+### 2.5 产物
 
 - 可执行程序：`lunar`
 - 动态库：`lunar_dll`（输出名为 `lunar`，对应平台扩展名）
 - 测试程序：`lunar_tests`（启用 `LUNAR_BUILD_TESTS` 时）
 
-### 2.5 可选构建开关
+### 2.6 可选构建开关
 
 - `-DLUNAR_ENABLE_SERIES_FALLBACK=ON|OFF`
   - `ON`（默认）：未找到 BSP 时自动切换到内置 VSOP87A + ELPMPP02
@@ -64,7 +129,7 @@ cmake --build build -j
   - `ON`（默认）：构建 gtest/ctest 测试目标
   - `OFF`：不构建测试目标
 
-### 2.6 运行测试
+### 2.7 运行测试
 
 ```bash
 cmake -S . -B build
diff --git a/src/emscripten/lunar_pre.js b/src/emscripten/lunar_pre.js
@@ -0,0 +1,64 @@
+Module['preRun']=Module['preRun']||[];
+Module['preRun'].push(function(){
+	if(typeof ENVIRONMENT_IS_NODE==='undefined'||!ENVIRONMENT_IS_NODE){
+		return;
+	}
+	if(typeof NODEFS==='undefined'){
+		return;
+	}
+
+	var node_fs=require('node:fs');
+
+	function ensure_dir(path){
+		var info=FS.analyzePath(path);
+		if(info.exists){
+			return;
+		}
+		FS.mkdir(path);
+	}
+
+	function mount_dir(path,root){
+		ensure_dir(path);
+		try{
+			FS.mount(NODEFS,{root:root},path);
+		}catch(ex){
+			var info=FS.analyzePath(path);
+			if(!info.exists||!info.object||!info.object.mounted){
+				throw ex;
+			}
+		}
+	}
+
+	function rewrite_host_path(text){
+		if(typeof text!=='string'){
+			return text;
+		}
+		if(/^[A-Za-z]:[\\/]/.test(text)){
+			var drive=text.charAt(0).toUpperCase();
+			var tail=text.slice(2).replace(/\\/g,'/');
+			if(!tail.startsWith('/')){
+				tail='/'+tail;
+			}
+			return '/'+drive+tail;
+		}
+		return text;
+	}
+
+	mount_dir('/working',process.cwd());
+	FS.chdir('/working');
+
+	for(var code=65;code<=90;++code){
+		var drive=String.fromCharCode(code);
+		var root=drive+':\\';
+		if(!node_fs.existsSync(root)){
+			continue;
+		}
+		mount_dir('/'+drive,root);
+	}
+
+	if(Array.isArray(arguments_)){
+		for(var i=0;i<arguments_.length;++i){
+			arguments_[i]=rewrite_host_path(arguments_[i]);
+		}
+	}
+});
diff --git a/src/emscripten/lunar_worker.js b/src/emscripten/lunar_worker.js
