Bug 75636
| Summary: | [PATCH] Update the Porter's handbook - Java section | ||||||
|---|---|---|---|---|---|---|---|
| Product: | Documentation | Reporter: | Herve Quiroz <hq> | ||||
| Component: | Books & Articles | Assignee: | Greg Lewis <glewis> | ||||
| Status: | Closed FIXED | ||||||
| Severity: | Affects Only Me | ||||||
| Priority: | Normal | ||||||
| Version: | Latest | ||||||
| Hardware: | Any | ||||||
| OS: | Any | ||||||
| Attachments: |
|
||||||
|
Description
Herve Quiroz
2004-12-29 22:20:19 UTC
Responsible Changed From-To: freebsd-doc->glewis You're a doc-commiter and the co-maintainer of bsd.java.mk, so this one is for you. 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
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> 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
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 Committed. Thanks Herve! Maybe we should open separate PRs on your NOTE2 and NOTE3? |