JAVA-UTILS-2.ECLASS

章节: eclass-manpages (5)
更新: 2024 年 11 月
索引返回主内容

名称

java-utils-2.eclass - Java 软件包的基础 eclass

描述

此 eclass 提供 java-pkg-2.eclass 和 java-pkg-opt-2.eclass 以及 ebuilds 使用的功能。

此 eclass 不应直接从 ebuild 中继承。相反，您应该为 Java 软件包继承 java-pkg-2，或者为具有可选 Java 支持的软件包继承 java-pkg-opt-2。

支持的 EAPIS

7 8

功能

java-pkg_doexamples [--subdir <subdir>] <file1/dir1> [<file2> ...]

将给定的参数安装到 /usr/share/doc/${PF}/examples。如果您只给它一个参数并且它是一个目录，它将安装该目录中的所有内容到 examples 目录。

Parameters:
--subdir - If the examples need a certain directory structure
$* - list of files to install

Examples:
        java-pkg_doexamples demo
        java-pkg_doexamples demo/* examples/*

java-pkg_addres <jar> <dir> [<find arguments> ...]

将资源文件添加到现有的 jar。重要的是，给定的目录实际上是相应资源树的根目录。目标目录以及 sources.lst、MANIFEST.MF、*.class、*.jar 和 *.java 文件将被自动排除。符号链接将始终被跟踪。其他参数将传递给 find。

Parameters:
$1 - jar file
$2 - resource tree directory
$* - arguments to pass to find

Example:
        java-pkg_addres ${PN}.jar resources ! -name "*.html"

java-pkg_rm_files <File1.java> [File2.java] ...

删除 ${S} 中不需要的文件。

偶尔，您会遇到需要删除文件的场景，无论是单元测试还是普通的 Java 类。

您可以通过以下两种方式使用此功能： - 在 src_prepare() 中自己调用它并将要删除的文件列表提供给 java-pkg_rm_files。 - 在 ebuild 中定义一个名为 JAVA_RM_FILES 的数组，其中包含要删除的文件列表。

两种方式都有效，开发者可以选择自己喜欢的。如果定义了 JAVA_RM_FILES 数组，它将在 src_prepare 阶段被自动传递给 java-pkg_rm_files。

请参见 java-utils-2_src_prepare。

        java-pkg_rm_files File1.java File2.java

java-pkg_dojar <jar1> [<jar2> ...]

安装任意数量的 jar。jar 默认情况下将安装到 /usr/share/${PN}(-${SLOT})/lib/ 中。您可以使用 java-pkg_jarinto 更改此路径。您永远不应该安装文件名中包含软件包版本的 jar。相反，请使用下面定义的 java-pkg_newjar。

        java-pkg_dojar dist/${PN}.jar dist/${PN}-core.jar

java-pkg_regjar </path/to/installed/jar>

在 package.env 中记录已安装（在 ${D} 中）的 jar。这主要是在软件包有 make 或自定义脚本来安装东西时使用。

警告：如果您想使用 shell 展开，则必须使用 ${D}/...，因为此函数中的 for 将无法展开路径，以下是一个示例

  java-pkg_regjar ${D}/opt/my-java/lib/*.jar

java-pkg_newjar <path/to/oldname.jar> [<newname.jar>]

安装具有新名称的 jar（默认值为 $PN.jar）

例如，安装没有版本的版本化 jar

java-pkg_addcp <classpath>

将某项内容添加到软件包的类路径中。对于 jar，您应该使用 dojar、newjar 或 regjar。这通常用于将目录添加到类路径。此函数的参数将附加到 JAVA_PKG_CLASSPATH

java-pkg_doso <path/to/file1.so> [...]

安装任意数量的 JNI 库。它们默认情况下将安装到 /usr/lib 中，但可以使用 java-pkg_sointo 更改此路径

Example:
        java-pkg_doso *.so

java-pkg_regso <file1.so> [...]

在 package.env 中注册已安装的 JNI 库。

Parameters:
$@ - JNI libraries to register

Example:
        java-pkg_regso *.so /path/*.so

java-pkg_jarinto </path/to/install/jars/into>

更改随后的 java-pkg_dojar 调用安装 jar 的路径。

java-pkg_sointo </path/to/install/sofiles/into>

更改随后的 java-pkg_doso 调用安装 JNI 库的路径。

java-pkg_dohtml <path/to/javadoc/documentation> [...]

安装 Javadoc HTML 文档。建议使用 java-pkg_dojavadoc。

        java-pkg_dohtml dist/docs/

java-pkg_dojavadoc [--symlink destination] <path/to/javadocs/root>

安装 javadoc 文档。这应该由 doc 使用标志控制。

Parameters:
$1: optional --symlink creates to symlink like this for html
           documentation bundles.
$2: - The javadoc root directory.

Examples:
        java-pkg_dojavadoc docs/api
        java-pkg_dojavadoc --symlink apidocs docs/api

java-pkg_dosrc <path/to/sources> [...]

安装包含软件包源代码的 zip 文件，以便它可以在诸如 eclipse 和 netbeans 之类的 IDE 中使用。Ebuild 需要 DEPEND 于 app-arch/zip 才能使用它。它也应该由 USE=source 控制。

Example:
java-pkg_dosrc src/*

java-pkg_dolauncher <filename> [options]

创建一个包装器脚本以启动/运行此软件包。如有必要，包装器将切换到适当的 VM。

如果软件包只安装一个具有设置的 Main-class 属性的 jar，则可以不带参数调用它。包装器将被命名为 ${PN}。

Parameters:
$1 - filename of launcher to create
$2 - options, as follows:
 --main the.main.class.to.start
 --jar /the/jar/too/launch.jar or just <name>.jar
 --java_args 'Extra arguments to pass to java'
 --pkg_args 'Extra arguments to pass to the package'
 --pwd Directory the launcher changes to before executing java
 -into Directory to install the launcher to, instead of /usr/bin
 -pre Prepend contents of this file to the launcher

java-pkg_dowar

安装 war 文件。TODO 文档

java-pkg_jar-from [--build-only] [--with-dependencies] [--virtual] [--into dir] <package> [<package.jar>] [<destination.jar>]

创建一个指向特定软件包中 jar 的符号链接。许多 java 软件包在 lib/ 目录中包含依赖项。您可以使用此函数来替换这些捆绑的依赖项。依赖项将被记录到 package.env DEPEND 行中，除非传递 “--build-only” 作为第一个参数，用于那些仅在构建时必须存在而在运行时不需要的 jar（例如 junit 测试）。

Example: get all jars from xerces slot 2
        java-pkg_jar-from xerces-2

Example: get a specific jar from xerces slot 2
        java-pkg_jar-from xerces-2 xml-apis.jar

Example: get a specific jar from xerces slot 2, and name it differently
        java-pkg_jar-from xerces-2 xml-apis.jar xml.jar

Example: get junit.jar which is needed only for building
        java-pkg_jar-from --build-only junit junit.jar

Parameters
        --build-only - makes the jar(s) not added into package.env DEPEND line.
          (assumed automatically when called inside src_test)
        --with-dependencies - get jars also from requested package's dependencies
          transitively.
        --virtual - Packages passed to this function are to be handled as virtuals
          and will not have individual jar dependencies recorded.
        --into $dir - symlink jar(s) into $dir (must exist) instead of .
$1 - Package to get jars from, or comma-separated list of packages in
        case other parameters are not used.
$2 - jar from package. If not specified, all jars will be used.
$3 - When a single jar is specified, destination filename of the
        symlink. Defaults to the name of the jar.

java-pkg_jarfrom

请参见 java-pkg_jar-from

java-pkg_getjars [--build-only] [--runtime-only] [--with-dependencies] <package1>[,<package2>...]

获取任何数量的软件包提供的类路径。除其他事项外，这可以传递给 'javac -classpath'。提供软件包被记录为 package.env DEPEND 行中的依赖项，除非传递 “--build-only” 作为第一个参数，用于那些仅在构建时必须存在而在运行时不需要的 jar（例如 junit 测试）。

Example: Get the classpath for xerces-2 and xalan,
        java-pkg_getjars xerces-2,xalan

Example Return:
        /usr/share/xerces-2/lib/xml-apis.jar:/usr/share/xerces-2/lib/xmlParserAPIs.jar:/usr/share/xalan/lib/xalan.jar


Parameters:
        --build-only - makes the jar(s) not added into package.env DEPEND line.
          (assumed automatically when called inside src_test)
        --runtime-only - marks the jar(s) not added into package.env RDEPEND line.
        --with-dependencies - get jars also from requested package's dependencies
          transitively.
$1 - list of packages to get jars from
  (passed to java-config --classpath)

java-pkg_getjar [--build-only] [--virtual] <package> <jarfile>

获取软件包中单个 jar 的完整路径。提供软件包被记录为 package.env DEPEND 行中的运行时依赖项，除非传递 “--build-only” 作为第一个参数，用于那些仅在构建时必须存在而在运行时不需要的 jar（例如 junit 测试）。

Example:
        java-pkg_getjar xerces-2 xml-apis.jar
returns
        /usr/share/xerces-2/lib/xml-apis.jar

Parameters:
        --build-only - makes the jar not added into package.env DEPEND line.
        --virtual - Packages passed to this function are to be handled as virtuals
          and will not have individual jar dependencies recorded.
$1 - package to use
$2 - jar to get

java-pkg_register-dependency <package>[,<package2>...] [<jarfile>]

将运行时依赖项注册到软件包、软件包列表或软件包中的单个 jar，到 package.env DEPEND 行中。只能在 src_install 阶段调用。用于二进制软件包，您不需要在构建过程中为 jar 创建符号链接或获取它们的类路径。因此，依赖项只需要在 ebuild 的 RDEPEND 中指定，并且应该在 DEPEND 中省略。

Parameters:
$1 - comma-separated list of packages, or a single package
$2 - if param $1 is a single package, optionally specify the jar
  to depend on

Examples:
Record the dependency on whole xerces-2 and xalan,
        java-pkg_register-dependency xerces-2,xalan

Record the dependency on ant.jar from ant-core
        java-pkg_register-dependency ant-core ant.jar

注意：既传递软件包列表作为第一个参数，又指定 jar 作为第二个参数是不允许的，会导致函数停止运行。我们假设您更有可能错误地传递这样的组合，而不是多个软件包提供具有相同名称的 jar 并且没有类冲突。

java-pkg_register-optional-dependency <package>[,<package2>...] [<jarfile>]

将可选运行时依赖项注册到软件包、软件包列表或软件包中的单个 jar，到 package.env OPTIONAL_DEPEND 行中。只能在 src_install 阶段调用。用于可以在类路径中使用其他软件包的软件包。如果安装了这些软件包，启动器将把它们放到类路径中。典型的情况是针对各种数据库的 JDBC 实现。这比为每个实现都使用 USE 标志来触发硬依赖项更好。

Parameters:
$1 - comma-separated list of packages, or a single package
$2 - if param $1 is a single package, optionally specify the jar to depend on

Example:
Record the optional dependency on some jdbc providers
        java-pkg_register-optional-dependency jdbc-jaybird,jtds-1.2,jdbc-mysql

java-pkg_register-environment-variable <name> <value>

将任意环境变量注册到 package.env 中。此软件包或任何依赖于此软件包的软件包的 gjl 启动器将在执行 java 命令之前将它导出到环境中。只能在 src_install 阶段调用。

java-pkg_get-bootclasspath <version>

返回给定提供 bootclasspath 的软件包版本的类路径。

java-pkg_find-normal-jars [<path/to/directory>]

在给定的目录（默认值为 $WORKDIR）中查找后缀为 .jar 的文件。

java-pkg_ensure-no-bundled-jars

尝试在 ${WORKDIR} 中查找捆绑的 jar 文件，如果找到则停止运行。此函数应该在使用系统 jar 文件的符号链接填充 WORKDIR 或删除捆绑的 jar 文件之后调用。

java-pkg_current-vm-matches <vm_string1> [<vm_string2> [<vm_string3>...]]

返回值：0：当前 vm 与任何提供的字符串匹配

java-pkg_get-source

确定应该使用哪个源版本，以传递给 -source。除非您想破坏东西，否则您可能不应该设置 _WANT_SOURCE

java-pkg_get-target

确定应该使用哪个目标版本，以传递给 -target。如果您不关心较低版本，您可以将 _WANT_TARGET 设置为 JDK 的版本。

java-pkg_get-javac

返回编译器可执行文件

java-pkg_javac-args

如果 ebuild 直接使用 javac 而不是使用 ejavac，它应该调用此函数以了解要使用哪个 -source/-target。

java-pkg_get-jni-cflags

回显 JNI 编译的 CFLAGS

java-pkg_register-ant-task [--version x.y] [<name>]

将此软件包注册为 ant 任务，以便 ant 在没有指定特定 ANT_TASKS 时加载它。请注意，即使没有此注册，ANT_TASKS 中指定的软件包也会被加载。主要由实际的 ant 任务软件包使用，但也可以由其他 ebuilds 使用，这些 ebuilds 过去将他们的 .jar 文件链接到 /usr/share/ant-core/lib 以获得自动加载，以实现向后兼容性。

Parameters
--version x.y Register only for ant version x.y (otherwise for any ant
                version). Used by the ant-* packages to prevent loading of mismatched
                ant-core ant tasks after core was updated, before the tasks are updated,
                without a need for blockers.
$1 Name to register as. Defaults to JAVA_PKG_NAME ($PN[-$SLOT])

ejunit

Junit 包装器函数。简化了运行测试并检查 DEPEND 中的 dev-java/junit。使用 org.junit.runner.JUnitCore 启动测试。

Parameters:
$1 - -cp or -classpath
$2 - classpath; junit and recorded dependencies get appended
$@ - the rest of the parameters are passed to java

Examples:
ejunit -cp build/classes org.blinkenlights.jid3.test.AllTests
ejunit org.blinkenlights.jid3.test.AllTests
ejunit org.blinkenlights.jid3.test.FirstTest org.blinkenlights.jid3.test.SecondTest

ejunit4

Junit4 包装器函数。简化了运行测试并检查 DEPEND 中的 dev-java/junit:4。使用 junit.textui.TestRunner 启动测试。

Parameters:
$1 - -cp or -classpath
$2 - classpath; junit and recorded dependencies get appended
$@ - the rest of the parameters are passed to java

Examples:
ejunit4 -cp build/classes org.blinkenlights.jid3.test.AllTests
ejunit4 org.blinkenlights.jid3.test.AllTests
ejunit4 org.blinkenlights.jid3.test.FirstTest \
        org.blinkenlights.jid3.test.SecondTest

java-utils-2_src_prepare

src_prepare 查找捆绑的 jar 文件。不要直接调用，而是通过 java-pkg-2_src_prepare 调用！

java-utils-2_pkg_preinst

pkg_preinst 查找缺失和不需要的依赖项。不要直接调用，而是通过 java-pkg-2_pkg_preinst 调用！

eant <ant_build_target(s)>

Ant 包装器函数。将使用适当的编译器，基于用户定义的编译器。还将从变量 ANT_TASKS 设置适当的 ANT_TASKS，以及变量

Variables:
EANT_GENTOO_CLASSPATH - calls java-pkg_getjars for the value and adds to the
                gentoo.classpath property. Be sure to call java-ant_rewrite-classpath in src_unpack.
EANT_NEEDS_TOOLS - add tools.jar to the gentoo.classpath. Should only be used
                for build-time purposes, the dependency is not recorded to
                package.env!
ANT_TASKS - used to determine ANT_TASKS before calling Ant.

ejavac <javac_arguments>

Javac 包装器函数。将使用适当的编译器，基于 /etc/java-config/compilers.conf

ejavadoc <javadoc_arguments>

javadoc 包装器函数。由于 1.8 中严格的 javadoc 规则，它将根据 VM 版本设置一些标志。

java-pkg_filter-compiler <compiler(s)_to_filter>

用于阻止使用某些编译器。应该在 src_compile 中使用。基本上，它只是附加到 JAVA_PKG_FILTER_COMPILER

java-pkg_force-compiler <compiler(s)_to_force>

用于强制使用特定的编译器。应该在 src_compile 中使用。一个常见的用途是在 amd64 上强制使用 ecj-3.1，以避免可能出现的 OutOfMemoryErrors。

java-pkg_clean

Java 软件包清理函数。这将删除所有 *.class 和 *.jar 文件，除了 JAVA_PKG_NO_CLEAN 中表达式指定的文件。

ECLASS 变量

JAVA_PKG_ALLOW_VM_CHANGE = ${JAVA_PKG_ALLOW_VM_CHANGE:="yes"}

允许此 eclass 更改活动的 VM？如果您的系统 VM 不足以运行软件包，则构建将失败，而不是尝试切换到另一个 VM。

覆盖默认值对于在本地测试特定 VM 很有用，但不应在最终的 ebuild 中使用。

JAVA_PKG_FORCE_VM

显式设置要使用的特定 VM。如果它无效，它将回退到 /etc/java-config-2/build/jdk.conf 选择使用的任何内容。

只应该用于测试和调试。

示例：使用 openjdk-11 来 emerge foo

        JAVA_PKG_FORCE_VM=openjdk-11 emerge foo

JAVA_PKG_NO_CLEAN

一个用于匹配 *.class 或 *.jar 文件的表达式数组，以防止它们被 java-pkg_clean 删除。

        JAVA_PKG_NO_CLEAN=(
                "*/standard.jar"
                "*/launch4j.jar"
                "*/apps/jetty/apache-tomcat*"
                "*/lib/jetty*"
        )

JAVA_PKG_WANT_BUILD_VM

一个包含 VM 句柄的列表，用于从这些 VM 中选择一个构建 VM。如果列表包含当前活动的 VM，则使用该 VM；否则，在列表中依次遍历，直到找到一个可用的/已安装的 VM。

这允许在 DEPEND 中使用显式 JDK 列表，而不是虚拟 JDK。使用此变量的用户必须确保 DEPEND 涵盖了列表中的至少一个句柄。还需要设置 JAVA_PKG_WANT_SOURCE 和 JAVA_PKG_WANT_TARGET。

JAVA_PKG_WANT_SOURCE

为编译指定非标准 Java 源版本（通过 javac -source 参数）。通常，这是从 DEPEND 中指定的 jdk 版本确定的。请参阅下面的 java-pkg_get-source 函数。

通常仅用于测试和调试。

使用 1.8 源代码来构建 baz

        JAVA_PKG_WANT_SOURCE=1.8 emerge baz

JAVA_PKG_WANT_TARGET

与 JAVA_PKG_WANT_SOURCE 相同（见上文），但用于 javac -target 参数，该参数影响生成的字节码的版本。通常，这是从 RDEPEND 中指定的 jre/jdk 版本确定的。请参阅下面的 java-pkg_get-target 函数。

通常仅用于测试和调试。

构建 bar 以与 1.8 兼容

        JAVA_PKG_WANT_TARGET=1.8 emerge bar

JAVA_TEST_EXTRA_ARGS

一个包含额外参数的数组，这些参数应在运行测试时传递给 java 命令。当需要向使用 System.getProperty() 的 Java 程序传递值时，它非常有用。如果它使用 System.getenv()，则使用 `export var=value` 代替。

它仅在运行测试时使用。

        JAVA_TEST_EXTRA_ARGS=(
                -Dsome.var=x
                "-Dother.var=   )

JAVA_TEST_RUNNER_EXTRA_ARGS

一个包含额外参数的数组，这些参数应在运行测试时传递给测试运行器。当需要向测试运行器传递额外参数时，它非常有用。

它仅在运行测试时使用。

        JAVA_TEST_RUNNER_EXTRA_ARGS=(
                -verbose 3
        )

JAVA_PKG_DEBUG

一个变量，设置为 "yes" 或 "y"，或任何长度不为零的字符串。当设置此变量时，java eclass 的详细程度会增加，并显示额外的日志。

        JAVA_PKG_DEBUG="yes"

JAVA_RM_FILES

一个包含要删除的文件列表的数组。如果定义了此数组，它将自动传递给 java-pkg_rm_files，以便在 src_prepare 阶段进行处理。

        JAVA_RM_FILES=(
                path/to/File1.java
                DELETEME.txt
        )

JAVA_PKG_FORCE_ANT_TASKS

一个由 $IFS 分隔的 ant 任务列表。可以在调用 emerge/ebuild 之前设置环境变量，以覆盖 ebuild 中设置的变量，主要用于在将最终的 (WANT_)ANT_TASKS 放入 ebuild 之前进行测试。仅影响 eant() 调用中的 ANT_TASKS，不影响 WANT_ANT_TASKS 中指定的依赖项。

JAVA_PKG_FORCE_ANT_TASKS="ant-junit ant-trax" \
        ebuild foo.ebuild compile

JAVADOC_CLASSPATH

一个由逗号或空格分隔的 java 包列表，这些包是生成 javadoc 所需的。如果存在具有不同依赖项的 jar 文件，可以使用它来避免在多 jar 包中过度加载编译类路径。

Example:
        JAVADOC_CLASSPATH="
                jna-4
                jsch
        "

JAVADOC_SRC_DIRS

一个包含应用程序源代码目录的数组，这些目录相对于 ${S}。它需要位于全局范围；如果放在 src_compile() 中，它将无法正常工作。它由 java-pkg-simple.eclass 使用，以决定是否调用 ejavadoc。如果定义了此变量，那么 java-pkg-simple_src_compile 不会自动调用 ejavadoc。然后需要从 ebuild 中显式调用 ejavadoc。它旨在用于多 jar 包，以避免仅为了生成 javadoc 而进行额外的编译运行。

Example:
        JAVADOC_SRC_DIRS=(
            "${PN}-core"
            "${PN}-jsch"
            "${PN}-pageant"
            "${PN}-sshagent"
            "${PN}-usocket-jna"
            "${PN}-usocket-nc"
            "${PN}-connector-factory"
        )

AUTHORS

Thomas Matthijs <[email protected]>，Karl Trygve Kalleberg <[email protected]>

MAINTAINERS

[email protected]

REPORTING BUGS

请通过 https://bugs.gentoo.org/ 报告错误。

FILES

java-utils-2.eclass

此文档由 man2html 使用手册页创建。
时间：2024 年 11 月 12 日，格林尼治标准时间 03:27:00