Struct Installer 

pub struct Installer {
    pub headless: bool,
    /* private fields */
}

The central context passed into your install and uninstall functions. Holds the embedded payload table, parsed CLI options, registered components, the out-dir for relative paths, the progress sink, the cancellation flag, and the optional log file.

You don’t construct this — the generated main does. User code receives &mut Installer and drives it via the methods on this type and the builder ops it returns (Installer::file, Installer::dir, Installer::uninstaller, etc.).

Fields

headless: bool

true after Installer::process_commandline sees --headless, or when the wizard’s headless runner sets it. Branch on this to skip GUI-only code paths (or to prompt for confirmation only when running attended).

Implementations

impl Installer

pub fn process_commandline(&mut self) -> Result<()>

Parse command-line arguments and apply them to the installer state.

All installers must call this. Typical placement is the first line inside the install / uninstall function, right after registering components:

pub fn install(i: &mut Installer) -> Result<()> {
    i.add_component("docs", "Documentation", "", 3);
    i.process_commandline()?;
    // ... wizard or headless install flow ...
}

Recognized flags:

• --headless — sets self.headless = true, disables GUI
• --list-components — print the component table and exit status 0
• --components a,b,c — install exactly this set (plus required)
• --with a,b — enable these in addition to defaults
• --without a,b — disable these (required cannot be disabled)
• --log <path> — tee all status / log / error messages to a file (append mode; see Installer::set_log_file)

Component-flag precedence: --components (when present) replaces the default selection entirely; otherwise --with adds to defaults and --without removes from them. --with and --without are applied on top of --components when both appear. Required components stay selected regardless.

Ordering: register every component (component) and every custom flag (option) before calling this. Unknown component ids and unregistered flags both error out.

impl Installer

pub fn total_steps(&self) -> u64

Total step weight across all currently-selected components. Every builder op (and step/begin_step) advances a cursor that runs from 0 up to this total; the progress sink receives cursor / total on each update.

pub fn reset_progress(&mut self)

Reset the step cursor to zero. Usually not needed — install_main leaves it alone and the wizard’s install page runs exactly once.

pub fn begin_step(&self, status: &str, weight: u32)

Open a weighted step without running a builder op. Use this around your own long-running work (downloads, service registration, etc.) so the progress bar advances; pair with Installer::set_step_progress for sub-step updates, then Installer::end_step to close it out.

i.begin_step("Downloading", 5);
for (done, total) in download_chunks(&url)? {
    i.set_step_progress(done as f64 / total as f64);
}
i.end_step();

pub fn set_step_progress(&self, fraction: f64)

Update progress within the currently-open step: fraction is interpreted as a position from 0.0 (step start) to 1.0 (step end). Outside an open step this is a no-op. Clamped to [0, 1].

pub fn end_step(&self)

Close the currently-open step, jumping the cursor to the end of its range. If no step is open this just snaps the cursor to the previous step_range_end.

pub fn step(&self, status: &str, weight: u32)

One-shot equivalent of begin_step + end_step for user code whose progress can’t be subdivided: advances the cursor by weight units and emits the status message.

impl Installer

pub fn set_log_file(&mut self, path: impl AsRef<Path>) -> Result<()>

Open a log file. Every subsequent status / log / error surfaced by the installer (via ProgressSink or the wizard) is also appended to this file, in the same format used by --headless stderr output ([*] <status>, <log>, [ERROR] <msg>).

The file is opened with create + append, so repeated runs build a chronological history. Call Installer::clear_log_file to stop logging. Errors only on file-open failure; subsequent write errors are silently swallowed so a broken log pipe can’t derail an install.

pub fn clear_log_file(&mut self)

Stop writing to the log file (if one was opened).

pub fn log_error(&self, err: &Error)

Record an error to the log file (no-op if no file is set). Called automatically by the wizard and headless runner on install failure.

pub fn add_option( &mut self, name: impl AsRef<str>, kind: OptionKind, help: impl AsRef<str>, ) -> &mut Self

Register a user-defined command-line option. Register all options before calling Installer::process_commandline; afterwards read values via Installer::option.

help is a one-line description retained for future autogenerated --help output. Pass "" if you don’t want one.

Option names must not collide with the built-ins (headless, list-components, components, with, without). The leading -- is implied — pass just "config" for --config.

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.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);

Ordering: call this before process_commandline. Unregistered flags cause a parse error, so every --<name> your installer accepts must be registered first.

pub fn is_option_registered(&self, name: impl AsRef<str>) -> bool

Whether an option with this name has been registered.

pub fn set_option_if_unset( &mut self, name: impl AsRef<str>, value: impl Into<OptionValue>, )

Set an option value only if it isn’t already set. Useful for seeding a sensible first-run default that CLI flags or prior wizard state can override.

pub fn set_option( &mut self, name: impl AsRef<str>, value: impl Into<OptionValue>, )

Set an option value (always overwrites). Accepts anything convertible to OptionValue.

pub fn option<T: FromOptionValue>(&self, name: &str) -> Option<T>

Typed accessor for a parsed option value.

Returns None if the option was never registered, not provided on the command line, or the stored value doesn’t convert to T.

For OptionKind::Flag, .option::<bool>(name) returns Some(false) when the flag is absent (flags are always populated).

pub fn cancellation_flag(&self) -> Arc<AtomicBool>

The shared cancellation flag. Flipping this to true causes the next file/dir/mkdir/remove op to error with “install cancelled”. The wizard’s Cancel button and the headless Ctrl+C handler both write through this.

pub fn is_cancelled(&self) -> bool

True if a cancel has been requested.

pub fn cancel(&self)

Request cancellation. Subsequent op .install() calls will return a “cancelled” error before doing any work.

pub fn check_cancelled(&self) -> Result<()>

Error out if cancellation has been requested. Called at the top of every builder op’s .install(); user code calling the op-level helpers can rely on this without any polling.

pub fn install_ctrlc_handler(&self)

Install a Ctrl+C / SIGINT handler tied to this installer’s cancellation flag. First press sets the flag (the next op errors with “cancelled”); a second press exits the process with status 130.

Called from the generated installer/uninstaller main() before install_main / uninstall_main. Idempotent: re-invocations are no-ops.

pub fn add_component( &mut self, id: impl AsRef<str>, label: impl AsRef<str>, description: impl AsRef<str>, progress_weight: u32, ) -> &mut Component

Register (or update) an optional component.

progress_weight is the number of step units the component contributes to the installer’s progress total when selected. Operations inside the component’s install code each advance the cursor by their own weight (default 1) — overshoot/undershoot happens if the actual op count diverges from progress_weight.

i.add_component("docs", "Documentation", "User-facing docs", 3);
i.add_component("core", "Core files", "Always installed", 10).required();
// Opt-in component: register, then deselect.
i.add_component("extras", "Extras", "Optional samples", 1);
i.set_component_selected("extras", false);

Components start selected. To make one opt-in, call set_component_selected with false after registration. Panics if a component with the same id is already registered.

Ordering: register every component before calling process_commandline — --components, --with, --without, and --list-components resolve against the registered set, and unknown ids error out.

pub fn is_component_selected(&self, id: &str) -> bool

Whether a component is currently selected. Unknown ids return false.

pub fn set_component_selected(&mut self, id: &str, on: bool)

Set the selected state of a component. Required components ignore attempts to deselect them. Unknown ids are silently ignored.

pub fn set_out_dir(&mut self, dir: impl AsRef<str>)

Set the base output directory for relative destination paths.

pub fn out_dir(&self) -> Option<&Path>

Get the configured output directory as a PathBuf if set.

pub fn set_status(&self, status: impl AsRef<str>)

Push a status update to the attached ProgressSink and log file. Same channel the builder ops use via .status(...).

pub fn set_progress(&self, fraction: f64)

Push a progress fraction (0.0–1.0) to the attached ProgressSink. Bypasses the step-weighted progress model — use sparingly.

pub fn log(&self, message: impl AsRef<str>)

Append a log line to the attached ProgressSink and log file.

pub fn set_progress_sink(&mut self, sink: Box<dyn ProgressSink>)

Attach a ProgressSink that receives status, progress, and log events.

pub fn has_progress_sink(&self) -> bool

True if a ProgressSink is currently attached.

pub fn clear_progress_sink(&mut self)

Remove the progress sink (if any).

pub fn file<'i>( &'i mut self, source: Source, dst: impl AsRef<str>, ) -> FileOp<'i>

Install a single embedded file. Pair with source!:

i.file(installrs::source!("app.exe"), "app.exe")
    .status("Installing app.exe")
    .install()?;

pub fn dir<'i>(&'i mut self, source: Source, dst: impl AsRef<str>) -> DirOp<'i>

Install an embedded directory tree.

pub fn uninstaller<'i>(&'i mut self, dst: impl AsRef<str>) -> UninstallerOp<'i>

Write the embedded uninstaller executable.

pub fn mkdir<'i>(&'i mut self, dst: impl AsRef<str>) -> MkdirOp<'i>

Create a directory (and its parents) on the target system.

pub fn remove<'i>(&'i mut self, path: impl AsRef<str>) -> RemoveOp<'i>

Remove a file or directory from the target system.

pub fn exists(&self, path: &str) -> Result<bool>

Check whether a path exists on the target system.