--- java-utils-2.eclass +++ java-utils-2.eclass @@ -9,38 +9,37 @@ # $Header: /var/cvsroot/gentoo-x86/eclass/java-utils-2.eclass,v 1.149 2011/12/27 17:55:12 fauli Exp $ # ----------------------------------------------------------------------------- -# @eclass-begin -# @eclass-shortdesc Java Utility eclass -# @eclass-maintainer java@gentoo.org -# +# @ECLASS: java-utils-2.eclass +# @MAINTAINER: +# java@gentoo.org +# @AUTHOR: +# @BLURB: Java Utility eclass +# @DESCRIPTION: # This eclass provides functionality which is used by # java-pkg.eclass and java-pkg-opt.eclass as well as from ebuilds. # -# @warning -# You probably don't want to inherit this directly from an ebuild. Instead, -# you should inherit java-ant for Ant-based Java packages, java-pkg for other -# Java packages, or java-pkg-opt for packages that have optional Java support. -# -# ----------------------------------------------------------------------------- +# Warning: +# You probably don't want to inherit this directly from an +# ebuild. Instead, you should inherit java-ant for Ant-based +# Java packages, java-pkg for other Java packages, or +# java-pkg-opt for packages that have optional Java support. inherit eutils versionator multilib IUSE="elibc_FreeBSD" # ----------------------------------------------------------------------------- -# @section-begin variables -# @section-title Variables -# +# @ECLASS-VARIABLE: WANT_JAVA_CONFIG +# @DESCRIPTION: # Summary of variables which control the behavior of building Java packges. -# ----------------------------------------------------------------------------- - # Make sure we use java-config-2 +# WANT_JAVA_CONFIG="2" export WANT_JAVA_CONFIG="2" # ----------------------------------------------------------------------------- -# @variable-external WANT_ANT_TASKS -# @variable-default "" -# +# @ECLASS-VARIABLE: WANT_ANT_TASKS +# @DEFAULT_UNSET +# @DESCRIPTION: # An $IFS separated list of ant tasks. # Ebuild can specify this variable before inheriting java-ant-2 eclass to # determine ANT_TASKS it needs. They will be automatically translated to @@ -50,38 +49,45 @@ # differently for different eant calls can't use this simplified approach. # You also cannot specify version or anything else than ant-*. # -# @example WANT_ANT_TASKS="ant-junit ant-trax" -# -# @seealso JAVA_PKG_FORCE_ANT_TASKS -# ----------------------------------------------------------------------------- -#WANT_ANT_TASKS +# Example: +# @CODE +# WANT_ANT_TASKS="ant-junit ant-trax" +# @CODE +# See also JAVA_PKG_FORCE_ANT_TASKS # ----------------------------------------------------------------------------- -# @variable-internal JAVA_PKG_PORTAGE_DEP -# +# @ECLASS-VARIABLE: JAVA_PKG_PORTAGE_DEP +# @INTERNAL +# @DESCRIPTION: # The version of portage we need to function properly. Previously it was # portage with phase hooks support but now we use a version with proper env # saving. For EAPI 2 we have new enough stuff so let's have cleaner deps. -# ----------------------------------------------------------------------------- has "${EAPI}" 0 1 && JAVA_PKG_PORTAGE_DEP=">=sys-apps/portage-2.1.2.7" # ----------------------------------------------------------------------------- -# @variable-internal JAVA_PKG_E_DEPEND -# +# @ECLASS-VARIABLE: JAVA_PKG_IUSE +# @DEFAULT_UNSET +# @DESCRIPTION: +# Use JAVA_PKG_IUSE instead of IUSE for doc, source and examples so that +# the eclass can automatically add the needed dependencies for the java-pkg_do* +# functions. + +# ----------------------------------------------------------------------------- +# @ECLASS-VARIABLE: JAVA_PKG_E_DEPEND +# @INTERNAL +# @DESCRIPTION: # This is a convience variable to be used from the other java eclasses. This is # the version of java-config we want to use. Usually the latest stable version # so that ebuilds can use new features without depending on specific versions. -# ----------------------------------------------------------------------------- JAVA_PKG_E_DEPEND=">=dev-java/java-config-2.1.9-r1 ${JAVA_PKG_PORTAGE_DEP}" has source ${JAVA_PKG_IUSE} && JAVA_PKG_E_DEPEND="${JAVA_PKG_E_DEPEND} source? ( app-arch/zip )" # ----------------------------------------------------------------------------- -# @variable-preinherit JAVA_PKG_WANT_BOOTCLASSPATH -# +# @ECLASS-VARIABLE: JAVA_PKG_WANT_BOOTCLASSPATH +# @DEFAULT_UNSET +# @DESCRIPTION: # The version of bootclasspath the package needs to work. Translates to a proper # dependency. The bootclasspath has to be obtained by java-ant_rewrite-bootclasspath -# ----------------------------------------------------------------------------- - if [[ -n "${JAVA_PKG_WANT_BOOTCLASSPATH}" ]]; then if [[ "${JAVA_PKG_WANT_BOOTCLASSPATH}" == "1.5" ]]; then JAVA_PKG_E_DEPEND="${JAVA_PKG_E_DEPEND} >=dev-java/gnu-classpath-0.98-r1:0.98" @@ -93,108 +99,192 @@ fi # ----------------------------------------------------------------------------- -# @variable-external JAVA_PKG_ALLOW_VM_CHANGE -# @variable-default yes -# +# @ECLASS-VARIABLE: JAVA_PKG_ALLOW_VM_CHANGE +# @DESCRIPTION: # Allow this eclass to change the active VM? # If your system VM isn't sufficient for the package, the build will fail. -# @note This is useful for testing specific VMs. -# ----------------------------------------------------------------------------- +# note: This is useful for testing specific VMs. JAVA_PKG_ALLOW_VM_CHANGE=${JAVA_PKG_ALLOW_VM_CHANGE:="yes"} # ----------------------------------------------------------------------------- -# @variable-external JAVA_PKG_FORCE_VM -# +# @ECLASS-VARIABLE: JAVA_PKG_FORCE_VM +# @DESCRIPTION: # Explicitly set a particular VM to use. If its not valid, it'll fall back to # whatever /etc/java-config-2/build/jdk.conf would elect to use. # # Should only be used for testing and debugging. # -# @example Use sun-jdk-1.5 to emerge foo -# JAVA_PKG_FORCE_VM=sun-jdk-1.5 emerge foo +# Example: Use sun-jdk-1.5 to emerge foo +# @CODE +# JAVA_PKG_FORCE_VM=sun-jdk-1.5 emerge foo +# @CODE # -# ----------------------------------------------------------------------------- +# JAVA_PKG_FORCE_VM="defined by /etc/java-config-2/build/jdk.conf" # ----------------------------------------------------------------------------- -# @variable-external JAVA_PKG_WANT_SOURCE -# +# @ECLASS-VARIABLE: JAVA_PKG_WANT_SOURCE +# @DESCRIPTION: # Specify a specific VM version to compile for to use for -source. # Normally this is determined from DEPEND. # See java-pkg_get-source function below. # # Should only be used for testing and debugging. # -# @seealso java-pkg_get-source +# See also: java-pkg_get-source # -# @example Use 1.4 source to emerge baz -# JAVA_PKG_WANT_SOURCE=1.4 emerge baz -# ----------------------------------------------------------------------------- +# Example: Use 1.4 source to emerge baz +# @CODE +# JAVA_PKG_WANT_SOURCE=1.4 emerge baz +# @CODE # ----------------------------------------------------------------------------- -# @variable-external JAVA_PKG_WANT_TARGET -# +# @ECLASS-VARIABLE: JAVA_PKG_WANT_TARGET +# @DESCRIPTION: # Same as JAVA_PKG_WANT_SOURCE above but for -target. # See java-pkg_get-target function below. # # Should only be used for testing and debugging. # -# @seealso java-pkg_get-target +# See also: java-pkg_get-target # -# @example emerge bar to be compatible with 1.3 -# JAVA_PKG_WANT_TARGET=1.3 emerge bar -# ----------------------------------------------------------------------------- +# Example: emerge bar to be compatible with 1.3 +# @CODE +# JAVA_PKG_WANT_TARGET=1.3 emerge bar +# @CODE # ----------------------------------------------------------------------------- -# @variable-internal JAVA_PKG_COMPILER_DIR -# @default /usr/share/java-config-2/compiler -# +# @ECLASS-VARIABLE: JAVA_PKG_COMPILER_DIR +# @INTERNAL +# @DESCRIPTION: # Directory where compiler settings are saved, without trailing slash. # Probably shouldn't touch this variable. -# ----------------------------------------------------------------------------- +# +# JAVA_PKG_COMPILER_DIR=/usr/share/java-config-2/compiler JAVA_PKG_COMPILER_DIR=${JAVA_PKG_COMPILER_DIR:="/usr/share/java-config-2/compiler"} # ----------------------------------------------------------------------------- -# @variable-internal JAVA_PKG_COMPILERS_CONF -# @variable-default /etc/java-config-2/build/compilers.conf -# +# @ECLASS-VARIABLE: JAVA_PKG_COMPILERS_CONF +# @INTERNAL +# @DESCRIPTION: # Path to file containing information about which compiler to use. # Can be overloaded, but it should be overloaded for testing. -# ----------------------------------------------------------------------------- +# +# JAVA_PKG_COMPILERS_CONF=/etc/java-config-2/build/compilers.conf JAVA_PKG_COMPILERS_CONF=${JAVA_PKG_COMPILERS_CONF:="/etc/java-config-2/build/compilers.conf"} # ----------------------------------------------------------------------------- -# @variable-external JAVA_PKG_FORCE_COMPILER -# +# @ECLASS-VARIABLE: JAVA_PKG_FORCE_COMPILER +# @DESCRIPTION: # Explicitly set a list of compilers to use. This is normally read from # JAVA_PKG_COMPILERS_CONF. # -# @note This should only be used internally or for testing. -# @example Use jikes and javac, in that order -# JAVA_PKG_FORCE_COMPILER="jikes javac" -# ----------------------------------------------------------------------------- +# Note: This should only be used internally or for testing. +# +# Example: Use jikes and javac, in that order +# @CODE +# JAVA_PKG_FORCE_COMPILER="jikes javac" +# @CODE # ----------------------------------------------------------------------------- -# @variable-external JAVA_PKG_FORCE_ANT_TASKS -# +# @ECLASS-VARIABLE: JAVA_PKG_FORCE_ANT_TASKS +# @DESCRIPTION: # An $IFS separated list of ant tasks. Can be set in environment before calling # emerge/ebuild to override variables set in ebuild, mainly for testing before # putting the resulting (WANT_)ANT_TASKS into ebuild. Affects only ANT_TASKS in # eant() call, not the dependencies specified in WANT_ANT_TASKS. # -# @example JAVA_PKG_FORCE_ANT_TASKS="ant-junit ant-trax" \ -# ebuild foo.ebuild compile -# -# @seealso WANT_ANT_TASKS -# ----------------------------------------------------------------------------- - -# TODO document me -JAVA_PKG_QA_VIOLATIONS=0 +# Example: +# @CODE +# JAVA_PKG_FORCE_ANT_TASKS="ant-junit ant-trax" \ +# ebuild foo.ebuild compile +# @CODE +# +# See also: WANT_ANT_TASKS # ----------------------------------------------------------------------------- -# @section-end variables -# ----------------------------------------------------------------------------- +# @ECLASS-VARIABLE: JAVA_PKG_QA_VIOLATIONS +# @INTERNAL +# @DESCRIPTION: +# TODO documentation is pending +JAVA_PKG_QA_VIOLATIONS=0 +# @ECLASS-VARIABLE: JAVA_PKG_SHAREPATH +# @INTERNAL +# @DESCRIPTION: +# TODO documentation is pending + +# @ECLASS-VARIABLE: JAVA_PKG_JARDEST +# @INTERNAL +# @DESCRIPTION: +# TODO documentation is pending +# See also java-pkg_jarinto and java-pkg_dojar + +# @ECLASS-VARIABLE: JAVA_PKG_LIBDEST +# @INTERNAL +# @DESCRIPTION: +# TODO documentation is pending + +# @ECLASS-VARIABLE: JAVA_PKG_SOURCESPATH +# @INTERNAL +# @DESCRIPTION: +# TODO documentation is pending + +# @ECLASS-VARIABLE: JAVA_PKG_CLASSPATH +# @INTERNAL +# @DESCRIPTION: +# TODO documentation is pending + +# @ECLASS-VARIABLE: JAVA_PKG_WARDEST +# @INTERNAL +# @DESCRIPTION: +# TODO documentation is pending + +# @ECLASS-VARIABLE: JAVADOC_PATH +# @INTERNAL +# @DESCRIPTION: +# TODO documentation is pending + +# @ECLASS-VARIABLE: JAVA_PKG_EXTRA_ENV +# @INTERNAL +# @DESCRIPTION: +# TODO documentation is pending + +# @ECLASS-VARIABLE: JAVA_PKG_EXTRA_ENV_VARS +# @INTERNAL +# @DESCRIPTION: +# TODO documentation is pending + +# @ECLASS-VARIABLE: JAVA_PKG_DEPEND_FILE +# @INTERNAL +# @DESCRIPTION: +# TODO documentation is pending + +# @ECLASS-VARIABLE: JAVA_PKG_ENV +# @INTERNAL +# @DESCRIPTION: +# TODO documentation is pending + +# @ECLASS-VARIABLE: JAVA_PKG_FILTER_COMPILER +# @INTERNAL +# @DESCRIPTION: +# See also: java-pkg_filter-compiler + +# @ECLASS-VARIABLE: JAVA_PKG_LIBRARY +# @INTERNAL +# @DESCRIPTION: +# TODO documentation is pending + +# @ECLASS-VARIABLE: JAVA_PKG_STRICT +# @DEFAULT_UNSET +# @DESCRIPTION: +# Enables additional checks in Java eclasses. This variable must be set when developing Java ebuilds + +# ----------------------------------------------------------------------------- +# @ECLASS-VARIABLE: JAVA_PKG_NAME +# @INTERNAL +# @DESCRIPTION: +# TODO documentation is pending # ----------------------------------------------------------------------------- # @section-begin install @@ -205,19 +295,18 @@ # ----------------------------------------------------------------------------- # ----------------------------------------------------------------------------- -# @ebuild-function java-pkg_doexamples -# +# @FUNCTION: java-pkg_doexamples +# @USAGE: | [|]... +# @DESCRIPTION: # Installs given arguments to /usr/share/doc/${PF}/examples # If you give it only one parameter and it is a directory it will install # everything in that directory to the examples directory. # -# @example -# java-pkg_doexamples demo -# java-pkg_doexamples demo/* examples/* -# -# @param --subdir - If the examples need a certain directory structure -# @param $* - list of files to install -# ------------------------------------------------------------------------------ +# Example: +# @CODE +# java-pkg_doexamples demo +# java-pkg_doexamples demo/* examples/* +# @CODE java-pkg_doexamples() { debug-print-function ${FUNCNAME} $* @@ -249,19 +338,19 @@ } # ----------------------------------------------------------------------------- -# @ebuild-function java-pkg_dojar -# +# @FUNCTION: java-pkg_dojar +# @USAGE: +# @DESCRIPTION: # Installs any number of jars. # Jar's will be installed into /usr/share/${PN}(-${SLOT})/lib/ by default. # You can use java-pkg_jarinto to change this path. # You should never install a jar with a package version in the filename. # Instead, use java-pkg_newjar defined below. # -# @example -# java-pkg_dojar dist/${PN}.jar dist/${PN}-core.jar -# -# @param $* - list of jars to install -# ------------------------------------------------------------------------------ +# Example: +# @CODE +# java-pkg_dojar dist/${PN}.jar dist/${PN}-core.jar +# @CODE java-pkg_dojar() { debug-print-function ${FUNCNAME} $* @@ -314,13 +403,12 @@ } # ------------------------------------------------------------------------------ -# @internal-function depend-java-query -# +# @FUNCTION: depend-java-query +# @INTERNAL +# @DESCRIPTION: # Wrapper for the depend-java-query binary to enable passing USE in env. # Using env variables keeps this eclass working with java-config versions that # do not handle use flags. -# ------------------------------------------------------------------------------ - depend-java-query() { # Used to have a which call here but it caused endless loops for some people # that had some weird bashrc voodoo for which. @@ -328,33 +416,35 @@ } # ------------------------------------------------------------------------------ -# @ebuild-function java-pkg_regjar -# +# @FUNCTION: java-pkg_regjar +# @USAGE: +# @DESCRIPTION: # Records an already installed jar in the package.env # This would mostly be used if the package has make or a custom script to # install things. # # Example: -# java-pkg_regjar ${D}/opt/foo/lib/foo.jar +# @CODE +# java-pkg_regjar ${D}/opt/foo/lib/foo.jar +# @CODE # # WARNING: -# if you want to use shell expansion, you have to use ${D}/... as the for in -# this function will not be able to expand the path, here's an example: -# -# java-pkg_regjar /opt/my-java/lib/*.jar -# -# will not work, because: -# * the `for jar in "$@"` can't expand the path to jar file names, as they -# don't exist yet -# * all `if ...` inside for will fail - the file '/opt/my-java/lib/*.jar' -# doesn't exist -# -# you have to use it as: -# -# java-pkg_regjar ${D}/opt/my-java/lib/*.jar -# -# @param $@ - jars to record -# ------------------------------------------------------------------------------ +# if you want to use shell expansion, you have to use ${D}/... +# as the for in this function will not be able to expand the +# path, here's an example: +# @CODE +# java-pkg_regjar /opt/my-java/lib/*.jar +# @CODE +# will not work, because: +# * the `for jar in "$@"` can't expand the path to jar file +# names, as they don't exist yet +# * all `if ...` inside for will fail - the file +# '/opt/my-java/lib/*.jar' doesn't exist +# you have to use it as: +# @CODE +# java-pkg_regjar ${D}/opt/my-java/lib/*.jar +# @CODE + # TODO should we be making sure the jar is present on ${D} or wherever? java-pkg_regjar() { debug-print-function ${FUNCNAME} $* @@ -396,16 +486,15 @@ } # ------------------------------------------------------------------------------ -# @ebuild-function java-pkg_newjar -# -# Installs a jar with a new name -# -# @example: install a versioned jar without the version -# java-pkg_newjar dist/${P}.jar ${PN}.jar -# -# @param $1 - jar to install -# @param $2 - new name for jar - defaults to ${PN}.jar if not specified -# ------------------------------------------------------------------------------ +# @FUNCTION: java-pkg_newjar +# @USAGE: [] +# @DESCRIPTION: +# Installs a jar with a new name or ${PN}.jar if no new name given. +# +# Example: install a versioned jar without the version +# @CODE +# java-pkg_newjar dist/${P}.jar ${PN}.jar +# @CODE java-pkg_newjar() { debug-print-function ${FUNCNAME} $* @@ -424,31 +513,30 @@ } # ------------------------------------------------------------------------------ -# @ebuild-function java-pkg_addcp -# +# @FUNCTION: java-pkg_addcp +# @USAGE: +# @DESCRIPTION: # Add something to the package's classpath. For jars, you should use dojar, # newjar, or regjar. This is typically used to add directories to the classpath. -# -# TODO add example -# @param $@ - value to append to JAVA_PKG_CLASSPATH -# ------------------------------------------------------------------------------ + +# TODO add Example java-pkg_addcp() { java-pkg_append_ JAVA_PKG_CLASSPATH "${@}" java-pkg_do_write_ } # ------------------------------------------------------------------------------ -# @ebuild-function java-pkg_doso -# +# @FUNCTION: java-pkg_doso +# @USAGE: +# @DESCRIPTION: # Installs any number of JNI libraries # They will be installed into /usr/lib by default, but java-pkg_sointo # can be used change this path # # Example: -# java-pkg_doso *.so -# -# @param $@ - JNI libraries to install -# ------------------------------------------------------------------------------ +# @CODE +# java-pkg_doso *.so +# @CODE java-pkg_doso() { debug-print-function ${FUNCNAME} $* @@ -485,15 +573,15 @@ } # ------------------------------------------------------------------------------ -# @ebuild-function java-pkg_regso -# +# @FUNCTION: java-pkg_regso +# @USAGE: +# @DESCRIPTION: # Registers an already JNI library in package.env. # # Example: -# java-pkg_regso *.so /path/*.so -# -# @param $@ - JNI libraries to register -# ------------------------------------------------------------------------------ +# @CODE +# java-pkg_regso *.so /path/*.so +# @CODE java-pkg_regso() { debug-print-function ${FUNCNAME} $* @@ -522,12 +610,10 @@ } # ------------------------------------------------------------------------------ -# @ebuild-function java-pkg_jarinto -# +# @FUNCTION: java-pkg_jarinto +# @USAGE: +# @DESCRIPTION: # Changes the path jars are installed into -# -# @param $1 - new location to install jars into. -# ----------------------------------------------------------------------------- java-pkg_jarinto() { debug-print-function ${FUNCNAME} $* @@ -535,12 +621,10 @@ } # ------------------------------------------------------------------------------ -# @ebuild-function java-pkg_sointo -# +# @FUNCTION: java-pkg_sointo +# @USAGE: +# @DESCRIPTION: # Changes the path that JNI libraries are installed into. -# -# @param $1 - new location to install JNI libraries into. -# ------------------------------------------------------------------------------ java-pkg_sointo() { debug-print-function ${FUNCNAME} $* @@ -548,14 +632,16 @@ } # ------------------------------------------------------------------------------ -# @ebuild-function java-pkg_dohtml -# +# @FUNCTION: java-pkg_dohtml +# @USAGE: +# @DESCRIPTION: +# DEPRECATED: use dohtml now. # Install Javadoc HTML documentation # -# @example -# java-pkg_dohtml dist/docs/ -# -# ------------------------------------------------------------------------------ +# Example: +# @CODE +# java-pkg_dohtml dist/docs/ +# @CODE java-pkg_dohtml() { debug-print-function ${FUNCNAME} $* @@ -572,19 +658,18 @@ } # ------------------------------------------------------------------------------ -# @ebuild-function java-pkg_dojavadoc -# +# @FUNCTION: java-pkg_dojavadoc +# @USAGE: [--symlink ] +# @DESCRIPTION: # Installs javadoc documentation. This should be controlled by the doc use flag. +# The optional --symlink creates to symlink like this for html documentation +# bundles. # -# @param $1: optional --symlink creates to symlink like this for html -# documentation bundles. -# @param $2: - The javadoc root directory. -# -# @example: -# java-pkg_dojavadoc docs/api -# java-pkg_dojavadoc --symlink apidocs docs/api -# -# ------------------------------------------------------------------------------ +# Example: +# @CODE +# java-pkg_dojavadoc docs/api +# java-pkg_dojavadoc --symlink apidocs docs/api +# @CODE java-pkg_dojavadoc() { debug-print-function ${FUNCNAME} $* @@ -638,21 +723,24 @@ } # ------------------------------------------------------------------------------ -# @ebuild-function java-pkg_dosrc -# -# Installs a zip containing the source for a package, so it can used in +# @FUNCTION: java-pkg_dosrc +# @USAGE: +# @DESCRIPTION: +# Creates and installs a zip containing the source for a package, so it can used in # from IDEs like eclipse and netbeans. +# Takes a list of paths to the base of the source directories like com or org. # # Ebuild needs to DEPEND on app-arch/zip to use this. # # It also should be controlled by USE=source. # -# @example: -# java-pkg_dosrc src/* -# -# ------------------------------------------------------------------------------ +# Example: +# @CODE +# java-pkg_dosrc src/* +# @CODE + # TODO change so it the arguments it takes are the base directories containing -# source -nichoj +# source -nichoj # TODO should we be able to handle multiple calls to dosrc? -nichoj # TODO maybe we can take an existing zip/jar? -nichoj # FIXME apparently this fails if you give it an empty directories @@ -697,16 +785,16 @@ } # ------------------------------------------------------------------------------ -# @ebuild-function java-pkg_dolauncher -# +# @FUNCTION: java-pkg_dolauncher +# @USAGE: [