Installation & Setup

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• Cargo.toml
• src/lib.rs
• src/types/manager.rs
• src/platform/mod.rs
• src/platform/traits.rs

rust-battery is a cross-platform Rust crate designed to provide unified access to notebook battery information. It wraps OS-specific interfaces into a consistent API, returning data such as state of charge, energy rates, and temperature in SI measurement units. The library supports a wide range of operating systems including Linux, macOS, Windows, and various BSD distributions.

The installation process primarily involves adding the crate as a dependency in a Rust project. The setup phase requires initializing a Manager object, which serves as the entry point for discovering and interacting with system batteries. This architectural approach abstracts away platform-specific complexities like Linux's sysfs, macOS's IOKit, or Windows' IOCTL calls.

Sources: README.md:1-25, src/lib.rs:1-15

Prerequisites

Before integrating rust-battery, ensure your environment meets the minimum version requirements for the Rust compiler.

Requirement	Minimum Version
Rustc	1.89+

Sources: README.md:46, Cargo.toml:13

Adding the Dependency

To include rust-battery in your project, add it to the [dependencies] section of your Cargo.toml file. The crate is published under the name starship-battery.

[dependencies]
starship-battery = "0.11.0"

Sources: README.md:48-52, Cargo.toml:1-5

Optional Features

The crate provides optional features that can be enabled to provide additional functionality, such as schema generation for configuration.

Feature	Dependency	Description
config-schema	schemars, serde	Enables serde and schemars traits for data structures like State.

Sources: Cargo.toml:17-18

Platform Support and Backend Architecture

The library automatically selects a backend based on the target operating system during compilation using cfg-if.

The following table details the backend implementation used for each supported platform:

Platform	Minimum Version	Backend Implementation	Key Dependencies
Linux	2.6.39+	SysFsManager	lazycell
macOS	10.10+	IoKitManager	objc2-io-kit, mach2
Windows	7+	PowerManager	windows-sys
NetBSD	-	SysMonManager	plist, nix
FreeBSD	-	IoCtlManager	nix

Sources: README.md:27-37, src/platform/mod.rs:1-35, Cargo.toml:25-60

Initializing the Manager

The core of the library setup is the Manager struct. It handles the lifecycle of battery discovery and updates.

1. Creation: Call Manager::new() to initialize the platform-specific backend.
2. Discovery: Use the batteries() method to get an iterator over detected battery devices.
3. Data Retrieval: Iterate through the results to access individual Battery objects.

Implementation Logic

The Manager holds an Arc to an internal PlatformManager. When batteries() is called, it creates a PlatformIterator that preloads battery data from the system.

Basic Setup Example

The following code demonstrates the standard setup and usage pattern for the library.

use starship_battery::Manager;

fn main() -> Result<(), starship_battery::Error> {
    // 1. Initialize the manager
    let manager = Manager::new()?;

    // 2. Iterate over batteries
    for (idx, maybe_battery) in manager.batteries()?.enumerate() {
        let battery = maybe_battery?;
        
        // 3. Access SI-unit data
        println!("Battery #{}:", idx);
        println!("Vendor: {:?}", battery.vendor());
        println!("State: {:?}", battery.state());
    }

    Ok(())
}

Sources: README.md:54-70, src/types/manager.rs:11-20

Conclusion

Setting up rust-battery requires minimal configuration, primarily focusing on the Manager initialization. By abstracting platform-specific system calls into a unified trait-based architecture, the library allows developers to focus on battery data processing rather than OS-specific quirks. The implementation ensures that all returned values are type-safe and compliant with SI measurement standards.

Sources: src/lib.rs:1-10, src/platform/traits.rs:43-60