# hspc HSP3ソースファイルをコンソールでコンパイル、ビルド、診断を行えるCLIツールです。 ## 充実した機能とオプション 基本機能のHSP3ソースファイルのコンパイル、自動実行ファイル作成、文字コードの自動識別、strmapファイルの出力に対応。 診断機能でソースファイルの文法エラーをコンソールに常時表示することが可能です。 hsphelp.idxファイルが作成されていれば、そのままコンソールでドキュメントを閲覧できます。 ## 環境変数の対応 環境変数 HSP3_ROOT にHSP3開発環境ディレクトリパスを設定する事で、hspc.exe直下の環境以外を利用可能になりました。 柔軟に複数のバージョンや環境を切り替えられるので、様々な環境でhspcが導入し易くなります。 # 注意事項(困ったら読むところ) ## 絶対パスと最後の区切り文字 hspcの使用するAPIとhspcmp.dllの都合上、一部引数には絶対パスが必要です。ディレクトリを指定する場合は**パスの最後に\\文字が必要**です。HSP3_ROOT環境変数とhsp3rootオプションの引数には、**/文字を使わない**でください。 絶対パスを必要とするものは、下記の通りです。 - HSP3_ROOT並びに --hsp3root オプションの引数 - --compath オプションの引数 - --rtmdir オプションの引数 - --hsp3root オプションの引数 ## MAX_PATH hspcの使用するAPIの都合上、取り扱えるファイルパスは260byteまでになります。 ## パスの文字コード hspcは内部でShift_JISとして文字列を取り扱っています。なので、Shift_JISで表現できない文字がパスに含まれると、文字化けにより機能しません。 ## システムロケール 上記の仕様から、システムロケールはShift_JIS系のみ対応しています。Unicode UTF-8 環境では機能しません。 ## プロセス実行と管理者権限 hspc.exeが子プロセスを実行するとき、自身の権限を子プロセスに継承させます。 そのため、管理者権限で起動したhspcは、デバッグ実行などで生まれる子プロセスにも管理者権限を付与することになります。 その結果、デバッグ実行したウィンドウにファイルなどをドラッグアンドドロップできない等の症状が生じます。 ## Wine環境 一部WinAPIが正しく動作しない場合、hspcは例外を返しコマンドを終了します。 -mによるiconinsツール使用でリソースの挿入に失敗する場合、hsed3.exeから自動実行ファイル作成を行ってください。iconinsツールを使用しない場合、-Mを使用して自動実行ファイル作成を行えます。 また、`hspc lint --watch`で子ディレクトリの監視ができない場合があります。 ## PowerShell 一部CUI環境ではピリオド(.)で引数を区切られてしまい、意図しない結果になる場合があります。 ダブルクォーテーションで囲むことで、意図した通りに引数を渡すことができます。(例:"-oout.ax") ## HSP3_ROOT 環境変数 HSP3_ROOTの影響を受けたくない場合、HSPC_DISABLE_ENV_HSP3ROOT 環境変数に "true"文字列を設定する事でオミットできます。 ## VS Code VS Code のターミナルから呼び出す場合、hspcは現在のターミナルに設定されているコードページに合わせるようにエンコードして標準出力します。そのため、-rオプションもしくは、-Rオプションによる子プロセスの標準出力コードページ次第では、その出力は文字化けになる場合がございます。 ## HSP3.7以降での自動実行ファイル作成 hspcmp.dllのバージョンが3.7以降の場合、hspc v3.5.x以降で実装されたmaker v3で、自動実行ファイル作成を行います。 maker v3の制約のため、hspc内部のカレントディレクトリは一時的にfileのあるディレクトリに移動します。 fileのあるディレクトリに作成された中間ファイル、packfile、exeファイルは、元のディレクトリへコピーされた後に削除されます。 # インストール・アンインストール hspcはCLIツールなので、解凍した先にパスを通すとコンソールで簡単にhspcコマンドを呼び出せるようになります。 hspc.exeを既存のHSP3開発環境ディレクトリに挿入することで、簡単にインストールできます。アンインストールはhspc.exeの削除で完了します。 配布zipには、最小限のHSP3開発環境を同梱しています。この環境を使用すると、解凍後すぐに使用できます。アンインストールも解凍したディレクトリを削除します。 HSP3_ROOT環境変数、--hsp3rootオプションにHSP3開発環境の絶対パスを設定することでも、その環境を使用することができます。一時的に環境を変更したいときに便利です。 ## 補助ツールを使用した導入について Readme.mdに記載された方法以外による導入時の問題や不具合につきましては、使用したツール作者様に対応していただきたく存じます。 # コマンド ```bat hspc ``` hspcは、コマンドで使用する機能を切り替えることができます。これにより、コンパイルだけでなく、継続的な診断や、ドキュメント閲覧ができます。 下記には、普段からよく使うコマンドレシピと、各コマンドの詳細な説明を記載しています。 ## よく使うコマンドレシピ集 ### デバッグ実行 HSPスクリプトエディタのF5に相当するコマンドです。 ```bat hspc -aCdwRoout app.hsp args ``` app.hspがコンパイルするファイルです。argsを付けることで、dir_cmdlineでその文字列を受け取ることができます。 -Rを-rに変えることで、コマンドはデバッグ実行したスクリプトの終了を待たずに終了します。 ### 自動実行ファイル作成 HSPスクリプトエディタのCtrl-F9に相当するコマンドです。 ```bat hspc -aPmC app.hsp ``` app.hspに対して、自動実行ファイルを行います。-mを-Mに変えることで、iconinsツールを使用しないよう制限する事ができます。 ### strmapファイル作成 ```bat hspc --strmap strmap app.hsp ``` カレントディレクトリにstrmapファイルを作成します。 この機能は、HSP3.6以降で使用できます。 ### 診断(常時監視) ```bat hspc lint --watch .\ ``` カレントディレクトリのソースファイルを一通りコンパイルが通るか診断します。ファイルを保存するなど、変更を加えると自動で再診断します。診断結果は、標準出力へ書き出されます。 watchを終了するには、コンソールにCtrl-Cキーを送信してください。 ## compile ```bat hspc rem or hspc compile ``` HSPソースファイルを中間ファイルへコンパイルします。オプションを組み合わせることで、普段使いの操作ができます。 中間ファイル、実行ファイル、strmapファイルの保存先に同名のファイルが存在する場合、上書き保存します。ファイルの上書き、もしくは削除に失敗したとき、コマンドは失敗して、その時点で終了します。 一文字オプションの後に正数を記入することで、そのオプションのレベルを指定する事ができます。(例:-D1m3) レベルを省略した場合、レベル0が設定されます。 | 一文字オプション文字 | 説明 | | ----: | ----- | | -a | ソースファイルのコードページを推測して、UTF-8の可能性があるなら-iオプションを有効にします。| | -C | カレントディレクトリをファイルのディレクトリに移動します。| | -D | コマンド終了時に中間ファイルを削除します。
レベル2で使用済みpackfileを削除します。| | -d | デバッグ情報を付与してソースファイルをコンパイルします。| | -E | コンパイルエラーでもコマンドの終了コードは0を返すようにします。| | -I | コンパイル中の詳報を標準出力します。| | -i | ソースファイルのコードページをUTF-8として扱います。| | -M | 自動実行ファイル作成を行います。
レベル3で--makerV3が有効になります。| | -m | 自動実行ファイル作成とiconinsツールによるリソース挿入を行います。
レベル3で--makerV3が有効になります。| | -o??? | 保存される中間ファイル名を???に設定します。| | -P | packfileをカレントディレクトリに生成します。| | -p | プリプロセス処理だけ行ってコマンドを終了します。| | -R | ソースファイルを実行して、終了するまで待機します。| | -r | ソースファイルを実行します。| | -S??? | strmapファイル作成して、???名で保存します。| | -u | ソースファイルをShift_JISからUTF-8へエンコードしてコンパイルします。| | -w | 中間ファイルにデバッグウィンドウ表示フラグを立てます。| | -v | hspcのバージョン情報を標準出力します。| | 複数文字オプション文字 | 説明 | | ----: | ----- | | --compath ??? | コモンディレクトリを???に設定します。| | --curdir ??? | カレントディレクトリを???に設定します。| | --hsp3root ??? | HSP3開発環境ディレクトリを???に設定します。| | --iconins | 自動実行ファイル作成時にiconinsツールによるリソース挿入を行います。| | --licence | hspcのライセンス情報を標準出力します。| | --makerV2 | 従来の方法で自動実行ファイル作成を行います。 | | --makerV3 | 新しい方法で自動実行ファイル作成を行います。| | --nonextramacro | HSP3拡張マクロを無効化してコンパイルします。| | --objname ??? | 保存する中間ファイル名を???に設定します。| | --printsymbols | シンボル一覧を標準出力します。| | --refname ??? | コンパイルログのソースファイル名を???に置き換えます。| | --rtmdir ??? | ランタイムディレクトリを???に設定します。| | --wait | -rで実行したスクリプトが終了するまで待機します。| | --version | hspcのバージョン情報を標準出力します。| ### 自動実行ファイル作成のレベルについて v3.4.x以前では、HSP3.6未満のバージョンでなければ-mオプションは使用できませんでした。 v3.5.xから、HSP3.7betaに対応するために、新しい自動実行ファイル作成方法「maker v3」を導入しました。 maker v3は、hspcが読み込んだhspcmp.dllのバージョンが3.7以上であれば、自動判定により有効化されます。 maker v3を明確に使用するには、--makerV3オプションまたは、-mオプション、-Mオプションにレベル3を指定して使用します。 ```bat hspc -aPmC --makerV3 app.hsp rem or hspc -aPm3C app.hsp ``` --makerv2、--makerv3オプションを使用すると、自動判定より優先して設定されます。つまり、HSP3.7以降でも、--makerv2を使用することで従来の自動実行ファイル作成方法でEXEファイルを作成しようとします。 ### 子プロセスについて hspcが-Rオプションや-rオプションで子プロセスを作成するとき、子プロセスは親のhspcコンソールへのアクセス権を持ちます。 これにより、hspcを立ち上げたコンソールを使用して子プロセスと対話する事ができます。 hspcは、--Waitオプションや-Rオプションによる子プロセス待機中に自身のプロセスが内外の原因問わず終了した場合、子プロセスも終了させます。 ## lint ``` hspc lint ``` ソースファイルをコンパイルして構文エラーが無いか診断するコマンドです。 ファイルとディレクトリは複数指定できます。ファイルを指定した場合、--watchで直接監視することはできません。同じ層のディレクトリを指定してください。 --allow、--ignoreオプションは、MS-DOSワイルドカードを使用してファイルパスを許可、制限することができます。両方のワイルドカードに適合したファイルパスを監視、診断します。 |オプション文字|説明| | ------- | ------- | | --addhspcopt ??? | 診断に使用するhspcオプションを追加します。 | | --allow ??? | 診断するファイルの拡張子を追加します。 | | --background | --watch、--onelineprintオプションを有効化、始動、終了テキストを出力します。 | | --hsp3root ??? | 使用するHSP3開発環境ディレクトリを???に設定します。 | | --ignore ??? | 無視するファイルパスを追加します。 | | --ignorednoninitvar | 未初期化変数の情報を非表示にします。 | | --inserthspcopt ??? | --addhspcoptオプションのエイリアスです。 | | --iniv | --ignorednoninitvarのエイリアスです。 | | --lineprint | --onelineprintオプションのエイリアスです。 | | --nosubdir | 子ディレクトリを監視しません。 | | --onelineprint | 診断結果を一行で出力します。 | | --relativepath | ファイルパスを相対パスで出力します。 | | --querylimit ??? | 一度に処理するファイル数を???(整数)で指定します。 | | --savedb ??? | 内部データベースを???ファイル名として保存します。 | | --sethspcopt ??? | 診断に使用するhspcオプションを設定します。 | | --watch | ファイルの変更を監視します。 | ## doc ``` hspc doc ``` hsphelp.idxからキーワードを検索して、検索結果を閲覧できます。 --keywordオプションは必ず引数を一つ取ります。引数に閲覧したいキーワードを指定してください。(例:`hspc doc --keyword "mes"`) |オプション文字|説明| | ------- | ------- | | --keyword | キーワードを検索して一致したドキュメントを出力します。 | | --hsp3root ??? | 使用するHSP3開発環境ディレクトリを???に設定します。| ## help ``` hspc help ``` hspcのヘルプドキュメントを閲覧します。 `hspc help `で、コマンドの概要を閲覧できます。(例:`hspc help compile`) オプションの説明は、`hspc help compile