storm-lua-minify
v0.11.0
Published
A Lua minifier also outputs source map
Maintainers
Readme
storm-lua-minify
このプログラムは mathiasbynens/luamin をベースにした Stormworks: Build and Rescue 向けのLua minifierです。
Stormworks: Build and Rescue 以外の用途にも使用可能です。
使い方
実行にはNode.js 24以上が必要です。
npm i storm-lua-minify
npx storm-lua-minify script.luarequireの展開モード
- オプションを設定しないと
require/dofile先を呼び出し位置へ直接展開する、Stormworks向けLuaを外部で作成する場合に馴染みのある方式となります。- ただし、実装上の制約により、文中で
requireを使用するとfunctionで包んで展開されることがあるので注意してください。
- ただし、実装上の制約により、文中で
-m/--require-wrapperは、requireの挙動を通常のLuaに近づけます。- 冒頭に
require関数を定義し、モジュールはそこに展開されます。
- 冒頭に
--#コメントの出力位置
--#を含むコメント(--[[# ... ]]を含む)は、出力に残ります。
- 既定では、エントリのファイルの先頭にある
--#コメントを、出力の先頭に集めます。-mを指定したときは、require関数の定義より前に置きます。- 「先頭」とは、ファイルの先頭から、空行を挟まず途切れなく続くコメントの塊です。通常の
--コメントが混ざっていても塊は続き、空行が1つでも入ればそこで終わります。塊に入らない--#コメントは、元の位置に出力します。 - 依存module(
requireやdofileで読み込むファイル)のコメントは、集めません。
- 「先頭」とは、ファイルの先頭から、空行を挟まず途切れなく続くコメントの塊です。通常の
--no-hoist-preserved-comments(設定ファイルでは"hoist-preserved-comments": false)を指定すると、すべてのコメントを元のファイルでの位置に近い場所へ出力します。
コンパイル進捗
対話環境で起動すると、現在のファイル、ステップ番号、処理段階を示す表示が出ます。内部処理の分岐によってステップ数の最大値が途中で増減することがあります。
--no-progressで進捗表示を無効化できます。- パイプやCIなどの非対話環境では既定で無効です。
- 非対話環境でも
--progressを指定するとステップの開始と完了を通常のログ行として標準エラーへ出力します。
最適化アノテーション
EmmyLuaアノテーション
EmmyLuaのclass/継承、field、param/return/type、alias/enumを最適化解析のヒントとして使用します。
保護アノテーション(独自)
宣言の直前(空行を挟まない位置)に、次のアノテーションを指定できます。
--@storm export: Luaコード外から名前で参照される宣言として、未使用削除と名前短縮の双方から保護します--@storm keep: 未使用削除から保護しますが、名前短縮は許可します--@storm keep-name: 名前短縮から保護しますが、未使用なら削除を許可します
未知の--@storm指示や引数付きの指示は、エラーになります。
最適化オプション
最適化オプションは、個別スイッチと機能グループの階層構造を持ち、すべての最適化オプションのスイッチに肯定形と否定形があります。
また、最適化オプションとは別に、Luaの動作に仮定を置くことで圧縮強度を高める設定(仮定モード)があります。仮定モードは最適化オプションとは別のレイヤーの設定です。
storm-lua-minify --function-optimizations --no-function-inlining script.lua
storm-lua-minify --no-optimizations --local-renaming script.lua設定ファイルはコマンドと同じキーを使い、平坦に書きます。設定ファイルを使用する際は明示的に--configオプションで指定してください。
各オプションの優先度は、コマンド指定値(個別スイッチ) > コマンド指定値(機能グループ) > 設定ファイル指定値(個別スイッチ) > 設定ファイル指定値(機能グループ) > 既定値の順です。
{
"runtime-profile": "stormworks",
"function-optimizations": false,
"function-inlining": true,
"global-renaming": true,
"never-rename-globals": ["onTick", "onDraw"]
}storm-lua-minify --config storm-lua-minify.json --no-function-inlining script.luaStormworksのproperty呼び出し
runtimeProfile: "stormworks" では、グローバルの property に対する各メソッド呼び出しの前に物理改行を入れます。requiredWhitespace: " " でも、同じテーブル・引数リスト・入れ子の式にある呼び出しを別行に置きます。メソッド名によらず適用し、property の自動的なグローバル別名化・名前短縮も抑止します。同名のローカル変数や仮引数は対象外です。入力に既にある別名経由の呼び出しを property.method(...) へ変換する機能ではありません。テーブルの末尾カンマは強制しません。
仮定モード
runtime-profileの影響を受けます。runtime-profileは、コマンドではstormworksが既定です。ライブラリAPIで省略した場合はlua53として扱います。
これらの機能は実際のコードに対して、圧縮が強まる仮定を置く機能です。仮定が誤っているとコードの結果が変化することがあるため、注意してください。
| 仮定 | 既定 | 説明 |
| ------------------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| allow-introspection-changes | lua53: OFFstormworks: ON | local名・生存期間、parameter、stack frameなどdebug APIから観測できる変更を許可します。現時点ではstormworksプロファイルではOFFできません |
| assume-annotations | OFF | EmmyLuaアノテーションを最適化の変換根拠として信頼します |
| assume-closed-field-names | OFF | プログラムが定義するfield名・method名は、外部から名前で参照されないと仮定し、名前単位で短縮します。field-renamingが有効なときだけ働き、通常のfield短縮の代わりに使われます。詳細 |
| allow-observable-table-read-changes | OFF | テーブルから読み取ってlocal変数を初期化する処理について、テーブルへの書き込み前へ移動する候補を許可します。local変数の値がテーブルへの書き込み前の値に変わる可能性があります |
assume-closed-field-names(名前単位のfield短縮)
既定のfield-renamingは、どのtableに届くかを一つずつ証明できたfieldだけを短縮します。クラスのインスタンスを引数・配列・fieldで受け渡すプログラムでは、証明できない参照が多く、短縮できるfieldが少なくなります。
--assume-closed-field-namesを指定すると、証明の代わりに名前単位で判断します。次の条件をすべて満たす名前を、全モジュールで同じ短い名前に置き換えます。
- プログラムが定義している(
t.name = ...、{ name = ... }、function t.name()、function t:name()のいずれかがある) - 外部の値を経由して読み書きされていない(下記)
- 文字列としても現れない(
"name"、t["name"]を含む)。実行時に文字列でfieldを引く表のキーを守るためです - 計算したキーで引く表(
handlers[name])の、識別子形式のキーではない。local変数かfieldに入れた表のconstructorとその後のfield代入を対象にします __で始まる名前、Lua標準ライブラリとStormworks APIの主なmember名(ツールが内蔵する一覧。完全ではなく、主な保護は下記の外部の値の追跡です)、never-rename-fieldsに指定した名前ではない--@storm export/--@storm keep-nameを付けた文に現れない- 短縮すると文字数が減る
「外部の値」は、server、property、matrix、g_savedataなどを起点に、代入・引数・戻り値・forの変数・table.insertを通って届く値です。その値に対して読み書きしたfield名と、外部の関数へ渡したtable constructorのキーは短縮されません。追跡はテーブル本体を受け渡す場合に限ります(dial.valueのように値を一つ取り出した結果は、field名を介した追跡に使いません)。関数の戻り値は、引数をそのまま返す場合と、外部の値を直接返す場合に追います。引数として渡す先は、呼び出し先を特定できる場合に追います。特定できない呼び出し(obj:new(data)のように受け手の型が分からない呼び出し)は、同じ名前の関数がプログラム内に1つだけのときに限って追い、2つ以上あれば追いません。
storm-lua-minify --assume-closed-field-names --never-rename-field ui_id script.lua{
"assume-closed-field-names": true,
"never-rename-fields": ["ui_id"]
}この仮定が成り立たないと、コードの動作が変わります。次のような場合は、never-rename-fieldsか--@storm keep-nameで保護してください。
- セーブデータ(
g_savedata)を、g_savedataを経由せずに別のtableへ読み出してから使う場合など、ツールが外部の値と判別できないfield名 - 外部の値を、呼び出し先を特定できない呼び出し(同名の関数が複数ある
obj:new(data)など)へ渡し、その中で読み書きするfield。追跡が届かないため、名前が自分のプログラムのfieldと重なるなら保護が必要です - 計算したキーで引く表を、引数や関数の戻り値として受け取っていて、
local変数やfieldに入れた生成元と結びつけられない場合 - 文字列を連結して組み立てたキー(
t["get_" .. kind])で引くfield loadや_ENVへの文字列で参照するfieldpairsで走査した順序や、json.stringify・tostringで出力したfield名に依存する処理。短縮でfield名が変わり、走査順も変わりえます
短縮されなかった名前と理由は、collectOptimizationDiagnosticsのwhole-program-field-rename診断(reasonがexternal-value、string-key、unowned-field、external-contract、keep-name、reserved-keyなど)で確認できます。
個別スイッチ
| スイッチ | 既定 | 説明 |
| -------------------------------------- | ------- | --------------------------------------------------------------------------- |
| local-renaming | ON | local名を短くします |
| local-name-reuse | ON | 生存期間が重ならないlocalで同じ名前を再利用します |
| global-renaming | OFF | 内部で使うglobal名を短くします(※1) |
| field-renaming | ON | 安全に変更できるfield名を短くします |
| global-aliasing | ON | プログラム内で代入されず、繰り返し参照するglobalへ短いlocal名を割り当てます |
| local-declaration-merging | ON | 連続するlocal宣言をまとめます |
| local-declaration-hoisting | ON | local宣言を移動してまとめやすくします |
| table-read-merging | ON | tableを読み取るlocal宣言をまとめます |
| field-sensitive-table-effects | ON | tableへの書き込みの影響をfield単位で判定します |
| constant-expression-evaluation | OFF | 定数だけからなる式を事前に計算します |
| local-constant-propagation | OFF | 再代入されないlocalの定数を参照先へ伝えます |
| interprocedural-constant-propagation | OFF | 関数の呼び出しを越えて定数を伝えます |
| parameter-pruning | ON | 使われない関数parameterを取り除きます |
| function-inlining | ON | 関数呼び出しを関数本体で置き換えます |
| function-specialization | ON | 呼び出し方に合わせて関数を特殊化します |
| field-value-propagation | ON | 安定したfieldの値を参照先へ伝えます |
| unused-local-removal | ON | 未使用のlocalを取り除きます |
| unused-function-removal | ON | 未使用のlocal関数を取り除きます |
| unused-field-initializer-removal | ON | 読み取られないfieldの初期化を取り除きます |
| unused-export-removal | ON | entryから到達できないmodule exportを取り除きます |
安全性の条件を満たさない候補は、スイッチが有効でも実行されません。
--global-renaming から短縮を保護する(※1)
--global-renamingを有効にすると、このツールは「プログラム中のどこかで代入されているグローバル名」を内部専用とみなしてリネームします。
これは通常のスクリプト内部の状態変数には安全ですが、実行環境が直接呼び出す関数名・変数名をうまく検出できません。
短縮から保護する必要がある名前をnever-rename-globalsへ列挙するか、前述の--@storm exportによって保護してください。
コマンドでは--name-rename-globals <保護名>を繰り返し記述します。設定ファイルではnever-rename-globalsに保護する名前の配列を与えます。
機能グループ
機能グループのスイッチを設定すると、個別スイッチをまとめてオンオフします。
| 機能グループ | 個別スイッチ |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| optimizations | 以下の全機能グループ(他の機能グループ設定の方が優先されます) |
| identifier-optimizations | local-renaming, local-name-reuse, global-renaming, field-renaming, global-aliasing |
| statement-optimizations | local-declaration-merging, local-declaration-hoisting, table-read-merging, field-sensitive-table-effects |
| constant-optimizations | constant-expression-evaluation, local-constant-propagation, interprocedural-constant-propagation |
| function-optimizations | parameter-pruning, function-inlining, function-specialization |
| object-optimizations | field-value-propagation |
| dead-code-optimizations | unused-code-removal, unused-export-removal |
| unused-code-removal | unused-local-removal, unused-function-removal, unused-field-initializer-removal |
Source Map
このツールは、圧縮後のコードと合わせて Source Map (.lua.map) を出力します。
.lua.map の sourcesContent には、エントリファイルおよび require/dofile で参照される全モジュールの元テキストがそのまま埋め込まれますので、Source Mapファイル単体で元コードを参照できます。
sourceMappingURLアノテーションの出力形式
出力される .min.lua の末尾に付く sourceMappingURL アノテーションの書式は、3種類から選べます。
本ツール作者による紹介記事で紹介したツールでは、Luaコードとしての有効性を保ちながら認識させるにはlegacyを使う必要があるため、非標準動作を既定としています。
| --source-mapping-url-style | 書式 | 特徴 |
| ---------------------------- | -------------------------------------- | ------------------------------------------------- |
| legacy(既定) | 複数行の --[[〜]] ブロックコメント | 従来形式 |
| line | 単一行の -- ラインコメント | 有効なLuaのままSource Map仕様の最終行規則を満たす |
| strict | Luaコメントで包まないマーカー文字列 | 最終行は有効なLua文ではなくなる |
開発者向けガイド
開発環境の構築、テスト構成、最適化を追加するときの判断基準、scripts/の調査・検証コマンドについては開発者向けガイドを参照してください。
ライブラリAPIのcollectOptimizationDiagnostics: trueでは、探索上限をspecialization-variant-limit/specialization-site-limit、Luaの実行資源制限をruntime-resource-limitで区別します(旧resource-budgetは廃止)。cost gateの例外は任意のfailureに種類と共同trial/ablationの段階を記録します。診断は既定offで、生成コード・Source Mapに影響しません。詳細は開発ガイドを参照してください。
