開発ガイド¶

このページでは、YanmaJS 自体の開発に必要なビルド・テスト・ツールの使い方を説明します。

前提条件¶

• Docker / Docker Compose
• Zig 0.16.0 以降（ホストで直接ビルドする場合）

YanmaJS の開発は Docker コンテナ上で行うことを前提としています。ホスト側に Zig をインストールしなくても、Docker 経由でビルド・テストが実行できます。

開発コンテナと UID/GID¶

コンテナはホストのユーザー ID(UID)・グループ ID(GID)で起動できます。これにより、コンテナ内で生成されたファイル(zig-out/ など)がホスト側でも自分の所有になり、権限の食い違いを避けられます。UID/GID を指定しない場合は既定値 1000:1000 で起動します。

自分の UID/GID が 1000 以外の場合は、リポジトリルートに .env を作成して指定します(.env は git 管理外)。

printf 'UID=%s\nGID=%s\n' "$(id -u)" "$(id -g)" > .env

docker compose は .env を自動で読み込み、compose.yaml の user: "${UID:-1000}:${GID:-1000}" に反映します。

プロジェクト構成¶

コンポーネントの一覧・役割・依存関係はコンポーネント構成を参照してください。

ビルド¶

Docker Compose 経由でビルドする場合は make build を使います。エンジン(yanmajs/)と CLI(yanmajs_cli/)の両方がビルドされます。

make build

これは内部的に以下のコマンドを実行します。

docker compose run --rm dev sh -c "zig build"

ホストに Zig 0.16.0+ がインストールされている場合は、リポジトリルートで直接 zig build を実行することもできます。

zig build

リポジトリ全体は単一の build.zig(ルート)で構成され、エンジン(yanmajs/)・ランタイム(yanmajs_runtime/)・CLI(yanmajs_cli/)などをモジュールとして繋いでいます。既定の zig build はエンジンの静的ライブラリと CLI(zig-out/bin/yanmajs)を生成します。make build-cli も同じ既定ビルドの別名です。

テスト¶

make test

内部的には docker compose run --rm dev sh -c "zig build test --summary all" が実行されます。ホスト上で直接テストする場合は make test-native を使うか、リポジトリルートで zig build test --summary all を実行してください。

yanmajs_runtime(EventLoop/FsModuleLoader/console・rejection ポリシー)のテストは別コマンドです。

make test-runtime

内部的には docker compose run --rm dev sh -c "zig build test-runtime --summary all" が実行されます。

C ABI(yanmajs_capi)¶

C ABI 層は yanmajs_capi/ のソースとして提供され、ルートの build.zig の capi ステップでビルドします。詳細な API 面の説明は C API ガイドを参照してください。

make build-capi

内部的には docker compose run --rm dev sh -c "zig build capi" が実行され、zig-out/lib/libyanmajs.so・zig-out/include/yanmajs.h が生成されます。

make test-capi

capi.zig 内のスモークテスト(13 本)を実行します(内部的には zig build test-capi --summary all)。

C API のサンプル(examples-c)¶

C ABI のサンプル 4 本(example/c/*.c)を、共有ライブラリ libyanmajs.so に対してビルドし、そのまま実行します。

make examples-c

内部的には docker compose run --rm dev sh -c "zig build examples-c" が実行されます。

CLI¶

YanmaJS は簡易的な CLI(yanmajs 実行ファイル)も yanmajs_cli/ のソースとして提供しています。make build(または make build-cli)でビルドすると zig-out/bin/yanmajs が生成されます。

# スクリプトファイルを実行
./zig-out/bin/yanmajs script.js

# 式を直接評価
./zig-out/bin/yanmajs -e "1 + 2"

# 引数なしで REPL を起動
./zig-out/bin/yanmajs

# 標準入力から読み込む
echo "1 + 2" | ./zig-out/bin/yanmajs

# ES モジュールとして実行(import/export・top-level await が使える)
./zig-out/bin/yanmajs --module main.mjs

モジュール関連のオプション¶

CLI はファイルシステムベースのモジュールローダーを内蔵しており、import()(dynamic import)はスクリプト実行時にも利用できます。

WASM サンドボックス(プレイグラウンド)¶

YanmaJS には、ブラウザ上で動作する WASM 版のプレイグラウンドが付属しています(WASM ビルドは yanmajs_wasm、HTML ページは yanmajs_sandbox)。以下のコマンドでビルドし、ローカルサーバーで配信できます。

make build-sandbox
make serve-docs

build-sandbox は WASM バイナリをビルドして docs/sandbox/ に配置し、serve-docs は docs/ ディレクトリを簡易 HTTP サーバー(デフォルトでポート 8080)で公開します。ブラウザで http://localhost:8080/sandbox/ を開くと、その場で JavaScript コードを実行できるプレイグラウンドが利用できます。

ドキュメントビルド¶

make build-doc

WASM サンドボックスのビルド、zensical によるドキュメント生成、サンドボックスの docs/ への配備を一括で行います。生成されたドキュメントは make serve-docs でローカル確認できます。

Makefile タスク一覧¶