Go: runtime: GOROOT() docs are confusing

[natefinch]

The docs say:

GOROOT returns the root of the Go tree. It uses the GOROOT environment variable, if set, or else the root used during the Go build.

Thus I expect this would print "Hi!":

package main

import (
    "fmt"
    "log"
    "os"
    "runtime"
)

func main() {
    err := os.Setenv("GOROOT", "Hi!")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(runtime.GOROOT())
}

However, this prints my real goroot, not "Hi!".

Either GOROOT() should actually check the environment variable when called, or the docs should be clarified to specify that it returns the GOROOT environment variable set at init() time.

[dmitshur]

@gopherbot added the Documentation label automatically due to "docs" in issue title, but I think it needs to be decided/confirmed whether it's a bug in implementation or documentation.

If the current behavior is deemed correct, here's a take at fixing the documentation:

GOROOT returns the root of the Go tree. It uses the GOROOT environment variable, if set at process start, or else the root used during the Go build.

Also, https://godoc.org/runtime#NumCPU has some precedent:

The set of available CPUs is checked by querying the operating system at process startup. Changes to operating system CPU allocation after process startup are not reflected.

[mvdan]

Oh well, I tried.

[rsc]

Decision: document current behavior. runtime.GOROOT is already too subtle without changing this detail.

[dmitshur]

In that case, it'll be a good idea to add a test for this behavior (if one doesn't already exist).

[gopherbot]

Change https://golang.org/cl/75751 mentions this issue: runtime: clarify GOROOT return value in documentation