Skip to content

プロジェクトCLI（onion new/build/run/test/clean）

onion コマンドは、設定より規約（convention over configuration）に基づく 軽量なプロジェクトワークフローも備えています。これはスクリプトランナーや REPLと共存します。new・build・run・test・clean は、それが 最初の引数と完全に一致する場合にのみ予約語として扱われるため、既存の onion [オプション] file.on [引数...] や onion repl の挙動はそのまま変わりません。

クイックスタート

onion new hello
cd hello
onion run
onion test

onion new hello は次の構成を作成します。

hello/
├── onion.toml
├── src/
│   └── main.on
└── tests/
    └── main_test.on

生成物は hello/target/ 以下に置かれ、onion clean で削除できます。 Gitリポジトリの初期化は行われず、既存のパスを上書きすることもありません。

生成されるマニフェスト:

[package]
name = "hello"
version = "0.1.0"

生成されるプログラム:

def main(): void {
  println("Hello, hello!")
}

生成されるテスト:

Assert::equals(4, 2 + 2)

コマンド

onion new <name>
onion build [--verbose]
onion run [--verbose] [-- <引数...>]
onion test [--verbose]
onion clean

build・run・test・clean はカレントディレクトリから開始して onion.toml が見つかるまで親方向に探索するため、src/ や tests/ など プロジェクト配下のネストしたディレクトリからでも実行できます。 プロジェクトルートに戻る必要はありません。

終了コードはすべてのプロジェクトコマンドで共通です。

  • 0 — コマンドが正常に完了した。
  • 1 — プロジェクト・マニフェスト・ビルド・テスト・実行時のいずれかの失敗。
  • 2 — コマンドライン引数の指定が不正。

マニフェスト

マニフェストが受け付けるのは [package] テーブル1つのみで、必須の 文字列キーは name（[A-Za-z][A-Za-z0-9_-]* に一致すること）と version（有効な SemVer 2.0 の バージョン）の2つだけです。未知のキー・未知のテーブル・重複キー・ 不正なTOML・無効な名前やバージョンはすべてエラーとなり、TOMLパーサーが 位置情報を提供できる場合は行・列も報告されます。依存関係の宣言、 ソースルートやエントリーポイントの上書き、コンパイラフラグ、スクリプトは 一切受け付けません。

ソースレイアウト

プロダクションソースは src/ 以下のすべての .on ファイル、テストは tests/ 以下のすべての _test.on ファイルです。どちらも再帰的に探索され、 プロジェクト相対パスでソートされ、シンボリックリンクはたどりません。 プロダクションソースが空の場合はビルドエラーになりますが、tests/ が 存在しない・空の場合はテスト0件の成功として扱われます。

ビルドキャッシュ

build は一度だけコンパイルし、結果を target/ 以下にキャッシュします。 コンパイラのバージョン・Javaのバージョン・マニフェストの正確なバイト列・ すべてのソースパスとその内容から計算したSHA-256フィンガープリントが 一致する限り、2回目以降の build（および run・test が最初に行う ビルド）はそのキャッシュを再利用します。

$ onion build
Built hello (1 classes)
$ onion build
Built hello (cached)

ソースの追加・削除・リネーム・内容の変更はいずれもキャッシュを無効化し、 フルリビルドを引き起こします。リビルドに失敗しても、直前の成功した target/classes やビルド状態ファイルが壊れることはありません — 新しい出力は一時領域にステージングされ、すべての成果物が正しく 書き込まれた後にのみ昇格されます。

エントリーポイントの規約

コンパイラはすべてのトップレベルソースに対してJVMの main を生成する ため、クラスファイルだけでは本物のエントリーポイントとヘルパー用の ソースを区別できません。そこでプロジェクトのビルドは、構文解析結果を 直接見て次のように判定します。

  1. src/main.on は、トップレベルの文（裸の式や変数宣言を含む）を 1つ以上持つ場合に候補となります。
  2. トップレベルに main という名前の関数を宣言しているプロダクション ソースは、それだけで候補となります。
  3. それ以外のコンパイラ生成の main はすべて無視されます。

run は候補がちょうど1つであることを要求します。候補が0件の場合は src/main.on に実行可能なコードを追加するか、トップレベルの main を 定義するようヒントとともに失敗し、候補が2件以上の場合はすべての候補の ソースと位置を列挙して失敗するため、あいまいさを解消できます。

テスト

test はまずプロダクションソースを一度だけビルドし、その後、発見した 各テストファイルをソート順に1つずつ、順番にコンパイル・実行します。

$ onion test
test tests/main_test.on ... ok

1 tests, 1 passed, 0 failed

各テストの stdout/stderr は、--verbose を指定しない限り失敗した 場合にのみ表示されます。あるテストのコンパイル失敗・アサーション失敗・ 実行時例外・0以外の数値結果は、そのテスト単体の失敗として報告され、 残りのテストはすべて実行され続けます。テストが1つも無いプロジェクトは 0 tests, 0 passed, 0 failed というサマリーとともに成功します。

クリーン

clean はプロジェクトの正規の target/ ディレクトリだけを削除します。

$ onion clean
Cleaned target

実行には有効な、発見済みのプロジェクトであることが前提となり、 target/ が存在するかどうかにかかわらず同じメッセージで成功します。 また target 自体がシンボリックリンクである場合は、それをたどって 削除するのではなく拒否します。

スクリプト・REPLとの互換性

new・build・run・test・clean は、最初の引数と完全に一致する 場合にのみ予約されます。それ以外——たとえば build.on という名前の ファイルや -- から始まるオプションなど——は既存のスクリプトランナーに そのまま渡され、onion repl [オプション...] も従来どおり対話シェルを 起動します。

対象外の機能

このバージョンでは、実際の利用実績に基づく判断より先に onion.toml が 巨大なビルド言語になってしまうのを避けるため、次の機能を意図的に 対象外としています: 依存関係の解決・公開、複数モジュール・ ワークスペース、ソース・テスト・出力・エントリーポイントの パス変更、ファイル単位の差分コンパイルや並列コンパイル、 プロジェクトのウォッチモード、テスト用アノテーションや新しい テストフレームワーク、パッケージ／アーカイブコマンド、フォーマッター・ リンター連携、ライフサイクルフックやマニフェストスクリプト、 ターミナルの色付け、既存ディレクトリを取り込むための onion init。

次のステップ