Golang 打包指南

本文档将列出 Golang 软件包打包的最佳实践。

旧版的指南中要求为每个依赖的库单独定义 -devel 的包,但随着 Changes/GolangPackagesVendoredByDefault 这一变动生效,现在要求所有新打包的 Golang 项目必须自带所有依赖项。当前版本的指南完全面向新的打包要求。

go2rpm

go2rpm 是一个能够自动完成一些打包相关步骤的实用工具。在手写 spec 文件之前,通常推荐先尝试用 go2rpm --name NAME --profile vendor IMPORT_PATH 命令自动生成。 go2rpm 将按照指南要求生成 spec 文件,下载上游源代码,用 Go Vendor Tools 提供的的 go_vendor_archive 工具打包依赖项,用 go_vendor_license 分析项目本身和依赖项提供的许可文件,请求用户补全不确定的许可,并最终生成一个完整的 SPDX 表达式。

导入路径(IMPORT_PATH)

Golang 软件包的路径由对应项目中的 go.mod 列出的完整 URL 定义。

%global goipath     github.com/kr/pretty

软件包命名

Fedora 目前不再允许单独打包 Golang 库,因此所有 Golang 包一定是面向用户的程序,必须按照 软件包命名指南正常命名。另外注意,除非上游项目的名称中就有 golang- 前缀,否则不得在软件包命名时使用这一前缀。

该要求对已有的软件包同样适用。从基于旧版指南的名字前缀 golang- 的软件包转换到自带依赖的打包配置时,必须通过软件包改名流程。通过这一要求,本指南力求确保两种不同打包方式的软件包可以轻松区分,也避免已有的名字前缀 golang- 的软件包下单独的 -devel 被移除后又被添加回稳定的 Fedora 分支。

Golang 包的处理器架构支持

Golang 自带的编译器和 gcc-go 都支持跨处理器架构编译。Golang 自带的编译器目前支持 x86、x86_64、ppc64le、ppc64(存在问题,请参考上游 Issue #13192)、s390x、armv7hl 和 aarch64。

程序应该设置 ExclusiveArch,以保证构建系统只为这些处理器架构进行编译。目前 %gometa 宏会通过 %{golang_arches} 宏自动添加它。打包者可以通过为 %gometa 宏添加 -f 参数来跳过 %ix86 架构的编译(参考 Changes/EncourageI686LeafRemoval)。-f 要求 %gometa 定义 ExclusiveArch: %{golang_arches_future} 而非默认的 ExclusiveArch: %{golang_arches},而 %{golang_arches_future} 即为 {golang_arches} 去掉 %ix86。

Go 编译参数

保留编译参数

软件包必须通过使用 %gobuild 宏或在上游提供的构建脚本中增加 %gobuild_*flags ,来保留 Fedora 要求的 Go 编译参数。

# 使用 %gobuild
%gobuild -o %{gobuilddir}/bin/%{name} %{goipath}

# 在上游提供的构建脚本中加入参数
%make_build BUILD_OPTS=%{gobuild_baseflags_shescaped}

# 如果上游脚本提供单独的 ldflags 配置参数
%make_build \
  BUILD_OPTS=%{gobuild_baseflags_shescaped} \
  GO_LDFLAGS=%{gobuild_ldflags_shescaped}

macros.go-compilers-golang 的行内注释提供了向上游构建脚本传递参数相关的更多信息。

推荐尽可能地使用 %gobuild 宏。上游提供的构建脚本不一定保证能够正确处理这些额外参数,或者可能存在其他问题。使用 %gobuild 时,也应注意按以下要求配置链接和构建参数。

传递其它参数

Golang 支持通过链接器参数(比如对 --version 的支持)和构建标签来实现按需编译。上游提供的构建脚本可能已经定义了所需的参数,但如果没有,则打包者需要手动添加。

请务必参考上游的构建流程和相关文档,以确定正确的链接器参数配置,保证 --version 命令需要的版本号正确嵌入,或者可选功能正确启用。

链接器参数

有些情况下,可能需要手动提供更多链接器参数,此时可以定义 $GO_LDFLAGS 环境变量,之后所有的宏都会读取它的值。

# 不同项目中 -X 的用法可能不同,此处仅供参考
export GO_LDFLAGS="-X %{goipath}/internal.Version=%{version}"

软件包不得通过 $LDFLAGS 环境变量来配置链接器参数。目前出于兼容性考量仍然支持该方式,但其已被弃用。

构建标签

Golang 支持通过构建标签在编译中包括或排除特定代码块。将 $GO_BUILDTAGS 参数设定为空格分隔的标签列表即可。

# 这些标签仅供参考,具体需要的标签请参考实际项目。
export GO_BUILDTAGS="systemd selinux"

软件包不得通过 $BUILDTAGS 环境变量配置构建标签。

宏相关依赖

软件包必须定义 BuildRequires: go-rpm-macros 以在构建时导入 Golang 编译器和相关宏的定义。

%gometa 宏会自动完成这一要求。

使用任意 %go_vendor_license_* 宏的软件包必须定义 BuildRequires: go-vendor-tools。

自带依赖项

软件包必须自带打包其依赖的所有 Go 模块。打包者应该使用 Go Vendor Tools 提供的 go_vendor_archive 命令生成可复现的依赖压缩包。如果不使用 Go Vendor Tools,则必须提供基于 go mod vendor 生成可复现的压缩包的脚本或操作步骤的文档。即使上游自己提供了依赖包,打包者也应该手动重新生成,以保证https://fedora.gitlab.io/sigs/go/go-vendor-tools/scenarios/#security-updates[基于 Go Vendor Tools 的安全更新]可以更高效地进行。

传统来说,specfile 中的 Source0 对应项目本体的源码包,而 Source1 则是依赖包。版本控制相关宏会自动填入需要的内容。

Source0:        %{gosource}
# %%archivename 对应 %%gosource 提供的文件名,
# 不包含拓展名。
Source1:        %{archivename}-vendor.tar.bz2
# go2rpm 生成的 go-vendor-tools 配置
Source2:        go-vendor-tools.toml

接下来,运行 go_vendor_archive create <PACKAGE_NAME>.spec 以生成依赖包。

包自带的 Provides

软件包必须为每一个自带的 Go 模块定义 bundled(golang(IMPORT_PATH)) = VERSION 的 Provides。https://gitlab.com/fedora/sigs/go/go-rpm-macros/-/blob/main/rpm/fileattrs/go_mod_vendor.attr?ref_type=heads[依赖生成器]会扫描许可目录下的任意 modules.txt 文件来自动完成这一要求。在 %files 中标定 vendor/modules.txt 为 %license,生成器就会自动扫描并生成对应的 Provides。vendor/modules.txt`在 `go_vendor_license_filelist 中已经预先定义(参考 安装许可文件 ),因此绝大多数的软件包都不需要额外配置。

# 只有不使用 %%go_vendor_license_filelist 时才需要明确定义
%license vendor/modules.txt

许可

软件包必须遵守 Fedora 许可指南。考虑到依赖项打包的要求,这意味着主项目和所有自带依赖项的许可文件都必须包含在打包中并标定为 %license。每个自带的模块都必须包含许可文件。缺失许可文件的模块不得包含在依赖包中,除非许可关系能够理清。

除此之外,软件包的 License: 标签必须是涵盖主项目和所有依赖项目的许可证合并的 SPDX 表达式。

使用 Go Vendor Tools 配置许可要求

Go Vendor Tools 提供了 go_vendor_license 命令和相关的宏,以按照上一章节列出的要求自动生成完整的 License: 定义和安装许可证文件所需的步骤。

在上传任意项目源代码到 Fedora 的缓存系统之前,打包者必须运行 go_vendor_license report(手动运行,通过 go2rpm 运行,或在*本地*构建时使用 %go_vendor_license_check 宏),并检查其输出。报告的任何错误都必须处理。如果输出本身出现错误,可以通过修改 Go Vendor Tools 配置文件的许可部分以调整 go_vendor_license 的运行。

本文档只列出和打包指南相关的 Go Vendor Tools 的基本功能,请参考 Go Vendor Tools 官方文档了解更多高级用法。打包者可以参考文档中的情景部分,在https://fedora.gitlab.io/sigs/go/go-vendor-tools/scenarios/#generate-go2rpm[生成新的 specfile],或https://fedora.gitlab.io/sigs/go/go-vendor-tools/scenarios/#manual-update[在上游更新版本时对应更新 specfile] 时运行 go_vendor_license,以保证许可定义有效且最新。

虽然 Go Vendor Tools 提供了自动扫描并解析许可文件的功能,但打包者仍然需要确保 License 标签下的所有许可都符合 Fedora 许可指南的要求,之后才能上传项目。

如果需要,可以参考https://fedora.gitlab.io/sigs/go/go-vendor-tools/scenarios/#manually-detecting-licenses[情景文档],在配置文件里手动定义特定文件对应的许可表达式。

go-vendor-tools.toml

软件包必须包含 go-vendor-tools.toml 文件,列出配置许可时使用的检测后端和其他配置选项。更多信息请参考https://fedora.gitlab.io/sigs/go/go-vendor-tools/config/[配置指南]。推荐的使用方式是通过 go2rpm 直接生成完成的 go-vendor-tools.toml。以下是最简单的配置:

[licensing]
detector = "askalono"

相关宏会调用这个文件,specfile 通常将其定义为 Source2:,即在项目源代码和依赖包之下。本文档接下来的部分将默认 %{S:2} (宏展开时得到 Source2 的路径)对应这个文件。

安装 go-vendor-tools

使用 Go Vendor Tools 提供的宏的软件包必须定义 BuildRequires: go-vendor-tools,并使用 %go_vendor_license_buildrequires 宏生成许可检测后端所需的依赖项。

BuildRequires:  go-vendor-tools
%generate_buildrequires
%go_vendor_license_buildrequires -c %{S:2}

安装许可文件

打包者应该使用 %go_vendor_license_install 宏安装主项目和所有依赖项的许可文件。默认配置下,该宏会将其安装到主项目包的许可目录下,并安装 vendor/modules.txt 文件,以生成 bundled() 依赖(参考 包自带的 Provides)。

# 将安装在主项目包的许可目录下
%go_vendor_license_install -c %{S:2}

接下来,该宏会根据传递给 %files -f 的文件列表,填入 %{go_vendor_license_filelist}。

%files -f %{go_vendor_license_filelist}

检查许可

先前提到,打包者必须借助 Go Vendor Tools 检查许可之后才能上传项目。go_vendor_license 报告的任何错误都必须处理。

除此之外,https://fedora.gitlab.io/sigs/go/go-vendor-tools/man/rpm_macros/#go_vendor_license_check[%go_vendor_license_check 宏]也会运行和 go_vendor_license report 一样的许可检查。软件包应该在 %check 阶段使用 go_vendor_license_check,以保证许可配置有误时构建会失败。Go Vendor Tools 会扫描主项目和依赖包的许可文件并将其合成成一个完整的 SPDX 表达式。检查相关的宏也会确认软件包的 License 定义和 go_vendor_license report 预期的值(在排除顺序和简化关系之后)一致。

# 扫描许可并确定 License 标签和
# go_vendor_license 计算的的一致。
%go_vendor_license_check -c %{S:2}

# 该宏也可以比较宏定义的许可表达式和
# go_vendor_license 的输出是否一致。
%go_vendor_license_check -c %{S:2} %{go_licenses}

如果许可缺失

go_vendor_license 会检测是否有缺少许可文件的 Go 模块。缺少许可文件的 Go 模块不得打包进依赖包,必须先在上游解决这一问题。

有些情况下,即使上游项目包含了所需的许可文件,go mod vendor 可能仍无法正确定位它。通常原因是许可文件的命名方式不标准,或在某个子目录下。如果是前一种情况,可以通过 post_commands 配置 go_vendor_archive`以人工下载许可文件,但打包者也必须向上游报告这一问题,并请求将许可文件重命名成 go mod vendor` 支持的格式。如果是后者,则应将许可文件复制到项目根目录以满足许可检查器的要求。

运行测试

软件包应该包含并运行单元测试。

允许跳过特定测试,尤其以下这几类是和 mock 或类似的特殊构建环境不兼容的单元测试:

  • 需要访问公网服务器或 API 的测试;

  • 需要修改系统配置的测试;

  • 需要系统上有特定其他程序运行的测试,比如数据库或日志服务。

如果一项测试因为其他原因无法运行,也可以跳过,但打包者应该向上游报告这一问题。同时建议在 specfile 中增加注释,说明跳过该测试的原因,并链接到上游的问题报告。

可以使用 %gocheck2 宏,在保留 Fedora 的构建参数和跳过测试的配置的前提下调用 go test。

软件包不得使用已弃用的旧版的 %gocheck 宏。

Go 模块模式

软件包应该通过定义 %global gomodulesmode GO111MODULE=on 来启用 Go 模块模式。通常该定义会写在 %build 开头,`%gobuild`之前。

Go 模块是 go 管理依赖项的系统,取代了之前使用的 $GOPATH 模式。通过定义 $GO111MODULE 环境变量为 on、off`或auto` 可以控制 Go 在两种模式间的选择。上游目前默认为`auto。 Fedora 定义的 `%gobuild 宏默认设置 GO111MODULE=off 以保证和旧的 Golang 打包指南的兼容性,但自带依赖包的配置下不再推荐该设置。建议启用模块模式以保证 %gobuild 能够读取并打包模块元数据,保证 Go embed 正常运作。

宏

go-vendor-tools 提供了 RPM 宏用于验证并安装许可文件。请参考 Go Vendor Tools RPM 宏文档 和 使用 Go Vendor Tools 配置许可要求。

go-rpm-macros 提供了 %gobuild 宏,负责注入 Fedora 默认的构建参数并调用 go build。

go-rpm-macros 也提供了辅助 forge-srpm-macros 提供的 版本控制系统宏 的脚本,帮助为保存在 GitHub 等常见版本控制库的项目定义源 URL 并解压软件包。相关的宏包括 %gometa、%gosource 和 %goprep。使用这些宏时不再需要手动定义源后再调用 %autosetup 或 %setup。请参考https://gitlab.com/fedora/sigs/go/go-rpm-macros/-/blob/main/doc/forge-wrappers.adoc?ref_type=heads[版本控制系统相关文档]及其中提供的样例 specfile 了解更多信息。

示例

go-vendor-tools 配置

这些条目由`go2rpm` 自动生成。所有 Go 软件包必须将 go-vendor-tools.toml 和 specfile 一起上传到 distgit。

go-vendor-tools.toml
[archive]

[licensing]
detector = "askalono"

[[licensing.licenses]]
path = "vendor/github.com/google/shlex/COPYING"
sha256sum = "cfc7749b96f63bd31c3c42b5c471bf756814053e847c10f3eb003417bc523d30"
expression = "Apache-2.0"

[[licensing.licenses]]
path = "vendor/github.com/jwalton/gchalk/LICENSE-chalk"
sha256sum = "44e453533edb9f1c037cb260c58f66f1d9b2e7823a07407cd6d04320e3925fea"
expression = "MIT"

[[licensing.licenses]]
path = "vendor/github.com/jwalton/gchalk/pkg/ansistyles/LICENSE-ansi-styles"
sha256sum = "310f4b4de77142b34acc5a58de93558fde5dea75891c7822b4086f71372ec983"
expression = "MIT"

[[licensing.licenses]]
path = "vendor/github.com/jwalton/go-supportscolor/LICENSE"
sha256sum = "892282511d65ac08025fbabcd8af330d0aa94e459d81a818251ff5a934383816"
expression = "MIT"

[[licensing.licenses]]
path = "vendor/gopkg.in/yaml.v3/LICENSE"
sha256sum = "d18f6323b71b0b768bb5e9616e36da390fbd39369a81807cca352de4e4e6aa0b"
expression = "MIT AND (MIT AND Apache-2.0)"

带版本控制系统宏的 specfile

go2rpm 默认按该配置生成 specfile,目前也推荐从该方法出发进行调整。

ov.spec
# Generated by go2rpm 1.17.1 (手动添加注释)
%bcond check 1

# https://github.com/noborus/ov
%global goipath         github.com/noborus/ov
Version:                0.43.0

%gometa -L -f

Name:           ov
Release:        %autorelease
Summary:        Feature-rich terminal-based text viewer

# Generated by go-vendor-tools
License:        Apache-2.0 AND BSD-3-Clause AND MIT AND MPL-2.0
URL:            %{gourl}
Source0:        %{gosource}
# Generated by go-vendor-tools
Source1:        %{archivename}-vendor.tar.bz2
# go2rpm 生成的 Go Vendor Tools 配置
Source2:        go-vendor-tools.toml

BuildRequires:  go-vendor-tools

%description
Feature-rich terminal-based text viewer. It is a so-called terminal pager.

%prep
# 解压上游源码 Source0 并应用补丁(如果有)。
# 同时创建 %%{gobuilddir},
# 保存 %%build 阶段的构建产物。
%goprep -p1
# 解压 Source1 对应的依赖包。
tar -xf %{S:1}

%generate_buildrequires
# 安装许可扫描器的依赖项。
%go_vendor_license_buildrequires -c %{S:2}

%build
# 按指南要求启动 Go 模块模式。
%global gomodulesmode GO111MODULE=on
# 保证构建产物中写入版本号。注意不同项目 -X 的用法不同。
export GO_LDFLAGS="-X main.Version=%{version}"
# 进行构建
%gobuild -o %{gobuilddir}/bin/ov %{goipath}
# 生成 Shell 自动完成
%{gobuilddir}/bin/%{name} --completion bash > %{name}.bash
%{gobuilddir}/bin/%{name} --completion fish > %{name}.fish
%{gobuilddir}/bin/%{name} --completion zsh  > %{name}.zsh

%install
# 安装许可文件
%go_vendor_license_install -c %{S:2}

# 安装 %%build 阶段构建的文件
install -m 0755 -vd                     %{buildroot}%{_bindir}
install -m 0755 -vp %{gobuilddir}/bin/* %{buildroot}%{_bindir}/

# 安装 %%build 阶段构建的 Shell 自动完成
install -Dpm 0644 ov.bash %{buildroot}%{bash_completions_dir}/ov
install -Dpm 0644 ov.fish %{buildroot}%{fish_completions_dir}/ov.fish
install -Dpm 0644 ov.zsh  %{buildroot}%{zsh_completions_dir}/_ov

%check
# 检查许可文件
%go_vendor_license_check -c %{S:2}
# 运行单元测试
%if %{with check}
%gocheck2
%endif

%files -f %{go_vendor_license_filelist}
%doc README.md
%{_bindir}/ov
%{bash_completions_dir}/ov
%{fish_completions_dir}/ov.fish
%{zsh_completions_dir}/_ov

%changelog
%autochangelog

手动配置的 specfile

go2rpm 默认采用前一种方式生成 specfile,但 Go 软件包也可以不使用版本控制系统宏来定义。此时注意需要手动定义 go-rpm-macros 的依赖,并对应配置 ExclusiveArch。

ov.spec
%bcond check 1

Name:           ov
Version:        0.43.0
Release:        %autorelease
Summary:        Feature-rich terminal-based text viewer
# Generated by go-vendor-tools
License:        Apache-2.0 AND BSD-3-Clause AND MIT AND MPL-2.0
URL:            https://github.com/noborus/ov
Source0:        %{url}/archive/v%{version}/ov-%{version}.tar.gz
# Generated by go-vendor-tools
Source1:        ov-%{version}-vendor.tar.bz2
Source2:        go-vendor-tools.toml

ExclusiveArch:  %{golang_arches_future}
BuildRequires:  go-rpm-macros
BuildRequires:  go-vendor-tools

%description
Feature-rich terminal-based text viewer. It is a so-called terminal pager.

%prep
# 解压上游源码 Source0 并应用补丁(如果有)。
%autosetup -p1
# 解压 Source1 对应的依赖包。
tar -xf %{S:1}

%generate_buildrequires
# 安装许可扫描器的依赖项。
%go_vendor_license_buildrequires -c %{S:2}

%build
# 按指南要求启动 Go 模块模式。
%global gomodulesmode GO111MODULE=on
# 保证构建产物中写入版本号。注意不同项目 -X 的用法不同。
export GO_LDFLAGS="-X main.Version=%{version}"
# 进行构建
%gobuild -o ov .
# 生成 Shell 自动完成
./ov --completion bash > ov.bash
./ov --completion fish > ov.fish
./ov --completion zsh  > ov.zsh

%install
# 安装许可文件
%go_vendor_license_install -c %{S:2}

# 安装 %%build 阶段构建的文件
install -Dp ./ov -t %{buildroot}%{_bindir}

# 安装 %%build 阶段构建的 Shell 自动完成
install -Dpm 0644 ov.bash %{buildroot}%{bash_completions_dir}/ov
install -Dpm 0644 ov.fish %{buildroot}%{fish_completions_dir}/ov.fish
install -Dpm 0644 ov.zsh  %{buildroot}%{zsh_completions_dir}/_ov

%check
# 检查许可文件
%go_vendor_license_check -c %{S:2}
# 运行单元测试
%if %{with check}
%gocheck2
%endif

%files -f %{go_vendor_license_filelist}
%doc README.md
%{_bindir}/ov
%{bash_completions_dir}/ov
%{fish_completions_dir}/ov.fish
%{zsh_completions_dir}/_ov

%changelog
%autochangelog