はじめに

Tauri は GUI アプリを作成するというイメージは当たり前にあるが、実は CLI 機能の実装も可能で、その機能を clap クレートを通して有している。

この機能の利用用途としては、例えばダークテーマモードで起動したり、デバッグモードで起動したりといった事が考えられる。

myapp.exe --debug --theme dark

また、CLI コマンドモードとしての利用も考えられるだろう。

myapp.exe run dev --verbose trace

これを実際にどう実装していけばいいかを試したので、それのメモを残す。

環境

Windows 11 Pro 23H2
Tauri 1.5.3

実装サンプル

Tauri の CLI 機能実装

CLI 機能として実装する場合、Tauri Config での実装方法が案内されている。

Tauri Config で定義するメリットとしては、後続のアプリ開発参入者が CLI 機能実装の状態を把握しやすいのと、プログラム側を複雑化させずに済むこと。

定義方法

Tarui Config での定義は以下のフォーマットで行う。
この args リストに実際の引数を定義し、 subcommands でサブコマンドを定義する。

tauri.config.json

{
  "tauri": {
    "cli": {
      "description": "",
      "longDescription": "",
      "beforeHelp": "",
      "afterHelp": "",
      "args": [],
      "subcommands": {
        "subcommand-name": {
        }
      }
    }
  }
}

args

{
  "args": [
    {
      "name": "source",
      "index": 1,
      "takesValue": true
    },
    {
      "name": "destination",
      "index": 2,
      "takesValue": true
    }
  ]
}

主な args アトリビュート

アトリビュート名	説明
name	引数名。 `--[name]` として使用される。 Ex: `--debug`
short	引数のショート名 `-[short_name]` として使用される。 Ex: `-d`
index	引数のインデックス。ヘルプ時の表示順等に影響を及ぼす。
takesValue	値を取るかどうかの設定。`--[option] [value]` として引数が値を取るかどうかを設定する。これを設定しない場合は `bool` タイプのフラッグとして扱われる。
description	引数の説明
longDescription	引数の長い説明
multiple	複数の値の受け取り方に対応。 `takesValue` の設定は必須。 Ex: `--add 4 10`, `-a 4 -a 10`, `--add=4,10`
possibleValues	受け取る値の定義を行う。定義から外れた値を受け取るとエラーを返す。 Ex: `["JPY", "USD", "EUR"]`

値の受け取り

引数の値の受け取りは、バックエンドとフロントエンドの両方で提供されている。

バックエンド

渡された引数が定義にマッチしているかは tauri::App の get_cli_matches() で取得する。

main.rs

fn main() {
    let app_state = config::AppState::new();

    tauri::Builder::default()
        .setup(|app: &mut tauri::App| {
+            debug!("{:?}", app.get_cli_matches());
            Ok(())
        })
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

この get_cli_matches() は、Result< Matches { args: HashMap<String, ArgData>, subcommand: Option<Box<SubcommandMatches>> } > を返すようになっている。また、この Matches は Serialize も設定されているので次のような取得も可能。

fn main() {
    let app_state = config::AppState::new();

    tauri::Builder::default()
        .setup(|app: &mut tauri::App| {
            debug!("{:?}", app.get_cli_matches());
+           match app.get_cli_matches() {
+               Ok(matches) => {
+                   debug!("{:?}", matches);
+                   // ここからマッチした値を取得してきて処理を行う。
+                   // 例えば以下のように引数 debug を取得している。
+                   // 帰ってくる値は Option<&ArgData> で渡される。
+                   if let Some(is_debug_mode) = matches.args.get("debug").clone() {
+                       debug!("{:?}", is_debug_mode);
+                   }
+               }
+               Err(e) => error!("{:?}", e),
+           }
            Ok(())
        })
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

更に、実際に値を取り出す場合は serde の機能に則って以下の様に正しい型で取得する。
.expect(msg) しているのは as_[T]() で帰ってくるのが Option<T> 型であるため。

if let Some(x) = matches.args.get("key").clone() {
    // Value::Bool の場合
    x.value.args.as_bool().expect("The value is not bool type.")
    
    // Value::Array の場合
    x.value.args.as_array().expect("The value is not array type.")
    
    // Value::String
    x.value.args.as_str().expect("The value is not str type.")
    
    // Value::Null
    x.value.args.as_str().expect("The value is not null type.")
}

フロントエンド

依存モジュールのインストール

npm i -D @tauri-apps/api/cli

使い方

+layout.svelte

<script lang="ts">
    import { getMatches } from '@tauri-apps/api/cli'
    
    $: getMatches().then((matches) => {
      //  { args, subcommand } としてわたってくるので、これに対して処理を行う。
    })
<script>

サブコマンドの実装

サブコマンドは "subcommands": {} として定義できる。
この subcommands の中身は cli 部分を継承している。なので、複数階層を持たせることも可能。

{
  "tauri": {
    "cli": {
      "subcommands": {
        "run": {
          "args": [
            {"name": "start", "takesValue": false},
            {"name": "dev", "takesValue": false}
          ]
        },
        "search": {
          "subcommands": {
            "google": {"args": [{"name": "word", "short": "w"}]},
            "bing": {"args": [{"name": "word", "short": "w"}]},
            "yahoo": {"args": [{"name": "word", "short": "w"}]}
          }
        }
      }
    }
  }
}

以下の様な呼び出しが出来たりする。

myapp.exe run dev
myapp.exe run start

myapp.exe search google --word orange
myapp.exe search yahoo -w apple

Windows での stdout へのパイプ

Windows 環境では、コンソール上で exe を実行しても即座に別プロセスでアプリが立ち上がるようになる。
そうすると困るのが、コンソール上に結果の出力をしてくれなくなるので CLI ツールとしての機能を持たせる目的が果たせないこと。

これを解決するには少しトリッキーなことをする必要がある。
それは、Tauri アプリを作成した際に生成される次の一文を削除すること。
コメントには「削除するな！」と書いてあるが、実際にこれが機能することによって起動時に別コンソールを立ち上げて、メインで利用しているところからはすぐに切り離すような挙動をふるまっている。

main.rs

// Prevents additional console window on Windows in release, DO NOT REMOVE!!
- #![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
+

引数があるかないかによって挙動を切り替える

GUI と CLI モードを両方持たせたい場合、この挙動を切り替えたい場合もある。
なので、「引数を持たせたとき」のみ CLI としてコンソールにパイプするという挙動に切り替えるアイデアを用いる。

これを達成するには、 windows_sys::Win32::System::Console::AllocConsole を用いる。
これは、 Win32_System_Console feature として提供されているので、次のように追加する。

cargo add windows-sys --features Win32_System_Console

Cargo.toml

[dependencies]
windows-sys = { version = "0.52.0", features = ["Win32_System_Console"] }

use windows_sys::Win32::System::Console::AllocConsole;

fn main() {
    unsafe {
        AllocConsole();
    }
}

ヘルプとバージョンの表示

デフォルトで --help と --version が引数として持つようになっている。
なので、CLI の設定を行っている時点で次の実装でヘルプ表示を行えるようになる。

tauri.config.json

{
  "tauri": {
    "cli": {
      "description": "Examples for cli implimentation in Tauri",
      "beforeHelp": "Help doc for myapp!!",
      "afterHelp": "Takanori Kishikawa, All rights reserved."
    }
  }
}

ヘルプ情報は Cargo.toml の authors=[] の値も使用されるので、適宜編集しておく。

Cargo.toml

[package]
name = "app"
version = "0.1.0" # ここのバージョンは無視してよい
description = "A Tauri App"
authors = ["Takanori Kishikawa"] # ここの情報は CLI の help 情報に表示されるので注意
license = ""
repository = ""
default-run = "app"
edition = "2021"
rust-version = "1.60"

こちらが実行部分の実装。

main.rs

fn main() {
    let app_state = config::AppState::new();

    tauri::Builder::default()
        .setup(|app| {
            debug!("{:?}", app.get_cli_matches());
            match app.get_cli_matches() {
                Ok(matches) => 
                
+                   // --help の表示
+                   if let Some(x) = matches.args.get("help").clone() {
+                       println!("{}", x.value.as_str().unwrap());
+                   }
                   
+                   // --version の表示
+                   if let Some(_) = matches.args.get("version").clone() {
+                       println!(
+                           "{}, Version: {}",
+                           app.config()
+                               .as_ref()
+                               .package
+                               .product_name
+                               .clone()
+                               .expect("To get product name is failed."),
+                           app.config()
+                               .as_ref()
+                               .package
+                               .version
+                               .clone()
+                               .expect("To get version is failed.")
+                       );
+                   }
                }
                Err(e) => println!("{}", e.to_string()),
            }
            Ok(())
        })
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

実行すると次の様に結果が得られる。

myapp.exe --help

myapp.exe --version

--version 引数について
特に何かを指定していなくても --version は引数として登録されている。
しかしながら、実際に使用してみると ArgData は次のように Null の情報のみが返ってくる状態になっている。

Matches { args: {"version": ArgData { value: Null, occurrences: 0 }}, subcommand: None }

恐らく Tauri の内部の書き込みが Clap を特殊ラップしているからだとは思うが、そのままだと思った挙動にならない。
なので、現状は上記の様に自分で --version について独自実装する必要がある様子。

実装サンプル

`--dark` でテーマを切り替える

以下の様に --dark を引数に持たせ、どちらかで切り替えるという事を考えてみる。
デフォルト値は light とする。

コマンド

myapp.exe --dark

コンフィグ

tauri.config.json

{
  "tauri": {
    "cli": {
      "description": "This is MyApp CLI functions",
      "args": [
        {
            "name": "dark",
            "takesValue": false,
            "multiple": false,
            "description": "Set theme to dark mode as launched."
        }
      ]
    }
  }
}

バックエンド

main.rs

mod config;

// 省略

fn main() {
    let app_state = config::AppState::new();

    tauri::Builder::default()
        // 省略
        .manage(app_state)
        .setup(|app| {
            match app.get_cli_matches() {
                Ok(matches) => {
                    debug!("{:?}", matches);

                    // 省略

                    // --dark 時の処理
                    if let Some(x) = matches.args.get("dark").clone() {
                        let app_state: State<'_, AppState> = app.state();
                        debug!("{:?}", app_state.settings.lock().unwrap());
                        let mut settings = app_state.settings.lock().unwrap();
                        settings.set_dark_mode(x.value.as_bool().unwrap());
                        debug!("{:?}", settings);
                    }
                }
                Err(e) => println!("{}", e.to_string()),
            }
            Ok(())
        })
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

フロントエンド

+page.svelte

<script lang="ts">
	import { Moon, Sun } from 'lucide-svelte';
	import { invoke } from '@tauri-apps/api';

	type Settings = {
		dark_mode: boolean;
	};

	let darkMode = false;
	$: invoke('get_settings').then((res) => {
		let settings = res as Settings;
		darkMode = settings.dark_mode;
		switchDarkMode(darkMode);
	});

	async function switchDarkMode(isDarkMode: boolean) {
		await invoke('set_dark_mode', { switch: isDarkMode });

		isDarkMode
			? document.documentElement.classList.add('dark')
			: document.documentElement.classList.remove('dark');
	}

	function toggleDarkMode() {
		darkMode = !darkMode;
		switchDarkMode(darkMode);
	}
</script>

<div class="h-screen bg-zinc-100 p-3 dark:bg-zinc-900">
	<div class="rounded-lg bg-white px-6 py-8 shadow-xl ring-1 ring-slate-900/5 dark:bg-slate-800">
		<div>
			<button on:click={toggleDarkMode}>
				<span
					class="inline-flex items-center justify-center rounded-md bg-indigo-500 p-2 text-white shadow-lg"
				>
					{#if darkMode}
						<Moon />
					{:else}
						<Sun />
					{/if}
				</span>
			</button>
		</div>
		<h3 class="mt-5 text-base font-medium tracking-tight text-slate-900 dark:text-white">
			Writes Upside-Down
		</h3>
		<p class="mt-2 text-sm text-slate-500 dark:text-slate-400">
			The Zero Gravity Pen can be used to write in any orientation, including upside-down. It even
			works in outer space.
		</p>
	</div>
</div>

結果

--dark 引数を付けることでダークモードに切り替えた状態での起動を出来ることが分かる。

ここで不正な引数を渡すと次の様にエラーを起こす。

myapp.log

[2024-03-22][07:20:15][DEBUG][app] Err(FailedToExecuteApi(ParseCliArguments("error: \"da\" isn't a valid value for '--theme <theme>...'\n\t[possible values: light, dark]\n\n\tDid you mean \"dark\"?\n\nFor more information try --help\n")))

これを取り出して String 化することで次の様なエラーメッセージをコンソールに出力することが出来る。

Err(e) => println!("{}", e.to_string())

failed to execute API: failed to parse CLI arguments: error: Found argument '--dar' which wasn't expected, or isn't valid in this context

       Did you mean '--dark'?

       If you tried to supply `--dar` as a value rather than a flag, use `-- --dar`

USAGE:
   myapp.exe --dark

For more information try --help

ここら辺のエラーメッセージの優秀さは Clap を使用しているが故の能力。
最小限の実装でこの読みやすさはありがたい。

アプリの状態管理はバックエンドで中央集権管理する
ダークモードの場合などは実際のところフロントエンド側で引数を受け取るだけでも完結できる。しかしながら、GUI アプリにおける状態管理は非常に複雑化しやすい性質を持っているため、アプリの状態管理としてはアプリ用のステートを用いて管理する。そうすることで、状態管理やそれを設定ファイルとして書き出す際など、アトリビュートの増大や利用目的のスケーリングに対応し易くなる。

まとめ

コンフィグの設定から、少々書くだけでも他のライブラリ群と同じように引数を用いた実装が出来ることが分かった。

しかしながら、Clap を使用しているというドキュメントの書き込みがあるものの、結構情報が足りてないようにも思えっる Tauri の機能部分の一つだと思う。

ただ、実際に実装していく上では結構重宝する機能だとは思うのでできればもう少し深堀しておきたい。

また機能見つけたら追記予定～～ (｀･ω･´)ゞ

Tauri アプリの CLI 機能実装

はじめに

環境

実装サンプル

Tauri の CLI 機能実装

定義方法

args

主な args アトリビュート

値の受け取り

バックエンド

フロントエンド

依存モジュールのインストール

使い方

サブコマンドの実装

Windows での stdout へのパイプ

引数があるかないかによって挙動を切り替える

ヘルプとバージョンの表示

実装サンプル

--dark でテーマを切り替える

コマンド

コンフィグ

バックエンド

フロントエンド

結果

まとめ

`--dark` でテーマを切り替える