doc: explain when to use -ldflags=-extar when cross-compiling

What version of Go are you using (go version)?

go version go1.16.3 darwin/amd64

Does this issue reproduce with the latest release?

Yes

What operating system and processor architecture are you using (go env)?

darwin + amd64

What did you do?

I am compiling Go into a static archive to be called with C code. It works when I compile for the native platform. It does not work when I try to cross-compile for Windows using mingw64

Works:

• cross-compile C for Win using mingw64 (no Go code) (to confirm that my C cross-compile toolchain works) x86_64-w64-mingw32-gcc only_c.c -o only_c.exe

• native compile: Go to static archive, exporting a function myExportedFunction, called by C executable: go build -buildmode=c-archive test.go # ( exports myExportedFunction ) clang test.c test.a -o test # ( test.c calls myExportedFunction )

No errors or warnings:

• compile Go to static archive targeting Windows (cross-compiled on OSX for use with mingw64) CC=x86_64-w64-mingw32-gcc GOOS=windows CGO_ENABLED=1 go build -o test.w64a -buildmode=c-archive test.go
• I have also tried using the below to build the archive (no change-- yields the same error below) CC=x86_64-w64-mingw32-gcc CXX=x86_64-w64-mingw32-g++ CPP=x86_64-w64-mingw32-cpp RANLIB=x86_64-w64-mingw32-ranlib AR=x86_64-w64-mingw32-ar LIBTOOL=/opt/mingw64/bin/libtool GOARCH=amd64 GOOS=windows CGO_ENABLED=1 go build -o test.w64a -buildmode=c-archive test.go

Fails:

• compile executable: C code to call exported Go function, cross-compiled on OSX targeting Windows using mingw64 x86_64-w64-mingw32-gcc test.c test.w64a -o test.exe
• error: /.../x86_64-w64-mingw32-ld: /.../ccmb8owx.o:test.c:(.text+0x29): undefined reference to "myExportedFunction"

What did you expect to see?

No error message, and test.exe file created

What did you see instead?

Error message