code review 15070043: cmd/cgo: stop using compiler error message text to anal...

src/cmd/cgo/doc.go

 // Copyright 2009 The Go Authors.  All rights reserved.
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
 /*
 
 Cgo enables the creation of Go packages that call C code.
 
 Using cgo with the go command
 
@@ skipping 251 matching lines @@
 C source.
 
 Cgo first invokes gcc -E -dM on the preamble, in order to find out
 about simple #defines for constants and the like. These are recorded
 for later use.
 
 Next, cgo needs to identify the kinds for each identifier. For the
 identifiers C.foo and C.bar, cgo generates this C program:
 
         <preamble>
-        void __cgo__f__(void) {
-        #line 1 "cgo-test"
-                foo;
-                enum { _cgo_enum_0 = foo };
-                bar;
-                enum { _cgo_enum_1 = bar };
-        }
-
-This program will not compile, but cgo can look at the error messages
-to infer the kind of each identifier. The line number given in the
-error tells cgo which identifier is involved.
-
-An error like "unexpected type name" or "useless type name in empty
-declaration" or "declaration does not declare anything" tells cgo that
-the identifier is a type.
-
-An error like "statement with no effect" or "expression result unused"
-tells cgo that the identifier is not a type, but not whether it is a
-constant, function, or global variable.
-
-An error like "not an integer constant" tells cgo that the identifier
-is not a constant. If it is also not a type, it must be a function or
-global variable. For now, those can be treated the same.
+        #line 1 "not-declared"
+        void __cgo_f_xxx_1(void) { typeof(foo) *__cgo_undefined__; }
+        #line 1 "not-type"
+        void __cgo_f_xxx_2(void) { foo *__cgo_undefined__; }
+        #line 1 "not-const"
+        void __cgo_f_xxx_3(void) { enum { __cgo_undefined__ = (foo)*1 }; }
+        #line 2 "not-declared"
+        void __cgo_f_xxx_1(void) { typeof(bar) *__cgo_undefined__; }
+        #line 2 "not-type"
+        void __cgo_f_xxx_2(void) { bar *__cgo_undefined__; }
+        #line 2 "not-const"
+        void __cgo_f_xxx_3(void) { enum { __cgo_undefined__ = (bar)*1 }; }
+
+This program will not compile, but cgo can use the presence or absence
+of an error message on a given line to deduce the information it
+needs. The program is syntactically valid regardless of whether each
+name is a type or an ordinary identifier, so there will be no syntax
+errors that might stop parsing early.
+
+An error on not-declared:1 indicates that foo is undeclared.
+An error on not-type:1 indicates that foo is not a type (if declared at all, it is an identifier).
+An error on not-const:1 indicates that foo is not an integer constant.
+
+The line number specifies the name involved. In the example, 1 is foo and 2 is bar.
 
 Next, cgo must learn the details of each type, variable, function, or
 constant. It can do this by reading object files. If cgo has decided
 that t1 is a type, v2 and v3 are variables or functions, and c4, c5,
 and c6 are constants, it generates:
 
         <preamble>
         typeof(t1) *__cgo__1;
         typeof(v2) *__cgo__2;
         typeof(v3) *__cgo__3;
@@ skipping 405 matching lines @@
 be overridden using command line flags: 6l -extld=clang
 -extldflags='-ggdb -O3'.  If any package in a build includes a .cc or
 other file compiled by the C++ compiler, the go tool will use the
 -extld option to set the host linker to the C++ compiler.
 
 These defaults mean that Go-aware build systems can ignore the linking
 changes and keep running plain '6l' and get reasonable results, but
 they can also control the linking details if desired.
 
 */