From rv@arabica.esil.univ-mrs.fr  Wed Dec 29 22:12:28 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 BEB3316A4CE
	for <FreeBSD-gnats-submit@freebsd.org>; Wed, 29 Dec 2004 22:12:28 +0000 (GMT)
Received: from arabica.esil.univ-mrs.fr (arabica.esil.univ-mrs.fr [139.124.41.108])
	by mx1.FreeBSD.org (Postfix) with ESMTP id 30F5543D80
	for <FreeBSD-gnats-submit@freebsd.org>; Wed, 29 Dec 2004 22:12:28 +0000 (GMT)
	(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.13.1/8.13.1) with ESMTP id iBTMCQMi087199
	for <FreeBSD-gnats-submit@freebsd.org>; Wed, 29 Dec 2004 23:12:26 +0100 (CET)
	(envelope-from rv@arabica.esil.univ-mrs.fr)
Received: (from rv@localhost)
	by arabica.esil.univ-mrs.fr (8.13.1/8.13.1/Submit) id iBTMCQOw087198;
	Wed, 29 Dec 2004 23:12:26 +0100 (CET)
	(envelope-from rv)
Message-Id: <200412292212.iBTMCQOw087198@arabica.esil.univ-mrs.fr>
Date: Wed, 29 Dec 2004 23:12:26 +0100 (CET)
From: Herve Quiroz <hq@freebsd.org>
Reply-To: Herve Quiroz <hq@freebsd.org>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: [PATCH] Update the Porter's handbook - Java section
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         75636
>Category:       docs
>Synopsis:       [PATCH] Update the Porter's handbook - Java section
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    glewis
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          update
>Submitter-Id:   current-users
>Arrival-Date:   Wed Dec 29 22:20:19 GMT 2004
>Closed-Date:    Tue Jan 11 21:47:09 GMT 2005
>Last-Modified:  Tue Jan 11 21:47:09 GMT 2005
>Originator:     Herve Quiroz
>Release:        FreeBSD 5.3-STABLE i386
>Organization:
>Environment:
System: FreeBSD 5.3-STABLE #1: Mon Dec 6 04:02:19 CET 2004 i386

>Description:

Document the latest features from bsd.java.mk and detail a new policy regarding
the 'java'category:

- USE_ANT
- HAVE_JIKES
- JAVALIBDIR
- New entries in SUB_LIST
- Additional notes regarding the 'java' category
- Improve the PLIST_FILES JAR file hint (use %%JAVAJARDIR%%)


NOTE: There are several statements such as:

  "... (see <makevar>MAKEVAR</makevar>, documented <link>here</link>) ..."

Another approach would be to use:

  "... (see <link><makevar>MAKEVAR</makevar></link>) ..."

But I will let that up to you.


NOTE2: I don't know where to document the JAVA_PREFERRED_PORT mechanism but I
doubt this is the right place. Probably on the FreeBSD Java project homepage,
if someone feels like updating it...


NOTE3: We should also consider adding a statement regarding the use of
javavmwrapper in application launcher shell scripts. I'm not quite sure about
this one though.

>How-To-Repeat:

>Fix:

Index: book.sgml
===================================================================
RCS file: /var/fcvs/doc/en_US.ISO8859-1/books/porters-handbook/book.sgml,v
retrieving revision 1.510
diff -u -r1.510 book.sgml
--- book.sgml	22 Dec 2004 23:51:15 -0000	1.510
+++ book.sgml	29 Dec 2004 21:56:53 -0000
@@ -1536,7 +1536,10 @@
 	      <row>
 		<entry><filename>java</filename></entry>
 		<entry>Software related to the Java language.</entry>
-		<entry></entry>
+		<entry><filename>java</filename> shall not be the only
+		  category for a port. Porters are also encouraged not to
+		  use <filename>java</filename> as the main category of a
+		  port.</entry>
 	      </row>
 
 	      <row>
@@ -4297,7 +4300,10 @@
 		<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>
+		dependencies of the port. In any case that <command>jikes</command>
+		is actually used in place of <command>javac</command>, then the
+		<makevar>HAVE_JIKES</makevar> variable is defined by
+		<filename>bsd.java.mk</filename>.</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
@@ -4435,6 +4441,11 @@
 		JDKs used
 		<filename>${JAVA_HOME}/lib/classes.zip</filename>.</entry>
 	    </row>
+	    <row>
+	      <entry><makevar>HAVE_JIKES</makevar></entry>
+	      <entry>Defined whenever <command>jikes</command> is used by
+	        the port (see <makevar>USE_JIKES</makevar> above).</entry>
+	    </row>
 	  </tbody>
 	</tgroup>
       </table>
@@ -4469,10 +4480,41 @@
 		Default:
 		<filename>${JAVASHAREDIR}/classes</filename>.</entry>
 	    </row>
+	    <row>
+	      <entry><makevar>JAVALIBDIR</makevar></entry>
+	      <entry>The directory where JAR files installed by other
+	        ports are located. Default:
+		<filename>${LOCALBASE}/share/java/classes</filename>.</entry>
+	    </row>
 	  </tbody>
 	</tgroup>
       </table>
 
+      <para>The related entries are defined in both
+	<makevar>PLIST_SUB</makevar> (documented
+	<link linkend="porting-plist">here</link>) and
+	<makevar>SUB_LIST</makevar>.</para>
+
+      </sect2>
+
+      <sect2 id="java-building-with-ant">
+	<title>Building with Ant</title>
+
+	<para>When the port is to be built using Apache Ant, it has to
+	  define <makevar>USE_ANT</makevar>. Ant is thus considered to be
+	  the sub-make command. When no <literal>do-build</literal> target
+	  is defined by the port, a default one will be set that simply
+	  runs Ant according to <makevar>MAKE_ENV</makevar>,
+	  <makevar>MAKE_ARGS</makevar> and <makevar>ALL_TARGETS</makevar>.
+	  This is similar to the <makevar>USE_GMAKE</makevar> mechanism,
+	  which is documented <link linkend="makefile-build">here</link>.
+	</para>
+
+	<para>If <command>jikes</command> is used in place of
+	  <command>javac</command> (see <makevar>USE_JIKES</makevar>
+	  <link linkend="java-variables">above</link>), then Ant will
+	  automatically use it to build the port.</para>
+
       </sect2>
 
       <sect2 id="java-best-practices">
@@ -4487,7 +4529,7 @@
 	  statement (where <filename>myport.jar</filename> is the name
 	  of the JAR file installed as part of the port):</para>
 
-	<programlisting>PLIST_FILES+= ${JAVAJARDIR:S,^${PREFIX}/,,}/myport.jar</programlisting>
+	<programlisting>PLIST_FILES+= %%JAVAJARDIR%%/myport.jar</programlisting>
 
 	<para>When porting a Java application, the port usually installs
 	  everything under a single directory (including its JAR
@@ -4548,6 +4590,10 @@
 	  the issue you are trying to resolve is related to either a JDK
 	  implementation or <filename>bsd.java.mk</filename>.</para>
 
+	<para>Similarly, there is a defined policy regarding the
+	  <makevar>CATEGORIES</makevar> of a Java port, which is detailed
+	  <link linkend="makefile-categories">here</link>.</para>
+
       </sect2>
 
     </sect1>
>Release-Note:
>Audit-Trail:
Responsible-Changed-From-To: freebsd-doc->glewis 
Responsible-Changed-By: hq 
Responsible-Changed-When: Wed Dec 29 22:21:46 GMT 2004 
Responsible-Changed-Why:  
You're a doc-commiter and the co-maintainer of bsd.java.mk, so this one is for 
you. 

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

From: Mark Linimon <linimon@lonesome.com>
To: Herve Quiroz <hq@FreeBSD.org>
Cc: FreeBSD-gnats-submit@FreeBSD.org, <freebsd-doc@FreeBSD.org>
Subject: Re: docs/75636: [PATCH] Update the Porter's handbook - Java section
Date: Thu, 30 Dec 2004 14:54:55 -0600 (CST)

 On Wed, 29 Dec 2004, Herve Quiroz wrote:
 
 > +      <para>The related entries are defined in both
 > +	<makevar>PLIST_SUB</makevar> (documented
 > +	<link linkend="porting-plist">here</link>) and
 > +	<makevar>SUB_LIST</makevar>.</para>
 
 (Sorry, I'm barely able to keep up with email ATM due to outside
 constraints, so I'm not sure this has already been addressed.)
 
 I keep trying to write the links this way and get gently reminded that
 there's a better idiom, one that gets rid of this dangling "here" word.
 Yeah, ok, here's a cut-and-paste from Simon:
 
   A link which says "here" is generally a bad idea, they will not really
   make sense in a printed version..
 
   I would suggest:
 
           in <xref linkend="dads-noinstall">.</para>
 
 e.g. the name associated with that reference will be picked up and used.
 It will also be properly highlighted in the web-based version.
 
 (You have 3 instances of this in the above IIRC.)
 
 Otherwise I think it looks good.
 
 mcl
 
 

From: Herve Quiroz <herve.quiroz@esil.univ-mrs.fr>
To: Mark Linimon <linimon@lonesome.com>
Cc: Herve Quiroz <hq@FreeBSD.org>, FreeBSD-gnats-submit@FreeBSD.org,
	freebsd-doc@FreeBSD.org
Subject: Re: docs/75636: [PATCH] Update the Porter's handbook - Java section
Date: Fri, 31 Dec 2004 01:21:35 +0100

 Hi Mark,
 
 On Thu, Dec 30, 2004 at 02:54:55PM -0600, Mark Linimon wrote:
 > (Sorry, I'm barely able to keep up with email ATM due to outside
 > constraints, so I'm not sure this has already been addressed.)
 
 No problem. I assigned the PR to Greg but I'm glad you gave me feedback.
 Thanks for the review.
 
 BTW, all I know of doc/SGML stuff is what I learnt from you so I'm
 always glad when you teach me a new hint ;)
 
 >   I would suggest:
 > 
 >           in <xref linkend="dads-noinstall">.</para>
 > 
 > e.g. the name associated with that reference will be picked up and used.
 > It will also be properly highlighted in the web-based version.
 > 
 > (You have 3 instances of this in the above IIRC.)
 
 Actually 5 :)
 
 Hence, the new patch.
 
 Herve
 
 
 Index: book.sgml
 ===================================================================
 RCS file: /var/fcvs/doc/en_US.ISO8859-1/books/porters-handbook/book.sgml,v
 retrieving revision 1.510
 diff -u -r1.510 book.sgml
 --- book.sgml	22 Dec 2004 23:51:15 -0000	1.510
 +++ book.sgml	31 Dec 2004 00:00:03 -0000
 @@ -1536,7 +1536,10 @@
  	      <row>
  		<entry><filename>java</filename></entry>
  		<entry>Software related to the Java language.</entry>
 -		<entry></entry>
 +		<entry><filename>java</filename> shall not be the only
 +		  category for a port. Porters are also encouraged not to
 +		  use <filename>java</filename> as the main category of a
 +		  port.</entry>
  	      </row>
  
  	      <row>
 @@ -4297,7 +4300,10 @@
  		<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>
 +		dependencies of the port. In any case that <command>jikes</command>
 +		is actually used in place of <command>javac</command>, then the
 +		<makevar>HAVE_JIKES</makevar> variable is defined by
 +		<filename>bsd.java.mk</filename>.</entry>
  	    </row>
  	  </tbody>
  	</tgroup>
 @@ -4435,6 +4441,11 @@
  		JDKs used
  		<filename>${JAVA_HOME}/lib/classes.zip</filename>.</entry>
  	    </row>
 +	    <row>
 +	      <entry><makevar>HAVE_JIKES</makevar></entry>
 +	      <entry>Defined whenever <command>jikes</command> is used by
 +	        the port (see <makevar>USE_JIKES</makevar> above).</entry>
 +	    </row>
  	  </tbody>
  	</tgroup>
        </table>
 @@ -4469,10 +4480,40 @@
  		Default:
  		<filename>${JAVASHAREDIR}/classes</filename>.</entry>
  	    </row>
 +	    <row>
 +	      <entry><makevar>JAVALIBDIR</makevar></entry>
 +	      <entry>The directory where JAR files installed by other
 +	        ports are located. Default:
 +		<filename>${LOCALBASE}/share/java/classes</filename>.</entry>
 +	    </row>
  	  </tbody>
  	</tgroup>
        </table>
  
 +      <para>The related entries are defined in both
 +	<makevar>PLIST_SUB</makevar> (documented in
 +	<xref linkend="porting-plist">) and
 +	<makevar>SUB_LIST</makevar>.</para>
 +
 +      </sect2>
 +
 +      <sect2 id="java-building-with-ant">
 +	<title>Building with Ant</title>
 +
 +	<para>When the port is to be built using Apache Ant, it has to
 +	  define <makevar>USE_ANT</makevar>. Ant is thus considered to be
 +	  the sub-make command. When no <literal>do-build</literal> target
 +	  is defined by the port, a default one will be set that simply
 +	  runs Ant according to <makevar>MAKE_ENV</makevar>,
 +	  <makevar>MAKE_ARGS</makevar> and <makevar>ALL_TARGETS</makevar>.
 +	  This is similar to the <makevar>USE_GMAKE</makevar> mechanism,
 +	  which is documented in <xref linkend="makefile-build">.</para>
 +
 +	<para>If <command>jikes</command> is used in place of
 +	  <command>javac</command> (see <makevar>USE_JIKES</makevar> in
 +	  <xref linkend="java-variables">), then Ant will automatically
 +	  use it to build the port.</para>
 +
        </sect2>
  
        <sect2 id="java-best-practices">
 @@ -4487,7 +4528,7 @@
  	  statement (where <filename>myport.jar</filename> is the name
  	  of the JAR file installed as part of the port):</para>
  
 -	<programlisting>PLIST_FILES+= ${JAVAJARDIR:S,^${PREFIX}/,,}/myport.jar</programlisting>
 +	<programlisting>PLIST_FILES+= %%JAVAJARDIR%%/myport.jar</programlisting>
  
  	<para>When porting a Java application, the port usually installs
  	  everything under a single directory (including its JAR
 @@ -4518,8 +4559,8 @@
  	  idea to override <makevar>DATADIR</makevar> to
  	  <filename>${JAVASHAREDIR}/${PORTNAME}</filename> for Java ports.
  	  Indeed, <makevar>DATADIR</makevar> is automatically addded to
 -	  <makevar>PLIST_SUB</makevar> (documented <link
 -	  linkend="porting-plist">here</link>) so you may use
 +	  <makevar>PLIST_SUB</makevar> (documented in <xref
 +	  linkend="porting-plist">) so you may use
  	  <literal>%%DATADIR%%</literal> directly in
  	  <filename>pkg-plist</filename>.</para>
  
 @@ -4548,6 +4589,10 @@
  	  the issue you are trying to resolve is related to either a JDK
  	  implementation or <filename>bsd.java.mk</filename>.</para>
  
 +	<para>Similarly, there is a defined policy regarding the
 +	  <makevar>CATEGORIES</makevar> of a Java port, which is detailed
 +	  in <xref linkend="makefile-categories">.</para>
 +
        </sect2>
  
      </sect1>

From: Greg Lewis <glewis@eyesbeyond.com>
To: Herve Quiroz <herve.quiroz@esil.univ-mrs.fr>
Cc: freebsd-gnats-submit@freebsd.org
Subject: Re: docs/75636: [PATCH] Update the Porter's handbook - Java section
Date: Tue, 11 Jan 2005 10:21:53 -0700

 I like Herve's latest patch, but suggest some minor changes to the first
 hunk.  The minor problem is that it causes the sentence not to start with
 a capital letter, which I found made things a little hard to read as the
 second and third columns of the page appeared to run together.
 
 Complete diff is included, but the only change should be minor rewording
 of the first hunk.  Herve, please let me know if this is ok.
 
 Index: book.sgml
 ===================================================================
 RCS file: /var/fcvs/doc/en_US.ISO8859-1/books/porters-handbook/book.sgml,v
 retrieving revision 1.510
 diff -u -r1.510 book.sgml
 --- book.sgml	22 Dec 2004 23:51:15 -0000	1.510
 +++ book.sgml	11 Jan 2005 17:11:14 -0000
 @@ -1536,7 +1536,11 @@
  	      <row>
  		<entry><filename>java</filename></entry>
  		<entry>Software related to the Java language.</entry>
 -		<entry></entry>
 +		<entry>The <filename>java</filename> category shall not be
 +		  the only one for a port. Save for ports directly related to
 +		  the Java language, porters are also encouraged not to
 +		  use <filename>java</filename> as the main category of a
 +		  port.</entry>
  	      </row>
  
  	      <row>
 @@ -4297,7 +4301,10 @@
  		<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>
 +		dependencies of the port. In any case that <command>jikes</command>
 +		is actually used in place of <command>javac</command>, then the
 +		<makevar>HAVE_JIKES</makevar> variable is defined by
 +		<filename>bsd.java.mk</filename>.</entry>
  	    </row>
  	  </tbody>
  	</tgroup>
 @@ -4435,6 +4442,11 @@
  		JDKs used
  		<filename>${JAVA_HOME}/lib/classes.zip</filename>.</entry>
  	    </row>
 +	    <row>
 +	      <entry><makevar>HAVE_JIKES</makevar></entry>
 +	      <entry>Defined whenever <command>jikes</command> is used by
 +	        the port (see <makevar>USE_JIKES</makevar> above).</entry>
 +	    </row>
  	  </tbody>
  	</tgroup>
        </table>
 @@ -4469,10 +4481,40 @@
  		Default:
  		<filename>${JAVASHAREDIR}/classes</filename>.</entry>
  	    </row>
 +	    <row>
 +	      <entry><makevar>JAVALIBDIR</makevar></entry>
 +	      <entry>The directory where JAR files installed by other
 +	        ports are located. Default:
 +		<filename>${LOCALBASE}/share/java/classes</filename>.</entry>
 +	    </row>
  	  </tbody>
  	</tgroup>
        </table>
  
 +      <para>The related entries are defined in both
 +	<makevar>PLIST_SUB</makevar> (documented in
 +	<xref linkend="porting-plist">) and
 +	<makevar>SUB_LIST</makevar>.</para>
 +
 +      </sect2>
 +
 +      <sect2 id="java-building-with-ant">
 +	<title>Building with Ant</title>
 +
 +	<para>When the port is to be built using Apache Ant, it has to
 +	  define <makevar>USE_ANT</makevar>. Ant is thus considered to be
 +	  the sub-make command. When no <literal>do-build</literal> target
 +	  is defined by the port, a default one will be set that simply
 +	  runs Ant according to <makevar>MAKE_ENV</makevar>,
 +	  <makevar>MAKE_ARGS</makevar> and <makevar>ALL_TARGETS</makevar>.
 +	  This is similar to the <makevar>USE_GMAKE</makevar> mechanism,
 +	  which is documented in <xref linkend="makefile-build">.</para>
 +
 +	<para>If <command>jikes</command> is used in place of
 +	  <command>javac</command> (see <makevar>USE_JIKES</makevar> in
 +	  <xref linkend="java-variables">), then Ant will automatically
 +	  use it to build the port.</para>
 +
        </sect2>
  
        <sect2 id="java-best-practices">
 @@ -4487,7 +4529,7 @@
  	  statement (where <filename>myport.jar</filename> is the name
  	  of the JAR file installed as part of the port):</para>
  
 -	<programlisting>PLIST_FILES+= ${JAVAJARDIR:S,^${PREFIX}/,,}/myport.jar</programlisting>
 +	<programlisting>PLIST_FILES+= %%JAVAJARDIR%%/myport.jar</programlisting>
  
  	<para>When porting a Java application, the port usually installs
  	  everything under a single directory (including its JAR
 @@ -4518,8 +4560,8 @@
  	  idea to override <makevar>DATADIR</makevar> to
  	  <filename>${JAVASHAREDIR}/${PORTNAME}</filename> for Java ports.
  	  Indeed, <makevar>DATADIR</makevar> is automatically addded to
 -	  <makevar>PLIST_SUB</makevar> (documented <link
 -	  linkend="porting-plist">here</link>) so you may use
 +	  <makevar>PLIST_SUB</makevar> (documented in <xref
 +	  linkend="porting-plist">) so you may use
  	  <literal>%%DATADIR%%</literal> directly in
  	  <filename>pkg-plist</filename>.</para>
  
 @@ -4547,6 +4589,10 @@
  	  <literal>ports</literal> category as for any other port, unless
  	  the issue you are trying to resolve is related to either a JDK
  	  implementation or <filename>bsd.java.mk</filename>.</para>
 +
 +	<para>Similarly, there is a defined policy regarding the
 +	  <makevar>CATEGORIES</makevar> of a Java port, which is detailed
 +	  in <xref linkend="makefile-categories">.</para>
  
        </sect2>
  
 
 -- 
 Greg Lewis                          Email   : glewis@eyesbeyond.com
 Eyes Beyond                         Web     : http://www.eyesbeyond.com
 Information Technology              FreeBSD : glewis@FreeBSD.org

From: Herve Quiroz <herve.quiroz@esil.univ-mrs.fr>
To: Greg Lewis <glewis@eyesbeyond.com>
Cc: freebsd-gnats-submit@freebsd.org
Subject: Re: docs/75636: [PATCH] Update the Porter's handbook - Java section
Date: Tue, 11 Jan 2005 18:55:59 +0100

 On Tue, Jan 11, 2005 at 10:21:53AM -0700, Greg Lewis wrote:
 > Complete diff is included, but the only change should be minor rewording
 > of the first hunk.  Herve, please let me know if this is ok.
 
 Indeed, it's better this way.
 
 Herve
State-Changed-From-To: open->closed 
State-Changed-By: glewis 
State-Changed-When: Tue Jan 11 21:46:28 GMT 2005 
State-Changed-Why:  
Committed.  Thanks Herve! 

Maybe we should open separate PRs on your NOTE2 and NOTE3? 

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