Command Line Interfaces

The handling of CLI arguments in Relm4 has some specifics you should be aware of.

The first one is that Relm4/GTK tries to parse the arguments again even if you parsed them yourself already. This means the program will crash with an error like Unknown option --non-gtk-arg. To fix this you can use the with_args method to provide the arguments the GTK app should parse. The easiest way is to just provide an empty Vec but this has the disadvantage that the standard GTK arguments don't work anymore.

We will now make it work in combination with the popular clap crate. To be precise we will use the derive feature which you can learn about in the clap documentation but it works with the builder pattern too of course.

To pass a Vec of GTK arguments we need to separate the arguments we want to consume ourselves from those we want to pass to GTK. In clap you can achieve this using a combination of allow_hyphen_values and trailing_var_arg.

#[derive(Parser, Debug)]
#[command(version, about, long_about = None)]
struct Args {
    /// some argument to test
    #[arg(long)]
    non_gtk_arg: bool,

    /// Unknown arguments or everything after -- gets passed through to GTK.
    #[arg(allow_hyphen_values = true, trailing_var_arg = true)]
    gtk_options: Vec<String>,
}

Now in our main function we can parse the CLI arguments using Args::parse() and pass args.gtk_options to GTK/Relm4. The first argument is (as per convention) the program invocation so we need to add that first:

    let program_invocation = std::env::args().next().unwrap();
    let mut gtk_args = vec![program_invocation];
    gtk_args.extend(args.gtk_options.clone());

    let app = RelmApp::new("relm4.test.helloworld_cli");
    app.with_args(gtk_args).run::<AppModel>(());

Result

To compile, run and pass arguments to the built binary in one command we can use cargo run -- and pass our arguments after that.

If you wonder what the -- means: This is the end of options convention: "The first -- argument that is not an option-argument should be accepted as a delimiter indicating the end of options. Any following arguments should be treated as operands, even if they begin with the '-' character."

We can now look at the result using cargo run -- --help:

Usage: cli [OPTIONS] [GTK_OPTIONS]...

Arguments:
  [GTK_OPTIONS]...  Unknown arguments or everything after -- gets passed through to GTK

Options:
      --non-gtk-arg  some argument to test
  -h, --help         Print help
  -V, --version      Print version

This is the help text provided by clap. If you want to see the GTK help text you can use cargo run -- -- --help:

Usage:
  cli [OPTION?]

Help Options:
  -h, --help                 Show help options
  --help-all                 Show all help options
  --help-gapplication        Show GApplication options

And if the GTK option is unique and not used by your program the (second) -- is not needed anymore, e.g. cargo run -- --help-all:

Usage:
  cli [OPTION?]

Help Options:
  -h, --help                 Show help options
  --help-all                 Show all help options
  --help-gapplication        Show GApplication options

GApplication Options:
  --gapplication-service     Enter GApplication service mode (use from D-Bus service files)

Of course you can replace cargo run -- by your binary name later, e.g.: your-cool-app --help-all.

The complete code

Here is a minimal working example code with some debug output:

use clap::Parser;
use gtk::prelude::GtkWindowExt;
use relm4::{gtk, ComponentParts, ComponentSender, RelmApp, SimpleComponent};

struct AppModel {}

#[relm4::component]
impl SimpleComponent for AppModel {
    type Init = ();
    type Input = ();
    type Output = ();

    view! {
        gtk::Window {
            set_title: Some("Hello world with CLI"),
            set_default_width: 300,
            set_default_height: 100,

            gtk::Label {
                set_label: "Hello world!",
            }
        }
    }

    fn init(
        _init: Self::Init,
        root: Self::Root,
        _sender: ComponentSender<Self>,
    ) -> ComponentParts<Self> {
        let model = AppModel {};
        let widgets = view_output!();

        ComponentParts { model, widgets }
    }
}

#[derive(Parser, Debug)]
#[command(version, about, long_about = None)]
struct Args {
    /// some argument to test
    #[arg(long)]
    non_gtk_arg: bool,

    /// Unknown arguments or everything after -- gets passed through to GTK.
    #[arg(allow_hyphen_values = true, trailing_var_arg = true)]
    gtk_options: Vec<String>,
}

fn main() {
    let args = Args::parse();
    dbg!(&args);

    let program_invocation = std::env::args().next().unwrap();
    let mut gtk_args = vec![program_invocation];
    gtk_args.extend(args.gtk_options.clone());

    let app = RelmApp::new("relm4.test.helloworld_cli");
    app.with_args(gtk_args).run::<AppModel>(());
}