From rv@arabica.esil.univ-mrs.fr  Fri May 14 05:19:30 2004
Return-Path: <rv@arabica.esil.univ-mrs.fr>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP
	id 3089716A4CE; Fri, 14 May 2004 05:19:30 -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 5F20143D5C; Fri, 14 May 2004 05:19:28 -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])
	by arabica.esil.univ-mrs.fr (8.12.10/8.12.10) with ESMTP id i4ECJQa4004734;
	Fri, 14 May 2004 14:19:26 +0200 (CEST)
	(envelope-from rv@arabica.esil.univ-mrs.fr)
Received: (from rv@localhost)
	by arabica.esil.univ-mrs.fr (8.12.10/8.12.10/Submit) id i4ECJPDt004733;
	Fri, 14 May 2004 14:19:25 +0200 (CEST)
	(envelope-from rv)
Message-Id: <200405141219.i4ECJPDt004733@arabica.esil.univ-mrs.fr>
Date: Fri, 14 May 2004 14:19:25 +0200 (CEST)
From: Herve Quiroz <herve.quiroz@esil.univ-mrs.fr>
Reply-To:
To: FreeBSD-gnats-submit@freebsd.org
Cc: Mark Linimon <linimon@lonesome.com>,
	Greg Lewis <glewis@freebsd.org>
Subject: [PATCH] Java section of the Porter's Handbook
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         66633
>Category:       docs
>Synopsis:       [PATCH] Java section of the Porter's Handbook
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    linimon
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Fri May 14 05:20:17 PDT 2004
>Closed-Date:    Fri May 21 00:05:10 PDT 2004
>Last-Modified:  Fri May 21 00:05:10 PDT 2004
>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 Java section of the Porter's handbook. It is up-to-date regarding
the latest additions of bsd.java.mk 2.0 commited by 4.10-RELEASE.

NOTE: I don't explain anything regarding the JAVA_PREFERRED_PORT variable in
this section.  JAVA_PREFERRED_PORT may be used to specify a preferred JDK port
(amongst the suitable ones) for JDK dependency. It allows the end-user to
override the default behaviour of bsd.java.mk (which tends to use native JDKs).
IMHO, this variable should be documented somewhere though, but probably not in
the Porter's handbook as this information is more relevant for users than
porters.

Greg Lewis is CC'ed (as the commiter of bsd.java.mk 2.0)
Mark Linimon is CC'ed (as he agreed sometime ago to be the reviewer)

>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.401
diff -u -r1.401 book.sgml
--- book.sgml	24 Apr 2004 17:39:57 -0000	1.401
+++ book.sgml	14 May 2004 11:59:45 -0000
@@ -3936,7 +3936,214 @@
     <sect1 id="using-java">
       <title>Using Java</title>
 
-      <para>This section is yet to be written.</para>
+      <para>If your port needs a JDK to either build, run or even extract the
+      distfile, then it should define <makevar>USE_JAVA</makevar>.</para>
+
+      <table frame="none">
+        <title>Variables to be defined by ports that use Java</title>
+
+      	<tgroup cols="2">
+      	  <thead>
+      	    <row>
+      	      <entry>Variable</entry>
+      	      <entry>Means</entry>
+      	    </row>
+      	  </thead>
+          <tbody>
+            <row>
+              <entry><makevar>USE_JAVA</makevar></entry>
+              <entry>Should be defined for the remaining variables to have any
+              effect.</entry>
+            </row>
+            <row>
+              <entry><makevar>JAVA_VERSION</makevar></entry>
+              <entry>List of space-separated suitable Java versions for the
+              port.  An optional <literal>"+"</literal> allows you to specify a
+              range of versions (allowed values: <literal>1.1[+] 1.2[+] 1.3[+]
+              1.4[+]</literal>).</entry>
+            </row>
+            <row>
+              <entry><makevar>JAVA_OS</makevar></entry>
+              <entry>List of space-separated suitable JDK port operating
+              systems for the port (allowed values: <literal>native
+              linux</literal>).</entry>
+            </row>
+            <row>
+              <entry><makevar>JAVA_VENDOR</makevar></entry>
+              <entry>List of space-separated suitable JDK port vendors for the
+              port (allowed values: <literal>freebsd bsdjava sun ibm
+              blackdown</literal>).</entry>
+            </row>
+            <row>
+              <entry><makevar>JAVA_BUILD</makevar></entry>
+              <entry>When set, it means that the selected JDK port should be
+              added to build dependencies of the port.</entry>
+            </row>
+            <row>
+              <entry><makevar>JAVA_RUN</makevar></entry>
+              <entry>This variable works exactly the same as
+              <makevar>JAVA_BUILD</makevar> but regarding run
+              dependencies.</entry>
+            </row>
+            <row>
+              <entry><makevar>JAVA_EXTRACT</makevar></entry>
+              <entry>This variable works exactly the same as
+              <makevar>JAVA_BUILD</makevar> but regarding extract
+              dependencies.</entry>
+            </row>
+            <row>
+              <entry><makevar>USE_JIKES</makevar></entry>
+              <entry>Whether the port should or should not use
+              <command>jikes</command> to build. When no value is set for this
+              variable, the port will use <command>jikes</command> to build if
+              available. You may also explicitely forbid or enforce the use of
+              <command>jikes</command> (by setting <literal>'no'</literal> or
+              <literal>'yes'</literal>). In the later case, <filename
+              role="package">devel/jikes</filename> will be added to build
+              dependencies of the port.</entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </table>
+
+      <para>Below is the list of all settings a port will receive after setting
+      <makevar>USE_JAVA</makevar>:</para>
+  
+      <table frame="none">
+        <title>Variables defined for ports that use Java</title>
+
+        <tgroup cols="2">
+          <thead>
+            <row>
+              <entry>Variable</entry>
+              <entry>Value</entry>
+            </row>
+          </thead>
+          <tbody>
+            <row>
+              <entry><makevar>JAVA_PORT</makevar></entry>
+              <entry>The name of the JDK port (e.g.
+              <literal>'java/jdk14'</literal>).</entry>
+            </row>
+            <row>
+              <entry><makevar>JAVA_PORT_VERSION</makevar></entry>
+              <entry>The full version of the JDK port (e.g.
+              <literal>'1.4.2'</literal>). If you only need the first two
+              digits of this version number, use
+              <makevar>${JAVA_PORT_VERSION:C/^([0-9])\.([0-9])(.*)$/\1.\2/}</makevar>.</entry>
+            </row>
+            <row>
+              <entry><makevar>JAVA_PORT_OS</makevar></entry>
+              <entry>The operating system used by the JDK port (e.g.
+              <literal>'linux'</literal>).</entry>
+            </row>
+            <row>
+              <entry><makevar>JAVA_PORT_VENDOR</makevar></entry>
+              <entry>The vendor of the JDK port (e.g.
+              <literal>'sun'</literal>).</entry>
+            </row>
+            <row>
+              <entry><makevar>JAVA_PORT_OS_DESCRIPTION</makevar></entry>
+              <entry>Description of the operating system used by the JDK port
+              (e.g. <literal>'Linux'</literal>).</entry>
+            </row>
+            <row>
+              <entry><makevar>JAVA_PORT_VENDOR_DESCRIPTION</makevar></entry>
+              <entry>Description of the vendor of the JDK port (e.g.
+              <literal>'FreeBSD Foundation'</literal>).</entry>
+            </row>
+            <row>
+              <entry><makevar>JAVA_HOME</makevar></entry>
+              <entry>Path to the installation directory of the JDK (e.g.
+              <literal>'/usr/local/jdk1.3.1'</literal>).</entry>
+            </row>
+            <row>
+              <entry><makevar>JAVAC</makevar></entry>
+              <entry>Path to the Java compiler to use (e.g.
+              <literal>'/usr/local/jdk1.1.8/bin/javac'</literal> or
+              <literal>'/usr/local/bin/jikes'</literal>).</entry>
+            </row>
+            <row>
+              <entry><makevar>JAR</makevar></entry>
+              <entry>Path to the JAR tool to use (e.g.
+              <literal>'/usr/local/jdk1.2.2/bin/jar'</literal> or
+              <literal>'/usr/local/bin/fastjar'</literal>).</entry>
+            </row>
+            <row>
+              <entry><makevar>APPLETVIEWER</makevar></entry>
+              <entry>Path to the <command>appletviewer</command> utility (e.g.
+              <literal>'/usr/local/linux-jdk1.2.2/bin/appletviewer'</literal>).</entry>
+            </row>
+            <row>
+              <entry><makevar>JAVA</makevar></entry>
+              <entry>Path to the <command>java</command> executable. Use this
+              for executing Java programs (e.g.
+              <literal>'/usr/local/jdk1.3.1/bin/java'</literal>).</entry>
+            </row>
+            <row>
+              <entry><makevar>JAVADOC</makevar></entry>
+              <entry>Path to the <command>javadoc</command> utility
+              program.</entry>
+            </row>
+            <row>
+              <entry><makevar>JAVAH</makevar></entry>
+              <entry>Path to the <command>javah</command> program.</entry>
+            </row>
+            <row>
+              <entry><makevar>JAVAP</makevar></entry>
+              <entry>Path to the <command>javap</command> program.</entry>
+            </row>
+            <row>
+              <entry><makevar>JAVA_KEYTOOL</makevar></entry>
+              <entry>Path to the <command>keytool</command> utility program.
+              This variable is availble only if the JDK is Java 1.2 or
+              higher.</entry>
+            </row>
+            <row>
+              <entry><makevar>JAVA_N2A</makevar></entry>
+              <entry>Path to the <command>native2ascii</command> tool.</entry>
+            </row>
+            <row>
+              <entry><makevar>JAVA_POLICYTOOL</makevar></entry>
+              <entry>Path to the <command>policytool</command> program. This
+              variable is available only if the JDK is Java 1.2 or
+              higher.</entry>
+            </row>
+            <row>
+              <entry><makevar>JAVA_SERIALVER</makevar></entry>
+              <entry>Path to the <command>serialver</command> utility
+              program.</entry>
+            </row>
+            <row>
+              <entry><makevar>RMIC</makevar></entry>
+              <entry>Path to the RMI stub/skeleton generator,
+              <command>rmic</command>.</entry>
+            </row>
+            <row>
+              <entry><makevar>RMIREGISTRY</makevar></entry>
+              <entry>Path to the RMI registry program,
+              <command>rmiregistry</command>.</entry>
+            </row>
+            <row>
+              <entry><makevar>RMID</makevar></entry>
+              <entry>Path to the RMI daemon program. This variable is only
+              available if the JDK is Java 1.2 or higher.</entry>
+            </row>
+            <row>
+              <entry><makevar>JAVA_CLASSES</makevar></entry>
+              <entry>Path to the archive that contains the JDK class files. On
+              JDK 1.2 or later, this is
+              <literal>${JAVA_HOME}/jre/lib/rt.jar</literal>. Earlier JDK's use
+              <literal>${JAVA_HOME}/lib/classes.zip</literal>.</entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </table>
+
+      <para>You may use the <literal>java-debug</literal> make target to get
+      information for debugging your port. It will display the value of many of
+      the forecited variables.</para>
+
     </sect1>
 
     <sect1 id="using-python">
>Release-Note:
>Audit-Trail:

From: Herve Quiroz <herve.quiroz@esil.univ-mrs.fr>
To: freebsd-gnats-submit@FreeBSD.org
Cc:  
Subject: Re: docs/66633: [PATCH] Java section of the Porter's Handbook
Date: Fri, 14 May 2004 14:56:04 +0200

 Hum. My e-mail is wrong in this PR. It should be:
 
 herve.quiroz@esil.univ-mrs.fr
 
 I don't know how I got this wrong...
 
 Herve
Responsible-Changed-From-To: freebsd-doc->linimon 
Responsible-Changed-By: linimon 
Responsible-Changed-When: Fri May 14 06:15:56 PDT 2004 
Responsible-Changed-Why:  
I agreed to work on this one earlier. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=66633 

From: Herve Quiroz <herve.quiroz@esil.univ-mrs.fr>
To: freebsd-gnats-submit@FreeBSD.org
Cc:  
Subject: Re: docs/66633: [PATCH] Java section of the Porter's Handbook
Date: Tue, 18 May 2004 18:56:35 +0200

 Mark,
 
 Is there a way to change my e-mail address in the Originator field of
 the PR? As I said earlier, I made a mistake and I can't receive the
 follow-ups...
 
 I also realized that some stuff is missing is the document I submitted,
 such as:
 
 - Explanation about defined constants (JAVAJARDIR, JAVASHAREDIR...)
 - Conventions regarding standard location for Java libraries,
   applications, API docs...
 
 Furthermore, I was also considering adding a subsection called "Best
 practices" that explains what a Java porters is expected to do. I could
 for instance discuss the source/binary issue, and evocate the 'java' vs
 'ports' PR issue we are currently discussing on freebsd-java...
 
 I have enough ideas for the first two items so I'll write up something
 soon on the subject.
 
 Herve
State-Changed-From-To: open->closed 
State-Changed-By: linimon 
State-Changed-When: Fri May 21 00:04:27 PDT 2004 
State-Changed-Why:  
Committed, thanks.  We'll work on the new text on the next 
iteration. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=66633 
>Unformatted:
