split ASAN; dev doc

.github/workflows/ci.yml

@@ -44,11 +44,9 @@ jobs:
         run: |
           ./scripts/install-deps.sh
           . emsdk/emsdk_env.sh
-          export EMCC_FORCE_STDLIBS=libc++
-          export FCITX_DISTRIBUTION=fcitx5-js
           emcmake cmake -B build -G Ninja \
             -DCMAKE_BUILD_TYPE=Release
-          cmake --build build
+          EMCC_FORCE_STDLIBS=libc++ FCITX_DISTRIBUTION=fcitx5-js cmake --build build
           npm pack
           cd build/sysroot/usr && tar cjvf ../../../fcitx5-js-dev.tar.bz2 include lib
 

.vscode/tasks.json

@@ -12,7 +12,15 @@
         {
             "type": "shell",
             "label": "Configure",
-            "command": "emcmake cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug",
+            "command": "rm -f build/CMakeCache.txt && emcmake cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug",
+            "group": {
+                "kind": "build"
+            }
+        },
+        {
+            "type": "shell",
+            "label": "Configure with ASAN",
+            "command": "rm -f build/CMakeCache.txt && emcmake cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug -DENABLE_ASAN=ON",
             "group": {
                 "kind": "build"
             }
@@ -31,6 +39,22 @@
                 "kind": "build"
             }
         },
+        {
+            "type": "shell",
+            "label": "Preview",
+            "command": "npx serve -l 9000 -S preview",
+            "group": {
+                "kind": "build"
+            }
+        },
+        {
+            "type": "shell",
+            "label": "Pack",
+            "command": "npm pack",
+            "group": {
+                "kind": "build"
+            }
+        },
         {
             "type": "shell",
             "label": "Format",

CMakeLists.txt

@@ -11,9 +11,15 @@ set(CMAKE_SHARED_LIBRARY_CREATE_C_FLAGS "-sSIDE_MODULE")
 set(CMAKE_SHARED_LIBRARY_CREATE_CXX_FLAGS "-sSIDE_MODULE")
 add_compile_options(-fPIC -fexceptions)
 
-if (CMAKE_BUILD_TYPE STREQUAL "Debug")
+option(ENABLE_ASAN "Enable Address Sanitizer" OFF)
+if (ENABLE_ASAN)
+    # Very slow. Not recommended to use with chinese-addons.
     add_compile_options(-fsanitize=address)
-    add_link_options(-fsanitize=address -gsource-map)
+    add_link_options(-fsanitize=address)
+endif()
+
+if (CMAKE_BUILD_TYPE STREQUAL "Debug")
+    add_link_options(-gsource-map)
 endif()
 
 set(CMAKE_INSTALL_PREFIX /usr)

README.md

@@ -1,3 +1,47 @@
 # Fcitx5 JS
 
 [Fcitx5](https://github.com/fcitx/fcitx5) input method framework ported to JavaScript with WebAssembly.
+
+The project provides an npm package `fcitx5-js-*.tgz`, which powers derivative apps for end user.
+
+Derivative | Note
+-|-
+[Fcitx5 Online](https://github.com/fcitx-contrib/fcitx5-online) | [Preview](https://fcitx-contrib.github.io/online/)
+
+## Build
+
+Fcitx5 JS can be built on Linux, macOS and WSL.
+
+### Install node
+You may use [nvm](https://github.com/nvm-sh/nvm)
+to install node.
+
+### Install pnpm and dev dependencies
+```sh
+npm i -g pnpm
+pnpm i
+pnpm --prefix=fcitx5-webview i
+./scripts/install-deps.sh
+```
+
+### Install emsdk
+https://emscripten.org/docs/getting_started/downloads.html
+
+### Build with CMake
+```sh
+emcmake cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug
+EMCC_FORCE_STDLIBS=libc++ FCITX_DISTRIBUTION=fcitx5-js cmake --build build
+```
+You can also use `Ctrl+Shift+B` (or `Cmd+Shift+B` on macOS) in VSCode to execute a task.
+
+### Preview
+```sh
+npx serve -l 9000 -S preview
+```
+See `interface FCITX` in [Fcitx5.d.ts](./page/Fcitx5.d.ts) for a list of JS APIs.
+They are methods of `window.fcitx` object.
+
+### Pack
+```sh
+npm pack
+```

package.json

@@ -23,6 +23,7 @@
     "error-stack-parser": "^2.1.4",
     "esbuild": "^0.24.0",
     "eslint": "^9.17.0",
+    "serve": "^14.2.4",
     "textarea-caret": "^3.1.0",
     "typescript": "^5.7.2",
     "uzip": "^0.20201231.0"

scripts/prepack.sh

@@ -2,5 +2,11 @@ set -e
 
 rm -rf dist/*
 mkdir -p dist
+
 cp -rL preview/{Fcitx5.{data,js,wasm},lib*} dist
+
+if [[ -e "$(readlink -f preview/Fcitx5.wasm.map)" ]]; then
+  cp -L preview/Fcitx5.wasm.map dist
+fi
+
 cp page/Fcitx5.d.ts dist