summaryrefslogtreecommitdiff
path: root/eclass
diff options
context:
space:
mode:
authorPatrice Clement <monsieurp@gentoo.org>2015-10-19 14:49:49 +0000
committerPatrice Clement <monsieurp@gentoo.org>2015-10-19 14:49:49 +0000
commit431bc3cd939515331a74bba5729e63de887a0b18 (patch)
tree58d4ade9df74e2f05d84a667a14ad2a4e17302e1 /eclass
parentdev-util/abi-compliance-checker: Add missing dependencies (diff)
downloadgentoo-431bc3cd939515331a74bba5729e63de887a0b18.tar.gz
gentoo-431bc3cd939515331a74bba5729e63de887a0b18.tar.bz2
gentoo-431bc3cd939515331a74bba5729e63de887a0b18.zip
java-{mvn-src,osgi,pkg-simple}.eclass: Rewrite documentation to make it compliant with the new style. Fixes bug 476946.
Signed-off-by: Patrice Clement <monsieurp@gentoo.org>
Diffstat (limited to 'eclass')
-rw-r--r--eclass/java-mvn-src.eclass55
-rw-r--r--eclass/java-osgi.eclass119
-rw-r--r--eclass/java-pkg-simple.eclass128
3 files changed, 127 insertions, 175 deletions
diff --git a/eclass/java-mvn-src.eclass b/eclass/java-mvn-src.eclass
index c34034eb00d7..a7f8e5bc2fa5 100644
--- a/eclass/java-mvn-src.eclass
+++ b/eclass/java-mvn-src.eclass
@@ -2,12 +2,13 @@
# Distributed under the terms of the GNU General Public License v2
# $Id$
-inherit java-pkg-simple
-
-# -----------------------------------------------------------------------------
-# @eclass-begin
-# @eclass-summary Eclass for Java packages from bare sources exported by Maven
-#
+# @ECLASS: java-mvn-src.eclass
+# @MAINTAINER:
+# java@gentoo.org
+# @AUTHOR:
+# Java maintainers (java@gentoo.org)
+# @BLURB: Eclass for Java packages from bare sources exported by Maven
+# @DESCRIPTION:
# This class is intended to build pure Java packages from the sources exported
# from the source:jar goal of Maven 2. These archives contain bare Java source
# files, with no build instructions or additional resource files. They are
@@ -16,38 +17,30 @@ inherit java-pkg-simple
# are often released together with binary packages, whereas the full build
# environment might be contained in some revision control system or not
# available at all.
-# -----------------------------------------------------------------------------
-
-# -----------------------------------------------------------------------------
-# @variable-external GROUP_ID
-# @variable-default ${PN}
-#
-# The groupId of the artifact, in dotted notation.
-# -----------------------------------------------------------------------------
+
+inherit java-pkg-simple
+
+# @ECLASS-VARIABLE: GROUP_ID
+# @DESCRIPTION:
+# The groupId of the artifact, in dotted notation. Default value is ${PN}.
: ${GROUP_ID:=${PN}}
-# -----------------------------------------------------------------------------
-# @variable-external ARTIFACT_ID
-# @variable-default ${PN}
-#
-# The artifactId of the artifact.
-# -----------------------------------------------------------------------------
+# @ECLASS-VARIABLE: ARTIFACT_ID
+# The artifactId of the artifact. Default value is ${PN}.
+
: ${ARTIFACT_ID:=${PN}}
-# -----------------------------------------------------------------------------
-# @variable-external MAVEN2_REPOSITORIES
-# @variable-default http://repo2.maven.org/maven2 http://download.java.net/maven/2
-#
+# @ECLASS-VARIABLE: MAVEN2_REPOSITORIES
+# @DESCRIPTION:
# The repositories to search for the artifacts. Must follow Maven2 layout.
-# -----------------------------------------------------------------------------
+# Default value is the following string:
+# "http://repo2.maven.org/maven2 http://download.java.net/maven/2"
: ${MAVEN2_REPOSITORIES:="http://repo2.maven.org/maven2 http://download.java.net/maven/2"}
-# -----------------------------------------------------------------------------
-# @variable-internal RELATIVE_SRC_URI
-#
+# @ECLASS-VARIABLE: RELATIVE_SRC_URI
+# @DESCRIPTION:
# The path of the source artifact relative to the root of the repository.
# Will be set by the eclass to follow Maven 2 repository layout.
-# -----------------------------------------------------------------------------
RELATIVE_SRC_URI=${GROUP_ID//./\/}/${ARTIFACT_ID}/${PV}/${ARTIFACT_ID}-${PV}-sources.jar
# Look for source jar in all listed repositories
@@ -55,7 +48,3 @@ for repo in ${MAVEN2_REPOSITORIES}; do
SRC_URI="${SRC_URI} ${repo}/${RELATIVE_SRC_URI}"
done
unset repo
-
-# ------------------------------------------------------------------------------
-# @eclass-end
-# ------------------------------------------------------------------------------
diff --git a/eclass/java-osgi.eclass b/eclass/java-osgi.eclass
index 46865fa8b1ce..62f3046445a8 100644
--- a/eclass/java-osgi.eclass
+++ b/eclass/java-osgi.eclass
@@ -2,26 +2,26 @@
# Distributed under the terms of the GNU General Public License v2
# $Id$
-# -----------------------------------------------------------------------------
-# @eclass-begin
-# @eclass-shortdesc Java OSGi eclass
-# @eclass-maintainer java@gentoo.org
-#
-# This eclass provides functionality which is used by
-# packages that need to be OSGi compliant. This means
-# that the generated jars will have special headers in their manifests.
-# Currently this is used only by Eclipse-3.3 - later
-# we could extend this so that Gentoo Java system would be
-# fully OSGi compliant.
-#
-# -----------------------------------------------------------------------------
+# @ECLASS: java-osgi.eclass
+# @MAINTAINER:
+# java@gentoo.org
+# @AUTHOR:
+# Java maintainers (java@gentoo.org)
+# @BLURB: Java OSGi eclass
+# @DESCRIPTION:
+# This eclass provides functionality which is used by packages that need to be
+# OSGi compliant. This means that the generated jars will have special headers
+# in their manifests. Currently this is used only by Eclipse-3.3 - later we
+# could extend this so that Gentoo Java system would be fully OSGi compliant.
inherit java-utils-2
+# @ECLASS-VARIABLE: _OSGI_T
+# @INTERNAL
+# @DESCRIPTION:
# We define _OSGI_T so that it does not contain a slash at the end.
# According to Paludis guys, there is currently a proposal for EAPIs that
# would require all variables to end with a slash.
-
_OSGI_T="${T/%\//}"
# must get Diego to commit something like this to portability.eclass
@@ -36,18 +36,17 @@ _canonicalise() {
fi
}
-# -----------------------------------------------------------------------------
-# @ebuild-function _java-osgi_plugin
-#
+# @FUNCTION: _java-osgi_plugin
+# @USAGE: <plugin name>
+# @INTERNAL
+# @DESCRIPTION:
# This is an internal function, not to be called directly.
#
-# @example
+# @CODE
# _java-osgi_plugin "JSch"
+# @CODE
#
# @param $1 - bundle name
-#
-# ------------------------------------------------------------------------------
-
_java-osgi_plugin() {
# We hardcode Gentoo as the vendor name
@@ -57,21 +56,20 @@ _java-osgi_plugin() {
EOF
}
-# -----------------------------------------------------------------------------
-# @ebuild-function _java-osgi_makejar
-#
+# @FUNCTION: _java-osgi_makejar
+# @USAGE: <jar name> <symbolic name> <bundle name> <header name>
+# @INTERNAL
+# @DESCRIPTION:
# This is an internal function, not to be called directly.
#
-# @example
+# @CODE
# _java-osgi_makejar "dist/${PN}.jar" "com.jcraft.jsch" "JSch" "com.jcraft.jsch, com.jcraft.jsch.jce;x-internal:=true"
+# @CODE
#
# @param $1 - name of jar to repackage with OSGi
# @param $2 - bundle symbolic name
# @param $3 - bundle name
# @param $4 - export-package header
-#
-# ------------------------------------------------------------------------------
-
_java-osgi_makejar() {
debug-print-function ${FUNCNAME} "$@"
@@ -104,9 +102,9 @@ _java-osgi_makejar() {
rm -rf "${_OSGI_T}/tmp_jar"
}
-# -----------------------------------------------------------------------------
-# @ebuild-function java-osgi_dojar
-#
+# @FUNCTION: @java-osgi_dojar
+# @USAGE: <jar name> <symbolic name> <bundle name> <header name>
+# @DESCRIPTION:
# Rewrites a jar, and produce an OSGi compliant jar from arguments given on the command line.
# The arguments given correspond to the minimal set of headers
# that must be present on a Manifest file of an OSGi package.
@@ -114,16 +112,14 @@ _java-osgi_makejar() {
# that create the Manifest from a file.
# It will call java-pkg_dojar at the end.
#
-# @example
+# @CODE
# java-osgi_dojar "dist/${PN}.jar" "com.jcraft.jsch" "JSch" "com.jcraft.jsch, com.jcraft.jsch.jce;x-internal:=true"
+# @CODE
#
# @param $1 - name of jar to repackage with OSGi
# @param $2 - bundle symbolic name
# @param $3 - bundle name
# @param $4 - export-package-header
-#
-# ------------------------------------------------------------------------------
-
java-osgi_dojar() {
debug-print-function ${FUNCNAME} "$@"
local jarName="$(basename ${1})"
@@ -131,9 +127,9 @@ java-osgi_dojar() {
java-pkg_dojar "${_OSGI_T}/osgi/${jarName}"
}
-# -----------------------------------------------------------------------------
-# @ebuild-function java-osgi_newjar
-#
+# @FUNCTION: java-osgi_newjar
+# @USAGE: <jar name> <symbolic name> <bundle name> <header name>
+# @DESCRIPTION:
# Rewrites a jar, and produce an OSGi compliant jar.
# The arguments given correspond to the minimal set of headers
# that must be present on a Manifest file of an OSGi package.
@@ -141,17 +137,15 @@ java-osgi_dojar() {
# that create the Manifest from a file.
# It will call java-pkg_newjar at the end.
#
-# @example
+# @CODE
# java-osgi_newjar "dist/${PN}.jar" "com.jcraft.jsch" "JSch" "com.jcraft.jsch, com.jcraft.jsch.jce;x-internal:=true"
+# @CODE
#
# @param $1 - name of jar to repackage with OSGi
# @param $2 (optional) - name of the target jar. It will default to package name if not specified.
# @param $3 - bundle symbolic name
# @param $4 - bundle name
# @param $5 - export-package header
-#
-# ------------------------------------------------------------------------------
-
java-osgi_newjar() {
debug-print-function ${FUNCNAME} "$@"
local jarName="$(basename $1)"
@@ -165,21 +159,20 @@ java-osgi_newjar() {
fi
}
-# -----------------------------------------------------------------------------
-# @ebuild-function _java-osgi_makejar-fromfile
-#
+# @FUNCTION:_java-osgi_makejar-fromfile
+# @USAGE: <jar to repackage with OSGi> <Manifest file> <bundle name> <version rewriting>
+# @INTERNAL
+# @DESCRIPTION:
# This is an internal function, not to be called directly.
#
-# @example
+# @CODE
# _java-osgi_makejar-fromfile "dist/${PN}.jar" "${FILESDIR}/MANIFEST.MF" "JSch" 1
+# @CODE
#
# @param $1 - name of jar to repackage with OSGi
# @param $2 - path to the Manifest file
# @param $3 - bundle name
# @param $4 - automatic version rewriting (0 or 1)
-#
-# ------------------------------------------------------------------------------
-
_java-osgi_makejar-fromfile() {
debug-print-function ${FUNCNAME} "$@"
@@ -212,27 +205,26 @@ _java-osgi_makejar-fromfile() {
rm -rf "${_OSGI_T}/tmp_jar"
}
-# -----------------------------------------------------------------------------
-# @ebuild-function java-osgi_newjar-fromfile()
-#
+# @FUNCTION: java-osgi_newjar-fromfile
+# @USAGE: <jar to repackage with OSGi> <Manifest file> <bundle name> <version rewriting>
+# @DESCRIPTION:
# This function produces an OSGi compliant jar from a given manifest file.
# The Manifest Bundle-Version header will be replaced by the current version
# of the package, unless the --no-auto-version option is given.
# It will call java-pkg_newjar at the end.
#
-# @example
+# @CODE
# java-osgi_newjar-fromfile "dist/${PN}.jar" "${FILESDIR}/MANIFEST.MF" "Standard Widget Toolkit for GTK 2.0"
+# @CODE
#
# @param $opt
# --no-auto-version - This option disables automatic rewriting of the
-# version in the Manifest file#
+# version in the Manifest file
+#
# @param $1 - name of jar to repackage with OSGi
# @param $2 (optional) - name of the target jar. It will default to package name if not specified.
# @param $3 - path to the Manifest file
# @param $4 - bundle name
-#
-# ------------------------------------------------------------------------------
-
java-osgi_newjar-fromfile() {
debug-print-function ${FUNCNAME} "$@"
local versionRewriting=1
@@ -252,26 +244,25 @@ java-osgi_newjar-fromfile() {
fi
}
-# -----------------------------------------------------------------------------
-# @ebuild-function java-osgi_dojar-fromfile()
-#
+# @FUNCTION: java-osgi_dojar-fromfile()
+# @USAGE: <jar to repackage with OSGi> <Manifest file> <bundle name>
+# @DESCRIPTION:
# This function produces an OSGi compliant jar from a given manifestfile.
# The Manifest Bundle-Version header will be replaced by the current version
# of the package, unless the --no-auto-version option is given.
# It will call java-pkg_dojar at the end.
#
-# @example
+# @CODE
# java-osgi_dojar-fromfile "dist/${PN}.jar" "${FILESDIR}/MANIFEST.MF" "Standard Widget Toolkit for GTK 2.0"
+# @CODE
#
# @param $opt
# --no-auto-version - This option disables automatic rewriting of the
# version in the Manifest file
+#
# @param $1 - name of jar to repackage with OSGi
# @param $2 - path to the Manifest file
# @param $3 - bundle name
-#
-# ------------------------------------------------------------------------------
-
java-osgi_dojar-fromfile() {
debug-print-function ${FUNCNAME} "$@"
local versionRewriting=1
diff --git a/eclass/java-pkg-simple.eclass b/eclass/java-pkg-simple.eclass
index 7abdb624de5e..c06bb11504a0 100644
--- a/eclass/java-pkg-simple.eclass
+++ b/eclass/java-pkg-simple.eclass
@@ -2,16 +2,13 @@
# Distributed under the terms of the GNU General Public License v2
# $Id$
-inherit java-utils-2
-
-if ! has java-pkg-2 ${INHERITED}; then
- eerror "java-pkg-simple eclass can only be inherited AFTER java-pkg-2"
-fi
-
-# -----------------------------------------------------------------------------
-# @eclass-begin
-# @eclass-summary Eclass for Java sources without build instructions
-#
+# @ECLASS: java-pkg-simple.eclass
+# @MAINTAINER:
+# java@gentoo.org
+# @AUTHOR:
+# Java maintainers (java@gentoo.org)
+# @BLURB: Eclass for packaging Java software with ease.
+# @DESCRIPTION:
# This class is intended to build pure Java packages from Java sources
# without the use of any build instructions shipped with the sources.
# There is no support for resources besides the generated class files,
@@ -19,92 +16,75 @@ fi
# the resulting jar, although these issues may be addressed by an
# ebuild by putting corresponding files into the target directory
# before calling the src_compile function of this eclass.
-# -----------------------------------------------------------------------------
+
+inherit java-utils-2
+
+if ! has java-pkg-2 ${INHERITED}; then
+ eerror "java-pkg-simple eclass can only be inherited AFTER java-pkg-2"
+fi
EXPORT_FUNCTIONS src_compile src_install
# We are only interested in finding all java source files, wherever they may be.
S="${WORKDIR}"
-# -----------------------------------------------------------------------------
-# @variable-external JAVA_GENTOO_CLASSPATH
-# @variable-default ""
-#
+# @ECLASS-VARIABLE: JAVA_GENTOO_CLASSPATH
+# @DEFAULT_UNSET
+# @DESCRIPTION:
# Comma or space separated list of java packages to include in the
# class path. The packages will also be registered as runtime
# dependencies of this new package. Dependencies will be calculated
# transitively. See "java-config -l" for appropriate package names.
-# -----------------------------------------------------------------------------
-# JAVA_GENTOO_CLASSPATH
-
-# -----------------------------------------------------------------------------
-# @variable-external JAVA_CLASSPATH_EXTRA
-# @variable-default ""
#
+# @CODE
+# JAVA_GENTOO_CLASSPATH="foo,bar-2"
+# @CODE
+
+# @ECLASS-VARIABLE: JAVA_CLASSPATH_EXTRA
+# @DEFAULT_UNSET
+# @DESCRIPTION:
# Extra list of colon separated path elements to be put on the
# classpath when compiling sources.
-# -----------------------------------------------------------------------------
-# JAVA_CLASSPATH_EXTRA
-# -----------------------------------------------------------------------------
-# @variable-external JAVA_SRC_DIR
-# @variable-default ""
-#
+# @ECLASS-VARIABLE: JAVA_SRC_DIR
+# @DEFAULT_UNSET
+# @DESCRIPTION:
# Directories relative to ${S} which contain the sources of the
# application. The default of "" will be treated mostly as ${S}
# itself. For the generated source package (if source is listed in
# ${JAVA_PKG_IUSE}), it is important that these directories are
# actually the roots of the corresponding source trees.
-# -----------------------------------------------------------------------------
-# JAVA_SRC_DIR
-
-# -----------------------------------------------------------------------------
-# @variable-external JAVA_ENCODING
-# @variable-default UTF-8
#
-# The character encoding used in the source files
-# -----------------------------------------------------------------------------
+# @CODE
+# JAVA_SRC_DIR="src/java/org/gentoo"
+# @CODE
+
+# @ECLASS-VARIABLE: JAVA_SRC_DIR
+# @DESCRIPTION:
+# The character encoding used in the source files.
: ${JAVA_ENCODING:=UTF-8}
-# -----------------------------------------------------------------------------
-# @variable-external JAVAC_ARGS
-# @variable-default ""
-#
-# Additional arguments to be passed to javac
-# -----------------------------------------------------------------------------
-# JAVAC_ARGS
+# @ECLASS-VARIABLE: JAVAC_ARGS
+# @DEFAULT_UNSET
+# @DESCRIPTION:
+# Additional arguments to be passed to javac.
-# -----------------------------------------------------------------------------
-# @variable-external JAVADOC_ARGS
-# @variable-default ""
-#
-# Additional arguments to be passed to javadoc
-# -----------------------------------------------------------------------------
-# JAVADOC_ARGS
+# @ECLASS-VARIABLE: JAVADOC_ARGS
+# @DEFAULT_UNSET
+# @DESCRIPTION:
+# Additional arguments to be passed to javadoc.
-# -----------------------------------------------------------------------------
-# @variable-external JAVA_JAR_FILENAME
-# @variable-default ${PN}.jar
-#
-# The name of the jar file to create and install
-# -----------------------------------------------------------------------------
+# @ECLASS-VARIABLE: JAVA_JAR_FILENAME
+# @DESCRIPTION:
+# The name of the jar file to create and install.
: ${JAVA_JAR_FILENAME:=${PN}.jar}
-# ------------------------------------------------------------------------------
-# @eclass-src_compile
-#
+# @FUNCTION: java-pkg-simple_src_compile
+# @DESCRIPTION:
# src_compile for simple bare source java packages. Finds all *.java
# sources in ${JAVA_SRC_DIR}, compiles them with the classpath
# calculated from ${JAVA_GENTOO_CLASSPATH}, and packages the resulting
# classes to ${JAVA_JAR_FILENAME}.
-#
-# variables:
-# JAVA_GENTOO_CLASSPATH - list java packages to put on the classpath.
-# JAVA_ENCODING - encoding of source files, used by javac and javadoc
-# JAVA_SRC_DIR - directories containing source files, relative to ${S}
-# JAVAC_ARGS - additional arguments to be passed to javac
-# JAVADOC_ARGS - additional arguments to be passed to javadoc
-# ------------------------------------------------------------------------------
java-pkg-simple_src_compile() {
local sources=sources.lst classes=target/classes apidoc=target/api
@@ -146,14 +126,12 @@ java-pkg-simple_src_compile() {
jar ${jar_args} -C ${classes} . || die "jar failed"
}
-# ------------------------------------------------------------------------------
-# @eclass-src_install
-#
+# @FUNCTION: java-pkg-simple_src_install
+# @DESCRIPTION:
# src_install for simple single jar java packages. Simply packages the
# contents from the target directory and installs it as
# ${JAVA_JAR_FILENAME}. If the file target/META-INF/MANIFEST.MF exists,
# it is used as the manifest of the created jar.
-# ------------------------------------------------------------------------------
java-pkg-simple_src_install() {
local sources=sources.lst classes=target/classes apidoc=target/api
@@ -186,20 +164,14 @@ java-pkg-simple_src_install() {
fi
}
-# ------------------------------------------------------------------------------
-# @internal-function java-pkg-simple_verbose-cmd
-#
+# @FUNCTION: java-pkg-simple_src_install
+# @DESCRIPTION:
# Print a command before executing it. To give user some feedback
# about what is going on, where the time is being spent, and also to
# help debugging ebuilds.
#
# @param $@ - command to be called and its arguments
-# ------------------------------------------------------------------------------
java-pkg-simple_verbose-cmd() {
echo "$*"
"$@"
}
-
-# ------------------------------------------------------------------------------
-# @eclass-end
-# ------------------------------------------------------------------------------