- Describe how to assign run dependencies to build dependencies correctly

Submitted by:	danfe

en_US.ISO8859-1/books/porters-handbook/book.sgml

@@ -3181,11 +3181,15 @@ ALWAYS_KEEP_DISTFILES=  yes
       <sect1 id="makefile-depend">
 	<title>Dependencies</title>
 
-	<para>Many ports depend on other ports.  There are seven variables that
+	<para>Many ports depend on other ports.  This is very convenient
-	  you can use to ensure that all the required bits will be on the
+	  and nice feature of most Unix-like operating systems,
-	  user's machine.  There are also some pre-supported dependency
+	  including &os;.  It allows not having to bundle common
-	  variables for common cases, plus a few more to control the behavior
+	  dependencies with every port or package, since a lot of ports
-	  of dependencies.</para>
+	  would share them.  There are seven variables that can be used
+	  to ensure that all the required bits will be on the user's
+	  machine.  There are also some pre-supported dependency
+	  variables for common cases, plus a few more to control the
+	  behavior of dependencies.</para>
 
 	<sect2>
 	  <title><makevar>LIB_DEPENDS</makevar></title>
@@ -3278,6 +3282,36 @@ ALWAYS_KEEP_DISTFILES=  yes
 	    not on the user's system.  The <replaceable>target</replaceable>
 	    part can be omitted if it is the same as
 	    <makevar>DEPENDS_TARGET</makevar>.</para>
+
+	  <para>Quite common situation is when
+	    <makevar>RUN_DEPENDS</makevar> is literally the same as
+	    <makevar>BUILD_DEPENDS</makevar>, especially if ported
+	    software is written in a scripted language or if it requires
+	    the same run-time environment used to build it.  In this
+	    case, it is very tempting, and indeed natural to directly
+	    assign one to another:</para>
+
+	  <programlisting>RUN_DEPENDS= ${BUILD_DEPENDS}</programlisting>
+
+	  <para>However, doing so can and often will result in
+	    run-time dependencies be polluted by superfluous entries, not
+	    present in original port's <makevar>BUILD_DEPENDS</makevar>.
+	    It happens due to the fact that &man.make.1 is being lazy
+	    when it evaluates assignments like these.  Most probably
+	    additional dependencies will be pulled by
+	    <filename>ports/Mk/bsd.*.mk</filename> when processing
+	    <makevar>USE_<replaceable>*</replaceable></makevar>
+	    variables, which most ports contain.  For example, such
+	    direct assignment along with
+	    <literal>USE_GMAKE=yes</literal> will bring
+	    <application>gmake</application> into
+	    <makevar>RUN_DEPENDS</makevar>, despite that it was not
+	    included explicitly in <makevar>BUILD_DEPENDS</makevar>.  To
+	    prevent this from happening, immediate expansion assignment
+	    should be used, i.e. expand the value before assigning it
+	    to the variable:</para>
+
+	    <programlisting>RUN_DEPENDS:=  ${BUILD_DEPENDS}</programlisting>
 	</sect2>
 
 	<sect2>