Gentoo Development: Difference between revisions

From Elvanör's Technical Wiki
Jump to navigation Jump to search
Line 58: Line 58:
* If the package uses an Ant build system with hardcoded classpath inside the build.xml (example: classpath="lib/helper_library.jar"), the best way currently it to use the eclass java-pkg_jarfrom to create a symlink to the Gentoo installed version.
* If the package uses an Ant build system with hardcoded classpath inside the build.xml (example: classpath="lib/helper_library.jar"), the best way currently it to use the eclass java-pkg_jarfrom to create a symlink to the Gentoo installed version.


* The following eclass can be used to rewrite an Ant buildfile with your own classpath. The program actually used is /usr/bin/xml-rewrite-2.py.
* The following eclass can be used to rewrite an Ant buildfile with your own classpath. The program actually used is /usr/bin/xml-rewrite-2.py, and you can look at the source code to see exactly what can be done.


  java-ant_xml-rewrite -f build.xml --change -e java -a classpath -v "${sitemesh_classpath}" || die
  java-ant_xml-rewrite -f build.xml --change -e java -a classpath -v "${sitemesh_classpath}" || die


* Report bugs in Java packages both in the main tree and the java-overlay. Don't report bugs in the experimental overlay though.
* Report bugs in Java packages both in the main tree and the java-overlay. Don't report bugs in the experimental overlay though.

Revision as of 10:50, 10 July 2007

  • If you write a simple ebuild, you still have to place it in the main Portage tree or in an overlay to install it via Portage.
  • Emerge app-portage/gentoolkit-dev which contains several utilities needed when developing on Gentoo.

General Ebuild development guide

  • A list of important variables available when writing ebuilds:
    • ${S}: Path to the temporary build directory.
    • ${P}: Package name and version.
    • ${PV}: Package version.
  • ebuild myebuild-1.0.ebuild digest will create the manifest for you. It must be able to access the distribution file. If the SRC_URI does not work yet, put the distfile in /usr/portage/distfiles directly. You must be root when running ebuild digest.
  • Patches must be kept in the files/ directory of the ebuild location if they are small. They should not be compressed.
  • Create a patch in the following way:
diff -u original-file.c modified-file.c > packagename-1.2.5-file.patch
  • Apply it like this (in an ebuild):
epatch "${FILESDIR}/${P}-file.patch"
  • dodoc always acts even if doc USE flag is not set, thus write something like:
use doc && dodoc doc/manual.pdf
  • Always use the program echangelog to document your changes. When you're using an overlay, use echangelog-tng (from the package overlay-utils). Set the environment variable ECHANGELOG_USER:
export ECHANGELOG_USER="Jean-Noël Rivasseau <elvanor@gmail.com>"
  • Naming Rules: Use syntax like package-1.1_rc2. package-1.1-rc2 is an error. If you create a tarball from a Subversion checkout, name it package-1.1_pre1536 or package-1.1_pre20070628 (revision number or date).
  • To clean the temporary work dir, or if anything goes strange, use ebuild clean command.
  • Use repoman (which is included as part of Portage) as a QA tool. It will report basic errors in ebuilds. Adjust manually PORTDIR and PORTDIR_OVERLAY environment variables if need be.

Java Ebuild writing guide

  • ANT_TASKS can be set (and should be set) manually on the ebuild, but only in src_compile() or src_test(). Note that ANT_TASKS basically controls the Ant class path, which is different than the one for javac. So -Dgentoo.classpath, for example, does not affect Ant classpath. Nor does it affect the classpath for the <java> task (although this seems to be in development). Currently it only interacts with the classpath for the <javac> task.
  • The jar names should not contain version number, if you need to rename them, there is an eclass for that: java-pkg_newjar.
  • If a package provides differents APIs, the package should be always SLOTed based on the version of the API.
  • If you use eclasses such as java-pkg_getjars twice, the jars will be recorded twice in package.env.
  • If some library needs to be used only during the build, use java-pkg_getjars --buildonly. The dependency won't be recorded into package.env.
  • To get the dependencies of one library (during ebuild writing), use --with-dependencies. Note that this is a java-config option.
  • Inheriting java-ant-2 adds dev-java/ant-core in DEPEND, so no need to add it explicitly.
  • If a package installs an Ant task, it should be registered in src_install() with java-pkg_register-ant-task. There should also be an RDEPEND on >=dev-java/ant-core-1.7.0.
  • If the package uses an Ant build system with hardcoded classpath inside the build.xml (example: classpath="lib/helper_library.jar"), the best way currently it to use the eclass java-pkg_jarfrom to create a symlink to the Gentoo installed version.
  • The following eclass can be used to rewrite an Ant buildfile with your own classpath. The program actually used is /usr/bin/xml-rewrite-2.py, and you can look at the source code to see exactly what can be done.
java-ant_xml-rewrite -f build.xml --change -e java -a classpath -v "${sitemesh_classpath}" || die
  • Report bugs in Java packages both in the main tree and the java-overlay. Don't report bugs in the experimental overlay though.