nagi.tomlでアプリの設定をまとめる

nagi.tomlは入口ファイル、Rust依存、手書きLowをまとめる設定です。CLI・VS Code・JetBrainsプラグインで使えます。

最小のプロジェクト

新しいフォルダーに、次の2ファイルを置きます。

my-app/
  nagi.toml
  main.nagi

nagi.toml：

entry = "main.nagi"

main.nagi（完全なコード）：

def main():
    print("Hello, Nagi project!")

my-appで実行します。nagicにPATHを通していない場合は、ビルド済みコンパイラの絶対パスを使ってください。

nagic check
nagic run

checkは型検査、runはビルドして実行します。lowerとbuildも同じ設定を使います。ソースの指定を省くと、現在のフォルダーから親へさかのぼり、最も近いnagi.tomlを選びます。my-app/srcなどの子フォルダーからも使えます。

別の場所から選ぶ場合：

nagic run --project my-app
nagic check --project my-app/nagi.toml

実行したアプリの作業フォルダーはnagi.tomlのある場所です。たとえば相対パスdata.sqliteはそこに作られ、呼び出したターミナルの場所によって変わりません。exeを直接実行するときは、そのプロセスの作業フォルダーが使われます。

Rustと手書きLowを追加する

entry = "src/main.nagi"
native = ["native/math.low"]

[rust]
file = "native/bridge.rs"

[rust.dependencies]
serde_json = "1.0"

ファイルの相対パスはすべてnagi.toml基準です。entry以外は省略できます。存在しない設定名、型の違い、空のパス、依存の重複はエラーになります。従来のversion文字列はそのまま使えます。Rustの型や実装との一致はbuildまたはrunで検査します。

ローカルcrateとfeatureを指定する

依存ごとにtableも使えます。次はローカルRustライブラリのサンプルの設定です。

entry = "library-pricing.nagi"

[rust]
file = "native.rs"

[rust.dependencies]
pricing = { version = "0.1", path = "engine", package = "nagi-pricing-engine", features = ["volume-discount"], default-features = false }

versionかpathの少なくとも一方が必要です。git・registry・workspace・target別依存・dev/build依存・optionalは未対応です。

pathは生成先やターミナルの場所にかかわらず、設定ファイル基準です。check・lower・symbolsはCargoを呼ばず、依存を取得せず、依存crateの存在確認も行いません。Rust crateをまだ用意していなくてもNagi側を検査できます。実際のpath、crateのAPI、依存解決はbuild/runでCargoが検査します。

Cargoは同じpackageへの依存経路でfeatureを統合します。default-features = falseを指定しても、別の経路が求める既定featureまで無効にはなりません。

再ビルドでは生成先の既存Cargo.lockを保持します。lockは解決したversionを記録しますが、ローカルcrateのソースは固定しません。固定した解決でビルドする場合は、サンプルのディレクトリでcargo build --release --locked --manifest-path build/library-pricing/Cargo.tomlを使えます。nagic build --lockedは未対応です。

動く例は Rust連携サンプルです。リポジトリのルートから：

.\target\release\nagic.exe run --project test-nagi-code/rust-bridge

CRC32、JSON整形、asyncのRust関数を呼びます。タスク管理サイトも入口を設定済みです。

コマンド引数との優先順位

nagic run main.nagiのようにソースだけを明示した場合は、従来どおりそのファイルを単独で処理します。近くにnagi.tomlがあっても自動では読みません。

--rust-depで同名のtableを置換すると、元のpath・package・features・default-featuresは残りません。CLIではversion文字列だけを指定できます。

引数内の相対パスはターミナルの作業フォルダー基準です。SOURCE・--project・--rust・--out・同名の--rust-depの重複はエラーです。--projectと--no-projectは同時に使えません。

プロジェクトの生成Low・Rust・Cargo.tomlはbuild/<入口のファイル名>/に出力します。ビルド用のキャッシュはbuild/native-target/です。実際の実行ファイルはbuild／runが標準エラーへ出すnative:行で確認できます。

Nagi 0.1.11への導入対象では、生成先の.nagi/内にbuild世代ごとの実行ファイルを保存します。同じ入口ソースと生成先ならアプリIDは変わりませんが、再ビルド後の実行ファイルのパスは変わります。起動中の旧実行ファイルを上書き・削除・停止する処理はありません。ビルドが失敗した場合は、新しい実行ファイルを起動せず、前回の成功を示すmetadataを残します。

公開版nagic 0.1.11の通常のCLI build/runは成功世代を自動削除せず、保持上限もありません。これはbuild/native-target/やNAGI_NATIVE_TARGET_DIRのCargo共有cacheとは別です。通常のCLI用generation cleanup commandはありません。JetBrains 0.1.3未リリース候補では、plugin管理runだけがcompiler 0.2.0へNAGI_RUN_RETENTION=latestを渡す保持modeを検証中です。公開compiler 0.1.11はこのmodeを実装していません。compiler 0.1.12の一時候補は中止され、この機能はJetBrains 0.1.3とcompiler 0.2.0で検証中です。

候補modeでもnative run成功が記録されたlatest、実行中・現在の入力が必要とするgeneration、失敗後のlast-good generationは保護します。compile成功だけではruntime成功とみなさず、latestにrun成功記録がなければ旧成功世代を回収しません。成功した通常buildを含む各generationの入力snapshotも調べるため、別appやnon-latest runが参照するgenerationを保護します。外部hardlink inputのfile identityがrun leaseと一致するときも、そのleaseとgenerationを保持します。依存元を回収した後に参照先がもう一度のsuccessful sweepまで残ることがあり、総generation数や容量の厳密な上限はありません。managed generationの入力metadataが不明な場合も安全側に保持します。unknown file、link/reparse point、failed staging、共有Cargo target cacheは削除しません。generation treeの外に置くrecovery journalを後続のplugin管理runで検査し、unknownまたはoversized journal recordは保持したまま正常なrecordの回収を続けます。CLIで容量を整理する場合も、実行中のgenerationやlatestが参照するgenerationを手動で削除しないでください。候補の回収modeはまだ検証中です。

同じ生成先への書込みはOSのlockで順番に行います。競合時はwaiting for output lock:を表示し、生成・Cargo・成功時の更新が終わるまで待ちます。アプリを実行している間はlockを保持しません。check・lower・cost reportの書込みも同じlockを使います。エディターの非書込みcheckには不要です。

明示したRustのpath依存も、そのcrateのある世代を保護します。別の出力先から入力として使った世代は、通常CLIの成果物と同様に保持し、自動回収しません。実行用の記録にhardlinkが残る場合も保持します。任意のRust includeやbuild scriptの依存をNagiがすべて発見する保証はありません。

NAGI_NATIVE_TARGET_DIRを指定すると、依存ライブラリのビルドを複数のアプリで共有できます。既定キャッシュでも別のアプリを識別します。0.1.10では環境変数を指定した場合だけ識別していたため、その経路を揃える変更です。実行ファイルをcacheやCargoのpackage名から探していたスクリプトは、native:行のパスを使ってください。識別子と内部パスはcompiler版をまたいで固定された名前ではありません。配布用の名前はコピー時に指定できます。

通常の生成Low・Rust・Cargo.tomlは調査や直接Cargoを実行するための出力です。ビルド失敗時にも更新されることがあり、成功世代の記録とは別です。Rustのpath依存や手書きRustの同時編集を固定する機能ではありません。

VS Codeで使う

Nagi拡張の0.1.1以降では、開いている.nagi / .lowから親へ最も近いnagi.tomlを探します。補助ファイルを開いた状態でも、型検査・Low変換・ビルド・実行はentryから行います。import先のエラーは元のファイルに表示します。

ファイルを開いた時と保存時に自動検査します。保存済みソースの未保存の変更はメモリ上で読みます。nagi.tomlが未保存の間は検査を待ち、保存後に開いているNagiファイルを再検査します。手動の型検査は保存せず、lower・build・runは編集中ファイルを保存してから処理します。入口からimportされていないファイルは、そのプロジェクトの検査対象に入りません。

コンパイラの場所だけはVS Codeのnagi.compilerPathかPATHで指定します。従来のnagi.rustFile・nagi.rustDependencies・nagi.nativeFilesもコマンド引数として使え、上の優先順位に従います。nagi.rustDependenciesの値はversion文字列だけです。依存tableはnagi.tomlに書きます。アプリごとの設定にはnagi.tomlを使うと、VS Codeとターミナルで同じ条件を再現できます。

拡張0.1.5以降と最新版のnagicでは、F12でプロジェクト内の関数・class・import先・ローカル変数の定義へ移動できます。引数・for・caseの名前も対象です。入口から読み込まれるHigh・Lowを扱い、開いているソースの未保存の変更もメモリ上で読みます。構文やimportを読めない場合は、保存済みの古い位置へ移動しません。新規ファイルとnagi.tomlの変更は保存してから使います。

宣言やローカル変数の型のホバー、関数・class・型とフィールドの補完、引数ヒントも使えます。これらは一度保存したファイルの未保存の編集も読みます。import先や手書きLowの未保存の内容も対象です。書きかけで解析できない場合は「保存済み」と示して宣言の候補を出し、ローカル型とフィールド候補は出しません。操作例と拡張の設定を参照してください。

IDE向けのsymbols

IDE向けのnagic symbols --project my-appは、読み込んだソースの関数・class・ローカル変数の参照位置と定義先をJSONで標準出力へ返します。ビルドや生成ファイルの書き込みは行いません。構文・importが読み込めれば、型エラーがあっても定義位置を取得できます。

JSONには関数の引数・戻り値・async、classのフィールドも含みます。型検査で確認できた変数の型はlocals、式の型・範囲・その型のフィールドはexpressionsに入ります。位置は元ファイルの1始まりの行・UTF-16列です。確定しない型は出力しません。これは編集補助の情報で、checkの成功を示すものではありません。

symbols --editor-inputでは標準入力の{"files":[{"file":"main.nagi","text":"..."}]}で既存のNagi/Lowファイルの編集中の内容を指定できます。相対パスはターミナルの作業フォルダー基準です。ディスクへ書き込まずに読み込み時のソースを置き換えます。このオプションはsymbolsとcheckで使えます。設定ファイルは保存済みのものを使います。check --editor-inputは生成ファイルを書き込みません。