omnizip 0.4.7-x86_64-linux

data/docs/troubleshooting/index.adoc

@@ -0,0 +1,207 @@
+---
+title: Troubleshooting
+nav_order: 80
+---
+
+== Troubleshooting
+
+Common problems and solutions when using Omnizip.
+
+=== Common Issues
+
+==== "Algorithm not found" Error
+
+**Problem**: Compression fails with algorithm not found error.
+
+**Solution**: Check available algorithms:
+
+[source,bash]
+----
+omnizip list
+----
+
+[source,ruby]
+----
+Omnizip::AlgorithmRegistry.registered.each do |name|
+  puts name
+end
+----
+
+**Causes**:
+* Typo in algorithm name
+* Algorithm not registered
+
+==== "File not found" Error
+
+**Problem**: Cannot read input file.
+
+**Solution**: Verify file paths and permissions:
+
+[source,bash]
+----
+# Check file exists
+ls -la input.txt
+
+# Check permissions
+chmod +r input.txt
+----
+
+==== "Out of memory" Error
+
+**Problem**: Large file compression fails.
+
+**Solutions**:
+
+1. Use lower compression level:
+[source,bash]
+----
+omnizip compress large.txt output.lzma --level 1
+----
+
+2. Use faster algorithm:
+[source,bash]
+----
+omnizip compress large.txt output.zst --algorithm zstandard
+----
+
+3. Use chunked processing:
+[source,ruby]
+----
+Omnizip.compress_file_chunked('large.txt', 'output.lzma',
+  chunk_size: 10 * 1024 * 1024
+)
+----
+
+==== "Archive corrupted" Error
+
+**Problem**: Cannot extract archive.
+
+**Solutions**:
+
+1. Verify archive integrity:
+[source,bash]
+----
+omnizip archive list archive.7z
+----
+
+2. Try recovery mode:
+[source,ruby]
+----
+reader = Omnizip::Formats::SevenZip::Reader.new('archive.7z',
+  salvage_mode: true
+)
+reader.extract_all('output/')
+----
+
+3. Check CRC:
+[source,ruby]
+----
+if Omnizip::Checksums.verify_file('archive.7z', :crc32)
+  puts "Archive is valid"
+else
+  puts "Archive is corrupted"
+end
+----
+
+=== Performance Issues
+
+==== Slow Compression
+
+**Solutions**:
+
+1. Use lower compression level:
+[source,bash]
+----
+omnizip compress input.txt output.lzma --level 3
+----
+
+2. Use faster algorithm:
+[source,bash]
+----
+omnizip compress input.txt output.zst --algorithm zstandard
+----
+
+3. Run independent archives in parallel processes (see the
+link:../guides/advanced-features/parallel-processing.html[Parallel Processing guide]):
+[source,ruby]
+----
+dirs = %w[data_a data_b]
+pids = dirs.map do |dir|
+  Process.fork { Omnizip.compress_directory(dir, "#{dir}.7z") }
+end
+pids.each { |pid| Process.wait(pid) }
+----
+
+==== Slow Decompression
+
+**Solutions**:
+
+1. Use buffered reading:
+[source,ruby]
+----
+reader = Omnizip::Formats::SevenZip::Reader.new('archive.7z',
+  buffer_size: 1024 * 1024
+)
+reader.extract_all('output/')
+----
+
+2. Extract specific files only:
+[source,bash]
+----
+omnizip archive extract archive.7z output/ \
+  --pattern 'important.txt'
+----
+
+=== Format-Specific Issues
+
+==== 7z Issues
+
+**Problem**: 7z archive not compatible with 7-Zip.
+
+**Solution**: Ensure standard options:
+
+[source,ruby]
+----
+writer = Omnizip::Formats::SevenZip::Writer.new('archive.7z',
+  algorithm: :lzma2,
+  level: 5  # Standard level
+)
+----
+
+==== ZIP Issues
+
+**Problem**: ZIP not readable by other tools.
+
+**Solution**: Use Deflate algorithm:
+
+[source,bash]
+----
+omnizip archive create archive.zip files/ \
+  --algorithm deflate --level 5
+----
+
+==== RAR Issues
+
+**Problem**: RAR extraction fails.
+
+**Solution**: Verify RAR version:
+
+[source,ruby]
+----
+# One reader covers both RAR4 and RAR5 (version auto-detected)
+reader = Omnizip::Formats::Rar::Reader.new('archive.rar')
+----
+
+### Getting Help
+
+If you continue to have issues:
+
+1. Check link:../resources/faq[FAQ]
+2. Review link:../guides/[usage guides]
+3. Search link:https://github.com/metanorma/omnizip/issues[GitHub issues]
+4. Create a new issue with:
+   * Omnizip version
+   * Ruby version
+   * Operating system
+   * Error message
+   * Minimal reproduction code

data/docs/xar_format.md

@@ -0,0 +1,216 @@
+# XAR Format Implementation
+
+## Overview
+
+This document describes the XAR (eXtensible ARchive) format implementation in Omnizip. XAR is primarily used on macOS for software packages (.pkg files), OS installers, and software distribution.
+
+## Format Structure
+
+XAR archives have a simple structure:
+
+```
++-------------------+
+| Header (28 bytes) |  Magic, sizes, checksum type
++-------------------+
+| Compressed TOC    |  GZIP-compressed XML
++-------------------+
+| TOC Checksum      |  SHA1 (20 bytes) or MD5 (16 bytes)
++-------------------+
+| File Data Heap    |  Compressed file contents
++-------------------+
+```
+
+### Header Format (28 bytes)
+
+| Offset | Size | Field               | Description                         |
+|--------|------|---------------------|-------------------------------------|
+| 0      | 4    | magic               | 0x78617221 ("xar!" in big-endian)   |
+| 4      | 2    | header_size         | Header size (28)                    |
+| 6      | 2    | version             | Format version (1)                  |
+| 8      | 8    | toc_compressed_size | Size of compressed TOC              |
+| 16     | 8    | toc_uncompressed_size | Size of uncompressed TOC          |
+| 24     | 4    | checksum_algorithm  | Checksum type (0=none, 1=sha1, 2=md5) |
+
+### Extended Header Format (64 bytes)
+
+For custom checksums (sha256, sha384, sha512):
+
+| Offset | Size | Field               | Description                         |
+|--------|------|---------------------|-------------------------------------|
+| 0-27   | 28   | (standard header)   | Standard header fields              |
+| 28     | 36   | checksum_name       | Null-terminated checksum name       |
+
+## Table of Contents (TOC)
+
+The TOC is a GZIP-compressed XML document:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<xar>
+  <toc>
+    <creation-time>1609459200.0</creation-time>
+    <checksum style="sha1">
+      <offset>0</offset>
+      <size>20</size>
+    </checksum>
+    <file id="1">
+      <name>example.txt</name>
+      <type>file</type>
+      <mode>0644</mode>
+      <uid>1000</uid>
+      <gid>1000</gid>
+      <size>1234</size>
+      <data>
+        <offset>0</offset>
+        <size>567</size>
+        <length>1234</length>
+        <encoding style="application/x-gzip"/>
+        <archived-checksum style="sha1">abc123...</archived-checksum>
+        <extracted-checksum style="sha1">def456...</extracted-checksum>
+      </data>
+    </file>
+  </toc>
+</xar>
+```
+
+### File Types
+
+- `file` - Regular file
+- `directory` - Directory
+- `symlink` - Symbolic link
+- `hardlink` - Hard link
+- `fifo` - Named pipe
+- `block` - Block device
+- `character` - Character device
+- `socket` - Unix socket
+
+### Compression Types
+
+| MIME Type              | Compression |
+|------------------------|-------------|
+| application/octet-stream | None      |
+| application/x-gzip     | GZIP       |
+| application/x-bzip2    | BZIP2      |
+| application/x-lzma     | LZMA       |
+| application/x-xz       | XZ         |
+
+### Checksum Types
+
+| Algorithm | TOC Code | Size (bytes) |
+|-----------|----------|--------------|
+| none      | 0        | 0            |
+| sha1      | 1        | 20           |
+| md5       | 2        | 16           |
+| sha224    | 3        | 28           |
+| sha256    | 3        | 32           |
+| sha384    | 3        | 48           |
+| sha512    | 3        | 64           |
+
+## API Usage
+
+### Creating Archives
+
+```ruby
+require 'omnizip'
+
+# Create archive with default options (gzip, sha1)
+Omnizip::Formats::Xar.create('archive.xar') do |xar|
+  xar.add_file('document.pdf')
+  xar.add_directory('resources/')
+  xar.add_symlink('link_to_doc', 'document.pdf')
+  xar.add_data("content", "data/file.txt")
+end
+
+# Create with specific options
+Omnizip::Formats::Xar.create('archive.xar',
+  compression: 'bzip2',
+  toc_checksum: 'sha256',
+  file_checksum: 'sha256',
+  compression_level: 9
+) do |xar|
+  xar.add_tree('/path/to/directory')
+end
+```
+
+### Reading Archives
+
+```ruby
+# List entries
+entries = Omnizip::Formats::Xar.list('archive.xar')
+entries.each do |entry|
+  puts "#{entry.name} (#{entry.size} bytes)"
+  puts "  Type: #{entry.type}"
+  puts "  Mode: #{entry.mode}"
+end
+
+# Read specific file data
+Omnizip::Formats::Xar.open('archive.xar') do |xar|
+  entry = xar.get_entry('document.pdf')
+  data = xar.read_data(entry)
+  puts data.bytesize
+end
+```
+
+### Extracting Archives
+
+```ruby
+# Extract all files
+Omnizip::Formats::Xar.extract('archive.xar', 'output/')
+
+# Extract with block for progress
+Omnizip::Formats::Xar.open('archive.xar') do |xar|
+  xar.entries.each do |entry|
+    puts "Extracting #{entry.name}..."
+    xar.extract_entry(entry, 'output/')
+  end
+end
+```
+
+## Implementation Details
+
+### Classes
+
+- `Omnizip::Formats::Xar` - Main module with convenience methods
+- `Omnizip::Formats::Xar::Reader` - Archive reader
+- `Omnizip::Formats::Xar::Writer` - Archive writer
+- `Omnizip::Formats::Xar::Header` - Binary header handling
+- `Omnizip::Formats::Xar::Toc` - XML TOC parsing/generation
+- `Omnizip::Formats::Xar::Entry` - File entry model
+
+### Dependencies
+
+The implementation uses only Ruby standard library:
+
+- `zlib` - GZIP compression for TOC
+- `digest` - Checksums (MD5, SHA1, SHA256, etc.)
+- `rexml/document` - XML parsing
+
+For file compression, uses existing Omnizip algorithms:
+
+- `Omnizip::Algorithms::Bzip2` - BZIP2 compression
+- `Omnizip::Algorithms::Lzma` - LZMA compression
+- `Omnizip::Formats::Xz` - XZ compression
+
+## Compatibility
+
+### libarchive Compatibility
+
+The implementation is compatible with libarchive's XAR support:
+
+- All libarchive test fixtures parse correctly
+- Archives created can be extracted by libarchive
+- Supports all compression and checksum methods
+
+### macOS Compatibility
+
+XAR is the native archive format for:
+
+- macOS Installer packages (.pkg)
+- macOS Software Update
+- Xcode downloads
+
+## References
+
+- XAR format specification: https://mackyle.github.io/xar/
+- libarchive XAR implementation: `archive_read_support_format_xar.c`
+- XAR project: https://github.com/mackyle/xar

data/examples/api_comparison.rb

@@ -0,0 +1,205 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# API Comparison Demo
+# Shows both Rubyzip compatibility and native Omnizip APIs side-by-side
+#
+
+puts "=== Omnizip: Dual API Demonstration ==="
+puts "Showing both rubyzip-compatible and native APIs"
+puts
+
+require "tmpdir"
+tmpdir = Dir.mktmpdir("omnizip_comparison")
+
+# =============================================================================
+# Example 1: Creating an archive
+# =============================================================================
+puts "1. Creating a ZIP archive"
+puts "   #{'=' * 70}"
+
+zip1_path = File.join(tmpdir, "compat.zip")
+zip2_path = File.join(tmpdir, "native.zip")
+
+# Rubyzip-compatible approach
+puts "\n   A) Rubyzip-compatible API:"
+puts "   #{'-' * 70}"
+puts <<~CODE
+  require 'omnizip/rubyzip_compat'
+
+  Zip::File.open('archive.zip', create: true) do |zip|
+    zip.add('file.txt') { 'Content' }
+  end
+CODE
+
+require "omnizip/rubyzip_compat"
+Zip::File.open(zip1_path, create: true) do |zip|
+  zip.add("file.txt") { "Content from rubyzip API" }
+end
+puts "   ✓ Created: #{zip1_path}"
+
+# Native Omnizip approach
+puts "\n   B) Native Omnizip API:"
+puts "   #{'-' * 70}"
+puts <<~CODE
+  require 'omnizip'
+
+  Omnizip::Zip::File.create('archive.zip') do |zip|
+    zip.add('file.txt') { 'Content' }
+  end
+CODE
+
+require "omnizip"
+Omnizip::Zip::File.create(zip2_path) do |zip|
+  zip.add("file.txt") { "Content from native API" }
+end
+puts "   ✓ Created: #{zip2_path}"
+
+# =============================================================================
+# Example 2: Reading an archive
+# =============================================================================
+puts "\n\n2. Reading archive contents"
+puts "   #{'=' * 70}"
+
+# Rubyzip-compatible approach
+puts "\n   A) Rubyzip-compatible API:"
+puts "   #{'-' * 70}"
+puts <<~CODE
+  Zip::File.open('archive.zip') do |zip|
+    content = zip.read('file.txt')
+    puts content
+  end
+CODE
+
+content1 = Zip::File.open(zip1_path) { |zip| zip.read("file.txt") }
+puts "   ✓ Read: #{content1}"
+
+# Native Omnizip approach
+puts "\n   B) Native Omnizip API (convenience method):"
+puts "   #{'-' * 70}"
+puts <<~CODE
+  content = Omnizip.read_from_archive('archive.zip', 'file.txt')
+  puts content
+CODE
+
+content2 = Omnizip.read_from_archive(zip2_path, "file.txt")
+puts "   ✓ Read: #{content2}"
+
+# =============================================================================
+# Example 3: Working with directories
+# =============================================================================
+puts "\n\n3. Compressing a directory"
+puts "   #{'=' * 70}"
+
+# Create sample directory
+sample_dir = File.join(tmpdir, "sample")
+FileUtils.mkdir_p(File.join(sample_dir, "subdir"))
+File.write(File.join(sample_dir, "file1.txt"), "File 1")
+File.write(File.join(sample_dir, "file2.txt"), "File 2")
+File.write(File.join(sample_dir, "subdir", "file3.txt"), "File 3")
+
+zip3_path = File.join(tmpdir, "dir_compat.zip")
+zip4_path = File.join(tmpdir, "dir_native.zip")
+
+# Rubyzip-compatible approach
+puts "\n   A) Rubyzip-compatible API (manual iteration):"
+puts "   #{'-' * 70}"
+puts <<~CODE
+  Zip::File.open('backup.zip', create: true) do |zip|
+    Dir.glob('dir/**/*').each do |file|
+      next if File.directory?(file)
+      zip.add(file.sub('dir/', ''), file)
+    end
+  end
+CODE
+
+Zip::File.open(zip3_path, create: true) do |zip|
+  Dir.glob(File.join(sample_dir, "**/*")).each do |file|
+    rel_path = file.sub("#{sample_dir}/", "")
+    if File.directory?(file)
+      zip.add("#{rel_path}/")
+    else
+      zip.add(rel_path, file)
+    end
+  end
+end
+puts "   ✓ Created with #{Zip::File.open(zip3_path) do |z|
+  z.entries.size
+end} entries"
+
+# Native Omnizip approach
+puts "\n   B) Native Omnizip API (one-liner):"
+puts "   #{'-' * 70}"
+puts <<~CODE
+  Omnizip.compress_directory('dir/', 'backup.zip')
+CODE
+
+Omnizip.compress_directory(sample_dir, zip4_path)
+puts "   ✓ Created with #{Omnizip.list_archive(zip4_path).size} entries"
+
+# =============================================================================
+# Example 4: Both APIs work on same archive
+# =============================================================================
+puts "\n\n4. Both APIs can work on the same archive"
+puts "   #{'=' * 70}"
+
+shared_zip = File.join(tmpdir, "shared.zip")
+
+# Create with rubyzip API
+puts "\n   Creating with Rubyzip API..."
+Zip::File.create(shared_zip) do |zip|
+  zip.add("from_rubyzip.txt") { "Created with Zip::" }
+end
+
+# Modify with native API
+puts "   Modifying with Native API..."
+source = File.join(tmpdir, "from_native.txt")
+File.write(source, "Added with Omnizip")
+Omnizip.add_to_archive(shared_zip, "from_native.txt", source)
+
+# Read with both APIs
+puts "\n   Reading with both APIs:"
+Zip::File.open(shared_zip) do |zip|
+  puts "   - Rubyzip sees: #{zip.names.join(', ')}"
+end
+puts "   - Native sees: #{Omnizip.list_archive(shared_zip).join(', ')}"
+
+# =============================================================================
+# Summary
+# =============================================================================
+puts "\n\n#{'=' * 76}"
+puts "SUMMARY: Which API should you use?"
+puts "=" * 76
+puts <<~SUMMARY
+
+  ┌─ Rubyzip Compatibility API ────────────────────────────────────────┐
+  │                                                                     │
+  │  Use when:                                                          │
+  │  • Migrating from rubyzip                                           │
+  │  • Maintaining existing code                                        │
+  │  • Need drop-in compatibility                                       │
+  │                                                                     │
+  │  require 'omnizip/rubyzip_compat'                                   │
+  │  Zip::File.open('archive.zip') { ... }                              │
+  │                                                                     │
+  └─────────────────────────────────────────────────────────────────────┘
+
+  ┌─ Native Omnizip API ───────────────────────────────────────────────┐
+  │                                                                     │
+  │  Use when:                                                          │
+  │  • Starting new projects                                            │
+  │  • Want convenience methods                                         │
+  │  • Need cleaner, more Ruby-idiomatic code                           │
+  │                                                                     │
+  │  require 'omnizip'                                                  │
+  │  Omnizip.compress_file('file.txt', 'archive.zip')                   │
+  │                                                                     │
+  └─────────────────────────────────────────────────────────────────────┘
+
+  💡 Both APIs work seamlessly together - choose based on your needs!
+
+SUMMARY
+
+puts "All demo files created in: #{tmpdir}"
+puts