SwiftPM 的 swift package archive-source 命令：为 Swift Package 生成源码归档的完整指南

SwiftPM 的 swift package archive-source 命令为 Swift Package 生成源码归档的完整指南【免费下载链接】swift-package-managerThe Package Manager for the Swift Programming Language项目地址: https://gitcode.com/gh_mirrors/sw/swift-package-managerswift package archive-source是 Swift Package ManagerSwiftPM内置的一个子命令用于为当前 Swift Package 创建一份干净的源码归档source archive。它面向发布、分发、归档场景可把整个包目录打包成单一的.zip文件。本文将基于 PackageArchiveSource.md 命令参考文档结合 SwiftPM 仓库中该命令的源码实现ArchiveSource.swift与测试用例PackageCommandTests.swift完整讲解其全部参数、默认行为与底层实现原理帮助你将其可靠地接入发布流程。一、命令作用与适用场景该命令在swift package下注册抽象描述是 Create a source archive for the package.为包创建源码归档。它位于 SwiftPM 的 Archiving packages 命令组中与swift package compute-checksum计算归档文件校验和配套使用。从 SwiftPackageCommand.swift 的子命令注册列表可以看到ArchiveSource.self是SwiftPackageCommand的官方子命令之一。典型适用场景包括发布前归档将包以 git 仓库中已提交HEAD的状态打包保证归档内容可复现构建产物之外的分发向依赖方提供不含.build、临时文件等噪音的纯净源码配合注册表/归档校验归档后用swift package compute-checksum计算 SHA-256 校验和便于发布到 Swift Package Registry 等场景。二、核心用法与--output参数在包目录下直接执行swift package archive-source即可在当前目录生成归档。真正驱动输出行为的是--output选项其帮助文本为 The absolute or relative path for the generated source archive.生成的源码归档的绝对或相对路径。从源码 ArchiveSource.swift 可以看到归档路径的确定逻辑显式指定若传入--output则直接使用该路径作为归档输出位置未指定时SwiftPM 会先loadPackageGraph()加载包图取出根包的manifest.displayName作为包名然后在包目录下生成包名.zip输出提示命令执行成功后若归档位于包目录内会打印相对路径如Created Bar.zip否则打印绝对路径。因此一个常用的版本化发布命令形如swift package archive-source --output Bar-1.2.3.zip归档同样支持绝对路径输出到包目录之外例如swift package archive-source --output /path/to/dist/Bar-1.2.3.zip三、底层实现两种归档路径命令的核心实现是 ArchiveSource.swift 中的archiveSource(at:to:fileSystem:cancellator:)方法它根据包目录是否为合法 Git 仓库选择两种不同的归档策略策略一包目录是 Git 仓库推荐使用GitRepositoryProvider判断目录是否为合法 Git 仓库若是则调用GitRepository.archive(to:)。该方法的实现位于 GitRepository.swift底层等价于执行git archive --format zip --prefix 包名/ --output 归档路径 HEAD关键行为包括归档内容是HEAD 提交中的文件而非工作区所有文件从而天然排除.build、.swiftpm、未跟踪文件等噪音--prefix会在归档内加一层以包名命名的顶层目录解压后文件位于包名/下避免污染解压目录未跟踪或已修改未提交的内容不会进入归档这保证了归档内容与已提交状态一致。策略二目录不是 Git 仓库此时回退到UniversalArchiver调用archiver.compress(directory:to:)直接压缩整个包目录。注意此时归档包含目录下的全部文件因此建议在压缩前自行清理临时产物。四、完整命令语法官方参考文档 PackageArchiveSource.md 给出了完整的命令语法swift package archive-source [--package-pathpackage-path] [--cache-pathcache-path] [--config-pathconfig-path] [--security-pathsecurity-path] [--scratch-pathscratch-path] [--swift-sdks-pathswift-sdks-path] [--toolsettoolset...] [--pkg-config-pathpkg-config-path...] [--enable-dependency-cache] [--disable-dependency-cache] [--enable-build-manifest-caching] [--disable-build-manifest-caching] [--manifest-cachemanifest-cache] [--enable-experimental-prebuilts] [--disable-experimental-prebuilts] [--verbose] [--very-verbose|vv] [--quiet] [--color-diagnostics] [--no-color-diagnostics] [--disable-sandbox] [--netrc] [--enable-netrc] [--disable-netrc] [--netrc-filenetrc-file] [--enable-keychain] [--disable-keychain] [--resolver-fingerprint-checkingresolver-fingerprint-checking] [--resolver-signing-entity-checkingresolver-signing-entity-checking] [--enable-signature-validation] [--disable-signature-validation] [--enable-prefetching] [--disable-prefetching] [--force-resolved-versions|disable-automatic-resolution|only-use-versions-from-resolved-file] [--skip-update] [--disable-scm-to-registry-transformation] [--use-registry-identity-for-scm] [--replace-scm-with-registry] [--default-registry-urldefault-registry-url] [--configurationconfiguration] [--Xcc...] [--Xswiftc...] [--Xlinker...] [--Xcxx...] [--tripletriple] [--sdksdk] [--toolchaintoolchain] [--swift-sdkswift-sdk] [--sanitizesanitize...] [--auto-index-store] [--enable-index-store] [--disable-index-store] [--enable-parseable-module-interfaces] [--jobsjobs] [--use-integrated-swift-driver] [--explicit-target-dependency-import-checkexplicit-target-dependency-import-check] [--build-systembuild-system] [--debug-info-format] [--enable-dead-strip] [--disable-dead-strip] [--disable-local-rpath] [--outputoutput] [--version] [--help]五、参数详解archive-source继承了SwiftPackageCommand的全局选项组OptionGroup(visibility: .hidden) var globalOptions: GlobalOptions因此上面这些参数绝大多数属于 SwiftPM 的全局/通用选项。下面按功能分组逐一说明。5.1 路径与环境类参数参数说明--package-pathpackage-path指定要操作的包路径默认当前目录。该选项会在任何其他操作之前切换工作目录。--cache-pathcache-path指定共享缓存目录路径。--config-pathconfig-path指定共享配置目录路径。--security-pathsecurity-path指定共享安全security目录路径。--scratch-pathscratch-path指定自定义 scratch 目录路径默认.build。--swift-sdks-pathswift-sdks-path已安装 Swift SDK 所在目录的路径。--toolsettoolset指定面向目标平台构建时使用的 toolset JSON 文件。可多次使用以指定多个 toolset它们会按指定顺序合并为一个最终的 toolset 用于当前构建。--pkg-config-pathpkg-config-path指定搜索 pkg-config.pc文件的备选路径可多次使用以指定多个路径。--outputoutput生成的源码归档的绝对或相对路径见上文核心用法。5.2 依赖缓存与解析类参数参数说明--enable-dependency-cache/--disable-dependency-cache是否在拉取依赖时使用共享缓存。--enable-build-manifest-caching/--disable-build-manifest-caching是否启用构建清单build manifest缓存。--manifest-cachemanifest-cachePackage.swift 清单的缓存模式合法值shared共享缓存、local包的构建目录、none禁用。--enable-experimental-prebuilts/--disable-experimental-prebuilts是否对宏macros使用预构建的 swift-syntax 库。--enable-prefetching/--disable-prefetching是否启用依赖预取prefetching。--force-resolved-versions/--disable-automatic-resolution/--only-use-versions-from-resolved-file只使用 Package.resolved 文件中的版本若该文件过期则解析失败。--skip-update解析过程中跳过从远端更新依赖。--resolver-fingerprint-checkingresolver-fingerprint-checking配置解析器对依赖指纹fingerprint的检查策略。--resolver-signing-entity-checkingresolver-signing-entity-checking配置解析器对依赖签名实体的检查策略。5.3 注册表Registry与凭证类参数参数说明--disable-scm-to-registry-transformation禁用源码控制SCM到注册表的转换。--use-registry-identity-for-scm在注册表中查找源码控制依赖并在可能时使用其注册表身份以帮助在两种来源之间去重。--replace-scm-with-registry在注册表中查找源码控制依赖并在可能时用注册表而非源码控制来获取它们。--default-registry-urldefault-registry-url默认注册表 URL替代registries.json配置文件。--enable-signature-validation/--disable-signature-validation是否验证从注册表下载的已签名包发布release的签名。--netrc即使有其他更优先的凭证存储也使用 netrc 文件。--enable-netrc/--disable-netrc是否从 netrc 文件加载凭证。--netrc-filenetrc-file指定 netrc 文件路径。--enable-keychain/--disable-keychain是否在 macOS keychain 中搜索凭证。5.4 构建配置与编译器透传类参数参数说明--configurationconfiguration使用的构建配置如 debug、release。--Xcc...将标志透传给所有 C 编译器调用。--Xswiftc...将标志透传给所有 Swift 编译器调用。--Xlinker...将标志透传给所有链接器调用。--Xcxx...将标志透传给所有 C 编译器调用。--tripletriple指定目标三元组target triple。--sdksdk指定 SDK 路径或名称。--toolchaintoolchain指定工具链路径。--swift-sdkswift-sdk过滤选择用于构建的特定 Swift SDK。--sanitizesanitize...开启运行时错误行为检查可选值address、thread、undefined、scudo。--jobsjobs构建过程中并行派生的任务数。--build-systembuild-system指定使用的构建系统。--use-integrated-swift-driver使用集成的 Swift 驱动driver。--enable-parseable-module-interfaces启用可解析的模块接口。5.5 诊断、索引与链接类参数参数说明--verbose提高详细程度包含信息性输出。--very-verbose/--vv提高详细程度包含调试输出。--quiet降低详细程度仅包含错误输出。--color-diagnostics/--no-color-diagnostics启用或禁用输出到 TTY 时的彩色诊断。默认在连接 TTY 时启用彩色诊断否则禁用。--disable-sandbox执行子进程时禁用沙箱。--auto-index-store/--enable-index-store/--disable-index-store启用或禁用构建时索引indexing-while-building功能。--explicit-target-dependency-import-checkexplicit-target-dependency-import-check指示本次构建应检查目标是否只 import 其显式声明的依赖。--debug-info-format使用的调试信息格式Debug Information Format。--enable-dead-strip/--disable-dead-strip启用/禁用链接器的死代码剥离。--disable-local-rpath禁用默认向 rpath 添加$ORIGIN/loader_path。--version显示版本信息。--help显示帮助信息。六、实战示例示例 1生成默认归档cd /path/to/MyPackage swift package archive-source # 输出: Created MyPackage.zip示例 2指定输出文件版本化发布swift package archive-source --output MyPackage-1.0.0.zip示例 3从任意目录打包指定包swift package archive-source --package-path /path/to/MyPackage --output /tmp/MyPackage-1.0.0.zip示例 4归档后计算校验和swift package compute-checksum MyPackage-1.0.0.zip七、行为验证来自仓库测试的证据仓库测试 PackageCommandTests.swift 中的ArchiveSourceTests结构体验证了archive-source的多个关键行为可作为行为契约参考无参数重复执行在 Git 仓库化的包fixtureDependencyResolution/External/Simple中的Bar包中反复执行archive-source每次都输出Created Bar.zip验证默认归档名取自包名且可覆盖已有归档--output为包内绝对路径指定--output Bar-1.2.3.zip后输出Created Bar-1.2.3.zip验证自定义输出名--output为包外路径输出到临时目录时打印绝对路径且归档成功非包目录报错在找不到Package.swift的目录中执行报错error: Could not find Package.swift in this directory or any of its parent directories.--output指向目录报错将输出路径指向一个已存在的目录时归档失败并报error: Couldn’t create an archive:说明--output必须是可写入的文件路径。这些用例与 GitRepository.swift 中git archive的失败信息 Couldnt create an archive 相互印证构成了该命令完整的可验证行为边界。八、注意事项Git 仓库状态影响内容在 Git 仓库中归档内容以HEAD为准未提交的修改不会进入归档若需要包含未提交内容请先提交或确认目录本身不是 Git 仓库此时走整目录压缩路径。--output目标不能是目录输出路径需为具体的归档文件路径。包名来源默认归档名取自根包的manifest.displayName因此包名不同的目录会生成不同的默认归档文件名。归档内目录层级Git 路径生成的归档带有包名/前缀目录解压时需注意这一层级。【免费下载链接】swift-package-managerThe Package Manager for the Swift Programming Language项目地址: https://gitcode.com/gh_mirrors/sw/swift-package-manager创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考