Update the Makefiles chapter.

Sponsored by:	Absolight

en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml

@@ -56,6 +56,14 @@
       <para>You should set <varname>PORTNAME</varname> to the base
 	name of your port, and <varname>PORTVERSION</varname> to the
 	version number of the port.</para>
+
+      <warning>
+	<para>Package name should be unique among all of the ports
+	  tree, check that there is not already a port with the same
+	  <varname>PORTNAME</varname> and if there is add one of <link
+	    linkend="porting-pkgnameprefix-suffix"><varname>PKGNAMEPREFIX</varname>
+	    or <varname>PKGNAMESUFFIX</varname></link>.</para>
+      </warning>
     </sect2>
 
     <sect2 xml:id="makefile-naming-revepoch">
@@ -302,7 +310,7 @@ PORTEPOCH=	1</programlisting>
       </sect3>
     </sect2>
 
-    <sect2>
+    <sect2 xml:id="porting-pkgnameprefix-suffix">
       <title><varname>PKGNAMEPREFIX</varname> and
 	<varname>PKGNAMESUFFIX</varname></title>
 
@@ -439,6 +447,14 @@ PORTEPOCH=	1</programlisting>
 	</listitem>
       </orderedlist>
 
+      <warning>
+	<para>Package name should be unique among all of the ports
+	  tree, check that there is not already a port with the same
+	  <varname>PORTNAME</varname> and if there is add one of <link
+	    linkend="porting-pkgnameprefix-suffix"><varname>PKGNAMEPREFIX</varname>
+	    or <varname>PKGNAMESUFFIX</varname></link>.</para>
+      </warning>
+
       <para>Here are some (real) examples on how to convert the name
 	as called by the software authors to a suitable package
 	name:</para>
@@ -1470,7 +1486,9 @@ PORTEPOCH=	1</programlisting>
       <para><varname>DISTNAME</varname> is the name of the port as
 	called by the authors of the software.
 	<varname>DISTNAME</varname> defaults to
-	<literal>${PORTNAME}-${PORTVERSION}</literal>, so override it
+	<literal>${PORTNAME}-${DISTVERSIONPREFIX}${DISTVERSION}${DISTVERSIONSUFFIX}</literal>,
+	and <varname>DISTVERSION</varname> defaults to
+	<literal>${PORTVERSION}</literal> so override it
 	only if necessary.  <varname>DISTNAME</varname> is only used
 	in two places.  First, the distribution file list
 	(<varname>DISTFILES</varname>) defaults to
@@ -1483,9 +1501,25 @@ PORTEPOCH=	1</programlisting>
 	<literal>${PORTNAME}-${PORTVERSION}</literal>-scheme can be
 	handled automatically by setting
 	<varname>DISTVERSION</varname>.
-	<varname>PORTVERSION</varname> and <varname>DISTNAME</varname>
+	<varname>PORTVERSION</varname> will be derived from it
-	will be derived automatically, but can of course be
+	automatically.</para>
-	overridden.  The following table lists some examples:</para>
+
+      <note>
+	<para>Only one of <varname>PORTVERSION</varname> and
+	  <varname>DISTVERSION</varname> can be set at a time.  If you
+	  set <varname>DISTVERSION</varname> and the derived
+	  <varname>PORTVERSION</varname> is not right, do not use
+	  <varname>DISTVERSION</varname>, set
+	  <varname>PORTVERSION</varname> to the right value and set
+	  <varname>DISTNAME</varname> with <varname>PORTNAME</varname>
+	  with either some computation of
+	  <varname>PORTVERSION</varname> or the verbatim upstream
+	  version.</para>
+      </note>
+
+      <para>The following table lists some examples of
+	<varname>DISTVERSION</varname> and the derived
+	<varname>PORTVERSION</varname>:</para>
 
       <informaltable frame="none" pgwide="0">
 	<tgroup cols="2">
@@ -1525,7 +1559,7 @@ PORTEPOCH=	1</programlisting>
 	  <varname>PKGNAMESUFFIX</varname> do not affect
 	  <varname>DISTNAME</varname>.  Also note that if
 	  <varname>WRKSRC</varname> is equal to
-	  <filename>work/${PORTNAME}-${PORTVERSION}</filename> while
+	  <filename>work/${DISTNAME}</filename> while
 	  the original source archive is named something other than
 	  <varname>${PORTNAME}-${PORTVERSION}${EXTRACT_SUFX}</varname>,
 	  you should probably leave <varname>DISTNAME</varname>
@@ -1558,22 +1592,20 @@ PORTEPOCH=	1</programlisting>
       <para>If the original tarball is part of one of the popular
 	archives such as SourceForge, GNU, or Perl CPAN, you may be
 	able refer to those sites in an easy compact form using
-	<varname>MASTER_SITE_<replaceable>*</replaceable></varname>
+	predefined macros (e.g., <literal>SF</literal>,
-	(e.g., <varname>MASTER_SITE_SOURCEFORGE</varname>,
+	<literal>GNU</literal> or <literal>CPAN</literal>).  Simply
-	<varname>MASTER_SITE_GNU</varname> and
+	set <varname>MASTER_SITES</varname> to one of these values.
-	<varname>MASTER_SITE_PERL_CPAN</varname>).  Simply set
+	Here is an example:</para>
-	<varname>MASTER_SITES</varname> to one of these variables and
+
-	<varname>MASTER_SITE_SUBDIR</varname> to the path within the
+      <programlisting>MASTER_SITES=	GNU/make</programlisting>
-	archive.  Here is an example:</para>
+
+      <para>Or you can use the older expanded format, though there
+	really are no reason to do so:</para>
 
       <programlisting>MASTER_SITES=		${MASTER_SITE_GNU}
 MASTER_SITE_SUBDIR=	make</programlisting>
 
-      <para>Or you can use a condensed format:</para>
+      <para>These values and variables are defined in
-
-      <programlisting>MASTER_SITES=	GNU/make</programlisting>
-
-      <para>These variables are defined in
 	<filename>/usr/ports/Mk/bsd.sites.mk</filename>.  There are
 	new entries added all the time, so make sure to check the
 	latest version of this file before submitting a port.</para>
@@ -1633,6 +1665,16 @@ MASTER_SITE_SUBDIR=	stardict/WyabdcRealPeopleTTS/${PORTVERSION}</programlisting>
 	      <entry><varname>/pub/gcc/releases/${DISTNAME}</varname></entry>
 	    </row>
 
+	    <row>
+	      <entry><varname>GH</varname></entry>
+	      <entry><varname>/${GH_ACCOUNT}/${GH_PROJECT}/legacy.tar.gz/${GH_TAGNAME}?dummy=/</varname></entry>
+	    </row>
+
+	    <row>
+	      <entry><varname>GHC</varname></entry>
+	      <entry><varname>/downloads/${GH_ACCOUNT}/${GH_PROJECT}/</varname></entry>
+	    </row>
+
 	    <row>
 	      <entry><varname>GNOME</varname></entry>
 	      <entry><varname>/pub/GNOME/sources/${PORTNAME}/${PORTVERSION:C/^([0-9]+\.[0-9]+).*/\1/}</varname></entry>
@@ -1643,13 +1685,28 @@ MASTER_SITE_SUBDIR=	stardict/WyabdcRealPeopleTTS/${PORTVERSION}</programlisting>
 	      <entry><varname>/gnu/${PORTNAME}</varname></entry>
 	    </row>
 
+	    <row>
+	      <entry><varname>HORDE</varname></entry>
+	      <entry><varname>/pub/${PORTNAME}</varname></entry>
+	    </row>
+
+	    <row>
+	      <entry><varname>LOGILAB</varname></entry>
+	      <entry><varname>/pub/${PORTNAME}</varname></entry>
+	    </row>
+
+	    <row>
+	      <entry><varname>MATE</varname></entry>
+	      <entry><varname>/releases/${PORTVERSION:C/^([0-9]+\.[0-9]+).*/\1/}</varname></entry>
+	    </row>
+
 	    <row>
 	      <entry><varname>MOZDEV</varname></entry>
 	      <entry><varname>/pub/mozdev/${PORTNAME:L}</varname></entry>
 	    </row>
 
 	    <row>
-	      <entry><varname>PERL_CPAN</varname></entry>
+	      <entry><varname>CPAN</varname></entry>
 	      <entry><varname>/pub/CPAN/modules/by-module/${PORTNAME:C/-.*//}</varname></entry>
 	    </row>
 
@@ -1764,7 +1821,8 @@ EXTRACT_ONLY=	source.tar.gz</programlisting>
 
       <para>Do not worry if the patches are compressed; they will be
 	decompressed automatically if the filenames end with
-	<filename>.gz</filename> or <filename>.Z</filename>.</para>
+	<filename>.Z</filename>, <filename>.gz</filename>,
+	<filename>.bz2</filename> or <filename>.xz</filename>.</para>
 
       <para>If the patch is distributed with some other files, such as
 	documentation, in a <command>gzip</command>ped tarball, you
@@ -3088,11 +3146,7 @@ LIB_DEPENDS=	libbar.so:${PORTSDIR}/foo/bar
 	<programlisting>OPTIONS_DEFINE=	BAR
 BAR_DESC=	Bar support
 
-.include &lt;bsd.port.options.mk&gt;
+BAR_LIB_DEPENDS=	libbar.so:${PORTSDIR}/foo/bar</programlisting>
-
-.if ${PORT_OPTIONS:MBAR}
-LIB_DEPENDS=	libbar.so:${PORTSDIR}/foo/bar
-.endif</programlisting>
       </example>
 
       <para>Testing option variables is the correct method.  It will
@@ -3462,17 +3516,8 @@ BAR_DESC=	Support feature bar
 
 OPTIONS_DEFAULT=FOO
 
-.include &lt;bsd.port.options.mk&gt;
+FOO_CONFIGURE_WITH=	foo
-
+BAR_RUN_DEPENDS=	bar:${PORTSDIR}/bar/bar
-.if ${PORT_OPTIONS:MFOO}
-CONFIGURE_ARGS+=--with-foo
-.else
-CONFIGURE_ARGS+=--without-foo
-.endif
-
-.if ${PORT_OPTIONS:MBAR}
-RUN_DEPENDS+=	bar:${PORTSDIR}/bar/bar
-.endif
 
 .include &lt;bsd.port.mk&gt;</programlisting>
 	</example>
@@ -3484,6 +3529,11 @@ RUN_DEPENDS+=	bar:${PORTSDIR}/bar/bar
 	  <programlisting>.if ! ${PORT_OPTIONS:MEXAMPLES}
 CONFIGURE_ARGS+=--without-examples
 .endif</programlisting>
+
+	  <para>Though, you should use the following so that the
+	    configure knob is really enabled and disabled when the
+	    option is.</para>
+	  <programlisting>EXAMPLES_CONFIGURE_WITH=	examples</programlisting>
 	</example>
 
 	<example xml:id="ports-options-practical-use">
@@ -3507,22 +3557,12 @@ SSL_DESC=		Build with OpenSSL support
 
 OPTIONS_DEFAULT=	PGSQL LDAP SSL
 
-.include &lt;bsd.port.options.mk&gt;
+PGSQL_USE=	pgsql=yes
+PGSQL_CONFIGURE_WITH=	postgres
 
-.if ${PORT_OPTIONS:MPGSQL}
+ICU_LIB_DEPENDS=	libicuuc.so:${PORTSDIR}/devel/icu
-USE_PGSQL=		yes
-CONFIGURE_ARGS+=	--with-postgres
-.else
-CONFIGURE_ARGS+=	--without-postgres
-.endif
 
-.if ${PORT_OPTIONS:MICU}
+EXAMPLES_CONFIGURE_WITH=	examples
-LIB_DEPENDS+=	libicuuc.so:${PORTSDIR}/devel/icu
-.endif
-
-.if ! ${PORT_OPTIONS:MEXAMPLES}
-CONFIGURE_ARGS+=	--without-examples
-.endif
 
 # Check other OPTIONS
 
@@ -3559,9 +3599,9 @@ CONFIGURE_ARGS+=	--without-examples
 
 	<note>
 	  <para>There is no need to add these to
-	    <varname>OPTIONS_DEFAULT</varname>.  To have them show up
+	    <varname>OPTIONS_DEFAULT</varname>.  To have them active,
-	    in the options selection dialog, however, they must be
+	    and show up in the options selection dialog, however, they
-	    added to <varname>OPTIONS_DEFINE</varname>.</para>
+	    must be added to <varname>OPTIONS_DEFINE</varname>.</para>
 	</note>
       </sect3>
     </sect2>
@@ -3598,12 +3638,8 @@ CONFIGURE_ARGS+=	--enable-foo
       <example>
 	<title>Correct Handling of an Option</title>
 
-	<programlisting>.if ${PORT_OPTIONS:MFOO}
+	<programlisting>FOO_LIB_DEPENDS=		libfoo.so:${PORTSDIR}/devel/foo
-LIB_DEPENDS+=		libfoo.so:${PORTSDIR}/devel/foo
+FOO_CONFIGURE_ENABLE=	foo</programlisting>
-CONFIGURE_ARGS+=	--enable-foo
-.else
-CONFIGURE_ARGS+=	--disable-foo
-.endif</programlisting>
       </example>
 
       <para>In the second example, the library libfoo is explicitly