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 35bc3a1447592f5d8b999b7ab95ee3afaaad1ef4..05fa52b3810dba05baed7a277ae631e656d8ebdd 100644 (file)
--- a/misc/cgo/test/test.go
+++ b/misc/cgo/test/test.go
@@ -319,6 +319,7 @@ typedef enum {
 
 // 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 ca18c45d9d965d4d6383af8889a35ef2afd2ccf8..b3f371b08c4cf0d1713592871a7a73acfc14c536 100644 (file)
--- a/src/cmd/cgo/doc.go
+++ b/src/cmd/cgo/doc.go
@@ -112,6 +112,13 @@ The default C and C++ compilers may be changed by the CC and CXX
 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