Since the go submodule is hard to patch with, here is a diff to try to
document some of the quirks and observations shared by abieber, sthen,
landry and stsp. While here, edit other parts for consistency and
grammar.

"roll" might be a bit informal and the new section could probably be
trimmed.

"./cmd/..." is also built by
This ... is a bit confusing but I left it as it. I am assuming it means
it builds whatever is inside the cmd directory.

Feedback is welcome. OK?

Index: go-module.5
===================================================================
RCS file: /cvs/src/share/man/man5/go-module.5,v
diff -u -p -r1.5 go-module.5
--- go-module.5 7 Feb 2025 02:53:30 -0000       1.5
+++ go-module.5 4 Nov 2026 23:45:38 -0000
@@ -40,32 +40,34 @@ tree.
 Adds Go toolchain support.
 Requires
 .Ev ALL_TARGET
-to be set to canonical Go import path of port.
-(Module sets it automatically for ports that use
+to be set to the canonical Go import path of the port.
+(The lang/go module sets it automatically for ports that use
 .Ev GH_ACCOUNT
 and
 .Ev GH_PROJECT
 macros.)
 .Pp
-During execution of
+During execution of the
 .Cm pre-configure
-target module moves source code from
+target, the lang/go module moves source code from
 .Pa ${MODGO_SUBDIR}
 to
 .Pa ${WRKSRC} ,
-subdirectory of
-.Pa ${MODGO_WORKSPACE}
-- specially-crafted Go workspace located at
+which is a subdirectory of
+.Pa ${MODGO_WORKSPACE} ,
+a specially-crafted Go workspace located at
 .Pa ${WRKDIR}/go .
 During
-.Cm do-build
-module calls
+.Cm do-build ,
+the lang/go module calls
 .Dq go install
 with
 .Ev GOPATH
 set to
 .Pa ${MODGO_WORKSPACE} ,
-runs its output through sed to prevent writes outside
+runs its output through
+.Xr sed 1
+to prevent writes outside of the
 .Ev WRKDIR
 sandbox and sends output to
 .Xr sh 1 .
@@ -82,8 +84,36 @@ and
 to
 .Pa ${PREFIX}/go ,
 depending on
-.Ev MODGO_TYPE
-contents.
+.Ev MODGO_TYPE .
+.Pp
+There are some quirks to consider that only apply when patching the main
+program (to patch a dependency instead of the main program, roll a
+distfile using
+.Dq go mod vendor
+in the source tree).
+These quirks arise because the
+.Cm pre-configure
+target moves source code around resulting in different targets
+potentially seeing different
+.Ev WRKSRC .
+If the
+.Cm configure
+target has not yet run,
+both the
+.Cm patch
+and the
+.Cm update-patches
+targets work.
+If the
+.Cm configure
+target has already run,
+the
+.Cm update-patches
+target breaks unless
+.Ev WRKDIST
+is temporarily set to
+.Ev WRKSRC :
+.Dl make WRKDIST=$(make show=WRKSRC) update-patches
 .Pp
 Sets
 .Ev BUILD_DEPENDS ,
@@ -106,15 +136,15 @@ May be any combination of:
 .Bl -tag -width lib
 .It bin
 ordinary binary, which should be installed to
-.Pa ${PREFIX}/bin ,
+.Pa ${PREFIX}/bin
 .It lib
-library, which should come with source code.
+library, which should come with source code
 .El
 .Pp
 Defaults to
 .Ar bin .
 .It Ev MODGO_WORKSPACE
-Path to Go workspace set up for port build process.
+Path to Go workspace set up for the port build process.
 Defaults to
 .Pa ${WRKDIR}/go .
 See Go documentation for details.
@@ -143,12 +173,12 @@ If this is set,
 .Ev MODGO_MODFILES
 and
 .Ev MODGO_VERSION
-need to be defined as well.
+need to be defined, as well.
 Setting this will also set
 .Ev ALL_TARGET .
 When
 .Ev MODGO_MODFILES
-is set, and a "cmd" directory is found in
+is set and a "cmd" directory is found in
 .Ev WRKSRC ,
 "./cmd/..." is also built by
 .Cm do-build
@@ -186,7 +216,7 @@ Go package names as arguments),
 and
 .Ev MODGO_{BUILD,RUN}_DEPENDS .
 .Pp
-This module adds one
+The lang/go module adds one
 .Xr make 1
 target:
 .Bl -tag -width modgo-gen-modules

Reply via email to