Address Makefile issues around the cgo build

[tashian]

Ok y’all, I’m pulling something out of the rabbit hole here.

I’ve noticed an issue with the Makefile for step-ca, where we use the variable GOFLAGS.
Actually, this has been confusing to me for a long time and I finally discovered why.
In the Makefile, we run, for example $(GOOS_OVERRIDE) $(GOFLAGS) go build -v -o $(PREFIX)bin/$(BINNAME) $(LDFLAGS) $(PKG)
By default, GOFLAGS is set to the value CGO_ENABLED=0
But if I run make build GOFLAGS="CGO_ENABLED=1", I get:

go: parsing $GOFLAGS: non-flag "CGO_ENABLED=1"
make: *** [Makefile:67: download] Error 1

In this case, GOFLAGS is being used both by the Makefile (as go env variables) and by go itself (as “A space-separated list of -flag=value settings to apply to go commands by default”)

So, then, how does the default case even work, since by default GOFLAGS is equal to CGO_ENABLED=0, a non-flag?
It works because by default GOFLAGS is set locally in the Makefile, and it won’t get exported to go as an env.

The only valid value for GOFLAGS that satisfies both go and the Makefile is “”
And this is the only value we use in automations and docs, because it creates a cgo build.
Or, it’s supposed to.
But sometimes it results in a non-cgo build.

Quick sideshow:
Normally, Go creates cgo binaries by default.
But (I think this is a recent change to Go), if gcc is not in $PATH, it will silently not use cgo.
So, the second issue is that our instructions for cgo builds might silently create a non-cgo build, as a user just encountered.
So we need to tell people to run make with CGO_ENABLED=1 set explicitly.
But there isn’t a way to do that. For some reason, make build CGO_ENABLED=1 does not pass CGO_ENABLED=1 to go.

Bottom line:

• The way we’re using it, GOFLAGS should be called GO_ENVS
• We should explicitly set CGO_ENABLED=1 if we want a cgo binary, so that when gcc doesn't exist, go will fail to compile instead of falling back to non-cgo
• GOFLAGS should be reserved for go

A couple backward-compatible options for getting out of this:

1. Change GOFLAGS to GO_ENVS to represent go build flags; and if GOFLAGS is passed in as "", silently set GO_ENVS to CGO_ENABLED=1. Otherwise, default it to CGO_ENABLED=0. This is what I did in this PR.
2. Don't bother with GO_ENVS, just accept CGO_ENABLED=1 into make and export it to go. If GOFLAGS is passed in as "", silently set CGO_ENABLED=1.

Alternatively, we could make a breaking change and just update the docs and cgo-related automations.

[maraino]

The expansion of the variables, is a little weird GO_ENVS ?= CGO_ENABLED=0 might be better.

[tashian]

@maraino ok I think this is ready.

Tests I've run:

Command	Result
make build	cgo disabled
make build GOFLAGS=""	cgo enabled
make build GOFLAGS="-x"	cgo disabled; -x passed to go
make build GO_ENVS="CGO_ENABLED=0"	cgo disabled
make build GO_ENVS="CGO_ENABLED=1"	cgo enabled
make build GO_ENVS="CGO_ENABLED=0" GOFLAGS=""	cgo disabled
make build GO_ENVS="CGO_ENABLED=1" GOFLAGS="-x -trimpath"	cgo enabled; -x -trimpath passed to go

But, GO_ENVS only makes sense if we will use it for more than CGO_ENABLED.
Otherwise we should just support:

make build CGO_ENABLED=1

Also: I made a small change to the README that removes a broken link to the docs folder.