Overview

Relevant source files

• .config/dotnet-tools.json
• Directory.Build.props
• Directory.Packages.props
• README.md
• build/build.csproj
• build/packages.lock.json
• global.json
• src/SharpCompress/Common/Tar/Headers/EntryType.cs
• src/SharpCompress/Common/Zip/WinzipAesEncryptionData.cs
• src/SharpCompress/SharpCompress.csproj
• src/SharpCompress/packages.lock.json
• tests/SharpCompress.Performance/SharpCompress.Performance.csproj
• tests/SharpCompress.Performance/packages.lock.json
• tests/SharpCompress.Test/SharpCompress.Test.csproj
• tests/SharpCompress.Test/packages.lock.json

Purpose and Scope

This document provides a high-level introduction to GrindCore.SharpCompress, explaining its purpose, architecture, capabilities, and key differentiators from the original SharpCompress library. This overview covers the project's structure, supported formats and frameworks, and the native compression integration that provides significant performance improvements.

For detailed information about specific subsystems:

• Archive format implementations and their capabilities: see Archive Format Support
• Reading archives using factories and abstractions: see Reading Archives
• Creating archives using writers: see Writing Archives
• Native compression stream implementations: see Compression Algorithms
• Build system and conditional compilation: see Architecture and Build System

What is GrindCore.SharpCompress?

GrindCore.SharpCompress is an enhanced fork of the SharpCompress library that integrates GrindCore native compression technology to provide substantial performance improvements while maintaining 100% API compatibility with the original library. The project serves as a drop-in replacement for SharpCompress, requiring no code changes for existing applications.

Sources: README.md1-8 src/SharpCompress/SharpCompress.csproj1-20

Key Differentiators

Aspect	Original SharpCompress	GrindCore.SharpCompress
Compression Implementation	Pure managed C#	Native C via GrindCore + managed C#
Performance	Standard managed performance	3-5x faster for major algorithms
Deflate/GZip	Managed implementation	Native ZLib-NG v2.2.1
LZMA/LZMA2	Managed implementation	Native LZMA v25.1.0
ZStandard	Managed implementation	Native ZStandard v1.5.7
LZ4	Not available	Native LZ4 v1.10.0
Brotli	Not available	Native Brotli v1.1.0
AOT Compatibility	Limited	Full support for .NET 8+
API Compatibility	N/A	100% compatible

Sources: README.md25-32 README.md108-125

Native Integration Philosophy

GrindCore.SharpCompress uses the System.IO.Compression pattern to provide native compression streams that integrate seamlessly with .NET's standard stream abstractions. This approach:

• Compiles compression algorithms directly from their original C implementations
• Eliminates external dependencies (no separate DLLs required)
• Provides platform-specific optimizations (SIMD, AVX2, SSE4)
• Maintains familiar .NET Stream-based APIs

Sources: README.md15-24

Architecture Overview

Diagram: System Architecture with Code Entities

This diagram shows the major components and their relationships, using actual class names from the codebase. The system is organized in layers:

1. Public API Layer: Entry points for client applications
2. Core Abstractions: Base classes providing common functionality
3. Format Implementations: Concrete implementations for specific archive formats
4. Stream Infrastructure: Support for buffering, format detection, and non-seekable streams
5. Compression Layer: Native and managed compression implementations
6. Native Integration: Optional GrindCore package dependency

Sources: README.md132-171 src/SharpCompress/SharpCompress.csproj1-137

Supported Archive Formats

The library provides comprehensive support for multiple archive formats with varying capabilities:

Format	Read	Write	Native Performance	Encryption Support	Special Features
ZIP	✅	✅	✅ (Deflate)	PKWARE, WinZip AES	Zip64, modifications
TAR	✅	✅	✅ (with compression)	N/A	POSIX/GNU/BSD headers
GZIP	✅	✅	✅	N/A	Single-entry format
RAR	✅	❌	N/A	RAR encryption	Solid archives, multi-volume
7-Zip	✅	❌	N/A	AES-256	Solid archives, BCJ filters
LZMA/XZ	✅	✅	✅	N/A	Block and Solid modes
ZSTD	✅	✅	✅	N/A	22 compression levels
LZ4	✅	✅	✅	N/A	12 compression levels
BROTLI	✅	✅	✅	N/A	11 compression levels
BZIP2	✅	✅	❌ (managed)	N/A	Original C# implementation

Note: RAR and 7-Zip are read-only due to proprietary format restrictions. Legacy formats like Shrink, Implode, Reduce, PPMd, and ARJ are also supported for reading.

Sources: README.md58-78

Target Frameworks and Platform Support

Diagram: Framework and Platform Targeting Strategy

The project targets 8 different frameworks from a single codebase using conditional compilation:

• Modern .NET (6, 8, 9, 10): Full feature support including AOT compilation and trimming for .NET 8+
• Legacy Frameworks (Standard 2.0/2.1, Framework 4.8/4.8.1): Requires polyfill packages for modern APIs

Platform-specific native binaries are automatically selected at runtime based on the operating system and architecture.

Sources: src/SharpCompress/SharpCompress.csproj11 src/SharpCompress/SharpCompress.csproj31-37 README.md180-188

Conditional Compilation Strategy

The build system uses two key preprocessor symbols:

• GRINDCORE: Defined when UseGrindCore MSBuild property is true (default). Includes native compression stream wrappers and excludes managed implementations.
• LEGACY_DOTNET: Defined for .NET Framework 4.8/4.8.1 and .NET Standard 2.0. Enables compatibility code and polyfills.

Sources: src/SharpCompress/SharpCompress.csproj38-45 src/SharpCompress/SharpCompress.csproj31-33

GrindCore Native Integration

The native integration is the library's primary differentiator, implemented through conditional compilation:

Diagram: Native Integration Compilation Flow

When UseGrindCore=true (the default):

1. The GRINDCORE preprocessor symbol is defined
2. Native stream wrapper files (*_GC.cs) are included in compilation
3. Managed implementation files are excluded from compilation
4. The GrindCore NuGet package (v0.7.0) is referenced
5. At runtime, wrappers delegate to platform-specific native libraries

When UseGrindCore=false:

1. The GRINDCORE symbol is not defined
2. Managed C# implementations are used instead
3. No native library dependency

Sources: src/SharpCompress/SharpCompress.csproj38-76 src/SharpCompress/SharpCompress.csproj78-128 src/SharpCompress/SharpCompress.csproj130-133

Package Dependencies

The dependency graph varies by target framework and build configuration:

Dependency	Condition	Purpose
GrindCore (0.7.0)	When UseGrindCore=true	Native compression implementations
Microsoft.Bcl.AsyncInterfaces (10.0.3)	Legacy frameworks	Async interface polyfills
System.Text.Encoding.CodePages (10.0.3)	Legacy frameworks	Character encoding support
System.Buffers (4.6.1)	Legacy frameworks	Span and Memory support
System.Memory (4.6.3)	Legacy frameworks	Modern memory APIs
Microsoft.NET.ILLink.Tasks (10.0.3)	.NET 8+	Trimming and AOT support

Sources: src/SharpCompress/packages.lock.json1-627 Directory.Packages.props1-28

Key System Components

The library is organized into several major subsystems, each documented in detail in separate wiki pages:

Public API Layer

• ArchiveFactory: Static factory methods for opening archives with random access (Archive Format Support)
• ReaderFactory: Static factory methods for sequential streaming reads (Reading Archives)
• WriterFactory: Static factory methods for creating new archives (Writing Archives)

Format Implementations

• ZIP: ZipArchive, ZipReader, ZipWriter - Full read/write support with encryption (ZIP Format)
• RAR: RarArchive, RarReader - Read-only with solid archive support (RAR Format)
• 7-Zip: SevenZipArchive - Read-only with LZMA2 and filters (7-Zip Format)
• TAR: TarArchive, TarReader, TarWriter - POSIX/GNU/BSD header support (TAR Format)
• Single-file: GZipArchive, BZip2Archive, LZipArchive, XZArchive (GZip and Single-File Formats)

Stream Infrastructure

• SharpCompressStream: Intelligent buffering with passthrough/buffered modes (Stream Infrastructure)
• RingBuffer: Circular buffer enabling limited backward seeking on non-seekable streams
• ReadOnlySubStream: Enforces entry boundaries during extraction

Compression Layer

• Native Streams (when GRINDCORE defined): DeflateStream_GC, GZipStream_GC, LzmaStream_GC, ZStandardStream_GC, LZ4Stream_GC, BrotliStream_GC (Native Compression Streams)
• Managed Streams: BZip2Stream, LZipStream, PPMdStream, legacy algorithms (Managed Compression Implementations)

Sources: src/SharpCompress/SharpCompress.csproj60-76 src/SharpCompress/SharpCompress.csproj78-128

Development and Build System

The project uses a custom build system defined in build/Program.cs with targets for:

• Building across all target frameworks
• Running tests
• Creating NuGet packages
• Generating benchmarks

The build process is automated via GitHub Actions for continuous integration.

For detailed information about the build pipeline, code formatting standards, and development workflow, see Build Pipeline and Automation.

Sources: build/build.csproj1-12

Exception Hierarchy

All library-specific exceptions inherit from SharpCompressException, enabling unified error handling:

Diagram: Exception Hierarchy

This design allows client code to catch all library exceptions with a single catch (SharpCompressException) block while still enabling specific exception handling when needed.

Sources: tests/SharpCompress.Test/ExceptionHierarchyTests.cs10-116

Project Metadata

Property	Value
Package ID	GrindCore.SharpCompress
Assembly Name	GrindCore.SharpCompress.dll
Authors	Adam Hathcock (original), Nanook (GrindCore integration)
License	MIT
Repository	https://github.com/Nanook/GrindCore.SharpCompress
Strong Named	Yes (signed with SharpCompress.snk)
NuGet Command	Install-Package GrindCore.SharpCompress

Sources: src/SharpCompress/SharpCompress.csproj3-19 README.md99-106