be a bit more forceful explaining that 'make update' is best effort

and not guaranteed to work (yet useful for porters!)

okay jca@

2 files changed, 40 insertions, 12 deletions

diff --git a/share/man/man5/bsd.port.mk.5 b/share/man/man5/bsd.port.mk.5
index 6f542c4c528..4f5808bc67e 100644
--- a/share/man/man5/bsd.port.mk.5
+++ b/share/man/man5/bsd.port.mk.5
@@ -1,4 +1,4 @@
-.\" $OpenBSD: bsd.port.mk.5,v 1.565 2022/07/06 09:42:15 espie Exp $
+.\" $OpenBSD: bsd.port.mk.5,v 1.566 2022/07/20 16:37:49 espie Exp $
 .\"
 .\" Copyright (c) 2000-2008 Marc Espie
 .\"
@@ -24,7 +24,7 @@
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: July 6 2022 $
+.Dd $Mdocdate: July 20 2022 $
 .Dt BSD.PORT.MK 5
 .Os
 .Sh NAME
@@ -698,9 +698,11 @@ Force rebuilding configure scripts using
 steps.
 .It Cm reinstall
 Force reinstallation of a port, by first cleaning the old installation.
-Seldom needed, as
+This will obviously not work for software used as dependencies of other
+installed software.
+In that case,
 .Cm update
-will often do the right thing.
+might do the right thing.
 .It Cm repackage
 Rebuild the packages of a port after removing existing packages.
 .It Cm run-depends-args
@@ -823,6 +825,16 @@ See
 and
 .Ev FORCE_UPDATE
 as well.
+.Pp
+However, see
+.Sx CAVEATS
+in
+.Xr ports 7 :
+.Cm update
+is always
+.Sq best-effort
+and will often not work correctly when
+updating to a significantly different newer version.
 .It Cm update-or-install
 Update an installed package or perform a fresh installation,
 by using
diff --git a/share/man/man7/ports.7 b/share/man/man7/ports.7
index 1b1b26e70b6..0b513c133b5 100644
--- a/share/man/man7/ports.7
+++ b/share/man/man7/ports.7
@@ -23,10 +23,10 @@
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.\" $OpenBSD: ports.7,v 1.129 2021/11/29 14:06:03 espie Exp $
+.\" $OpenBSD: ports.7,v 1.130 2022/07/20 16:37:50 espie Exp $
 .\" $FreeBSD: ports.7,v 1.7 1998/06/23 04:38:50 hoek Exp $
 .\"
-.Dd $Mdocdate: November 29 2021 $
+.Dd $Mdocdate: July 20 2022 $
 .Dt PORTS 7
 .Os
 .Sh NAME
@@ -431,12 +431,11 @@ the
 See the next section for more details, since most of the fine points of
 bulk package building also apply to updates.
 .Pp
-There are bugs in the ports tree, most related to libtool, which make some
-updates prefer the already installed libraries instead of the newly built
-ones.
-This shows up as undefined references in libraries, in which case there
-is no choice but to proceed the old way: deinstall the offending package
-and everything built on top of it, build and install new packages.
+However, also note that
+.Li make update
+is not guaranteed to work, see
+.Sx CAVEATS
+below.
 .Sh BULK PACKAGE BUILDING
 Building any significant number of packages from the ports tree should use
 .Xr dpb 1 ,
@@ -726,3 +725,20 @@ This man page was originated by
 from the
 .Fx
 project.
+.Sh CAVEATS
+Building a new version of an already installed package is not guaranteed
+to work.
+.Pp
+The safer way would be to create a sandbox for building the updated port
+using
+.Xr proot 1
+.Po see also
+.Xr bulk 8
+.Pc ,
+and then update the installed package.
+.Pp
+Specifically: most software expects building in a virgin environment
+with only the required dependency.
+As a result, lots of time, libraries and headers under
+.Pa /usr/local
+will be favored over the currently building version.