# Gentoo Overlay 与自定义 ebuild

URL: https://caijiao.org/gentoo/overlay-ebuild
Source: docs/gentoo/overlay-ebuild.md
Description: 本章介绍 Gentoo Overlay 的概念和使用方法，以及如何创建和管理自定义 ebuild，实现软件包扩展与定制。

在掌握日志分析与调试后，下一步是 **学习 Gentoo Overlay 与自定义 ebuild 的使用方法**，扩展软件包来源和定制功能。

## 一、什么是 Overlay

- **Overlay**：Portage 的扩展软件仓库  
- 允许用户获取官方 Portage 未包含的软件包  
- 支持自定义软件包和实验性版本  

常用 Overlay 管理工具：`eselect-repository` 或 `layman`（旧版）

## 二、添加 Overlay

1. 使用 `eselect-repository` 添加官方或第三方 Overlay：

```bash
eselect repository list          # 查看已启用 Overlay
eselect repository enable guru-mirror
emerge --sync guru-mirror
````

2. 手动添加 Overlay（使用 git）：

```bash
git clone https://github.com/username/overlay.git /var/lib/layman/overlayname
```

3. 更新 Overlay：

```bash
emerge --sync overlayname
```

## 三、自定义 ebuild

1. ebuild 目录结构示例：

```
my-overlay/
└── app-misc/
    └── hello/
        └── hello-1.0.ebuild
```

2. 创建简单 ebuild 示例 `hello-1.0.ebuild`：

```bash
EAPI=8

DESCRIPTION="Hello World example"
HOMEPAGE="https://example.com"
SRC_URI="https://example.com/hello-1.0.tar.gz"

LICENSE="GPL-2"
SLOT="0"
KEYWORDS="~amd64 ~x86"

src_install() {
    dodoc README
    dobin hello.sh
}
```

3. 添加到 Overlay 并安装：

```bash
ebuild hello-1.0.ebuild manifest
emerge --ask app-misc/hello
```

## 四、管理自定义 ebuild

- 定期更新 Overlay 与 ebuild
- 使用 `repoman` 检查 ebuild 语法和质量：

```bash
repoman manifest app-misc/hello
repoman full
```

- 保持版本控制（如 git）管理自定义 Overlay

## 五、建议操作

- 对实验性软件使用 Overlay，避免破坏稳定系统
- 熟悉 ebuild 格式和 Portage 构建流程
- 使用 Overlay 管理多个软件源，实现灵活定制