Ebuild_Manpage

Atom base 只是完整的 category/packagename ，又常叫做"catpkg"。

    sys-apps/sed
    sys-libs/zlib
    net-misc/dhcp

更具体一点，使用包含特定版本的 atom 也是可以接受的。版本必须和前缀一起使用，所以可以将版本号作为后缀添加到 base 上。

    sys-apps/sed-4.0.5
    sys-libs/zlib-1.1.4-r1
    net-misc/dhcp-3.0_p2

版本号可能跟随诸如像 1.2a 或 4.5.2z 的字符，注意这些字母并不代表 alpha, beta 等状态。对于这种情况可以使用可选的后缀，如_alpha, _beta, _pre (pre-release), _rc (release candidate), 或 _p (patch)。这些后缀可以不受限制的任意链接。

有时你可能希望依赖于一个大致的版本，而不是一直指定特定的版本。所以，这里还提供了标准的布尔运算符：

    >media-libs/libgd-1.6
    >=media-libs/libgd-1.6
    =media-libs/libgd-1.6
    <=media-libs/libgd-1.6
    <media-libs/libgd-1.6

现在为了更加精巧，ebuild 还提供了定义屏蔽包和版本范围匹配的功能。另外，这些扩展的前缀和后缀可以和上面提到的 atom 类型以各种方式组合。

• ~

  匹配指定基础版本的任何修订版。如以下例子中，匹配'1.0.2a', '1.0.2a-r1', '1.0.2a-r2'等。

  ~net-libs/libnet-1.0.2a

• !

  阻止该软件包同时安装

  !app-text/dos2unix

• !!

  阻止该软件同时安装，并且明确禁止在升级的时候临时安装它们。该语法从 EAPI 2 开始支持。

  !!<sys-apps/portage-2.1.4_rc1

• *

  匹配基于指定的基础版本的任意版本软件包。=*=之前必须是有效的版本号。例如，=2=是有效的版本号，=2.=则不是，所以=2*=是被允许的，=2.*=则不被允许。

         =dev-libs/glib-2*
         !=net-fs/samba-2*
  

从 EAPI 1 开始，可以限制 atom 匹配特定的 SLOT。这通过在冒号后面加上一个 SLOT 来实现

    x11-libs/qt:3
    ~x11-libs/qt-3.3.8:3
    >=x11-libs/qt-3.3.8:3
    =x11-libs/qt-3.3*:3

从 EAPI 5 开始，一个 slot 依赖可能包含一个可选的 sub-slot，该部分位于常规 slot 之后，并且以=/=字符分隔。

    dev-libs/icu:0/0
    dev-libs/icu:0/49
    dev-lang/perl:0/5.12
    dev-libs/glib:2/2.30

从 EAPI 5 开始，slot 操作符包含一个冒号，后面跟着以下操作符之一：

• *

  表示任何 slot 值都是可以接受的。另外，对于运行时依赖，如果卸载了指定版本的软件包并且在其他的 slot 中将其替换为了另一个匹配的软件包，则该软件包不会损坏。

         dev-libs/icu:*
         dev-lang/perl:*
         dev-libs/glib:*
  

• =

  表示任何 slot 值都是可以接受的。另外，对于运行时依赖，除非安装了 slot 和 sub-slot 等于该软件包在可安装时的最佳安装版本的 slot 和 sub-slot 的匹配软件包，否则该软件包会损坏。

         dev-libs/icu:=
         dev-lang/perl:=
         dev-libs/glib:=
  

• slot=

  表示只能接受特定的 slot 值，否则其行为与普通 slot 操作符相同。

         dev-libs/icu:0=
         dev-lang/perl:0=
         dev-libs/glib:2=
  

为了实现等号 slot 操作符，包管理软件需要存储匹配软件包的最佳已安装版本的 slot/sub-slot 对。该语法仅供包管理软件使用且一定不能在 ebuild 中使用。包管理软件可以通过在保存软件包依赖时在分号和等好之间插入适当的 slot/sub-slot 对来实现次目的。sub-slot 部分在这里必须不能省略（当 SLOT 变量省略 sub-slot 部分时，该软件包被认为是具有一个等于常规 slot 的隐式 sub-slot）。

    dev-libs/icu:0/0=
    dev-libs/icu:0/49=
    dev-lang/perl:0/5.12=
    dev-libs/glib:2/2.30=

从 EAPI 2 开始，任何 atom 可以被匹配的特定 USE flag 设置限制。当和 SLOT 依赖一起使用时，USE 依赖出现在 SLOT 依赖的右手侧。

无条件的 USE 依赖

Example	Meanning
foo[bar,baz]	foo 必须同时启用 bar 和 baz
foo[-bar,baz]	foo 必须禁用 bar 同时启用 baz

有条件的 USE 依赖

Compat Form	Equivalent Expaned Form
foo[!bar?]	bar? ( foo ) !bar? ( foo[-bar] )
foo[bar=]	bar? ( foo[bar] ) !bar? ( foo[-bar] )
foo[!bar=]	bar? ( foo[-bar] ) !bar? ( foo[bar] )

USE 依赖可以指定有关匹配包的 IUSE 中可能或可能不存在的 flag 值为默认假设。这种默认值被通过在 flag 后紧接()或(-)指定。使用()表现为好像一个缺少的 flag 存在并且被启用，或(-)表现为好像 flag 存在并且被禁用。

    media-video/ffmpeg[threads(+)]
    media-video/ffmpeg[-threads(-)]

有时程序或许会根据 USE 变量依赖不同的东西。Portage 提供了一些选项来处理这种情况。注意当使用下面的语法时，每个情况都被认为是在它出现的范围内的的一个 Atom。这意味着每一个 Atom 都有条件的包含多个 Atom 并且可以被嵌套到无限深度。

usevar? ( Atom )

当用户在 USE 中含有 jpeg flag 的时候要 include jpeg library，简单的使用如下语法：

jpeg? (media-libs/jpeg)

!uservar? ( Atom )

如果你仅想在用户在他们的 USE 变量中没有确定选项时 include 一个 package，使用如下语法：

!nophysfs?( dev-games/physfs )

当在你想添加可选功能并默认启用该功能时，这通常非常有用。

usevar? ( Atom if true ) !usevar? ( Atom if false )

对于 C 中的三目算符之类的功能，你必须使用两个语句，一个为普通语句，一个为反向语句。如果一个软件包使用 GTK2 和 GTK1，但不是同时，那么你可以像这样处理：

gtk2? ( =x11-libs/gtk+-2*) !gtk2? ( =x11-libs/gtk+-1*)

这种方法模式优先使用 GTK2 库。

|| ( Atom Atom … )

当一个软件包可以使用几个不同的软件包但不适合使用虚包时，这个语法可以被轻松使用。

    || (
            app-games/unreal-tournament
            app-games/unreal-tournament-goty
    )

这里我们看到 unreal-tourament 有一个普通的版本，还有一个 goty 的版本。因为它们提供相同的基本文件集，所以一个软件包可以使用其中任意一个。因为使用范围很小，所以添加虚包时不合适的。

另一个好的例子是当软件包可以使用多个视频接口构建，但仅能使用其中一个接口。

    || (
            sdl? ( media-libs/libsdl )
            svga? ( media-libs/svgalib )
            opengl? ( virtual/opengl )
            ggi? ( media-libs/libggi )
            virtual/x11
    )

这里只有一个软件包将会被选中，并且偏好顺序由它们出现的顺序决定。所以 sdl 是最佳选择，接下来是 svga，然后是 opengl，再是 ggl，并且 X 作为默认如果用户没有指定上面提到的任何一种。

注意，如果列出的任何一个软件包已经 merge，包管理器将会使用它并认为依赖已满足。

• defualt

  为当前正在执行的阶段调用默认阶段函数实现。该方程从 EAPI 2 开始支持。

• defualt_*

  从 EAPI 2 开始，默认 pkg_nofetch 和 src_*阶段函数可以通过方程以 defualt_开头并以相应的阶段函数名结尾的函数访问。例如，调用名为 defualt_src_compile 的函数等同于调用 src_compile 函数的默认实现。

  Defualt Phase Functions
  defualt_src_unpack
  defualt_src_prepare
  defualt_src_comfigure
  defualt_src_compile
  defualt_src_test

• assert [reason]

  检查 shell 的 PIPESTATUS 数组变量的值，如果有任何非 0 值（表示失败），调用 die 并且 reason 作为失败消息。

• die [reason]

  使当前 emerge 程序中止。最后显示的信息将包括 reason。

  从 EAPI 4 开始，所有 helper 每当发生某种错误就自动调用 die。helper 调用可以以 nofatal 为前缀，以防止错误变成 fatal。

• nofatal [helper]

  执行 helper 并且如果失败也不调用 die。nofatal helper 从 EAPI 4 开始可用。

• use <USE item>

  如果 USE item 在 USE 变量中，函数会默默返回 0（aka shell true）。如果 USE item 不在 USE 变量中，函数会默默返回 1（aka shell false）。usev 时 use 的详细版本。

• usev <USE item>

  就像 use，但在 use 返回 true 的时候同时 echo USE item。

• usex <USE flag> [true output] [false output] [true suffix] [false suffix]

  如果 USE flags 设置了，echo [true output][true suffix] （默认为"yes"），否则 echo [false output][false suffix] （默认为"no"）。usex heper 从 EAPI 5 开始可用。

• use_with <USE item> [configure name] [configure opt]

  对于创建自定义选项以传递到配置脚本很有用。如果 USE item 在 USE 变量中并且 configure opt 指定了，那么字符串–with-[configure-name]=[configure opt]将会被 echo。如果 configure opt 没有被指定，那么仅–with-[configure name]会被 echo。如果 USE item 不在 USE 变量中，那么字符串–without-[configure name]将会被 echo。如果 configure name 没有被指定，那么 USE item 将会在其位置上使用。从 EAPI 4 开始，空的 configure opt 参数可以被识别。在 EAPI 3 和更早中，空的 configure opt 参数被视为未被提供。

        USE="opengl"
        myconf=$(use_with opengl)
        (myconf now has the value "--with-opengl")
  
        USE="jpeg"
        myconf=$(use_with jpeg libjpeg)
        (myconf now has the value "--with-libjpeg")
  
        USE=""
        myconf=$(use_with jpeg libjpeg)
        (myconf now has the value "--without-libjpeg")
  
        USE="sdl"
        myconf=$(use_with sdl SDL all-plugins)
        (myconf now has the value "--with-SDL=all-plugins")
  

• use_enable <USE item> [configure name] [configure opt]

  和上面的 use_with 一样，除了配置选项是 --enable- 替代 --with- 、 --disable- 替代 --without- 。从 EAPI 4 开始，空的 configure opt 参数可以被识别。在 EAPI 3 和更早中，空的 configure opt 参数被视为未被提供。

• has <item> <item list>

  如果 item 在 item list 中，则 has 返回 0，否则返回 1。还有另外一个版本，hasv，会有条件的 echo item。

  item list 由 IFS 变量分隔。该变量的默认值为' '或空格。这是一个 bash 设置。

• hasv <item> <item list>

  就像 has，但在 has 返回 true 的时候同时 echo item。

• has_version [-b] [-d] [-r] [--host-root] <category/package-version>

  检查 category/package-version 是否已安装。该参数接受在 DEPEND 变量中可接受的所有值。如果 category/package-version i 已安装，该函数返回 0，否则返回 1。该软件包默认在 ROOT 中搜索。

  在 EAPI 5 和 EAPI 6 中，如果提供了–host-root 选项，则软件包在 build host 中搜索。

  在 EAPI 7 和之后，令人困惑的–host-root 选项被替换为-b，和 build host 中 BDEPEND 满足的依赖关系对应。类似的，-d 选项对应 SYSROOT 中的 DEPEND 并且-r 选项对应 ROOT 中的 RDEPEND。

• best_version [-b] [-d] [-r] [--host-root] <package name>

  该函数将会在当前已安装软件包的数据库中查找 package name 并且 echo 找到的软件包的“best version”，或者如果没有安装则为空。软件包默认在 ROOT 中搜索。它接受于 has_version 一样的选项。

        VERINS="$(best_version net-ftp/glftpd)"
        (VERINS now has the value "net-ftp/glftpd-1.27" if glftpd-1.27 is       installed)
  

• einfo disposable message

  和 elog 一样，当应该在消息对用户不重要时使用（像构建过程中的进度或状态信息）。

• elog informative message

  如果你需要显示信息并且你希望用户阅读并提起注意，那么使用 elog。它就像 echo 一样，但是添加一点输出，以引起用户的注意。信息还会被 portage 记录以供之后查看。

• ewarn warning message

  和 einfo 一样，但是应该对用户显示警告时使用。

• eqawarn QA warning message

  和 einfo 一样，但应该在对用户显示 QA 警告时使用

• eerror error message

  和 einfoi 一样，但应该在对用户显示错误时使用。

• ebegin helpful message

  就像 einfo，我们输出 helpful message，然后提示以下操作可能需要一些时间才能完成。一旦任务完成，你需要调用 eend。

• eend <status> [error message]

  跟随在 ebegin 消息之后，并使用适当"OK"或"!!"（错误）标记。如果 status 是非 0 的，那么附加的 error message 会被显示。

• unpack <source> [list of more sources]

  该函数解压所源文件列表到当前目录中。该函数会将 source 附加到 DISTDIR 变量中。

• econf [configure options]

  用于替代 configure。执行：

        ${ECONF_SOURCE:-.}/configure \
            ${CBUILD:+--build=${CBUILD}} \
            --datadir="${EPREFIX}"/usr/share \
            --host=${CHOST} \
            --infodir="${EPREFIX}"/usr/share/info \
            --localstatedir="${EPREFIX}"/var/lib \
            --prefix="${EPREFIX}"/usr \
            --mandir="${EPREFIX}"/usr/share/man \
            --sysconfdir="${EPREFIX}"/etc \
            ${CTARGET:+--target=${CTARGET}} \
            --disable-dependency-tracking \
            ${EXTRA_ECONF} \
            configure options || die "econf failed"
  

  注意 EXTRA_ECONF 仅适用于用户，不适用于 ebuild writer。如果你希望传递更多的参数到 configure，只需将额外的参数传递给 econf。另外注意如果 configure 脚本失败，econf 自动调用 die。从 EAPI 3 开始，econf 使用被之前的 EAPI 值忽略的${EPREFIX}变量。从 EAPI 4 开始，如果字符串 disable-dependency-tarcking 出现在 configure –help 的输出中，econf 会在参数中添加–disable-dependency-tracking。从 EAPI 5 开始，如果字符串 disable-silent-rules 出现在 configure –help 中，econf 会在参数中添加 disable-silent-rules。

• emake [make options]

  在 ebuild 中必须使用它来代替 make。执行 ${MAKE:-make} ${MAKEOPTS} make options ${EXTRA_EMAKE} ，并且从 EAPI 4 开始会自动调用 die 。

  MAKEOPTS 变量由用户设置，所以能够开启一些像并行构建的特性。更多细节请见 make.conf(5)。

  EXTRA_EMAKE knob 是 portage 的特性，所以开发者可以在调试 ebuild 时覆盖一些东西。这不是任何 EAPI 规范的一部分。

  警告 ：你必须确定你的构建在并行编译上没有任何问题(make -j2)。应该对它进行彻底的测试，因为众所周知并行编译有时会失败，但又不总是如此。如果你确定你的软件包在并行构建中失败，并且无法解决这个问题，那么你应该显式的运行 emake -j1 。这是不得已的办法，因为它会显著的降低具有很多处理器的在系统的构建速度。

• einstall [make options] 这用来代替 make install。执行：

        make \
            prefix=${ED}/usr \
            datadir=${ED}/usr/share \
            infodir=${ED}/usr/share/info \
            localstatedir=${ED}/var/lib \
            mandir=${ED}/usr/share/man \
            sysconfdir=${ED}/etc \
            ${EXTRA_EINSTALL} \
            make options \
            install
  

  请 不 要用它代替 emake install DESTDIR=${D} 。那是安装 make-based 软件包的首选方法。还有，不要使用 EXTRA_EINSTALL 变量，因为它仅适用于用户。

• docompress [-x] <path> [list of more paths]

  从 EAPI 4 开始，docompress helper 用来管理用以从可选的压缩中包括或排除的文件的列表。如果首个参数是-x，其后每个后续参数都添加到排除列表中。否则，将每个参数添加到包含列表。包含列表最初包含 /usr/share/doc 、 /usr/share/info 和 /usr/share/man 。排除列表最初包含 /usr/share/doc/${PF}/html 。

  可选压缩应在 src_install 完成后执行，并且在执行任何后续阶段函数之前。对于包含列表中的每一项，假设它有 D 变量前置的值，那么：

  • 如果它是一个目录，则应将其时为该目录下的每个文件或目录都在包含列表中。
  • 如果项目是文件，则可以将其压缩除非如下所述已将其排除在外。
  • 如果项目不存在，则将其忽略。

  ---

  一个项目是否被排除根据如下决定：对于每个在排除列表中的项目，假设它具有 D 变量前置的值，那么：

  • 如果它是一个目录，则应将其时为该目录下的每个文件或目录都在排除列表中。
  • 如果项目是一个文件，则它将不会被压缩。
  • 如果项目不存在，则将其忽略。

• dosed s:orig:change:g <filename>

  从 EAPI 4 开始，dosed helper 不在存在。ebuild 应该直接调用 sed（并且假设为 GNU sed）

  在\({ED}中的文件名上执行 sed。如果未给出表达式，则将`s:\){D}::g`作为默认表达式。注意该表达式没有使用便宜前缀。

  dosed s:/usr/local:/usr:g /usr/bin/some-script 在 ${ED}/usr/bin/some-script 上运行 sed。

• dodir <path> [more paths]

  在${ED}中创建目录。

  dodir /usr/lib/apache 创建 ${ED}/usr/lib/apache 。请注意，do*函数将会为你运行 dodir。

  如果该目录在 merge 的时候为空，那么请改用 keepdir。

• diropts [options for install(1)]

  可用于为在 dodir 中使用的安装函数定义选项。默认为-m0755

• into <path>

  为其他函数像 dobin、dosbin、doman、doinfo、dolib 设置 root(DESTTREE)

  默认 root 是/usr

• keepdir <path> [more paths]

  类似于 dodir，但是用户创建原本为空的目录。PMS 未定义对完全空目录的处理，使用 keepdir 可以保证它们被追踪。

• dobin <binary> [list of more binaries]

  安装二进制或一列表的二进制到 DESTTREE/bin 中。创建所有必要的目录。

• dosbin <binary> [list of more binaries]

  安装二进制或一列表的二进制到 DESTTREE/sbin 中。创建所有必要的目录。

• doinitd <init.d script> [list of more init.d scripts]

  安装 Gentoo init.d 脚本。它们将会被安装到 Gentoo init.d 脚本的正确位置(etc/init.d)。创建所有必要的目录。

• doconfd <conf.d file> [list of more conf.d files]

  安装 Gentoo conf.d 文件。它们将会被安装到 Gentoo conf.d 文件的正确位置(etc/conf.d)。创建所有必要的目录。

• doenvd <env.d entry> [list of more conf.d entries]

  安装 Gentoo env.d 条目。它们将会被安装到 Gentoo env.d 条目的正确位置(etc/env.d)。创建所有必要的目录。

• dolib <libraray> [list of more libraries]
• dolib.a <libraray> [list of more libraries]

• dolib.so <libraray> [list of more libraries]

  安装库或一个列表的库到 DESTTREE/lib。创建所有必要的目录。

• libopts [options for install(1)]

  可用于为在 dolib 函数中使用的安装函数的定义选项。默认值为-m0644

• doman [-i18n=<locale>] <man-page> [list of more man-pages]

  根据手册文件结尾将 manual-pages 安装到 /usr/share/man/man[0-9n] 中。如果文件尚未压缩，则将其压缩。你可以用-i18n 选项指定特定语言环境的 manpages。那么 man-page 将会被安装到 /usr/share/man/<locale>/man[0-9n] 中。从 EAPI 2 开始，一个在文件名中包含语言环境的特定语言环境 manpage 将会被安装到 /usr/share/man/<locale>/man[0-9n] ，如果删除了文件名的语言环境部分，-i18n 选项将会没有效果。例如，在 EAPI2 中，命名为 foo.<locale>.1 的 manpage 将会安装为 /usr/share/man/<locale>/man1/foo.1 。从 EAPI 4 开始，-i18n 选项将会优先于语言环境后缀。

• dohard <filename> <linkname>

  从 EAPI 4 开始，dohard helper 不再继续存在。ebuild 应该直接调用 ln(1)。

• dosym <filename> <linkname>

  执行 ln 命令以创建符号链接。

• doheader [-r] <file> [list of more files]

  将给定的头文件安装到/usr/include 中，默认文件模式为 0644（可以通过 insopts 函数修改）。设置-r 设置递归。doheader helper 从 EAPI 5 开始可用。

• dohtml [-a filetypes] [-r] [-x list-of-dirs-to-ignore] [list-of-files-and-dirs]

  将文件列表（以空格分隔）中的文件安装到/usr/share/doc/${PF}/html 中，提供的文件以.htm、.html、.css、.js 结尾，设置-a 限制将会包含什么类型的文件，-A 追加到默认列表，设置-x 设置要排除的目录（默认不包括 CVS），-p 设置文档前缀，-r 设置为递归。

• doinfo <info-file> [list of more info-files]

  安装 info-page 到 DESTDIR/info 中。文件将会自动被 gzip 压缩。创建所有必要的目录。

• domo <locale-file> [list of more locale-files]

  根据 local-file 的结尾将 locale-file 安装到 DESTDIR/usr/share/locale/[LANG]中。创建所有必要的目录。

• fowners [-h|-H|-L|-P|-R] [user][:group] <file> [files]

• fperms [-R] <permissions> <file> [files]

  执行 chown(foweners)或 chmod(fperms)更改文件权限。

• insinto [path] 设置 doins 函数的目的路径。

  默认路径为/。

• insopts [options for install(1)]

  可用于定义 doins 中使用的安装函数的选项。默认值为-m0644。

• doins [-r] <file> [list of more files]

  安装文件到被 insinto 控制的路径。该函数使用 install(1)。创建所有必须的目录。设置-r 设置递归。从 EAPI 4 开始，doins 和 newins 都保留符号链接。在 EAPI 3 或更早，符号链接被取消引用而不是保留。

• exeinto [path]

  设置 doexe 函数的目的路径。

  默认路径为/。

• exeopts [options for install(1)]

  可用于为 doexe 中使用的安装函数定义选项。默认值为-m0755。

• doexe <executable> [list of more executables]

  安装可执行文件到被 exeinto 控制的路径中。该函数使用 install(1)。创建所有必要的目录。

• docinto [path]

  设置安装到文档树中时 dodoc 和 dohtml 所使用的子目录（基于/usr/share/doc/${PF}/）。默认没有子目录，或仅""。

• dodoc [-r] <document> [list of more documents]

  安装文档或一列表的文档到 /usr/share/doc/${PF}/<docinfo path> 。文档被标记为压缩。创建所有必要的目录。从 EAPI 4 开始，通过开启新的-r 选项启用对递归的支持。

• newbin <old file> <new filename>
• newsbin <old file> <new filename>
• newinitd <old file> <new filename>
• newconfd <old file> <new filename>
• newenvd <old file> <new filename>
• newlib.so <old file> <new filename>
• newlib.a <old file> <new filename>
• newman <old file> <new filename>
• newins <old file> <new filename>
• newexe <old file> <new filename>

• newdoc <old file> <new filename>

  所有这些函数就像 do*函数一样，但是它们仅处理一个文件，并且文件被安装为[new filename]。从 EAPI 5 开始，当第一个参数为 - （连字符）时，将读取标准输入。