SWCompression

一个包含（解）压缩算法和各种存档和容器处理的框架。

这是什么？

SWCompression 是一个框架，包含一系列用于

使用不同算法进行解压缩（有时也进行压缩）的函数。
读取（有时也写入）不同格式的存档。
读取（有时也写入）如ZIP、TAR 和 7-Zip 这样的容器。

它还适用于 Apple 平台、Linux 以及 Windows。

以下表格列出了所有功能。 "待定"表示该功能计划中但尚未实现。

	Deflate	BZip2	LZMA/LZMA2	LZ4
解压缩	✅	✅	✅	✅
压缩	✅	✅	待定	✅

	Zlib	GZip	XZ	ZIP	TAR	7-Zip
读取	✅	✅	✅	✅	✅	✅
写入	✅	✅	待定	待定	✅	待定

此外，SWCompression 仅使用 Swift 编写。

安装

SWCompression 可以通过 Swift Package Manager、CocoaPods 或 Carthage 集成到您的项目中。

Swift 包管理器

要使用 SPM 安装，将 SWCompression 添加到包依赖项中，并将其指定为目标依赖项，例如：

import PackageDescription

let package = Package(
    name: "PackageName",
    dependencies: [
        .package(name: "SWCompression", url: "https://github.com/tsolomko/SWCompression.git",
                 from: "4.8.0")
    ],
    targets: [
        .target(
            name: "TargetName",
            dependencies: ["SWCompression"]
        )
    ]
)

更多详细信息，请参阅 Swift 包管理器文档。

CocoaPods

在 Podfile 中添加以下行：pod 'SWCompression', '~> 4.8' 和 use_frameworks!。

运行 pod install 以完成安装。

如果您只需要框架的部分功能，可以使用子 podspecs 只安装它们。可用的子 spec 如下：

SWCompression/BZip2
SWCompression/Deflate
SWCompression/Gzip
SWCompression/LZMA
SWCompression/LZMA2
SWCompression/LZ4
SWCompression/SevenZip
SWCompression/TAR
SWCompression/XZ
SWCompression/Zlib
SWCompression/ZIP

可选依赖项

对于 ZIP 和 7-Zip，最常用的压缩方法是 Deflate 和 LZMA/LZMA2。因此，SWCompression/ZIP 子 spec 以 SWCompression/Deflate 子 spec 为依赖项，SWCompression/LZMA 子 spec 是 SWCompression/SevenZip 的依赖项。

但它们也支持其他压缩方法，其中一些已在 SWCompression 中实现。对于 CocoaPods 配置，某些压缩方法有一定程度的“可选依赖项”。

在这个上下文中，“可选依赖项”意味着只有当您在 Podfile 中明确指定相应子 spec 并安装时，SWCompression/ZIP 或 SWCompression/7-Zip 才会支持某种压缩方法。

“可选依赖项”列表

对于 SWCompression/ZIP
- SWCompression/BZip2
- SWCompression/LZMA
对于 SWCompression/SevenZip
- SWCompression/BZip2
- SWCompression/Deflate
- SWCompression/LZ4

注意：如果使用 Swift Package Manager 或 Carthage，您将总是拥有所有功能（ZIP 和 7-Zip 都使用了 Deflate、BZip2、LZMA/LZMA2 和 LZ4 支持）。

Carthage

将以下内容添加到 Cartfile：github "tsolomko/SWCompression" ~> 4.8。

然后：

如果您使用 Xcode 12 或更高版本，您应该运行 carthage update --use-xcframeworks。之后，从 Carthage/Build/ 目录中将 SWCompression.xcframework 和 BitByteData.xcframework 文件拖放到 Xcode 目标 "General" 选项卡中的 "Frameworks, Libraries, and Embedded Content" 部分中。
如果您使用 Xcode 11 或更低版本，您应该运行 carthage update。之后，从 Carthage/Build/<platform>/ 目录中将 SWCompression.framework 和 BitByteData.framework 文件拖放到 Xcode 目标 "General" 选项卡中的 "Embedded Binaries" 部分中。

对于 Xcode 12 或更高版本，您目前还可以使用 xconfig workaround。

请注意，非-xcframework 安装 SWCompression 我们可能会在未来主要更新中删除对它的支持。

用法

基本示例

例如，如果您想解压缩 "deflated" 数据，请使用

// let data = <Your compressed data>
let decompressedData = try? Deflate.decompress(data: data)

然而，您不太可能在任何存档之外遇到压缩数据。因此，在 GZip 存档的情况下，您应该使用

let decompressedData = try? GzipArchive.unarchive(archive: data)

错误处理

大多数 SWCompression 函数可能会抛出错误，并且您需要处理这些错误。如果您查看可用的错误类型和它们的情况，您可能会因为它们数量众多而感到害怕。然而，大多数情况（例如 XZError.wrongMagic）都存在于诊断目的。

因此，您只需要处理您存档/算法中最常见的错误类型。例如

do {
    // let data = <Your compressed data>
    let decompressedData = try XZArchive.unarchive(archive: data)
} catch let error as XZError {
    // <handle XZ related error here>
} catch let error {
    // <handle all other errors here>
}

文档

SWCompression 公共 API 的每个函数或类型都有文档。可以在其自己的网站或者通过一个稍微简短的链接找到这些文档：swcompression.tsolomko.me

复杂示例

该仓库中包含一个小型命令行程序“swcomp”，位于“Sources/swcomp”目录下。它可以使用Swift包管理器进行构建。

重要提示：“swcomp”命令行工具**不**适用于一般用途。

贡献

无论您发现了一个错误、有建议、想法、反馈或其它，请在GitHub上创建一个问题。如果您有任何疑问，可以在讨论页面提问。

如果您在错误情况下，附加导致错误发生的文件（存档等）将特别有帮助。

如果您想贡献力量，请在GitHub上创建一个拉取请求。

注意：如果您考虑为SWCompression工作，请注意Xcode项目（SWCompression.xcodeproj）是手动创建的，您不应该使用swift package generate-xcodeproj命令。

在本地点击测试

如果您想在计算机上运行测试，需要在克隆仓库后执行一些额外的步骤

./utils.py download-bbd-macos
git submodule update --init --recursive
cd "Tests/Test Files"
cp gitattributes-copy .gitattributes
git lfs pull
git lfs checkout

第一条命令将下载BitByteData依赖项，这需要已安装Carthage。在使用Xcode 12或更高版本时，还应该传递--xcf选项，或使用xconfig绕过。请注意，在构建SWCompression的Xcode项目时，您可能会看到ld警告关于未找到目录的警告。这些是预期的并且无害的。最后，请记住，非-xcframework方法安装依赖项的支持可能会在未来主要更新中被删除。

其余的命令将下载测试中使用的文件。这些文件存储在一个独立的仓库中，使用Git LFS。这种复杂设置有两个原因。首先，其中一些文件可能相当大，如果SWCompression的用户在安装时必须下载它们，那就太不幸了。其次，Swift包管理器和当代版本的Xcode并不总是与git-lfs启用的仓库很好地工作。为了防止任何潜在的问题，测试文件被移到了另一个仓库。

请注意，如果您想添加新的测试文件类型，除了运行git lfs track之外，还必须将这条命令添加到“Tests/Test Files/.gitattributes”文件中的内容复制到“Tests/Test Files/gitattributes-copy”文件中。请不要将“.gitattributes”文件提交到git历史记录中。出于某种原因，它被git忽略！

另外，请留意GitHub上Git LFS的带宽配额：尝试通过git lfs pull限制下载lfs文件。在CI中，我们使用一些缓存技术来帮助配额，因此如果您要添加需要几个新测试文件的新测试，您应该尝试一起提交它们，以减少CI重建缓存（重建缓存需要对所有测试文件运行git lfs pull）的次数。

性能

推荐使用整个模块优化以获得最佳性能。在发布构建配置中默认启用它们。

测试结果文档包含各种功能的基准测试结果。

为什么？

首先，现有处理压缩、归档和容器的工作方案存在某些缺点。它们可能不支持特定的压缩算法或归档格式，它们都有不同的API，有时这会让用户感到有些困惑，尤其是在一个项目中混合不同的库时。本项目通过提供易于使用和记忆的统一API尝试提供缺少（有时存在）的功能。

其次，在某些情况下，可能有必要拥有一个完全用Swift编写的压缩框架，不依赖于系统库或用其他语言实现的解决方案。此外，由于SWCompression完全是用Swift编写的，不包含Objective-C，它还可以用于Linux和Windows。

SWCompression 版本4.8.6

SWCompression 版本4.8.6

SWCompression 版本4.8.6

SWCompression

这是什么？

安装

Swift 包管理器

CocoaPods

可选依赖项

Carthage

用法

基本示例

错误处理

文档

复杂示例

贡献

在本地点击测试

性能

为什么？

未来计划

许可证

参考资料