Update README to reflect current implementation

- Updated line count from ~260 to ~500 lines
- Removed thiserror dependency reference (only anyhow now)
- Added AptConfig documentation and configuration options
- Updated API documentation with all new methods
- Added configuration usage examples
- Fixed rollback claim (now implemented, not missing)
- Added configuration_usage example reference
- All examples and tests verified working
This commit is contained in:
robojerk 2025-09-13 11:24:37 -07:00
parent 2daad2837d
commit ac4987c7d1

View file

@ -11,8 +11,8 @@ This library provides a simple transaction interface that mimics DNF's imperativ
- **Simple transaction interface**: `add_package()`, `resolve()`, `commit()`, `rollback()`
- **DNF-like API**: Easy to port from rpm-ostree
- **Version-based rollback**: Track versions and restore previous states
- **Minimal dependencies**: Only `anyhow` and `thiserror`
- **~260 lines total**: Focused and maintainable
- **Minimal dependencies**: Only `anyhow`
- **~500 lines total**: Focused and maintainable
## Quick Start
@ -50,17 +50,28 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
```rust
pub struct AptTransaction {
packages: Vec<String>,
newly_installed: HashSet<String>, // packages that weren't installed before
upgraded: HashMap<String, String>, // package -> old_version for upgrades
config: AptConfig, // APT configuration options
}
impl AptTransaction {
pub fn new() -> Result<Self>; // Create new transaction
pub fn new() -> Result<Self>; // Create new transaction (default config)
pub fn with_config(config: AptConfig) -> Result<Self>; // Create with custom config
pub fn for_testing() -> Result<Self>; // Create for testing (dry run)
pub fn add_package(&mut self, name: &str) -> Result<()>; // Add package
pub fn resolve(&self) -> Result<()>; // Resolve dependencies
pub fn commit(&mut self) -> Result<()>; // Commit transaction
pub fn rollback(&self) -> Result<()>; // Rollback transaction
pub fn packages(&self) -> &[String]; // Get package list
pub fn changed_packages(&self) -> Vec<String>; // Get changed packages
pub fn is_empty(&self) -> bool; // Check if empty
pub fn resolve(&self) -> Result<()>; // Resolve dependencies
pub fn commit(&mut self) -> Result<()>; // Commit transaction
pub fn rollback(&self) -> Result<()>; // Rollback transaction
pub fn packages(&self) -> &[String]; // Get package list
pub fn changed_packages(&self) -> Vec<String>; // Get changed packages
pub fn is_empty(&self) -> bool; // Check if empty
pub fn config(&self) -> &AptConfig; // Get configuration
pub fn set_config(&mut self, config: AptConfig); // Update configuration
pub fn enable_dry_run(&mut self); // Enable dry run mode
pub fn disable_dry_run(&mut self); // Disable dry run mode
pub fn enable_quiet(&mut self); // Enable quiet mode
pub fn disable_quiet(&mut self); // Disable quiet mode
}
```
@ -73,6 +84,23 @@ pub fn is_package_installed(name: &str) -> Result<bool>; // Check install
pub fn get_package_info(name: &str) -> Result<AptPackage>; // Get package info
```
### Configuration
```rust
pub struct AptConfig {
pub no_install_recommends: bool, // Don't install recommended packages
pub no_install_suggests: bool, // Don't install suggested packages
pub assume_yes: bool, // Assume yes to all prompts
pub quiet: bool, // Quiet output
pub dry_run: bool, // Dry run mode (don't actually execute)
}
impl AptConfig {
pub fn new() -> Self; // Create with default values
pub fn for_testing() -> Self; // Create for testing (dry run + quiet)
}
```
## Installation
Add to your `Cargo.toml`:
@ -96,7 +124,7 @@ apt-wrapper = "0.1.0"
2. **Import the crate** in your Rust code:
```rust
use apt_wrapper::{AptTransaction, init, search_packages, is_package_installed};
use apt_wrapper::{AptTransaction, AptConfig, init, search_packages, is_package_installed};
```
3. **Initialize the library** before use:
@ -117,6 +145,7 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
The crate provides these main components:
- **`AptTransaction`**: Main transaction interface for package operations
- **`AptConfig`**: Configuration options for APT behavior
- **`init()`**: Initialize the library (required before use)
- **`search_packages()`**: Search for available packages
- **`is_package_installed()`**: Check if a package is installed
@ -142,7 +171,7 @@ fn example() -> Result<()> {
Here's a complete example of using the crate:
```rust
use apt_wrapper::{AptTransaction, init, search_packages, is_package_installed};
use apt_wrapper::{AptTransaction, AptConfig, init, search_packages, is_package_installed};
use anyhow::Result;
fn main() -> Result<()> {
@ -241,6 +270,30 @@ tx.rollback()?;
println!("Changed packages: {:?}", tx.changed_packages());
```
### Configuration Options
```rust
use apt_wrapper::{AptTransaction, AptConfig};
// Create with custom configuration
let config = AptConfig {
no_install_recommends: true,
no_install_suggests: true,
assume_yes: true,
quiet: false,
dry_run: true,
};
let mut tx = AptTransaction::with_config(config)?;
// Or modify configuration at runtime
tx.enable_dry_run();
tx.enable_quiet();
// For testing
let mut test_tx = AptTransaction::for_testing()?;
```
## Testing
```bash
@ -251,6 +304,7 @@ cargo test
```bash
cargo run --example simple_usage
cargo run --example configuration_usage
```
## Design Philosophy
@ -260,14 +314,14 @@ This wrapper is designed to be:
1. **Simple**: Minimal API surface, easy to understand
2. **Focused**: Only what's needed for apt-ostree porting
3. **DNF-like**: Familiar interface for rpm-ostree developers
4. **Minimal**: ~260 lines total, no complex abstractions
4. **Minimal**: ~500 lines total, no complex abstractions
## Differences from DNF
- **APT is declarative**: Dependencies are resolved automatically
- **No complex repo management**: APT uses simple text files
- **Simpler error handling**: APT provides clear error messages
- **No transaction rollback**: APT doesn't have built-in rollback
- **Transaction rollback**: Implemented two-phase rollback (remove new, downgrade upgraded)
## OSTree Integration