Skip to content

installer-api.md

Latest commit

 

History

History
151 lines (113 loc) · 5.81 KB

installer-api.md

File metadata and controls

151 lines (113 loc) · 5.81 KB
Raw

Installer API

InstallRS has a component system that lets users pick which optional features to install, plus a CLI parser that handles built-in flags (--headless, --log, etc.) and any custom flags you register. This doc covers both.

Components

Register optional features with Installer::add_component:

i.add_component(id, label, description, progress_weight)

Arguments:

  • id — internal identifier (stable string, used by CLI flags and is_component_selected).
  • label — what the user sees in the wizard checkbox list.
  • description — a short blurb shown when the user hovers/selects the component.
  • progress_weight — how many step units the component contributes to the progress bar when selected. (See progress reporting.)

Components start selected by default. To make one opt-in, call set_component_selected(id, false) after registration. Chain .required() to mark a component as required (always selected, greyed-out in the wizard, always on in headless mode):

i.add_component("core", "Core files", "Always installed", 10)
    .required();
i.add_component("docs", "Documentation", "User manual and readme", 3);
i.add_component("extras", "Extra samples", "Optional example files", 1);
i.set_component_selected("extras", false);

Query selection state inside the install callback:

if i.is_component_selected("docs") {
    i.dir(source!("docs"), "docs").install()?;
}

The wizard renders a components_page(...) with one checkbox per component. Users can also drive selection from the command line via --components, --with, --without — see Built-in flags below.

Command-line parsing

Every installer must call i.process_commandline()? after registering components and custom options (before running the wizard or doing headless work). This parses argv and applies all recognized flags.

Built-in flags

  • --headless — disable the GUI; run the install callback inline.
  • --list-components — print available components and exit 0.
  • --components a,b,c — install exactly this set (required components are always included even if not listed).
  • --with a,b / --without c — delta from defaults.
  • --log <path> — tee every status / log / error message to a file (append mode). Format: [*] <status>, <log>, [ERROR] <msg>.

Unknown flags cause process_commandline() to return an error — so register every custom flag you expect users to pass before calling it.

Custom CLI options

Register your own flags via i.add_option(name, OptionKind, help), then read them after process_commandline() with a typed getter. The third argument is a one-line description retained for future autogenerated --help output (pass "" if none).

use installrs::OptionKind;

i.add_option("config", OptionKind::String, "Path to a config file");
i.add_option("port", OptionKind::Int, "Listen port");
i.add_option("verbose", OptionKind::Flag, "Enable trace output");
i.add_option("fast", OptionKind::Bool, "Skip slow validation");

i.process_commandline()?;

let config: Option<String> = i.option("config");
let port: i64 = i.option("port").unwrap_or(8080);
let verbose: bool = i.option("verbose").unwrap_or(false);

OptionKind variants:

Variant Syntax Semantics
Flag --name Boolean (true if passed, else false).
String --name value Arbitrary string.
Int --name 42 Signed integer (i64).
Bool --name true Explicit boolean

Bool options accept true/false, yes/no, on/off, 1/0 (case-insensitive).

option::<T> is generic over FromOptionValue, which is implemented for bool, String, i64, i32, u64, and u32. Mismatched types (e.g. option::<i64> on a String option) return None.

Seeding and overwriting option values

Options can be set programmatically — useful for platform-dependent defaults that the user can override via CLI flags or wizard widgets:

  • i.set_option_if_unset(name, value) — set only if no value is present. Won't clobber a CLI-provided value or one set by an earlier callback. Use this for sensible first-run defaults.
  • i.set_option(name, value) — always overwrite. Use this when user code needs to force a value regardless of what's there.
  • i.is_option_registered(name) — check whether an option was registered via i.add_option(...).

value is anything that converts to OptionValue (bool, String, &str, i64, etc.).

Integration with custom wizard pages

Custom-page widgets are automatically wired to installer options by key:

  • On page entry, widget values pre-fill from the option store.
  • On forward navigation, widget values write back to the option store.

So CLI pre-fills work for free — if you register --username via i.add_option("username", OptionKind::String, "") before process_commandline, passing --username=alice on the command line pre-fills the username text widget on the custom page.

See GUI wizard — custom pages for the widget API.

See also

  • How-to — recipes for components, options, and CLI flags.
  • GUI Wizard — the components page and custom pages that render the components and custom options registered here.
  • Embedded files, builder ops, and progress — each component declares a progress_weight; this page explains how it maps to the progress bar.
  • Internationalization — translating component labels and descriptions.