phb: add the BUILD_RUN_DEPENDS variable

2 files changed, 20 insertions, 23 deletions

diff --git a/documentation/content/en/books/porters-handbook/makefiles/_index.adoc b/documentation/content/en/books/porters-handbook/makefiles/_index.adoc
index dff50499cd..38b747c226 100644
--- a/documentation/content/en/books/porters-handbook/makefiles/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/makefiles/_index.adoc
@@ -3532,51 +3532,47 @@ Also, the name of the dependency is put into the package so that `pkg install` (
 The _target_ part can be omitted if it is the same as `DEPENDS_TARGET`.
 
 A quite common situation is when `RUN_DEPENDS` is literally the same as `BUILD_DEPENDS`, especially if ported software is written in a scripted language or if it requires the same build and run-time environment.
-In this case, it is both tempting and intuitive to directly assign one to the other:
+In this case, use the `BUILD_RUN_DEPENDS` variable.
 
-[.programlisting]
-....
-RUN_DEPENDS=	${BUILD_DEPENDS}
-....
+[[makefile-build_depends]]
+=== `BUILD_DEPENDS`
 
-However, such assignment can pollute run-time dependencies with entries not defined in the port's original `BUILD_DEPENDS`.
-This happens because of man:make[1]'s lazy evaluation of variable assignment.
-Consider a [.filename]#Makefile# with `USE_*`, which are processed by [.filename]#ports/Mk/bsd.*.mk# to augment initial build dependencies.
-For example, `USES= gmake` adds package:devel/gmake[] to `BUILD_DEPENDS`.
-To prevent such additional dependencies from polluting `RUN_DEPENDS`, create another variable with the current content of `BUILD_DEPENDS` and assign it to both `BUILD_DEPENDS` and `RUN_DEPENDS`:
+This variable specifies executables or files this port requires to build.
+Like `RUN_DEPENDS`, it is a list of ``_path:dir_``[:``_target_``] tuples.
+For example,
 
 [.programlisting]
 ....
-MY_DEPENDS=	some:devel/some \
-		other:lang/other
-BUILD_DEPENDS=	${MY_DEPENDS}
-RUN_DEPENDS=	${MY_DEPENDS}
+BUILD_DEPENDS=	unzip:archivers/unzip
 ....
 
-[IMPORTANT]
+will check for an executable called `unzip`, and descend into the [.filename]#archivers/unzip# subdirectory of the ports tree to build and install it if it is not found.
+
+[NOTE]
 ====
-_Do not_ use `:=` to assign `BUILD_DEPENDS` to `RUN_DEPENDS` or vice-versa.
-All variables are expanded immediately, which is exactly the wrong thing to do and almost always a failure.
+"build" here means everything from extraction to compilation.
+The dependency is checked from within the `extract` target.
+The _target_ part can be omitted if it is the same as `DEPENDS_TARGET`
 ====
 
-[[makefile-build_depends]]
-=== `BUILD_DEPENDS`
+[[makefile-build_run_depends]]
+=== `BUILD_RUN_DEPENDS`
 
-This variable specifies executables or files this port requires to build.
+This variable specifies executables or files this port requires to build and to run.
 Like `RUN_DEPENDS`, it is a list of ``_path:dir_``[:``_target_``] tuples.
 For example,
 
 [.programlisting]
 ....
-BUILD_DEPENDS=	unzip:archivers/unzip
+BUILD_RUN_DEPENDS=	unzip:archivers/unzip
 ....
 
 will check for an executable called `unzip`, and descend into the [.filename]#archivers/unzip# subdirectory of the ports tree to build and install it if it is not found.
 
 [NOTE]
 ====
-"build" here means everything from extraction to compilation.
-The dependency is checked from within the `extract` target.
+"build_run" here means everything from configuration to compilation, plus run-time.
+The dependency is checked from within the `configure` target and within the `install`.
 The _target_ part can be omitted if it is the same as `DEPENDS_TARGET`
 ====
 
diff --git a/documentation/content/en/books/porters-handbook/order/_index.adoc b/documentation/content/en/books/porters-handbook/order/_index.adoc
index ef8881f3af..2e5e50032e 100644
--- a/documentation/content/en/books/porters-handbook/order/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/order/_index.adoc
@@ -171,6 +171,7 @@ This block is optional. The variables are:
 * crossref:makefiles[makefile-fetch_depends,`FETCH_DEPENDS`]
 * crossref:makefiles[makefile-extract_depends,`EXTRACT_DEPENDS`]
 * crossref:makefiles[makefile-patch_depends,`PATCH_DEPENDS`]
+* crossref:makefiles[makefile-build_run_depends,`BUILD_RUN_DEPENDS`]
 * crossref:makefiles[makefile-build_depends,`BUILD_DEPENDS`]
 * crossref:makefiles[makefile-lib_depends,`LIB_DEPENDS`]
 * crossref:makefiles[makefile-run_depends,`RUN_DEPENDS`]