From ac4987c7d113fcdbe3ae36898525d68b4e31fd2b Mon Sep 17 00:00:00 2001 From: robojerk Date: Sat, 13 Sep 2025 11:24:37 -0700 Subject: [PATCH] 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 --- README.md | 80 ++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 67 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 30d9db5..5b72c8e 100644 --- a/README.md +++ b/README.md @@ -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> { ```rust pub struct AptTransaction { packages: Vec, + newly_installed: HashSet, // packages that weren't installed before + upgraded: HashMap, // package -> old_version for upgrades + config: AptConfig, // APT configuration options } impl AptTransaction { - pub fn new() -> Result; // Create new transaction + pub fn new() -> Result; // Create new transaction (default config) + pub fn with_config(config: AptConfig) -> Result; // Create with custom config + pub fn for_testing() -> Result; // 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; // 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; // 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; // Check install pub fn get_package_info(name: &str) -> Result; // 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> { 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