Axoupdater

https://docs.rs/axoupdater/latest/
Admin
Axoupdater is a Rust crate providing a robust and flexible library for managing software updates and...
Tokens:142,211
Snippets:1,382
Trust Score:9.1
Update:3 months ago
Show doc for...
Tokens:
Raw
### Execute Installer Command

Source: https://docs.rs/axoupdater/latest/src/axoupdater/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Configures and executes an installer command, handling platform-specific arguments and environment variables. It captures the output and status of the installation process.

```rust
        let path = if cfg!(windows) {
            "powershell"
        } else {
            installer_path.as_str()
        };
        let mut command = Cmd::new(path, "execute installer");
        if cfg!(windows) {
            // don't fall over on default security-policy windows machines
            // which require opt-in to execing powershell scripts.
            // This doesn't bypass proper organization-set policies.
            command.arg("-ExecutionPolicy").arg("ByPass");
            command.arg(&installer_path);
        }
        if self.print_installer_stdout {
            command.stdout(Stdio::inherit());
        }
        if self.print_installer_stderr {
            command.stderr(Stdio::inherit());
        }
        command.check(false);
        // On Windows, fixes a bug that occurs if the parent process is
        // PowerShell Core.
        // https://github.com/PowerShell/PowerShell/issues/18530
        command.env_remove("PSModulePath");
        let install_prefix = self.install_prefix_root()?;
        // Forces the generated installer to install to exactly this path,
        // regardless of how it's configured to install.
        command.env("CARGO_DIST_FORCE_INSTALL_DIR", &install_prefix);

        // Also set the app-specific name for this; in the future, the
        // CARGO_DIST_ version may be removed.
        let app_name = self.name.clone().unwrap_or_default();
        let app_name_env_var = app_name_to_env_var(&app_name);
        let app_specific_env_var = format!("{app_name_env_var}_INSTALL_DIR");
        command.env(app_specific_env_var, &install_prefix);

        // If the previous installation didn't modify the path, we shouldn't either
        if !self.modify_path {
            let app_specific_modify_path = format!("{app_name_env_var}_NO_MODIFY_PATH");
            command.env(app_specific_modify_path, "1");
        }

        let result = command.output();
```

--------------------------------

### Configure Installer Path (String)

Source: https://docs.rs/axoupdater/latest/src/axoupdater/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Tests the configuration of the installer path using a String.

```rust
let mut updater = AxoUpdater::new();
updater.configure_installer_path("/tmp".to_string());
```

--------------------------------

### Set Install Directory (String)

Source: https://docs.rs/axoupdater/latest/src/axoupdater/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Tests setting the installation directory using a String.

```rust
let mut updater = AxoUpdater::new();
updater.set_install_dir("/tmp".to_string());
```

--------------------------------

### Use Release Installer

Source: https://docs.rs/axoupdater/latest/src/axoupdater/lib.rs.html?search=u32+-%3E+bool

Revert to using the default behavior of downloading the installer from the release source. This is the default setting.

```rust
pub fn use_release_installer(&mut self) -> &mut AxoUpdater {
    self.installer_path = None;

    self
}
```

--------------------------------

### Enable Installer Stdout Output

Source: https://docs.rs/axoupdater/latest/src/axoupdater/lib.rs.html?search=std%3A%3Avec

Enables printing the standard output of the underlying installer process. Use this to capture or view the installer's output during an update.

```rust
pub fn enable_installer_stdout(&mut self) -> &mut AxoUpdater {
    self.print_installer_stdout = true;

    self
}
```

--------------------------------

### Get Receipt Path for Application

Source: https://docs.rs/axoupdater/latest/src/axoupdater/receipt.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Searches through the possible configuration paths obtained from `get_config_paths` and returns the path to the first existing installation receipt file for the given application name. Returns `None` if no receipt is found.

```rust
/// Iterates through the list of possible receipt locations from
/// `get_config_paths` and returns the first that contains a valid receipt.
pub(crate) fn get_receipt_path(app_name: &str) -> AxoupdateResult<Option<Utf8PathBuf>> {
    for receipt_prefix in get_config_paths(app_name)? {
        let install_receipt_path = receipt_prefix.join(format!("{app_name}-receipt.json"));
        if install_receipt_path.exists() {
            return Ok(Some(install_receipt_path));
        }
    }

    Ok(None)
}
```

--------------------------------

### Configure Installer Path (String Slice)

Source: https://docs.rs/axoupdater/latest/src/axoupdater/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Tests the configuration of the installer path using a string slice.

```rust
let mut updater = AxoUpdater::new();
updater.configure_installer_path("/tmp");
```

--------------------------------

### Perform Run Test

Source: https://docs.rs/axoupdater/latest/src/axoupdater/test/helpers.rs.html?search=

Installs an application binary to the user's home directory (`~/.cargo/bin`) and simulates running its updater. It handles cleanup of previous installations and asserts that the binary does not exist before installation. Recommended for CI environments due to file system writes.

```rust
pub fn perform_runtest(runtest_args: &RuntestArgs) -> PathBuf {
    let RuntestArgs {
        app_name,
        package,
        owner,
        bin,
        binaries,
        args,
        release_type,
    } = runtest_args;

    let basename = bin.file_name().unwrap();
    let home = homedir::my_home().unwrap().unwrap();

    let app_home = &home.join(".cargo").join("bin");
    let app_path = &app_home.join(basename);

    let config_path = get_config_paths(app_name)
        .unwrap()
        // Accept whichever path comes first; it doesn't matter to us.
        .first()
        .expect("no possible legal config paths found!?")
        .to_owned()
        .into_std_path_buf();

    // Ensure we delete any previous copy that may exist
    // at this path before we copy in our version.
    if app_path.exists() {
        std::fs::remove_file(app_path).unwrap();
    }
    assert!(!app_path.exists());

    // Install to the home directory
    std::fs::copy(bin, app_path).unwrap();
    
```

--------------------------------

### Configure Installer Path (PathBuf)

Source: https://docs.rs/axoupdater/latest/src/axoupdater/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Tests the configuration of the installer path using a std::path::PathBuf.

```rust
let mut updater = AxoUpdater::new();
let mut path = PathBuf::new();
path.push("/tmp");
updater.configure_installer_path(&path.to_string_lossy());
```

--------------------------------

### Set Install Directory (String Slice)

Source: https://docs.rs/axoupdater/latest/src/axoupdater/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Tests setting the installation directory using a string slice.

```rust
let mut updater = AxoUpdater::new();
updater.set_install_dir("/tmp");
```

--------------------------------

### perform_runtest

Source: https://docs.rs/axoupdater/latest/axoupdater/test/helpers/fn.perform_runtest.html

Installs an application and runs its updater. Returns the path where the binary was expected to be installed.

```APIDOC
## Function perform_runtest

### Description
Actually installs your app and runs its updater. For detailed information on the arguments, see `RuntestArgs`. This function performs several assertions of its own, then returns the path to which the binary was expected to have been installed in order to allow the caller to perform additional tests or assertions. Because it writes to real files outside a temporary directory, it’s highly recommended that this only becalled within CI builds. Note that, at the moment, this always attempts to install to CARGO_HOME (~/.cargo/bin).

### Signature
```rust
pub fn perform_runtest(runtest_args: &RuntestArgs) -> PathBuf
```

### Parameters
#### Path Parameters
- **runtest_args** (*&RuntestArgs*) - Required - Arguments for the runtest operation.
```

--------------------------------

### Configure Installer Path (Path)

Source: https://docs.rs/axoupdater/latest/src/axoupdater/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Tests the configuration of the installer path using a std::path::Path.

```rust
let mut updater = AxoUpdater::new();
let path = Path::new("/tmp");
updater.configure_installer_path(&path.to_string_lossy());
```

--------------------------------

### set_install_dir

Source: https://docs.rs/axoupdater/latest/src/axoupdater/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Configures AxoUpdater with the install path to use. This is only needed if installing without an explicit install prefix.

```APIDOC
## set_install_dir

### Description
Configures AxoUpdater with the install path to use. This is only needed if installing without an explicit install prefix.

### Method
`&mut self`

### Parameters
* `path` (impl Into<Utf8PathBuf>) - The installation directory path.

### Returns
`&mut AxoUpdater` - A mutable reference to the AxoUpdater instance.
```

--------------------------------

### Handle Installation Result

Source: https://docs.rs/axoupdater/latest/src/axoupdater/lib.rs.html?search=

Processes the output of the installer command, determining if the installation failed and extracting stdout/stderr. It handles cleanup by restoring the old version if the installation failed or deleting the current executable if successful on Windows.

```rust
let failed;
        let stdout;
        let stderr;
        let statuscode;
        if let Ok(output) = &result {
            failed = !output.status.success();
            stdout = if output.stdout.is_empty() {
                None
            } else {
                Some(String::from_utf8_lossy(&output.stdout).to_string())
            };
            stderr = if output.stderr.is_empty() {
                None
            } else {
                Some(String::from_utf8_lossy(&output.stderr).to_string())
            };
            statuscode = output.status.code();
        } else {
            failed = true;
            stdout = None;
            stderr = None;
            statuscode = None;
        }

        if let Some((ourselves, old_path)) = to_restore {
            if failed {
                std::fs::rename(ourselves, old_path)?;
            } else {
                #[cfg(windows)]
                self_replace::self_delete_at(&ourselves)
                    .map_err(|_| AxoupdateError::CleanupFailed {})?;
            }
        }

        // Return the original AxoprocessError if we failed to launch
        // the command at all
        result?;

        // Otherwise return a more specific error with status code and
        // stdout/err. Note that this stdout/stderr will be None if the
        // caller requested us to print stdout/stderr to the terminal.
        if failed {
            return Err(AxoupdateError::InstallFailed {
                status: statuscode,
                stdout,
                stderr,
            });
        }

        let result = UpdateResult {
            old_version: self.current_version.clone(),
            new_version: release.version.clone(),
            new_version_tag: release.tag_name.to_owned(),
            install_prefix,
        };

        Ok(Some(result))
```

--------------------------------

### Set Install Directory (Path)

Source: https://docs.rs/axoupdater/latest/src/axoupdater/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Tests setting the installation directory using a std::path::Path.

```rust
let mut updater = AxoUpdater::new();
let path = Path::new("/tmp");
updater.set_install_dir(&path.to_string_lossy());
```

--------------------------------

### Enable All Installer Output

Source: https://docs.rs/axoupdater/latest/src/axoupdater/lib.rs.html?search=std%3A%3Avec

Enables printing both standard output and standard error from the underlying installer process. This provides the most verbose logging for the installer.

```rust
pub fn enable_installer_output(&mut self) -> &mut AxoUpdater {
    self.print_installer_stdout = true;
    self.print_installer_stderr = true;

    self
}
```

--------------------------------

### Handle Installation Result

Source: https://docs.rs/axoupdater/latest/src/axoupdater/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Processes the output of the installer command, determining if the installation failed and extracting stdout/stderr. It handles cleanup or restoration of files based on the success of the installation.

```rust
        let failed;
        let stdout;
        let stderr;
        let statuscode;
        if let Ok(output) = &result {
            failed = !output.status.success();
            stdout = if output.stdout.is_empty() {
                None
            } else {
                Some(String::from_utf8_lossy(&output.stdout).to_string())
            };
            stderr = if output.stderr.is_empty() {
                None
            } else {
                Some(String::from_utf8_lossy(&output.stderr).to_string())
            };
            statuscode = output.status.code();
        } else {
            failed = true;
            stdout = None;
            stderr = None;
            statuscode = None;
        }

        if let Some((ourselves, old_path)) = to_restore {
            if failed {
                std::fs::rename(ourselves, old_path)?;
            } else {
                #[cfg(windows)]
                self_replace::self_delete_at(&ourselves)
                    .map_err(|_| AxoupdateError::CleanupFailed {{ }})?;
            }
        }

        // Return the original AxoprocessError if we failed to launch
        // the command at all
        result?;

        // Otherwise return a more specific error with status code and
        // stdout/err. Note that this stdout/stderr will be None if the
        // caller requested us to print stdout/stderr to the terminal.
        if failed {
            return Err(AxoupdateError::InstallFailed {
                status: statuscode,
                stdout,
                stderr,
            });
        }

        let result = UpdateResult {
            old_version: self.current_version.clone(),
            new_version: release.version.clone(),
            new_version_tag: release.tag_name.to_owned(),
            install_prefix,
        };

        Ok(Some(result))
```

--------------------------------

### Set Install Directory

Source: https://docs.rs/axoupdater/latest/src/axoupdater/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Configures the directory where the application will be installed. This is primarily used when installing without an explicit installation prefix.

```rust
pub fn set_install_dir(&mut self, path: impl Into<Utf8PathBuf>) -> &mut AxoUpdater {
        self.install_prefix = Some(path.into());

        self
    }
```

--------------------------------

### Set Install Directory (PathBuf)

Source: https://docs.rs/axoupdater/latest/src/axoupdater/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Tests setting the installation directory using a std::path::PathBuf.

```rust
let mut updater = AxoUpdater::new();
let mut path = PathBuf::new();
path.push("/tmp");
updater.set_install_dir(&path.to_string_lossy());
```

--------------------------------

### Configure Custom Installer Path

Source: https://docs.rs/axoupdater/latest/src/axoupdater/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Specifies a custom path for the installer, overriding the default behavior of downloading from the release source. Use this when you have a pre-downloaded or custom-built installer.

```rust
pub fn configure_installer_path(&mut self, path: impl Into<Utf8PathBuf>) -> &mut AxoUpdater {
        self.installer_path = Some(path.into().to_owned());

        self
    }
```

--------------------------------

### Write Install Receipt to Disk

Source: https://docs.rs/axoupdater/latest/src/axoupdater/test/helpers.rs.html?search=std%3A%3Avec

Generates an install receipt and writes it to the specified configuration path. Returns the path to the created receipt file. Ensure the `config_path` is writable.

```rust
fn write_receipt(
    app_name: &str,
    package: &str,
    owner: &str,
    binaries: &[String],
    version: &str,
    prefix: &Path,
    config_path: &PathBuf,
    release_type: &ReleaseSourceType,
) -> std::io::Result<PathBuf> {
    let contents = install_receipt(
        app_name,
        package,
        owner,
        binaries,
        version,
        &prefix.to_string_lossy(),
        release_type,
    );
    let receipt_name = config_path.join(format!("{}-receipt.json", package));
    std::fs::create_dir_all(config_path)?;
    std::fs::write(&receipt_name, contents)?;

    Ok(receipt_name)
}
```

--------------------------------

### Enable Installer Stderr Output

Source: https://docs.rs/axoupdater/latest/src/axoupdater/lib.rs.html?search=std%3A%3Avec

Enables printing the standard error of the underlying installer process. Use this to capture or view any error messages from the installer.

```rust
pub fn enable_installer_stderr(&mut self) -> &mut AxoUpdater {
    self.print_installer_stderr = true;

    self
}
```

--------------------------------

### Configure Custom Installer Path

Source: https://docs.rs/axoupdater/latest/src/axoupdater/lib.rs.html?search=u32+-%3E+bool

Specify a custom path for the installer instead of downloading it from the release source. This method takes a path that can be converted into a `Utf8PathBuf`.

```rust
pub fn configure_installer_path(&mut self, path: impl Into<Utf8PathBuf>) -> &mut AxoUpdater {
    self.installer_path = Some(path.into().to_owned());

    self
}
```

--------------------------------

### perform_runtest

Source: https://docs.rs/axoupdater/latest/axoupdater/test/helpers/fn.perform_runtest.html?search=

Actually installs your app and runs its updater. Returns the path to which the binary was expected to have been installed, allowing the caller to perform additional tests or assertions. Recommended for CI builds as it writes to real files.

```APIDOC
## perform_runtest

### Description
Installs an application and runs its updater. Returns the installation path for further assertions. This function writes to real files and should primarily be used in CI environments.

### Function Signature
`pub fn perform_runtest(runtest_args: &RuntestArgs) -> PathBuf`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **runtest_args** (`&RuntestArgs`) - Required - Arguments for the runtest operation. See `RuntestArgs` for details.

### Request Example
```json
{
  "runtest_args": { ... } 
}
```

### Response
#### Success Response (PathBuf)
* **PathBuf** - The path to which the binary was expected to have been installed.

### Response Example
```json
"/path/to/installed/binary"
```
```

--------------------------------

### Load Install Receipt - AxoUpdater

Source: https://docs.rs/axoupdater/latest/axoupdater/struct.AxoUpdater.html

Attempts to load an install receipt to prepare for an update. If a valid receipt is found, it populates the `source` and `current_version` fields. This method is useful for applications that use cargo-dist for installation.

```rust
pub fn load_receipt(&mut self) -> AxoupdateResult<&mut AxoUpdater>
```

--------------------------------

### Write Install Receipt to Disk

Source: https://docs.rs/axoupdater/latest/src/axoupdater/test/helpers.rs.html?search=u32+-%3E+bool

Generates an install receipt and writes it to the specified config path. Returns the path to the created receipt file. Ensure the config directory exists before calling.

```rust
fn write_receipt(
    app_name: &str,
    package: &str,
    owner: &str,
    binaries: &[String],
    version: &str,
    prefix: &Path,
    config_path: &PathBuf,
    release_type: &ReleaseSourceType,
) -> std::io::Result<PathBuf> {
    let contents = install_receipt(
        app_name,
        package,
        owner,
        binaries,
        version,
        &prefix.to_string_lossy(),
        release_type,
    );
    let receipt_name = config_path.join(format!("{package}-receipt.json"));
    std::fs::create_dir_all(config_path)?;
    std::fs::write(&receipt_name, contents)?;

    Ok(receipt_name)
}
```

--------------------------------

### Use Release Installer

Source: https://docs.rs/axoupdater/latest/src/axoupdater/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Resets AxoUpdater to use the installer provided with the new release. This is the default behavior.

```rust
pub fn use_release_installer(&mut self) -> &mut AxoUpdater {
        self.installer_path = None;

        self
    }
```

--------------------------------

### Generate Install Receipt String

Source: https://docs.rs/axoupdater/latest/src/axoupdater/test/helpers.rs.html?search=std%3A%3Avec

Generates a JSON string representing an install receipt. This is useful for creating mock receipts for testing purposes.

```rust
fn install_receipt(
    app_name: &str,
    package: &str,
    owner: &str,
    binaries: &[String],
    version: &str,
    prefix: &str,
    release_type: &ReleaseSourceType,
) -> String {
    let binaries = binaries
        .iter()
        .map(|name| format!(r#"{}""#, name))
        .collect::<Vec<String>>()
        .join(", ");
    RECEIPT_TEMPLATE
        .replace("BINARIES", &binaries)
        .replace("PACKAGE", package)
        .replace("OWNER", owner)
        .replace("APP_NAME", app_name)
        .replace("INSTALL_PREFIX", &prefix.replace('\\', "\\\\"))
        .replace("VERSION", version)
        .replace("RELEASE_TYPE", &release_type.to_string())
}
```

--------------------------------

### Load Install Receipt - AxoUpdater

Source: https://docs.rs/axoupdater/latest/axoupdater/struct.AxoUpdater.html?search=std%3A%3Avec

Attempts to load an install receipt to prepare for an update. Populates `source` and `current_version` if a valid receipt is found. Shell and Powershell installers from cargo-dist v0.9.0+ create receipts.

```rust
pub fn load_receipt(&mut self) -> AxoupdateResult<&mut AxoUpdater>

```

--------------------------------

### InstallReceipt Struct Definition

Source: https://docs.rs/axoupdater/latest/src/axoupdater/receipt.rs.html?search=

Defines the structure for an install receipt, containing information about the installation path, binaries, libraries, release source, version, provider, and path modification settings.

```rust
use std::{
    env::{self, current_dir, current_exe},
    path::PathBuf,
};

use crate::{errors::*, AxoUpdater, ReleaseSource};
use axoasset::SourceFile;
use axotag::Version;
use camino::Utf8PathBuf;
use serde::Deserialize;

fn default_as_true() -> bool {
    true
}

/// Information parsed from a cargo-dist install receipt
#[derive(Clone, Debug, Deserialize)]
pub struct InstallReceipt {
    /// The path this app has been installed to
    pub install_prefix: Utf8PathBuf,
    /// A list of binaries installed by this app
    #[allow(dead_code)]
    pub binaries: Vec<String>,
    /// A list of libraries installed by this app
    // Added in cargo-dist 0.20.0, missing in older receipts
    #[serde(default = "Vec::new")]
    #[allow(dead_code)]
    pub cdylibs: Vec<String>,
    /// Information about where this release was fetched from
    pub source: ReleaseSource,
    /// Installed version
    pub version: String,
    /// Information about the tool used to produce this receipt
    pub provider: ReceiptProvider,
    /// Information about whether new installations should modify system paths
    // Added in cargo-dist 0.23.0, missing in older receipts
    #[serde(default = "default_as_true")]
    pub modify_path: bool,
}

/// Tool used to produce this install receipt
#[derive(Clone, Debug, Deserialize)]
pub struct ReceiptProvider {
    /// The name of the tool used to create this receipt
    pub source: String,
    /// The version of the above tool
    pub version: String,
}

```

--------------------------------

### Generate Install Receipt

Source: https://docs.rs/axoupdater/latest/src/axoupdater/test/helpers.rs.html?search=std%3A%3Avec

Generates a JSON string representing an install receipt. This is useful for testing the receipt generation logic with different application names, packages, owners, binaries, versions, install prefixes, and release source types.

```rust
fn install_receipt(
    app_name: &str,
    package: &str,
    owner: &str,
    binaries: &[String],
    version: &str,
    app_home: &str,
    release_source_type: &ReleaseSourceType,
) -> String {
    let receipt = InstallReceipt {
        version: version.to_owned(),
        provider: ProviderInfo {
            source: "cargo-dist".to_owned(),
            version: "0.10.0-prerelease.1".to_owned(),
        },
        source: SourceInfo {
            app_name: app_name.to_owned(),
            name: package.to_owned(),
            owner: owner.to_owned(),
            release_type: release_source_type.to_string(),
        },
        binaries: binaries.to_owned(),
        install_prefix: app_home.to_owned(),
    };
    serde_json::to_string(&receipt).unwrap()
}
```

```rust
let expected = r#"{"binaries":["cargo-dist"],"install_prefix":"/tmp/prefix","provider":{"source":"cargo-dist","version":"0.10.0-prerelease.1"},"source":{"app_name":"cargo-dist","name":"cargo-dist","owner":"axodotdev","release_type":"github"},"version":"0.5.0"}"#;

    let actual = install_receipt(
        "cargo-dist",
        "cargo-dist",
        "axodotdev",
        &["cargo-dist".to_owned()],
        "0.5.0",
        "/tmp/prefix",
        &ReleaseSourceType::GitHub,
    );
    assert_eq!(expected, actual);
```

```rust
let expected = r#"{"binaries":["axolotlsay"],"install_prefix":"/tmp/prefix","provider":{"source":"cargo-dist","version":"0.10.0-prerelease.1"},"source":{"app_name":"axolotlsay","name":"cargodisttest","owner":"mistydemeo","release_type":"github"},"version":"0.5.0"}"#;

    let actual = install_receipt(
        "axolotlsay",
        "cargodisttest",
        "mistydemeo",
        &["axolotlsay".to_owned()],
        "0.5.0",
        "/tmp/prefix",
        &ReleaseSourceType::GitHub,
    );
    assert_eq!(expected, actual);
```

```rust
let expected = r#"{"binaries":["bin1", "bin2"],"install_prefix":"/tmp/prefix","provider":{"source":"cargo-dist","version":"0.10.0-prerelease.1"},"source":{"app_name":"axolotlsay","name":"cargodisttest","owner":"mistydemeo","release_type":"github"},"version":"0.5.0"}"#;

    let actual = install_receipt(
        "axolotlsay",
        "cargodisttest",
        "mistydemeo",
        &["bin1".to_owned(), "bin2".to_owned()],
        "0.5.0",
        "/tmp/prefix",
        &ReleaseSourceType::GitHub,
    );
    assert_eq!(expected, actual);
```

```rust
let expected = r#"{"binaries":["axolotlsay"],"install_prefix":"/tmp/prefix","provider":{"source":"cargo-dist","version":"0.10.0-prerelease.1"},"source":{"app_name":"axolotlsay","name":"cargodisttest","owner":"mistydemeo","release_type":"axodotdev"},"version":"0.5.0"}"#;

    let actual = install_receipt(
        "axolotlsay",
        "cargodisttest",
        "mistydemeo",
        &["axolotlsay".to_owned()],
        "0.5.0",
        "/tmp/prefix",
        &ReleaseSourceType::Axo,
    );
    assert_eq!(expected, actual);
```

--------------------------------

### Test Install Receipt with Multiple Binaries

Source: https://docs.rs/axoupdater/latest/src/axoupdater/test/helpers.rs.html?search=

Tests the generation of an install receipt for an application with multiple binary targets. Verifies that all specified binaries are included in the receipt.

```rust
let expected = r#"{"binaries":["bin1", "bin2"],"install_prefix":"/tmp/prefix","provider":{"source":"cargo-dist","version":"0.10.0-prerelease.1"},"source":{"app_name":"axolotlsay","name":"cargodisttest","owner":"mistydemeo","release_type":"github"},"version":"0.5.0"}"#;

    let actual = install_receipt(
        "axolotlsay",
        "cargodisttest",
        "mistydemeo",
        &["bin1".to_owned(), "bin2".to_owned()],
        "0.5.0",
        "/tmp/prefix",
        &ReleaseSourceType::GitHub,
    );
```

--------------------------------

### Execute Update Process

Source: https://docs.rs/axoupdater/latest/src/axoupdater/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Executes the update process for the application. It first checks if an update is needed, then fetches the release information, and proceeds to download and install the appropriate installer based on the operating system.

```rust
if !self.is_update_needed().await? {
    return Ok(None);
}

let release = match &self.requested_release {
    Some(r) => r,
    None => {
        self.fetch_release().await?;
        self.requested_release.as_ref().unwrap()
    }
};
let tempdir = TempDir::new()?;

// If we've been given an installer path to use, skip downloading and
// install from that.
let installer_path = if let Some(path) = &self.installer_path {
    path.to_owned()
// Otherwise, proceed with downloading the installer from the release
// we just looked up.
} else {
    let app_name = self.name.clone().unwrap_or_default();
    let installer_url = match env::consts::OS {
        "macos" | "linux" => release
            .assets
            .iter()
            .find(|asset| asset.name == format!("{app_name}-installer.sh")),
        "windows" => release
            .assets
            .iter()
            .find(|asset| asset.name == format!("{app_name}-installer.ps1")),
        _ => unreachable!(),
    };

    let installer_url = if let Some(installer_url) = installer_url {
        installer_url
    } else {
        return Err(AxoupdateError::NoInstallerForPackage {});
    };

    let extension = if cfg!(windows) { ".ps1" } else { ".sh" };

    let installer_path = 
        Utf8PathBuf::try_from(tempdir.path().join(format!("installer{extension}")))?;

    #[cfg(unix)]
    {
        let installer_file = File::create(&installer_path)?;
        let mut perms = installer_file.metadata()?.permissions();
        perms.set_mode(0o744);
        installer_file.set_permissions(perms)?;
    }

    let download = self
        .client
        .get(&installer_url.browser_download_url)
        .header(reqwest::header::ACCEPT, "application/octet-stream")
        .send()
        .await?;
    let download_text = download.text().await?;

    LocalAsset::write_new_all(&download_text, &installer_path)?;

    installer_path
};

// Before we update, rename ourselves to a temporary name.
// This is necessary because Windows won't let an actively-running
// executable be overwritten.
// If the update fails, we'll move it back to where it was before
// we began the update process.
let to_restore = if cfg!(target_family = "windows") {
    let old_filename = std::env::current_exe()?;

    let mut new_filename = old_filename.as_os_str().to_os_string();
    // Filename follows the pattern set here: https://docs.rs/self-replace/1.5.0/self_replace/#implementation
    new_filename.push(OsStr::new(".previous.exe"));
    Some(new_filename)
} else {
    None
};

// TODO: Implement the actual update execution logic here using installer_path and to_restore

Ok(Some(UpdateResult::Updated))

```

--------------------------------

### Test Install Receipt with Different App/Package

Source: https://docs.rs/axoupdater/latest/src/axoupdater/test/helpers.rs.html?search=

Tests the generation of an install receipt with different application and package names. Ensures the receipt correctly reflects these distinct identifiers.

```rust
let expected = r#"{"binaries":["axolotlsay"],"install_prefix":"/tmp/prefix","provider":{"source":"cargo-dist","version":"0.10.0-prerelease.1"},"source":{"app_name":"axolotlsay","name":"cargodisttest","owner":"mistydemeo","release_type":"github"},"version":"0.5.0"}"#;

    let actual = install_receipt(
        "axolotlsay",
        "cargodisttest",
        "mistydemeo",
        &["axolotlsay".to_owned()],
        "0.5.0",
        "/tmp/prefix",
        &ReleaseSourceType::GitHub,
    );
```

--------------------------------

### Test Install Receipt Generation

Source: https://docs.rs/axoupdater/latest/src/axoupdater/test/helpers.rs.html?search=

Tests the generation of an install receipt for a single binary application. Verifies the JSON output matches the expected structure and content.

```rust
let expected = r#"{"binaries":["cargo-dist"],"install_prefix":"/tmp/prefix","provider":{"source":"cargo-dist","version":"0.10.0-prerelease.1"},"source":{"app_name":"cargo-dist","name":"cargo-dist","owner":"axodotdev","release_type":"github"},"version":"0.5.0"}"#;

    let actual = install_receipt(
        "cargo-dist",
        "cargo-dist",
        "axodotdev",
        &["cargo-dist".to_owned()],
        "0.5.0",
        "/tmp/prefix",
        &ReleaseSourceType::GitHub,
    );
    assert_eq!(expected, actual);
```

--------------------------------

### Load Install Receipt for Specific App Name

Source: https://docs.rs/axoupdater/latest/src/axoupdater/receipt.rs.html?search=std%3A%3Avec

Loads an install receipt for a specified application name. This is useful when the receipt might exist under different names, such as after an application has been renamed.

```rust
pub fn load_receipt_as(&mut self, app_name: &str) -> AxoupdateResult<&mut AxoUpdater> {
        let receipt = load_receipt_for(app_name)?;

        self.source = Some(receipt.source);
        self.current_version = Some(receipt.version.parse::<Version>()?);

        let provider = crate::Provider {
            source: receipt.provider.source,
            version: receipt.provider.version.parse::<Version>()?,
        };

        self.current_version_installed_by = Some(provider);
        self.install_prefix = Some(receipt.install_prefix);
        self.modify_path = receipt.modify_path;

        Ok(self)
    }
```

--------------------------------

### InstallReceipt Struct Definition

Source: https://docs.rs/axoupdater/latest/src/axoupdater/receipt.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Defines the structure for an install receipt, which contains information about the application's installation, source, version, and provider. Includes default handling for optional fields like `cdylibs` and `modify_path`.

```rust
use std::{
    env::{self, current_dir, current_exe},
    path::PathBuf,
};

use crate::{errors::*, AxoUpdater, ReleaseSource};
use axoasset::SourceFile;
use axotag::Version;
use camino::Utf8PathBuf;
use serde::Deserialize;

fn default_as_true() -> bool {
    true
}

/// Information parsed from a cargo-dist install receipt
#[derive(Clone, Debug, Deserialize)]
pub struct InstallReceipt {
    /// The path this app has been installed to
    pub install_prefix: Utf8PathBuf,
    /// A list of binaries installed by this app
    #[allow(dead_code)]
    pub binaries: Vec<String>,
    /// A list of libraries installed by this app
    // Added in cargo-dist 0.20.0, missing in older receipts
    #[serde(default = "Vec::new")]
    #[allow(dead_code)]
    pub cdylibs: Vec<String>,
    /// Information about where this release was fetched from
    pub source: ReleaseSource,
    /// Installed version
    pub version: String,
    /// Information about the tool used to produce this receipt
    pub provider: ReceiptProvider,
    /// Information about whether new installations should modify system paths
    // Added in cargo-dist 0.23.0, missing in older receipts
    #[serde(default = "default_as_true")]
    pub modify_path: bool,
}

/// Tool used to produce this install receipt
#[derive(Clone, Debug, Deserialize)]
pub struct ReceiptProvider {
    /// The name of the tool used to create this receipt
    pub source: String,
    /// The version of the above tool
    pub version: String,
}
```

--------------------------------

### Normalize Installation Path

Source: https://docs.rs/axoupdater/latest/src/axoupdater/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Normalizes an installation path by canonicalizing it. It handles potential errors during canonicalization by returning the original path if the canonicalization fails, ensuring a consistent path representation.

```rust
let raw_root = self.install_prefix_root()?;
let canonicalized = if let Ok(path) = raw_root.canonicalize() {
    path
} else {
    raw_root.into_std_path_buf()
};
let normalized = Utf8PathBuf::from_path_buf(canonicalized)
    .map_err(|path| AxoupdateError::CaminoConversionFailed { path })?;
Ok(normalized)
```

--------------------------------

### Get Install Prefix Root

Source: https://docs.rs/axoupdater/latest/src/axoupdater/lib.rs.html?search=u32+-%3E+bool

Retrieves the root of the install prefix, stripping a trailing `/bin` component if present. This method includes logic to work around a bug in older versions of `cargo-dist`.

```rust
pub fn install_prefix_root(&self) -> AxoupdateResult<Utf8PathBuf> {
    let Some(install_prefix) = &self.install_prefix else {
        return Err(AxoupdateError::NotConfigured {
            missing_field: "install_prefix".to_owned(),
        });
    };

    let mut install_root = install_prefix.to_owned();
    // Works around a bug in cargo-dist between 0.10.0 and 0.15.0, in which
    // prefix-style workspaces like CARGO_HOME had the prefix incorrectly
    // set to include the `bin` directory.
    if install_root.ends_with("bin") {
        install_root.pop();
    }
    Ok(install_root)
}
```

--------------------------------

### AxoUpdater::enable_installer_stdout

Source: https://docs.rs/axoupdater/latest/axoupdater/struct.AxoUpdater.html

Enables printing the underlying installer's standard output.

```APIDOC
## AxoUpdater::enable_installer_stdout

### Description
Enables printing the underlying installer’s stdout.

### Method
`enable_installer_stdout(&mut self) -> &mut AxoUpdater`

### Returns
- `&mut AxoUpdater`: A mutable reference to the AxoUpdater instance for chaining.
```

--------------------------------

### Get Install Root Path

Source: https://docs.rs/axoupdater/latest/src/axoupdater/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Retrieves the root directory of the installation, intelligently stripping a trailing `/bin` component if present. This function accounts for a historical bug in cargo-dist related to inconsistent `install_prefix` reporting.

```rust
pub fn install_prefix_root(&self) -> AxoupdateResult<Utf8PathBuf> {
        let Some(install_prefix) = &self.install_prefix else {
            return Err(AxoupdateError::NotConfigured {
                missing_field: "install_prefix".to_owned(),
            });
        };

        let mut install_root = install_prefix.to_owned();
        // Works around a bug in cargo-dist between 0.10.0 and 0.15.0, in which
        // prefix-style workspaces like CARGO_HOME had the prefix incorrectly
        // set to include the `bin` directory.
        
```

--------------------------------

### Rust Result unwrap() Example

Source: https://docs.rs/axoupdater/latest/axoupdater/errors/type.AxoupdateResult.html?search=std%3A%3Avec

Demonstrates the basic usage of `unwrap()` to get the Ok value. Panics if the Result is an Err.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.unwrap(), 2);
```

--------------------------------

### Get GitHub Releases

Source: https://docs.rs/axoupdater/latest/src/axoupdater/release/github.rs.html?search=u32+-%3E+bool

Fetches all releases for a given application from a GitHub repository. It handles pagination and filters releases to include only those with installer assets.

```APIDOC
## get_github_releases

### Description
Fetches all releases for a specified application from a GitHub repository. This function handles paginating through GitHub's release API and filters the results to include only releases that contain an installer asset for the given application name.

### Function Signature
```rust
pub(crate) async fn get_github_releases(
    name: &str, 
    owner: &str, 
    app_name: &str, 
    client: &reqwest::Client, 
    token: &Option<String>
) -> AxoupdateResult<Vec<Release>>
```

### Parameters
- **name** (*&str*): The name of the repository.
- **owner** (*&str*): The owner of the repository.
- **app_name** (*&str*): The name of the application to filter releases by.
- **client** (*&reqwest::Client*): The HTTP client to use for making requests.
- **token** (*&Option<String>*): An optional authentication token for GitHub API.

### Returns
- `AxoupdateResult<Vec<Release>>`: A result containing a vector of `Release` objects if successful, or an `AxoupdateError` otherwise.
```

--------------------------------

### Get Latest GitHub Release

Source: https://docs.rs/axoupdater/latest/src/axoupdater/release/github.rs.html

Fetches the latest release for a given repository and application name. It checks for the existence of an installer asset and returns a `Release` object if found, otherwise `None`.

```APIDOC
## get_latest_github_release

### Description
Fetches the latest release for a given repository and application name. It checks for the existence of an installer asset and returns a `Release` object if found, otherwise `None`.

### Function Signature
```rust
pub(crate) async fn get_latest_github_release(
    name: &str, 
    owner: &str, 
    app_name: &str, 
    client: &reqwest::Client, 
    token: &Option<String>,
) -> AxoupdateResult<Option<Release>>
```

### Parameters
- `name` (str): The name of the repository.
- `owner` (str): The owner of the repository.
- `app_name` (str): The name of the application.
- `client` (&reqwest::Client): The HTTP client to use for the request.
- `token` (&Option<String>): An optional authentication token for GitHub API.

### Returns
- `AxoupdateResult<Option<Release>>`: A result containing an optional `Release` object if the latest release is found and contains an installer asset, or an error.
```

--------------------------------

### Get Specific GitHub Tag Release

Source: https://docs.rs/axoupdater/latest/src/axoupdater/release/github.rs.html

Fetches a specific release by tag name for a given repository and application name. It returns a `Release` object if the tag is found and contains an installer asset.

```APIDOC
## get_specific_github_tag

### Description
Fetches a specific release by tag name for a given repository and application name. It returns a `Release` object if the tag is found and contains an installer asset.

### Function Signature
```rust
pub(crate) async fn get_specific_github_tag(
    name: &str, 
    owner: &str, 
    app_name: &str, 
    tag: &str, 
    client: &reqwest::Client, 
    token: &Option<String>,
) -> AxoupdateResult<Release>
```

### Parameters
- `name` (str): The name of the repository.
- `owner` (str): The owner of the repository.
- `app_name` (str): The name of the application.
- `tag` (str): The specific tag of the release to fetch.
- `client` (&reqwest::Client): The HTTP client to use for the request.
- `token` (&Option<String>): An optional authentication token for GitHub API.

### Returns
- `AxoupdateResult<Release>`: A result containing the `Release` object for the specified tag, or an error if not found or if it lacks an installer asset.
```

--------------------------------

### Get Latest GitHub Release

Source: https://docs.rs/axoupdater/latest/src/axoupdater/release/github.rs.html

Fetches the latest release for a given repository and application. It checks if the release contains an installer asset; if not, it returns None to allow fallback to iterating through other releases. Requires a reqwest client and an optional authentication token.

```rust
pub(crate) async fn get_latest_github_release(
    name: &str,
    owner: &str,
    app_name: &str,
    client: &reqwest::Client,
    token: &Option<String>,
) -> AxoupdateResult<Option<Release>> {
    let api: String = github_api(app_name)?;
    let mut request = client
        .get(format!("{api}/repos/{owner}/{name}/releases/latest"))
        .header(ACCEPT, "application/json")
        .header(
            USER_AGENT,
            format!("axoupdate/{}", env!("CARGO_PKG_VERSION")),
        );
    if let Some(token) = token {
        request = request.bearer_auth(token);
    }
    let gh_release: GithubRelease = request
        .send()
        .await?;
        .error_for_status()
        .map_err(|_| AxoupdateError::NoStableReleases {
            app_name: app_name.to_owned(),
        })?;
        .json()
        .await?;

    // Ensure that this release contains an installer asset; if not, it may be
    // a mismarked "latest" release that's not installable by us.
    // Returning None here will let us fall back to iterating releases.
    if !gh_release
        .assets
        .iter()
        .any(|asset| asset.name.starts_with(&format!("{app_name}-installer"))) 
    {
        return Ok(None);
    }

    match Release::try_from_github(app_name, gh_release) {
        Ok(release) => Ok(Some(release)),
        Err(e) => Err(e),
    }
}
```

--------------------------------

### Get Latest GitHub Release with Custom Endpoint

Source: https://docs.rs/axoupdater/latest/src/axoupdater/release/github.rs.html?search=

Fetches the latest GitHub release for a given repository and owner, using a custom GitHub Enterprise base URL. Ensure the APP_INSTALLER_GHE_BASE_URL environment variable is set before calling. The mock server setup demonstrates how to intercept and respond to the API request.

```rust
let server = MockServer::start_async().await;
env::set_var("APP_INSTALLER_GHE_BASE_URL", server.base_url());

let latest_release_http_call = server
    .mock_async(|when, then| {
        when.method("GET")
            .path("/api/v3/repos/owner/name/releases/latest");
        then.status(StatusCode::OK.as_u16())
            .header("content-type", "application/json")
            .json_body(json!(build_test_git_hub_release()));
    })
    .await;

let client = reqwest::Client::new();
let result = get_latest_github_release("name", "owner", "app", &client, &None).await;
env::remove_var("APP_INSTALLER_GHE_BASE_URL");

assert!(result.is_ok());
assert!(result.unwrap().is_some());

latest_release_http_call.assert();
```

--------------------------------

### Load Install Receipt from Path

Source: https://docs.rs/axoupdater/latest/src/axoupdater/receipt.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Loads and deserializes an `InstallReceipt` from a specified file path. This function assumes the file exists and is a valid JSON.

```rust
fn load_receipt_from_path(install_receipt_path: &Utf8PathBuf) -> AxoupdateResult<InstallReceipt> {
    Ok(SourceFile::load_local(install_receipt_path)?.deserialize_json()?)
}
```

--------------------------------

### Test AxoUpdater Installer Path Configuration (String)

Source: https://docs.rs/axoupdater/latest/src/axoupdater/lib.rs.html

Tests the `configure_installer_path` method of AxoUpdater with a String input.

```Rust
#[test]
fn test_installer_path_string() {
    let mut updater = AxoUpdater::new();
    updater.configure_installer_path("/tmp".to_string());
}
```

--------------------------------

### set_install_dir

Source: https://docs.rs/axoupdater/latest/src/axoupdater/lib.rs.html?search=std%3A%3Avec

Configures the installation directory for AxoUpdater. This is primarily used when installing without an explicit install prefix.

```APIDOC
## set_install_dir

### Description
Configures AxoUpdater with the install path to use. This is only needed if installing without an explicit install prefix.

### Method
`&mut self` (This is a builder pattern method, it returns a mutable reference to the AxoUpdater instance)

### Parameters
* `path` (impl Into<Utf8PathBuf>) - The desired installation directory path.

### Returns
`&mut AxoUpdater` - A mutable reference to the AxoUpdater instance for chaining.
```

--------------------------------

### ReleaseSource Search Examples

Source: https://docs.rs/axoupdater/latest/axoupdater/struct.ReleaseSource.html?search=

Examples of how to search for ReleaseSource. These examples demonstrate different search patterns and types.

```APIDOC
## Search Examples

### Example 1: Searching for a specific type

```
std::vec
```

### Example 2: Searching for a type conversion

```
u32 -> bool
```

### Example 3: Searching for a more complex type transformation

```
Option<T>, (T -> U) -> Option<U>
```
```

--------------------------------

### Perform Run Test

Source: https://docs.rs/axoupdater/latest/src/axoupdater/test/helpers.rs.html?search=std%3A%3Avec

Installs the application binary and simulates running its updater. This function is intended for CI environments as it writes to the actual file system. It asserts that the binary is not present before installation and copies the provided binary to the expected location.

```rust
pub fn perform_runtest(runtest_args: &RuntestArgs) -> PathBuf {
    let RuntestArgs {
        app_name,
        package,
        owner,
        bin,
        binaries,
        args,
        release_type,
    } = runtest_args;

    let basename = bin.file_name().unwrap();
    let home = homedir::my_home().unwrap().unwrap();

    let app_home = &home.join(".cargo").join("bin");
    let app_path = &app_home.join(basename);

    let config_path = get_config_paths(app_name)
        .unwrap()
        // Accept whichever path comes first; it doesn't matter to us.
        .first()
        .expect("no possible legal config paths found!?")
        .to_owned()
        .into_std_path_buf();

    // Ensure we delete any previous copy that may exist
    // at this path before we copy in our version.
    if app_path.exists() {
        std::fs::remove_file(app_path).unwrap();
    }
    assert!(!app_path.exists());

    // Install to the home directory
    std::fs::copy(bin, app_path).unwrap();

}
```
Tokens:
Raw