go: embed: go:embed produces error when "go.mod" has go version < 1.16

The expectation is that you don’t use embed until you are ready to bump your users forward. Build tags are not sufficient, precisely because of tools that need to analyze everything, such as go mod tidy. The same thing happens (or will happen) with any language change gated by the go.mod version.

This is intentional, because a //go:embed comment will only work correctly with Go 1.16 or later. A //go:embed comment requires importing the “embed” package, which is only available in Go 1.16. So compiling a package with an earlier language version will fail.

As a developer I often rely on the compiler to tell me when I have broken the code. When I change the signature of a function for instance, the compiler will tell me if I have neglected to fix any call sites.

The fact that it will fail on errors on files guarded by build tags is a good thing. I develop on an intel machine. If my change breaks the build on s390 machines, the compiler will tell me. If it didn’t I might end up shipping code which failed to compile on my first s390 user.

Of course people will tell me I should make sure that my CI system builds and test on every possible permutation of supported architectures, OSes, compiler versions etc. And they may be right. But it is far better that compiler tells me about these problems straight away.

If this issue was “fixed” by allowing the code above to compile without error, it would make development and testing far harder. Please don’t do it.

To @lestrrat, my suggestion would be: if you really have to support Go versions < 1.16, then don’t use embed. In general I would aggressively kill off support for old Go versions, and only use language features and APIs available on the oldest Go version you do support.

The confusion is in the fact that we (well, at least I) have used build tags to switch between certain features that were newly introduced. For example, I have the following successfully compiling in go1.16rc1

// +build go1.15

package ecutil

import (
  "math/big"
)

func bigIntFillBytes(v *big.Int, buf []byte) []byte {
  v.FillBytes(buf)
  return buf
}

// +build !go1.15

package ecutil

import (
  "math/big"
)

func bigIntFillBytes(v *big.Int, buf []byte) []byte {
  data := v.Bytes()
  if len(data) > len(buf) {
    panic("ecutil: invalid call to bigIntFillBytes (len(data) > len(buf))")
  }

  copy(buf[len(buf)-len(data):], data)
  return buf
}

// go.mod
module ...
go 1.13 // FillBytes doesn't exist in 1.13, let alone 1.14

In this scenario, I was able to provide support for go 1.14 that doesn’t have (math/big).FillBytes() while utilizing the new feature that only appeared in go 1.15

At first glance I fail to see the difference between the above and below

// +build go1.16
import "embed"

// +build !go1.16
// (code without embed)

// go.mod file
module ...
go 1.15 // kaput

(math/big).Int.FillBytes doesn’t exist in go 1.14, why should it compile, when import "embed" doesn’t? I still think this is inconsistent, but I closed this issue because I realized that this was not something new in go1.16 (and hence unlikely to be changed).

Hope that clears up my reasoning on this issue, at least.

I believe that the build tag solution now works correctly with 1.15.11 - go mod tidy is now resilient to stdlib imports which don’t exist.

For the record, you can work around this issue by declaring go 1.16 in your go.mod file and using build tags to guard the use of go:embed. For example:

// +build go1.16

package m

import (
	_ "embed"
	"fmt"
)

//go:embed hello.txt
var s string

Funny enough, I can “workaround” the issue by removing go 1.11 statement from library’s go.mod. 😃

It would be great if there is an official document to list the features each version supports (and to explain features and functionalities are different).

https://tip.golang.org/doc/go1.16 explains which new features were added to go1.16 which are not in go1.15. Once 1.16 is released, anything before 1.15 becomes unsupported.

If we try to “help” our users by maintaining a table mapping features to versions, this will in effect be supporting unsupported versions of Go and telling people that it is OK to use them. This effort will be far better spent encouraging the community to upgrade to the current tools.

Having spent little time playing around with //go:embed and encountering the error myself, I would say that error message is simple, clear, and reasonable.

If you want to use a language feature introduced in Go 1.16, you will need tools >= 1.16 and version 1.16 or greater specified in your go.mod. I may be missing something, but I can’t think of any scenario where someone would want to add embedding while keeping the Go version specified as 1.15 or less.

I have learned that go mod tidy on 1.15 which uses io/fs, regardless of build tags, will fail. Fair enough! Closing.

For reference, that’s #40067, and it even affects users of modules that try and use new standard library packages.

No module can successfully guard its use of a new standard library package with a build tag and have it not still break downstream users with older Go versions. (I expect this to start happening pretty often now that everyone is excited for embed, unlike when maphash was added.)