Struct Installer 

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

Fields

headless: bool

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.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 new( entries: &'static [EmbeddedEntry], uninstaller_data: &'static [u8], uninstaller_compression: &'static str, ) -> Self

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 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::get_option or Installer::option_value.

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.option("config", OptionKind::String, "Path to a config file");
i.option("port", OptionKind::Int, "Listen port");
i.option("verbose", OptionKind::Flag, "Enable trace output");
i.process_commandline()?;
let config: Option<String> = i.get_option("config");
let port: i64 = i.get_option("port").unwrap_or(8080);
let verbose: bool = i.get_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_default( &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). Same as set_option_value but accepts anything convertible to OptionValue.

pub fn get_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, .get_option::<bool>(name) returns Some(false) when the flag is absent (flags are always populated).

pub fn option_value(&self, name: &str) -> Option<&OptionValue>

Raw parsed value for an option, or None if not set.

pub fn set_option_value(&mut self, name: &str, value: OptionValue)

Store (or overwrite) a parsed option value directly. The wizard calls this when a custom-page widget commits its current value on forward navigation. User code can call it too, e.g. to seed a value from a config file before the wizard opens.

pub fn option_values_snapshot(&self) -> HashMap<String, OptionValue>

Clone of the full parsed-options map. Used by the wizard to pre-fill custom-page widgets from already-set option values (whether from the CLI or a previous wizard run).

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 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.component("docs", "Documentation", "User-facing docs", 3);
i.component("extras", "Extras", "Optional samples", 1).default_off();
i.component("core", "Core files", "Always installed", 10).required();

Components start selected (default = true); call .default_off() on ones the user has to opt into. Later calls with the same id update the existing component in place.

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 components(&self) -> &[Component]

All registered components, in registration order.

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.

pub fn install_main( &mut self, install_fn: impl Fn(&mut Installer) -> Result<()>, )

Entry point for installer binaries. Call this from main().

The user’s install_fn is expected to call Installer::process_commandline itself (typically right after registering components).

pub fn uninstall_main( &mut self, uninstall_fn: impl Fn(&mut Installer) -> Result<()>, )

Entry point for uninstaller binaries. Call this from main().