YAP — Yet Another Packager

YAP 可根据单个 PKGBUILD 规范，为多种 GNU/Linux 发行版构建原生软件包。只需编写一次软件包，即可生成 .deb、.rpm、.apk 和 .pkg.tar.zst。所有构建都在隔离的 OCI 容器（Docker 或 Podman）中运行。

功能

• 多格式输出：DEB（Debian/Ubuntu）、RPM（Fedora/RHEL/Rocky/openSUSE）、APK（Alpine）、TAR.ZST（Arch）
• 容器隔离：可复现构建，不污染宿主机，支持 Docker 和 Podman
• 基于 PKGBUILD：熟悉的 Arch Linux 语法，并扩展支持发行版和架构覆盖设置
• 交叉编译：为不同于宿主机的架构构建
• 感知依赖关系的构建：默认顺序构建；可通过 --parallel 选择并行拓扑排序
• 软件包签名：APK RSA + DEB/RPM/Pacman GPG（无需 gpg 二进制文件）
• SBOM 生成：生成 CycloneDX 1.5 和 SPDX 2.3 附加文件
• 发布：yap publish 可将 DEB/RPM（以及作为原始文件的 APK/Pacman）上传至 OpenArtifact 仓库
• 按格式压缩：DEB 和 RPM 支持 zstd/gzip/xz
• 变更日志支持：changelog PKGBUILD 字段会按发行版格式生成原生变更日志
• Pacman 脚本片段：完整支持 6 个生命周期钩子（安装前/后、升级前/后、移除前/后）
• 结构化日志：基于 slog，长行采用树形渲染，无外部 UI 依赖

安装

单行命令（Linux/macOS，amd64/arm64）：

curl -fsSL https://raw.githubusercontent.com/M0Rf30/yap/main/scripts/install.sh | sh

固定版本或仅安装一个工具：

curl -fsSL https://raw.githubusercontent.com/M0Rf30/yap/main/scripts/install.sh \
  | sh -s -- --version v2.1.3 --tool yap

手动下载：

wget https://github.com/M0Rf30/yap/releases/latest/download/yap_Linux_x86_64.tar.gz
tar -xzf yap_Linux_x86_64.tar.gz
sudo mv yap /usr/local/bin/
yap version

从源代码构建

git clone https://github.com/M0Rf30/yap.git
cd yap
make build
sudo mv yap /usr/local/bin/

需要 Docker 或 Podman：

# Docker
sudo systemctl enable --now docker && sudo usermod -aG docker $USER

# Podman
sudo systemctl enable --now podman

快速开始

1. 项目结构

创建 yap.json：

{
  "name": "My Package",
  "description": "A sample package built with YAP",
  "buildDir": "/tmp/yap-build",
  "output": "artifacts",
  "projects": [
    { "name": "my-package" }
  ]
}

2. PKGBUILD

创建 my-package/PKGBUILD：

pkgname=my-package
pkgver=1.0.0
pkgrel=1
pkgdesc="My awesome application"
arch=('x86_64')
license=('GPL-3.0')
url="https://github.com/user/my-package"
makedepends=('gcc' 'make')
source=("https://github.com/user/my-package/archive/v${pkgver}.tar.gz")
sha256sums=('SKIP')

build() {
    cd "${srcdir}/${pkgname}-${pkgver}"
    make
}

package() {
    cd "${srcdir}/${pkgname}-${pkgver}"
    install -Dm755 my-package "${pkgdir}/usr/bin/my-package"
    install -Dm644 README.md "${pkgdir}/usr/share/doc/${pkgname}/README.md"
}

3. 构建

# Auto-detect host distro from /etc/os-release
yap build .

# Specific distribution
yap build ubuntu-jammy .
yap build fedora-38 /path/to/project
yap build --cleanbuild --no-makedeps ubuntu-jammy .

4. 输出

artifacts/
├── my-package_1.0.0-1_amd64.deb
├── my-package-1.0.0-1.x86_64.rpm
├── my-package-1.0.0-r1.apk
└── my-package-1.0.0-1-x86_64.pkg.tar.zst

项目配置（yap.json）

{
  "name": "My Multi-Package Project",
  "description": "Project description",
  "buildDir": "/tmp/yap-builds",
  "output": "dist",
  "projects": [
    { "name": "package-one", "install": true },
    { "name": "package-two" }
  ]
}

字段	必填	默认值	说明
name	是	—	项目集合名称
description	是	—	项目集合描述
buildDir	是	—	构建/工作目录
output	是	—	已构建软件包的输出目录
projects	是	—	要构建的软件包有序数组
projects[].name	是	—	包含软件包 PKGBUILD 的子目录
projects[].install	否	false	构建后立即安装，以便后续软件包可以依赖它
compressionDeb / compressionRpm	否	zstd	按格式压缩：zstd/gzip/xz
signing	否	—	签名配置（参见软件包签名）
repos	否	—	解析依赖项前要配置的额外软件包仓库
skipDeps	否	—	要从 makedepends 中排除的软件包名称
targetArch	否	宿主机	交叉编译目标架构
parallel	否	false	并行构建互不依赖的软件包（拓扑排序）
sbom	否	false	生成 SBOM 附加文件
sbomFormat	否	both	cyclonedx/spdx/both
publish	否	—	yap publish 的默认设置（参见发布到 OpenArtifact）；不会保存令牌

软件包之间的构建顺序由 install 标志以及每个 PKGBUILD 的 depends/makedepends 决定——yap.json 层级没有 depends 字段。完整规范请参见 yap.schema.json。

编辑器验证（JSON Schema）

仓库根目录附带 yap.json 的 JSON Schema：yap.schema.json。 它记录了所有受支持的字段（压缩、签名、仓库、SBOM、 交叉编译等）。在 yap.json 中引用它，即可在支持 JSON Schema 的编辑器中使用自动补全和 内联验证：

{
  "$schema": "https://www.schemastore.org/yap.json",
  "name": "My Multi-Package Project",
  "...": "..."
}

该 Schema 已发布到 SchemaStore， 因此编辑器（VS Code、JetBrains、Neovim 等）会按文件名自动验证任何 yap.json，无需添加 $schema 行。

PKGBUILD 扩展

特定发行版的变量

使用 __（双下划线）按发行版覆盖任意变量。优先级（数值越高优先级越高）：

优先级	语法	示例
4+	架构 + 发行版	depends_x86_64__ubuntu_noble
4	仅架构	depends_x86_64
3	发行版 + 代号	depends__ubuntu_noble
2	发行版	depends__ubuntu
1	包管理器	depends__apt
0	基础（回退）	depends

pkgdesc="My application"
pkgdesc__debian="My application for Debian/Ubuntu"
pkgdesc__ubuntu_noble="My application optimized for Ubuntu 24.04"

makedepends=('gcc' 'make')
makedepends__apt=('build-essential' 'cmake')
makedepends__yum=('gcc-c++' 'cmake3')
makedepends__ubuntu_noble=('build-essential' 'cmake' 'pkg-config' 'libtool')

特定架构的变量

depends=('glibc' 'gcc')
depends_x86_64=('glibc' 'gcc' 'lib32-glibc')
depends_aarch64=('glibc' 'gcc' 'aarch64-linux-gnu-gcc')

source=('https://example.com/generic-source.tar.gz')
source_x86_64=('https://example.com/x86_64-optimized.tar.gz')
source_aarch64=('https://example.com/aarch64-source.tar.gz')

sha256sums=('generic_hash')
sha256sums_x86_64=('x86_64_specific_hash')
sha256sums_aarch64=('aarch64_specific_hash')

支持的架构：x86_64、i686、aarch64、armv7h、armv6h、armv5、ppc64、ppc64le、s390x、mips、mipsle、riscv64、pentium4、any。

校验和类型

支持的类型（从强到快）：b2sums、sha512sums、sha384sums、sha256sums、sha224sums、cksums。

# BLAKE2b (recommended)
b2sums=('2f240f2a3d2f8d8f...')

# CRC32 (format: checksum filesize)
cksums=('1234567890 2048576')

更新日志

changelog=CHANGELOG.md

• DEB：usr/share/doc/<pkgname>/changelog.Debian.gz（符合 Lintian 规范）
• RPM：将原生 %changelog 条目嵌入包元数据
• Pacman：归档中的 .CHANGELOG
• APK：忽略（Alpine 没有相应惯例）

Pacman 脚本片段

pre_install()  { echo "Before install"; }
post_install() { systemctl daemon-reload; }
pre_upgrade()  { systemctl stop myservice; }
post_upgrade() { systemctl start myservice; }
pre_remove()   { systemctl disable myservice; }
post_remove()  { systemctl daemon-reload; }

仅当至少定义了一个钩子时，才会生成到 <pkgname>.install 中。若未定义 pre/post_upgrade，则回退使用 pre/post_install。

特定包管理器的字段

# DEB
section=utils
priority=optional

# RPM
group="Applications/System"
requires_pre=('shadow-utils')

# APK
maintainer="John Doe <[email protected]>"

支持的发行版

发行版 ID	格式	包管理器
almalinux	.rpm	yum
alpine	.apk	apk
amzn	.rpm	yum
arch	.pkg.tar.zst	pacman
centos	.rpm	yum
debian	.deb	apt
fedora	.rpm	yum
linuxmint	.deb	apt
opensuse-leap	.rpm	zypper
opensuse-tumbleweed	.rpm	zypper
ol	.rpm	yum
pop	.deb	apt
rhel	.rpm	yum
rocky	.rpm	yum
ubuntu	.deb	apt

模型上下文协议（MCP）

YAP 附带配套的 yap-mcp 二进制文件，可通过模型上下文协议提供相同的构建流水线， 因此任何兼容 MCP 的大模型客户端（Claude Desktop、opencode、Cursor、Zed、Continue、 Goose 等）都可以直接驱动 yap。

快速开始（发布版二进制文件）：

curl -fsSL https://raw.githubusercontent.com/M0Rf30/yap/main/scripts/install.sh | sh
# then add { "mcpServers": { "yap": { "command": "yap-mcp" } } } to your client config

或者拉取独立的 OCI 镜像（也以 io.github.M0Rf30/yap 列在 MCP 注册表中）：

docker pull ghcr.io/m0rf30/yap-mcp:latest
# client config:
# { "mcpServers": { "yap": { "command": "docker",
#   "args": ["run","-i","--rm","ghcr.io/m0rf30/yap-mcp:latest"] } } }

Claude Code 插件（服务端 + 技能合二为一）

/plugin marketplace add M0Rf30/claude-plugins
/plugin install yap@M0Rf30

Smithery

npx @smithery/cli install io.github.M0Rf30/yap --client claude

完整的工具功能、各客户端的配置片段、安全模型和 故障排查内容请参阅 MCP.md。随附的技能卡片 skills/yap/SKILL.md 遵循 Anthropic Agent Skills 布局，并免费为 Agent 提供工作流速查表。分发 渠道和发布步骤记录在 PUBLISHING.md 中。

CLI 参考

命令

yap build [distro[-release]] <path>   # Build packages (distro auto-detected if omitted)
yap zap [distro] <path>               # Clean build environment
yap prepare [distro[-release]]        # Prepare host build environment
yap pull <distro>                     # Pull pre-built container images
yap install <artifact-file>           # Install a built artifact
yap publish [artifact-or-dir]...      # Upload built packages to an OpenArtifact repository
yap graph [path]                      # Show dependency graph
yap list-distros                      # List supported distributions
yap status                            # Show host status and runtime detection
yap version                           # Show version information
yap completion <shell>                # Generate shell completion (bash/zsh/fish/powershell)

构建标志

# Build behavior
--cleanbuild, -c            # Clean srcdir before build
--no-build, -o              # Download sources only
--zap, -z                   # Deep clean staging directory
--skip-hash-check, -H       # Skip source checksum verification
--no-container              # Build natively on the host (skip container dispatch)

# Dependencies
--no-makedeps, -d           # Skip makedeps installation
--skip-sync, -s             # Skip package manager sync
--skip-deps pkg1,pkg2       # Omit specific packages from makedeps
--parallel, -P              # Enable parallel topo-sort (opt-in)

# Version
--pkgver 1.2.3, -w          # Override package version
--pkgrel 2, -r              # Override release number

# Range / filter
--from package1             # Start from specific package
--to package5               # Stop at specific package
--only pkg1,pkg2            # Build only listed packages
--skip pkg1,pkg2            # Skip listed packages

# Source access
--ssh-password pass, -p     # Password for SSH source access
--source-retries <n>        # Retries after first attempt for source/gensum/toolchain downloads (default 3; env: YAP_SOURCE_MAX_RETRIES)

# Cross-compilation
--target-arch arm64, -t     # Cross-compile for target architecture
--skip-toolchain-validation, -T

# Repositories / trust
--repo "<spec>"             # Add an extra package repository (repeatable)
--allow-unverified-repos, -U  # Allow apt sources without a verifiable Signed-By key

# Signing
--sign, -K                  # Enable artifact signing
--sign-key /path/to/key     # Private key path
--sign-passphrase pass      # Passphrase (prefer env: YAP_SIGN_PASSPHRASE)
--sign-key-name mykey       # APK key name

# SBOM
--sbom, -S                  # Generate SBOM sidecars
--sbom-format cyclonedx     # CycloneDX 1.5 only
--sbom-format spdx          # SPDX 2.3 only
--sbom-format both          # Both (default)

# Compression
--compression-deb gzip      # DEB: zstd|gzip|xz (default: zstd)
--compression-rpm xz        # RPM: zstd|gzip|xz (default: zstd)

# Debug / output
--debug-dir /path, -D       # Emit split debug info
--verbose                   # Verbose logging
--no-color                  # Disable colored output

Shell 补全

yap completion bash > /etc/bash_completion.d/yap
yap completion zsh > /usr/share/zsh/site-functions/_yap
yap completion fish > ~/.config/fish/completions/yap.fish
yap completion powershell > yap.ps1

包签名

格式	算法	输出
APK	RSA PKCS#1 v1.5 SHA1	.SIGN.RSA.<keyname>.rsa.pub 内嵌流
DEB	OpenPGP	<package>.deb.asc（ASCII 装甲分离签名）
RPM	OpenPGP	<package>.rpm.asc + 可选的 RPM 内嵌签名（通过 rpmpack）
Pacman	OpenPGP	<package>.pkg.tar.zst.sig（二进制分离签名）

签名使用 github.com/ProtonMail/go-crypto/openpgp，无需 gpg 二进制文件。

密钥解析顺序（从高到低）

1. --sign-key <path> CLI 标志
2. 格式环境变量：YAP_APK_KEY、YAP_DEB_KEY、YAP_RPM_KEY、YAP_PACMAN_KEY
3. 全局环境变量：YAP_SIGN_KEY
4. yap.json 字段 signing.keyPath
5. ~/.config/yap/keys/<format>.{rsa,gpg}，然后是 ~/.config/yap/keys/default.{rsa,gpg}

密码短语的解析顺序与密钥相同，并带有 _PASSPHRASE 后缀。

yap.json 签名配置

{
  "signing": {
    "enabled": true,
    "keyPath": "~/.config/yap/keys/release.gpg",
    "keyName": "release"
  }
}

验证已签名的软件包

# APK (after distributing the public key to /etc/apk/keys/)
apk add my-package.apk

# DEB
gpg --verify my-package_1.0.0_amd64.deb.asc my-package_1.0.0_amd64.deb

# RPM
rpm -K my-package-1.0.0-1.x86_64.rpm

# Pacman
pacman-key --verify my-package-1.0.0-1-x86_64.pkg.tar.zst.sig

发布到 OpenArtifact

yap publish 会将构建好的软件包上传到托管的 OpenArtifact 仓库；该仓库会自行提供 apt/dnf 索引（Release、Packages、repomd.xml）。

格式	使用的路由	说明
DEB	POST {url}/api/v1/repositories/{deb-repo}/debs	multipart file、distribution、component
RPM	POST {url}/api/v1/repositories/{rpm-repo}/packages	multipart file
APK	PUT {url}/repos/raw/{apk-repo}/{apk-path}/{file}	托管的 raw 仓库；OpenArtifact 目前还没有 apk 索引
Pacman	PUT {url}/repos/raw/{pacman-repo}/{pacman-path}/{file}	raw 仓库；软件包旁的 .sig/.asc 附属文件也会上传

export YAP_OA_URL=https://oa.example.com
export YAP_OA_TOKEN_FILE=~/.config/yap/oa-token        # or YAP_OA_TOKEN
export YAP_OA_DEB_REPO=debs YAP_OA_RPM_REPO=rpms

yap build ubuntu-jammy .
yap publish --distribution jammy --component main ./dist   # or a single file
yap publish --dry-run ./dist                               # list only, no network

设置按以下顺序解析（后者优先）：yap.json 的 publish 对象、YAP_OA_* 环境变量、命令行标志。

{
  "output": "dist",
  "publish": {
    "url": "https://oa.example.com",
    "debRepo": "debs",
    "rpmRepo": "rpms",
    "distribution": "jammy",
    "component": "main"
  }
}

设置	yap.json	环境变量	标志
服务 URL	url	YAP_OA_URL	--url
API 令牌	—	YAP_OA_TOKEN、YAP_OA_TOKEN_FILE	--token-file
DEB 仓库	debRepo	YAP_OA_DEB_REPO	--deb-repo
RPM 仓库	rpmRepo	YAP_OA_RPM_REPO	--rpm-repo
APK raw 仓库 / 路径	apkRepo / apkPath	YAP_OA_APK_REPO / YAP_OA_APK_PATH	--apk-repo / --apk-path
Pacman raw 仓库 / 路径	pacmanRepo / pacmanPath	YAP_OA_PACMAN_REPO / YAP_OA_PACMAN_PATH	--pacman-repo / --pacman-path
apt 发行版 / 组件	distribution / component	YAP_OA_DISTRIBUTION / YAP_OA_COMPONENT	--distribution / --component

其他标志：--config <yap.json|dir>（默认值为 ./yap.json）、--retries <n> （每个请求的尝试次数，默认值为 3）、--timeout <duration>（每个请求的超时时间，默认值为 30m）、--insecure-http、--dry-run。

行为：

• 令牌：需要具有目标仓库写入权限的 OpenArtifact API 令牌（deploy 令牌 oa_dep_… 即可）。令牌通过 Authorization: Bearer … 发送，不接受来自 yap.json 或标志值的令牌（因此不会出现在进程列表中），并且会从日志和错误信息中隐藏。令牌只会通过 https 发送；若使用 http，则仅限环回主机，除非传入 --insecure-http。
• 参数：软件包文件和／或目录。不带参数时，会发布 yap.json 中的 output 目录。扫描目录时，若某种格式未配置仓库，则会跳过找到的软件包并发出警告；在这种情况下，显式指定文件则会报错。
• 验证：服务器返回的 SHA-256（raw 文件则为 X-Checksum-Sha256）必须与本地文件的值相同，否则发布失败。
• 重试：连接错误以及 HTTP 408/429/5xx 响应会采用指数退避和随机抖动进行重试；其他 4xx 响应（令牌错误、仓库错误、软件包无效）会立即失败。
• 幂等性：DEB/RPM 软件包在服务器上不可变，服务器会返回 409。随后 yap 会在仓库列表中查询 SHA-256：字节相同则视为成功（“未更改”）；同名同版本但字节不同则失败。如果 X-Checksum-Sha256 已匹配，则会跳过 raw 文件；否则会替换文件（除非仓库强制要求发行版本不可变，此时发布会失败）。
• 签名：OpenArtifact 会对仓库索引签名；yap 不会为 DEB/RPM 上传每个软件包的 .asc 文件。对于 APK/Pacman raw 仓库，软件包旁的 .sig/.asc 附属文件会一并上传。

如果任何软件包失败，退出状态将为非零；仍会继续尝试处理其余软件包。

生成 SBOM

yap build --sbom .                        # Both formats (default)
yap build --sbom --sbom-format cyclonedx .
yap build --sbom --sbom-format spdx .

与每个构件一同输出：

artifacts/
└── my-package_1.0.0-1_amd64.deb
    my-package_1.0.0-1_amd64.deb.cdx.json   ← CycloneDX 1.5
    my-package_1.0.0-1_amd64.deb.spdx.json  ← SPDX 2.3

捕获的信息：名称、版本、许可证、运行时／构建依赖项、源 URL 和校验和、文件哈希、DESCRIBES/DEPENDS_ON 关系。

高级用法

交叉编译

yap build --target-arch=aarch64 ubuntu-jammy .
yap build --target-arch=armv7 fedora-38 .
yap build --target-arch=i686 alpine .
yap build --target-arch=ppc64le arch .

YAP 会自动安装所需的交叉编译工具链并配置构建环境。

多包项目

{
  "name": "My Suite",
  "projects": [
    { "name": "core-library", "install": true },
    { "name": "main-application", "install": true },
    { "name": "plugins", "install": false }
  ]
}

设置 "install": true 的包会在构建后立即安装，以便后续包将它们用作构建时依赖项。

# Sequential (default) — explicit ordering via "install" field
yap build .

# Parallel — topo-sort + worker pool
yap build --parallel .

构建环境准备

yap prepare                    # Auto-detect host distro
yap prepare ubuntu-jammy
yap prepare fedora-38
yap prepare --golang arch
yap prepare --skip-sync rocky-9

CI/CD 集成

GitHub Actions

name: Build Packages
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install YAP
        run: |
          wget https://github.com/M0Rf30/yap/releases/latest/download/yap_Linux_x86_64.tar.gz
          tar -xzf yap_Linux_x86_64.tar.gz
          sudo mv yap /usr/local/bin/

      - name: Build Packages
        run: yap build

      - name: Upload Artifacts
        uses: actions/upload-artifact@v4
        with:
          name: packages
          path: artifacts/

GitLab CI

build-packages:
  stage: build
  image: ubuntu:22.04
  before_script:
    - apt-get update && apt-get install -y wget docker.io
    - wget https://github.com/M0Rf30/yap/releases/latest/download/yap_Linux_x86_64.tar.gz
    - tar -xzf yap_Linux_x86_64.tar.gz && mv yap /usr/local/bin/
  script:
    - yap build
  artifacts:
    paths:
      - artifacts/
    expire_in: 1 week

示例

examples 目录中包含可直接构建的完整项目：

示例	描述
circular-deps	循环依赖检测——YAP 会以清晰的错误信息终止
dependency-orchestration	包含 5 个包的项目，自动解析依赖并安排构建顺序
yap	为 YAP 自身打包——包含安装脚本的 Go 应用程序
split-package	一次构建生成多个可安装的包，并支持发行版覆盖
multi-architecture	特定架构的源、依赖和校验和

PKGBUILD 示例

简单的 C 应用程序

pkgname=hello-world
pkgver=1.0.0
pkgrel=1
pkgdesc="A simple Hello World program"
arch=('x86_64')
license=('MIT')
makedepends=('gcc')
source=("hello.c")
sha256sums=('SKIP')

build() { gcc -o hello hello.c; }

package() { install -Dm755 hello "${pkgdir}/usr/bin/hello"; }

Python 应用程序

pkgname=python-myapp
pkgver=2.1.0
pkgrel=1
pkgdesc="My Python application"
arch=('any')
license=('Apache-2.0')
depends=('python3')
makedepends__apt=('python3-dev' 'python3-setuptools')
makedepends__yum=('python3-devel' 'python3-setuptools')
source=("https://pypi.io/packages/source/m/myapp/myapp-${pkgver}.tar.gz")
sha256sums=('...')

build() {
    cd "${srcdir}/myapp-${pkgver}"
    python3 setup.py build
}

package() {
    cd "${srcdir}/myapp-${pkgver}"
    python3 setup.py install --root="${pkgdir}" --optimize=1
}

使用 systemd 的 Web 服务

pkgname=web-service
pkgver=1.5.0
pkgrel=1
pkgdesc="My web service"
arch=('x86_64')
license=('GPL-3.0')
depends=('systemd')
backup=('etc/web-service/config.yml')
source=("web-service-${pkgver}.tar.gz" "web-service.service")
sha256sums=('...' 'SKIP')

build() {
    cd "${srcdir}/web-service-${pkgver}"
    make build
}

package() {
    cd "${srcdir}/web-service-${pkgver}"
    install -Dm755 web-service "${pkgdir}/usr/bin/web-service"
    install -Dm644 ../web-service.service \
        "${pkgdir}/usr/lib/systemd/system/web-service.service"
    install -Dm644 config.yml "${pkgdir}/etc/web-service/config.yml"
    install -dm755 "${pkgdir}/var/lib/web-service"
    install -dm755 "${pkgdir}/var/log/web-service"
}

开发

Make 目标

make all              # clean, deps, fmt, lint, test, doc, build
make build            # build the yap binary
make build-all        # build for linux/darwin/windows, amd64/arm64
make clean            # clean build artifacts
make deps             # download and tidy Go modules
make fmt              # gofmt
make lint             # golangci-lint
make lint-md          # markdownlint
make test             # run all tests (-p 1 -v, sequential required)
make test-coverage    # tests with coverage report (coverage.html)
make release          # create release packages

make doc              # view all package documentation
make doc-serve        # start pkgsite on localhost:8080
make doc-generate     # generate static docs in docs/api/
make doc-package PKG=./pkg/builders/apk

make docker-build DISTRO=ubuntu
make docker-build-all
make docker-list-distros

make i18n-check       # verify localization file integrity
make i18n-stats       # localization statistics

测试

测试必须按顺序运行（-p 1）：

make test
go test ./pkg/source -v
go test ./pkg/builders/deb -v
go test ./pkg/graph -v
go test -race ./pkg/builders/...
go test -timeout 30s ./pkg/download/...

国际化

支持的语言：英语（en）、意大利语（it）。

系统会根据 LANG/LC_ALL/LC_MESSAGES/LANGUAGE 自动检测语言。可使用 --language / -l 覆盖：

yap --language=it build .

要添加语言：将 pkg/i18n/locales/en.yaml 复制为 pkg/i18n/locales/{code}.yaml，完成翻译，在 pkg/i18n/i18n.go 的 SupportedLanguages 中添加语言代码，然后提交 PR。

故障排查

容器运行时

systemctl status docker       # or podman
docker run --rm hello-world   # test access
sudo usermod -aG docker $USER # fix permissions (re-login required)

构建失败

yap build --verbose
yap zap ubuntu-jammy /path/to/project
yap status

权限问题

sudo chown -R $USER:$USER artifacts/
setsebool -P container_manage_cgroup true   # SELinux (Red Hat family)

性能

yap build --skip-sync     # skip package manager sync
yap build --cleanbuild    # clean source before build

参与贡献

1. Fork 此仓库
2. 创建功能分支：git checkout -b feature/my-feature
3. 进行修改并添加测试
4. 运行 make fmt lint test
5. 提交更改并创建拉取请求

社区准则请参阅 CODE_OF_CONDUCT.md。

许可证

GNU General Public License v3.0。请参阅 LICENSE.md。

致谢

• 感谢 Zachary Huff 为 Pacur 做出的贡献；Pacur 是启发 YAP 的项目
• 感谢 Arch Linux 社区提供 PKGBUILD 格式
• 感谢所有贡献者

使用 Go、Cobra、Docker / Podman 构建。

---

报告问题 · 讨论 · Wiki