From owner-freebsd-doc@FreeBSD.ORG Fri May 21 09:50:27 2004 Return-Path: Delivered-To: freebsd-doc@hub.freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 3E4B716A4CE for ; Fri, 21 May 2004 09:50:27 -0700 (PDT) Received: from freefall.freebsd.org (freefall.freebsd.org [216.136.204.21]) by mx1.FreeBSD.org (Postfix) with ESMTP id 202EC43D54 for ; Fri, 21 May 2004 09:50:27 -0700 (PDT) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (gnats@localhost [127.0.0.1]) i4LGoDQU074496 for ; Fri, 21 May 2004 09:50:13 -0700 (PDT) (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.12.11/8.12.11/Submit) id i4LGoD6r074495; Fri, 21 May 2004 09:50:13 -0700 (PDT) (envelope-from gnats) Resent-Date: Fri, 21 May 2004 09:50:13 -0700 (PDT) Resent-Message-Id: <200405211650.i4LGoD6r074495@freefall.freebsd.org> Resent-From: FreeBSD-gnats-submit@FreeBSD.org (GNATS Filer) Resent-To: freebsd-doc@FreeBSD.org Resent-Reply-To: FreeBSD-gnats-submit@FreeBSD.org, Herve Quiroz Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 9B08716A4CE; Fri, 21 May 2004 09:46:32 -0700 (PDT) Received: from arabica.esil.univ-mrs.fr (arabica.esil.univ-mrs.fr [139.124.41.108]) by mx1.FreeBSD.org (Postfix) with ESMTP id BFAD243D1D; Fri, 21 May 2004 09:46:31 -0700 (PDT) (envelope-from rv@arabica.esil.univ-mrs.fr) Received: from arabica.esil.univ-mrs.fr (localhost.esil.univ-mrs.fr [127.0.0.1])i4LGj7a4015634; Fri, 21 May 2004 18:45:07 +0200 (CEST) (envelope-from rv@arabica.esil.univ-mrs.fr) Received: (from rv@localhost)i4LGj6Pr015633; Fri, 21 May 2004 18:45:06 +0200 (CEST) (envelope-from rv) Message-Id: <200405211645.i4LGj6Pr015633@arabica.esil.univ-mrs.fr> Date: Fri, 21 May 2004 18:45:06 +0200 (CEST) From: Herve Quiroz To: FreeBSD-gnats-submit@FreeBSD.org X-Send-Pr-Version: 3.113 cc: linimon@FreeBSD.org Subject: docs/67001: [PATCH] Java section of the Porter's Handbook (continued) X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list Reply-To: Herve Quiroz List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 21 May 2004 16:50:27 -0000 >Number: 67001 >Category: docs >Synopsis: [PATCH] Java section of the Porter's Handbook (continued) >Confidential: no >Severity: non-critical >Priority: low >Responsible: freebsd-doc >State: open >Quarter: >Keywords: >Date-Required: >Class: change-request >Submitter-Id: current-users >Arrival-Date: Fri May 21 09:50:12 PDT 2004 >Closed-Date: >Last-Modified: >Originator: Herve Quiroz >Release: FreeBSD 5.2.1-RELEASE-p5 i386 >Organization: >Environment: System: FreeBSD arabica.esil.univ-mrs.fr 5.2.1-RELEASE-p5 FreeBSD 5.2.1-RELEASE-p5 #3: Thu May 6 20:17:47 CEST 2004 >Description: Here is the second part of the Java section of the Porter's handbook: - Added a table for constants. - Added a "Best practices" subsection that depicts the encouraged policy for Java ports regarding many aspects (location of JAR files, use of PLIST_FILES, category for PRs)... NOTE: There is (again) nothing regarding JAVA_PREFERRED_PORT but now I think we should make a short statement about it. This will probably be part of the next iteration. NOTE2: A lot of information from http://www.freebsd.org/java/docs/howtoports.html is deprecated. IIRC someone already posted something regarding this (with a patch to update it) on the freebsd-java mailing list for review. NOTE3: I had problems referencing sections of the same document. It works for 'html' but not for 'html-split'. Mark Linimon is CC'ed (as we already worked together on the first part) >How-To-Repeat: >Fix: Index: book.sgml =================================================================== RCS file: /home/ncvs/doc/en_US.ISO8859-1/books/porters-handbook/book.sgml,v retrieving revision 1.405 diff -u -r1.405 book.sgml --- book.sgml 21 May 2004 07:10:59 -0000 1.405 +++ book.sgml 21 May 2004 16:27:42 -0000 @@ -4151,6 +4151,108 @@ to get information for debugging your port. It will display the value of many of the forecited variables. + Additionally, the following constants are defined so all Java ports + may be installed in a consistent way: + + + Constants defined for ports that use Java + + + + + Constant + Value + + + + + JAVASHAREDIR + The base directory for everything related to Java. Default value + is ${PREFIX}/share/java. + + + JAVAJARDIR + The directory where JAR files should be installed. Default value + is ${JAVASHAREDIR}/classes. + + +
+ + + Best practices + + When porting a Java library, your port should install the JAR + file(s) in ${JAVAJARDIR}, and everything else + under ${JAVASHAREDIR}/${PORTNAME} (except for the + documentation, see below). In order to reduce the packing file size, + you may reference the JAR file(s) directly in the + Makefile. Just use the following statement (where + myport.jar is the name of the JAR file installed + as part of the port): + + PLIST_FILES+= ${JAVAJARDIR:S,^${PREFIX}/,,}/myport.jar + + When porting a Java application, the port usually install + everything under a single directory (including its JAR dependencies). + The use of ${JAVASHAREDIR}/${PORTNAME} is strongly + encouraged in this extend. It is up the porter to decide whether the + port should install the additional JAR dependencies under this + directory or directly use the already installed ones (from + ${JAVAJARDIR}). + + Regardless of the type of your port (library or application), the + additional documentation should be installed in the usual location as + for any port (see this + section). The JavaDoc tool is known to produce a different set + of files depending on the version of the JDK that is used. For ports + that do not enforce the use of a particular JDK, it is therefore a + complex task to specify the packing list + (pkg-plist). This is one reason why porters are + strongly encouraged to use the PORTDOCS macro. This + feature is unfortunately not (yet) documented in this document so you + should refer to bsd.port.mk itself for further + information. Moreover, even if you can predict the set of files that + will be generated by javadoc, the size of the + resulting pkg-plist advocates for the use of the + forecited PORTDOCS macro. + + The default value for DATADIR is + ${PREFIX}/share/${PORTNAME}. It is a good idea to + override DATADIR to + ${JAVASHAREDIR}/${PORTNAME} for Java ports. + Indeed, DATADIR is automatically addded to + PLIST_SUB (documented here) so you may use + %%DATADIR%% directly in + pkg-plist. + + As for the choice of building Java ports from source or directly + installing them from a binary distribution, there is no defined policy + at the time of writing. However, people from the FreeBSD Java Project + encourage porters to have their ports built from source whenever it is + a trivial task. + + All the features that have been presented in this section are + implemented in bsd.java.mk. If you ever think that + your port needs more sophisticated Java support, please first have a + look at the bsd.java.mk + CVS log as it usually takes some time to document the latest + features. Then, if you think the support you are lacking would be + beneficial to many other Java ports, feel free to discuss it on the + FreeBSD Java mailing list. + + Although there is a java category for PRs, it + refers to the JDK porting effort from the FreeBSD Java project. + Therefore, you should submit your Java port in the + ports category as for any other port, unless of + course it turns out that the issue you are trying to resolve is related + to either a JDK implementation or + bsd.java.mk. + + + >Release-Note: >Audit-Trail: >Unformatted: