FreeBSD 使用 Synth 命令安装 Ports 集软件

Synth 是 FreeBSD 系统下的可以并发构建 Ports 的工具，用于从源码构建软件包并安装到 FreeBSD 系统中。

Synth 可以用来替代传统的 portmaster、portupgrade 等工具，它能够提供更加稳定、更加高效的源码构建体验。

安装 Synth

在 FreeBSD 系统中可以使用 Ports 或 Packages 二进制包安装 Synth。推荐使用 Ports 安装 Synth。

使用 Ports 安装 Synth

推荐使用 Ports 安装 Synth，是因为需需要使用 Ports 安装其他的应用，这样能够一直保持依赖一致，不会出现依赖错误。

1）转到 Synth 的 Ports 目录

cd /usr/ports/ports-mgmt/synth

2）可选的自定义配置选项：

make config

3）编译安装 Synth 并清除临时文件：

make install clean

# 或者使用 doas 或 sudo
doas make install clean

使用 pkg 安装 Synth

当然也可以使用 pkg 安装 Synth，但是应当注意，我们安装 Synth 就是为了使用 Ports 安装软件，因此应当使 pkg 使用的分支与 Ports 使用的分支相同。

使用如下命令安装 Synth：

pkg install synth

# 或者使用 doas 或 sudo
doas pkg install synth

核心概念

使用 Synth 安装 Ports 应用，了解以下几个概念，能够更好的帮助你了解使用 Synth 安装 Ports 应用：

Ports 树：存放软件构建脚本的目录，默认为 /usr/ports 或 /usr/dports
Distfiles：软件源码压缩包，默认存放在 /usr/ports/distfiles
本地仓库：Synth 构建的 .pkg 包及仓库元数据存放的目录，默认为 /var/synth/live_packages
构建环境：基于 tmpfs（内存文件系统）或磁盘的隔离工作区，每个构建任务独立运行；
配置文件 Profile：存储 Synth 配置的文件集（默认使用的名称为 LiveSystem），可以在多个 Profile 之间进行切换。

工作流程简述

使用 Synth 安装 Ports 应用，大致按照如下的顺序运行：

读取 Synth 的配置文件，初始化构建环境
分析当前需要安装的 Port 的依赖关系，确定构建的先后顺序
以并发的方式快速编译构建 Port，生成应用的 .pkg 软件包
更新本地仓库的元数据
使用 pkg 命令从本地仓库中存放的 .pkg 软件包安装或升级软件

交互式配置

Synth 应用提供了一个以交互方式初始化配置的命令，这样就不用手动的去编辑配置文件。

在安装 Synth 后使用之前，需要先初始化配置，使用如下命令初始化配置：

doas synth configure

配置项详细说明

进入配置菜单后，可通过按配置项修改各项的值，修改后的值会使用 * 标记，按 Enter 保存配置，Esc 退出配置程序：

配置项	作用	使用说明
Ports directory	存放 Ports 树的目录	优先读取 `PORTSDIR` 环境变量的值，或者从 `/usr/share/mk` 读取变量的值，或者尝试使用 `/usr/dports` 或 `/usr/ports`
Packages directory	本地仓库，也就是 `.pkg` 包存放目录	默认值为 `/var/synth/live_packages`
Distfiles directory	源码的压缩包存放目录	默认值为 `/usr/ports/distfiles`
Port options directory	编译选项的缓存目录	扫描文件系统
Build logs directory	构建时的日志存放目录	默认值为 `/var/log/synth`，`/var` 不足时可改为 `/home/synth/logs`
Build base directory	构建环境的挂载点	默认值为 `/usr/obj/synth-live`
System root directory	构建环境的系统根目录	默认为 `/`
Compiler cache directory	ccache 缓存目录（加速重复构建）	默认禁用，如要启用请输入有效路径，需要先安装 `ccache`，建议设置为 `/var/cache/ccache`
`Num` concurrent builders	并发构建的任务数	一般占物理 CPU 核心数的 75%
`Max` jobs per builder	单个构建任务的并行作业数	不超过 5
Use tmpfs for work area	构建工作区时使用 tmpfs	内存充足时默认启用
Use tmpfs for /usr/local	构建环境的 `/usr/local` 使用 tmpfs 内存文件系统	默认启用
Display using ncurses	构建时使用 ncurses 交互式界面	默认启用
Fetch prebuilt packages	优先从外部仓库下载匹配的预编译包	默认禁用

配置文件路径

使用 synth configure 生成的配置存储在 /usr/local/etc/synth/synth.ini 文件中。

核心命令详解

升级与预构建系统

升级系统

升级系统，自动检测系统中可升级的软件，并构建所有的依赖 Port，更新本地仓库，然后使用 pkg 升级系统。

1）更新 Ports 树：

git -C /usr/ports pull

2）执行命令升级系统：

synth upgrade-system

预构建软件包

预构建系统中需要升级的软件包，它只编译生成 .pkg 软件包，并更新本地仓库，而不更新系统。

后续手动执行 pkg upgrade 升级系统

Port 构建子命令

子命令的功能说明：

子命令	功能说明
`just-build`	仅构建指定 Port，如果为最新版本则跳过，不会更新仓库、也不安装软件
`build`	构建指定的 Port，构建完成后，会询问是否重建仓库、是否安装软件
`install`	构建指定的 Port，然后更新本地仓库，并安装软件
`force`	强制删除软件包，重新构建指定 Port，续询问是否重建仓库 / 安装软件
`test`	强制重建 Port 并启用开发者测试模式（`DEVELOPER_MODE`），不更新本地仓库

如上的构建命令，可以使用两种方式构建 Port：

可以直接指定单个或多个 Port 源
指定一个包含 Port 源的文件，文件中一行为一个 Port 源

Port 源的格式为 category/portname，如 lang/python311。

使用示例

1）直接构建多个 Port 源：

synth install editors/joe editors/nano www/firefox

2）指定文件构建多个 Port 源：

# /tmp/build.list 内容
editors/joe
editors/nano
www/firefox

# 执行构建
synth build /tmp/build.list

状态检查子命令

检查系统升级状态

模拟 upgrade-system 的执行流程，列出所有需要构建的 Port，不真正的构建软件包。

输出的完整列表会保存至 /var/synth/synth_status_results.txt 文件中。

1）当不指定任何参数时，查看系统中所有 Port 的状态：

synth status

2）当指定 Port 源时，查看特定的 Port 源的状态：

synth status lang/python311

检查全 ports 树状态

模拟 everything 命令，列出全 Ports 树中所有需要构建的端口，只适用于镜像站点维护者使用。

使用方法为：

synth status-everything

仓库管理

功能为检查本地仓库中包的完整性，删除损坏的软件包，重建仓库的元数据。

使用方法为：

sudo synth rebuild-repository

清理无用源码包

扫描 ports 树，删除 Port 源代码目录 distfiles 中无用的源码包：

synth purge-distfiles

钩子脚本 Hooks

Synth 支持使用钩子脚本，在构建的过程中可以自定义操作。

钩子文件说明

所有钩子文件需放在 /usr/local/etc/synth/ 目录中，且文件必须具有可执行权限。

钩子文件名	触发时机	可用的环境变量
`hook_run_start`	构建任务开始时	`PORTS_QUEUED`（待构建 Port 数）、`PROFILE`
`hook_run_end`	构建任务结束时	`PORTS_BUILT`/`FAILED`/`IGNORED`/`SKIPPED`
`hook_pkg_success`	单个端口构建成功时	`ORIGIN`（Port 源）、`PKGNAME`（软件包名）
`hook_pkg_failure`	单个端口构建失败时	`ORIGIN`、`PKGNAME`
`hook_pkg_ignored`	当前 Port 被 Ports 树标记为可忽略	`ORIGIN`、`PKGNAME`
`hook_pkg_skipped`	Port 因安装依赖失败而跳过	`ORIGIN`、`PKGNAME`

构建失败发送邮件通知示例

1）创建 /usr/local/etc/synth/hook_pkg_failure 文件：

#!/bin/sh
echo "Port $ORIGIN (pkg: $PKGNAME) build failed!" | mail -s "Synth Build Failure" admin@example.com

2）为文件添加执行权限：

sudo chmod +x /usr/local/etc/synth/hook_pkg_failure

环境变量控制

可以在执行 Synth 命令时，指定如下的环境变量可临时修改 Synth 行为，常用变量如下：

环境变量	作用说明	适用场景
`SYNTHPROFILE`	临时指定 Profile	切换不同构建环境
`WHYFAIL`	显示依赖/选项检查失败的详细原因	排查构建失败问题

总结

Synth 是 FreeBSD 下功能强大的源码构建工具，它能够实现环境隔离、并发构建、本地仓库管理等功能。本文介绍了如何安装 Synth，初始化 Synth，以及各个子命令的使用方法，最后还讲解了切换配置文件及钩子和环境变量的使用。在查看完本文后你将能够掌握 Synth 的使用方法。