Fix YAML linting issues and update system requirements to Debian 13+
- Fix trailing spaces and blank lines in Forgejo workflows - Update system requirements from Ubuntu Jammy/Bookworm to Debian 13+ (Trixie) - Update test treefile to use Debian Trixie instead of Ubuntu Jammy - Update documentation to reflect modern system requirements - Fix yamllint errors for CI/CD functionality - Ensure compatibility with modern OSTree and libapt versions
This commit is contained in:
parent
ec0da91864
commit
3dec23f8f7
85 changed files with 12569 additions and 1088 deletions
224
docs/apt-ostree-daemon-plan/development-commands-analysis.md
Normal file
224
docs/apt-ostree-daemon-plan/development-commands-analysis.md
Normal file
|
|
@ -0,0 +1,224 @@
|
|||
# Development Commands Analysis: rpm-ostree Integration
|
||||
|
||||
## Overview
|
||||
|
||||
This document analyzes the missing development and debugging commands from rpm-ostree that should be integrated into apt-ostree. These commands are marked with `RPM_OSTREE_BUILTIN_FLAG_HIDDEN` and are essential for development, testing, and debugging purposes.
|
||||
|
||||
## Commands Analysis
|
||||
|
||||
### 1. testutils Command
|
||||
|
||||
**Purpose**: Development debugging tool for testing and development workflows.
|
||||
|
||||
**Flags**: `RPM_OSTREE_BUILTIN_FLAG_LOCAL_CMD | RPM_OSTREE_BUILTIN_FLAG_HIDDEN`
|
||||
|
||||
**Subcommands**:
|
||||
- `inject-pkglist` - Inject package list metadata into OSTree commits
|
||||
- `script-shell` - Run scripts in bubblewrap containers
|
||||
- `generate-synthetic-upgrade` - Generate synthetic OS updates by modifying ELF files
|
||||
- `integration-read-only` - Run integration tests on booted machine
|
||||
- `c-units` - Run C unit tests
|
||||
- `moo` - Test command for development verification
|
||||
|
||||
**Implementation Details**:
|
||||
|
||||
#### C++ Side (rpmostree-builtin-testutils.cxx)
|
||||
```cpp
|
||||
// inject-pkglist: Creates new commit with pkglist metadata
|
||||
// - Reads existing commit
|
||||
// - Creates RPM database package list
|
||||
// - Writes new commit with pkglist metadata
|
||||
// - Updates ref to point to new commit
|
||||
|
||||
// script-shell: Runs scripts in isolated containers
|
||||
// - Uses bubblewrap for containerization
|
||||
// - Mounts root filesystem
|
||||
// - Executes test scripts safely
|
||||
```
|
||||
|
||||
#### Rust Side (testutils.rs)
|
||||
```rust
|
||||
// generate-synthetic-upgrade: Modifies ELF binaries
|
||||
// - Finds ELF files in system directories
|
||||
// - Mutates specified percentage of binaries
|
||||
// - Creates new OSTree commit with modified files
|
||||
// - Useful for testing upgrade paths
|
||||
|
||||
// integration-read-only: Validates system state
|
||||
// - Tests status JSON parsing
|
||||
// - Validates package variants
|
||||
// - Ensures client bindings work correctly
|
||||
```
|
||||
|
||||
**Integration Plan for apt-ostree**:
|
||||
1. Create `src/commands/testutils.rs` module
|
||||
2. Implement all subcommands with APT equivalents
|
||||
3. Add to CLI with hidden flag
|
||||
4. Integrate with existing command structure
|
||||
|
||||
### 2. shlib-backend Command
|
||||
|
||||
**Purpose**: Shared library backend for IPC operations and package management.
|
||||
|
||||
**Flags**: `RPM_OSTREE_BUILTIN_FLAG_LOCAL_CMD | RPM_OSTREE_BUILTIN_FLAG_HIDDEN`
|
||||
|
||||
**Subcommands**:
|
||||
- `get-basearch` - Get base architecture
|
||||
- `varsubst-basearch` - Variable substitution for architecture
|
||||
- `packagelist-from-commit` - Extract package list from OSTree commit
|
||||
|
||||
**Implementation Details**:
|
||||
```cpp
|
||||
// IPC-based communication using Unix domain sockets
|
||||
// - Creates sealed memfd for data transfer
|
||||
// - Uses DNF context for package operations
|
||||
// - Integrates with OSTree repository operations
|
||||
// - Handles package list extraction and formatting
|
||||
```
|
||||
|
||||
**Integration Plan for apt-ostree**:
|
||||
1. Create `src/commands/shlib_backend.rs` module
|
||||
2. Replace DNF with APT equivalents
|
||||
3. Implement IPC communication layer
|
||||
4. Add architecture detection and variable substitution
|
||||
5. Integrate with OSTree operations
|
||||
|
||||
### 3. internals Command
|
||||
|
||||
**Purpose**: Internal system commands for advanced operations.
|
||||
|
||||
**Status**: Referenced in header file but implementation not found in current rpm-ostree source.
|
||||
|
||||
**Flags**: Not specified (likely `RPM_OSTREE_BUILTIN_FLAG_LOCAL_CMD`)
|
||||
|
||||
**Integration Plan for apt-ostree**:
|
||||
1. Research if this command exists in newer rpm-ostree versions
|
||||
2. If not implemented, consider what internal operations would be useful
|
||||
3. Implement as placeholder for future development
|
||||
4. Add to CLI with appropriate flags
|
||||
|
||||
## Implementation Strategy
|
||||
|
||||
### Phase 1: Core Infrastructure
|
||||
1. **Command Structure**: Add hidden command support to CLI
|
||||
2. **Flag System**: Implement `APT_OSTREE_BUILTIN_FLAG_HIDDEN` equivalent
|
||||
3. **Module Organization**: Create development commands module
|
||||
|
||||
### Phase 2: testutils Implementation
|
||||
1. **inject-pkglist**: APT package list injection
|
||||
2. **script-shell**: Bubblewrap container execution
|
||||
3. **synthetic-upgrade**: ELF binary modification for testing
|
||||
4. **integration-tests**: System validation and testing
|
||||
|
||||
### Phase 3: shlib-backend Implementation
|
||||
1. **IPC Layer**: Unix domain socket communication
|
||||
2. **Package Operations**: APT-based package management
|
||||
3. **Architecture Detection**: Debian architecture handling
|
||||
4. **Variable Substitution**: APT-specific variable handling
|
||||
|
||||
### Phase 4: Integration and Testing
|
||||
1. **Command Registration**: Add to main command dispatch
|
||||
2. **Hidden Flag Support**: Implement in CLI help system
|
||||
3. **Testing Framework**: Integration with existing test suite
|
||||
4. **Documentation**: Developer and testing guides
|
||||
|
||||
## Technical Considerations
|
||||
|
||||
### APT vs DNF Differences
|
||||
- **Package Format**: DEB vs RPM
|
||||
- **Database Structure**: APT cache vs DNF sack
|
||||
- **Architecture Names**: Debian vs Red Hat conventions
|
||||
- **Variable Substitution**: APT-specific variables
|
||||
|
||||
### OSTree Integration
|
||||
- **Package Metadata**: APT package list format
|
||||
- **Commit Structure**: OSTree commit metadata
|
||||
- **Repository Operations**: OSTree repo integration
|
||||
- **Deployment Management**: System deployment handling
|
||||
|
||||
### Security and Isolation
|
||||
- **Bubblewrap**: Container execution for scripts
|
||||
- **File Descriptors**: Secure IPC communication
|
||||
- **Permission Handling**: Root and user operations
|
||||
- **Resource Limits**: Memory and process constraints
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
src/commands/
|
||||
├── testutils.rs # Development testing utilities
|
||||
├── shlib_backend.rs # Shared library backend
|
||||
└── internals.rs # Internal system commands (future)
|
||||
|
||||
src/cli.rs # Add hidden command support
|
||||
src/commands/mod.rs # Register development commands
|
||||
```
|
||||
|
||||
## CLI Integration
|
||||
|
||||
### Hidden Command Support
|
||||
```rust
|
||||
#[derive(Subcommand)]
|
||||
pub enum Commands {
|
||||
// ... existing commands ...
|
||||
|
||||
/// Development and debugging tools (hidden)
|
||||
#[command(hide = true)]
|
||||
Testutils(TestutilsArgs),
|
||||
|
||||
/// Shared library backend (hidden)
|
||||
#[command(hide = true)]
|
||||
ShlibBackend(ShlibBackendArgs),
|
||||
|
||||
/// Internal system commands (hidden)
|
||||
#[command(hide = true)]
|
||||
Internals(InternalsArgs),
|
||||
}
|
||||
```
|
||||
|
||||
### Flag System
|
||||
```rust
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub struct CommandFlags {
|
||||
pub local_cmd: bool,
|
||||
pub hidden: bool,
|
||||
pub requires_root: bool,
|
||||
pub container_capable: bool,
|
||||
pub supports_pkg_installs: bool,
|
||||
}
|
||||
```
|
||||
|
||||
## Benefits of Integration
|
||||
|
||||
### Development Workflow
|
||||
1. **Testing**: Automated testing and validation
|
||||
2. **Debugging**: Package list inspection and modification
|
||||
3. **Integration**: System state validation
|
||||
4. **Scripting**: Safe script execution in containers
|
||||
|
||||
### Quality Assurance
|
||||
1. **Package Management**: Validate APT integration
|
||||
2. **OSTree Operations**: Test commit and deployment logic
|
||||
3. **System Integration**: Verify daemon and client communication
|
||||
4. **Error Handling**: Test edge cases and failure modes
|
||||
|
||||
### Maintenance and Support
|
||||
1. **Troubleshooting**: Debug package and deployment issues
|
||||
2. **Development**: Rapid iteration and testing
|
||||
3. **Documentation**: Generate system state reports
|
||||
4. **Validation**: Ensure system consistency
|
||||
|
||||
## Conclusion
|
||||
|
||||
Integrating these development commands from rpm-ostree into apt-ostree will provide essential tools for development, testing, and debugging. The commands are designed to be hidden from normal users while providing powerful capabilities for developers and system administrators.
|
||||
|
||||
The implementation should maintain the same logical structure and behavior as rpm-ostree while adapting to APT-specific package management and Debian system conventions. This will ensure that apt-ostree provides the same level of development support as the original rpm-ostree implementation.
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Research**: Verify current rpm-ostree implementation status
|
||||
2. **Design**: Create detailed implementation specifications
|
||||
3. **Implementation**: Develop commands with proper testing
|
||||
4. **Integration**: Add to CLI and command dispatch system
|
||||
5. **Testing**: Validate functionality and performance
|
||||
6. **Documentation**: Create developer and testing guides
|
||||
Loading…
Add table
Add a link
Reference in a new issue