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