cmd/cgo: document #include <> search path behaviour
cgo effectively prepends -I${SRCDIR} to the header include path of all
preambles it processes, so when an #include <> matches a header file
both in the source directory and also another include directory, the
local copy will be used in preference.
This behaviour is surprising but unfortunately also longstanding and
relied upon by packages in the wild, so the best we can do is to
document it.
Fixes #41059
Change-Id: If6d2818294b2bd94ea0fe5fd6ce77e54b3e167a6
Reviewed-on: https://go-review.googlesource.com/c/go/+/251758
Reviewed-by: Ian Lance Taylor <iant@golang.org>
diff --git a/misc/cgo/test/test.go b/misc/cgo/test/test.go
index 35bc3a1..05fa52b 100644
--- a/misc/cgo/test/test.go
+++ b/misc/cgo/test/test.go
@@ -319,6 +319,7 @@
// issue 4339
// We've historically permitted #include <>, so test it here. Issue 29333.
+// Also see issue 41059.
#include <issue4339.h>
// issue 4417
diff --git a/src/cmd/cgo/doc.go b/src/cmd/cgo/doc.go
index ca18c45..b3f371b 100644
--- a/src/cmd/cgo/doc.go
+++ b/src/cmd/cgo/doc.go
@@ -112,6 +112,13 @@
environment variables, respectively; those environment variables
may include command line options.
+The cgo tool will always invoke the C compiler with the source file's
+directory in the include path; i.e. -I${SRCDIR} is always implied. This
+means that if a header file foo/bar.h exists both in the source
+directory and also in the system include directory (or some other place
+specified by a -I flag), then "#include <foo/bar.h>" will always find the
+local version in preference to any other version.
+
The cgo tool is enabled by default for native builds on systems where
it is expected to work. It is disabled by default when
cross-compiling. You can control this by setting the CGO_ENABLED
