Trivial bug in Go 1.21 doc?

[Jon Forrest]

% go version

go version go1.21.0 linux/amd64

https://pkg.go.dev/cmd/compile says:

"Compile, typically invoked as “go tool compile,” compiles a single Go package comprising the files named on the command line. It then writes a single object file named for the basename of the first source file with a .o suffix."

Consider the following:

empty.go

-----

package main

func main() {
}

------

% go tool compile empty.go

% ls

-rw-r--r--   1 jonf   30 Sep 18 16:36 empty.go
-rw-r--r--   1 jonf 1544 Sep 18 16:38 empty.o

So far, so good. However, the .o file isn't an object file, in spite of its name.

% file empty.o
empty.o: current ar archive

% ar tv empty.o
rw-r--r-- 0/0    218 Dec 31 16:00 1969 __.PKGDEF
rw-r--r-- 0/0   1197 Dec 31 16:00 1969 _go_.o

This clearly shows that the .o file is an archive file, not an object file.

"Go tool compile" is acting like the -pack flag was given. Is this a documentation

error?

Cordially,

Jon Forrest

[Ian Lance Taylor]

It kind of depends on precisely what we mean by "object file". The Go
compiler emits a file in a binary format that can be read by tools
like "go tool nm" or "go tool objdump". It is in a format used only
by Go, and can't be read by tools like plain "nm" or "objdump". It's
true that the file happens to be readable by "ar". But it's not an
archive in any useful sense, because the contents of the archive can't
be read by any tools other than the Go tools.

As it happens, the "go tool compile" -pack option will emit the same
file. The only effect of -pack is to change the default output name
from x.o to x.a.

So it's just semantics. Maybe the documentation could describe more
precisely what is happening, but it's not wrong.

The reason that object files look like archive files boils down to
cgo. When using cgo, the go command will add other files to the
archive. Because object files look like archive files, adding those
other files just requires appending them to the compiler output. So
it's an efficiency hack.

Ian

[Jon Forrest]

On Monday, September 18, 2023 at 5:25:27 PM UTC-7 Ian Lance Taylor wrote:

It kind of depends on precisely what we mean by "object file". The Go
compiler emits a file in a binary format that can be read by tools
like "go tool nm" or "go tool objdump". It is in a format used only
by Go, and can't be read by tools like plain "nm" or "objdump". It's
true that the file happens to be readable by "ar". But it's not an
archive in any useful sense, because the contents of the archive can't
be read by any tools other than the Go tools.

I suggest adding all this to the documentation for "go tool compile".

There's no way I know of to learn it currently from the documentation.

There's a reason why this is important to me, but I'll save it for another

post.

Thanks, Ian, as always.

Jon

[Ian Lance Taylor]

On Mon, Sep 18, 2023 at 6:05 PM Jon Forrest <nob...@gmail.com> wrote:
>
>
> On Monday, September 18, 2023 at 5:25:27 PM UTC-7 Ian Lance Taylor wrote:
>
>
> It kind of depends on precisely what we mean by "object file". The Go
> compiler emits a file in a binary format that can be read by tools
> like "go tool nm" or "go tool objdump". It is in a format used only
> by Go, and can't be read by tools like plain "nm" or "objdump". It's
> true that the file happens to be readable by "ar". But it's not an
> archive in any useful sense, because the contents of the archive can't
> be read by any tools other than the Go tools.
>
> I suggest adding all this to the documentation for "go tool compile".
> There's no way I know of to learn it currently from the documentation.

I'm not sure we want to document it, because we may very well decide
to change it in the future.

From our perspective, the only thing we want to document is that the
output of the compiler is readable by link, nm, and objdump.

Ian