Gentoo Ebuild 编写基本指南

From Gentoo Wiki
Jump to:navigation Jump to:search
This page is a translated version of the page Basic guide to write Gentoo Ebuilds and the translation is 31% complete.
Outdated translations are marked like this.
Other languages:

这篇文章 包含了关于 ebuild 开发的初学者说明。

Write an ebuild to install a piece of software on Gentoo, when there are no suitable preexisting ebuilds. It's a relatively straight forward task, and is the only way to cleanly install most "third party" software system-wide. The ebuild will allow the package manager to track every file installed to the system, to allow clean updates and removal.

提示
From the ebuild article: An ebuild file is a text file, usually stored in a repository, which identifies a specific software package and tells the Gentoo package manager how to handle it. Ebuilds use a bash-like syntax style and are standardized through the Package Manager Specification, by adhering to a specific EAPI version.

Ebuilds contain metadata about each version of a piece of available software (name, version number, license, home page address...), dependency information (both build-time and run-time), and instructions on how to build and install the software (configure, compile, build, install, test...).

Once an ebuild is working, it can be shared by submitting it in a pull request or in a separate ebuild repository and making it accessible publicly. With a little effort, ebuilds can be proposed and maintained in the GURU repository.

附注
See the dev manual on writing ebuilds for full reference documentation. See the quick start to writing ebuilds in the dev manual for further examples of how to write ebuilds. See the ebuild article for explanations about ebuilds themselves, the ebuild repository article about what an ebuild repository is, and the creating an ebuild repository article on how to create them.

ebuild 仓库

In order for ebuilds to be available to Portage, they are placed in an ebuild repository that is configured for Portage through /etc/portage/repos.conf (see the section on repository management for general information about working with ebuild repositories).

Create an ebuild repository to experiment in, while following on with this guide. The rest of the article will consider a repository in /var/db/repos/example_repository.

eselect repository 会简单创建一个仓库：

root #eselect repository create example_repository
附注
Ebuilds can be installed with the ebuild command, however this is not recommended - this command is for development purposes only. This article will use the ebuild command with the ebuild file for testing during development, but be sure to use the emerge command with an ebuild in a repository otherwise.

如何创建一个 ebuild

Ebuilds are simply text files, in their most basic form. All that is needed to start writing ebuilds is a text editor, to provide installable software packages for Gentoo.

附注
In this section, {CATEGORY}, {PN}, and {P} represent package category, package name, and package name and version, and are standard variables used in ebuilds. Together, these variables can represent a version specifier.

Some editors have optional ebuild functionality, in that case there skip to the appropriate section. Otherwise a skeleton ("template") may be used to get started quicker.

从脚手架开始

其他编辑器的用户从 skel.ebuild 手动复制：

user $mkdir --parents /var/db/repos/example_repository/{CATEGORY}/{PN}
user $cp /var/db/repos/gentoo/skel.ebuild /var/db/repos/example_repository/{CATEGORY}/{PN}
user $cd /var/db/repos/example_repository/{CATEGORY}/{PN}
user $nano {P}.ebuild

Vim

当创建一个空的 ebuild 文件时，vim 插件可以自动生成脚手架。

安装 app-vim/gentoo-syntax 后，创建相应 ebuild 目录，然后在命令行使用 vim 打开新的“{P}.ebuild”文件后，可以自动生成能修改和保存的基本脚手架：

user $mkdir --parents /var/db/repos/example_repository/{CATEGORY}/{PN}
user $cd /var/db/repos/example_repository/{CATEGORY}/{PN}
user $vim {P}.ebuild

Emacs

Emacs 用户则取决于具体的 Emacs 发行版。（分别由 app-emacs/ebuild-mode 或 app-xemacs/ebuild-mode 提供）

Language server

There is a language server for gentoo ebuild.

示例

为了展示典型过程，这个示例会为 2.6.1 版本的 Scrub 创建 ebuild（假如还没有这个 ebuild）。

在之前创建的 ebuild 仓库 中，创建存放 ebuild 的目录：

user $mkdir -p /var/db/repos/example_repository/app-misc/scrub

把 shell 工作目录改为新的路径：

user $cd /var/db/repos/example_repository/app-misc/scrub
提示
Some shells, such as Bash, provide the last parameter of the previous command in the "$_" variable. This can be used to call the newly created directory without specifying the path on the command line, as long as this is used as the directly next command.
user $cd $_

This example will use Vim to create the ebuild file and provide a skeleton to serve as a basis to write the ebuild on, but use editor of choice (see previous section about using Emacs, or the skeleton file):

user $vim ./scrub-2.6.1.ebuild

Add important information about the new package by setting the ebuild-defined variables: DESCRIPTION, HOMEPAGE, SRC_URI, LICENSE. Licenses like BSD-clause-3 which are not found in the tree might be mapped in metadata :

文件 scrub-2.6.1.ebuild使用 vim 从模板里编辑新文件。
# Copyright 1999-2024 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
 
EAPI=8
 
DESCRIPTION="Some words here"
HOMEPAGE="https://github.com/chaos/scrub"
SRC_URI="https://github.com/chaos/scrub/releases/download/2.6.1/scrub-2.6.1.tar.gz"
 
LICENSE="GPL-2"
SLOT="0"
KEYWORDS="~amd64 ~x86"
IUSE=""
 
DEPEND=""
RDEPEND="${DEPEND}"
BDEPEND=""

This — with the omission of those lines with ="" — is the minimum information necessary to get something that will work. Ebuilds inheriting certain eclasses might come with a different set of minimal information, e.g. ant-jsch-1.10.9.ebuild. Save the file - voila an ebuild, in its most basic form, it's that simple!

附注
Using the ${PN} variable inside SRC_URI is allowed, though this is not necessarily best practice. While it may be shorter to type, there is some reasoning on why not to use it that may be worth consideration.

代码 avoid using PN as such
SRC_URI="https://github.com/gentoo/${PN}/releases/download/${PV}/${P}.tar.gz"
# Reads better as, e.g.
SRC_URI="https://github.com/gentoo/gentoo/releases/download/${PV}/${P}.tar.gz"

See this ebuild file format policy guide page for more recommendations.

It is possible to test fetching and unpacking the upstream sources by the new ebuild, using the ebuild command:

user $GENTOO_MIRRORS="" ebuild ./scrub-2.6.1.ebuild manifest clean unpack
Appending /var/db/repos/customrepo to PORTDIR_OVERLAY...
>>> Downloading 'https://github.com/chaos/scrub/releases/download/2.6.1/scrub-2.6.1.tar.gz'
--2023-03-03 23:35:13--  https://github.com/chaos/scrub/releases/download/2.6.1/scrub-2.6.1.tar.gz
Resolving github.com... 140.82.121.4
Connecting to github.com|140.82.121.4|:443... connected.
HTTP request sent, awaiting response... 302 Found
Location: https://objects.githubusercontent.com/github-production-release-asset-2e65be/23157201/405a65b8-2d4d-11e4-8f82-3e3a9951b650?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIWNJYAX4CSVEH53A%2F20230303%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20230303T223513Z&X-Amz-Expires=300&X-Amz-Signature=7d7d925ff8392ee2ba12028c73c8d8c3b3a7086b5aec11bbfae335222a4f2eb0&X-Amz-SignedHeaders=host&actor_id=0&key_id=0&repo_id=23157201&response-content-disposition=attachment%3B%20filename%3Dscrub-2.6.1.tar.gz&response-content-type=application%2Foctet-stream [following]
--2023-03-03 23:35:13--  https://objects.githubusercontent.com/github-production-release-asset-2e65be/23157201/405a65b8-2d4d-11e4-8f82-3e3a9951b650?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIWNJYAX4CSVEH53A%2F20230303%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20230303T223513Z&X-Amz-Expires=300&X-Amz-Signature=7d7d925ff8392ee2ba12028c73c8d8c3b3a7086b5aec11bbfae335222a4f2eb0&X-Amz-SignedHeaders=host&actor_id=0&key_id=0&repo_id=23157201&response-content-disposition=attachment%3B%20filename%3Dscrub-2.6.1.tar.gz&response-content-type=application%2Foctet-stream
Resolving objects.githubusercontent.com... 185.199.108.133, 185.199.109.133, 185.199.110.133, ...
Connecting to objects.githubusercontent.com|185.199.108.133|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 362536 (354K) [application/octet-stream]
Saving to: '/var/cache/distfiles/scrub-2.6.1.tar.gz.__download__'
 
/var/cache/distfiles/scrub-2.6.1. 100%[============================================================>] 354.04K  --.-KB/s    in 0.08s   
 
2023-03-03 23:35:13 (4.31 MB/s) - '/var/cache/distfiles/scrub-2.6.1.tar.gz.__download__' saved [362536/362536]
 
 * scrub-2.6.1.tar.gz BLAKE2B SHA512 size ;-) ...                                                                               [ ok ]
>>> Unpacking source...
>>> Unpacking scrub-2.6.1.tar.gz to /var/tmp/portage/app-misc/scrub-2.6.1/work
>>> Source unpacked in /var/tmp/portage/app-misc/scrub-2.6.1/work

这会下载并解压源压缩包。如果没有错误的话，输出内容会像示例一样。

For some exceptionally simple packages like this one, that do not need patching or other more advanced treatment, the ebuild may work just so - with no further adjustments needed.

尤其刚开始时，最好在这步运行测试套件：

root #ebuild scrub-2.6.1.ebuild clean test install

要在系统实际安装新 ebuild 的话，运行：

root #ebuild scrub-2.6.1.ebuild clean install merge

在 ebuld 中为上游源代码打补丁

A patch can be created from the unpacked source code as explained in the Creating a patch article. Patches should then be put in the files directory and be listed in an array called PATCHES as explained in the devmanual:

代码 将在 src_prepare 期间应用补丁
PATCHES=(
	"${FILESDIR}"/${P}-foo.patch
	"${FILESDIR}"/${P}-bar.patch
)
 
src_prepare() {
    default
    ...
}

QA 测试

Use pkgcheck (dev-util/pkgcheck) to check for QA errors in an ebuild:

user $pkgcheck scan

另请参阅

外部资源

Retrieved from "https://wiki.gentoo.org/index.php?title=Basic_guide_to_write_Gentoo_Ebuilds/zh-cn&oldid=1270152"