Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

cmd/go: ldflags -X needs better documentation #18246

Closed
james-lawrence opened this issue Dec 8, 2016 · 15 comments
Closed

cmd/go: ldflags -X needs better documentation #18246

james-lawrence opened this issue Dec 8, 2016 · 15 comments

Comments

@james-lawrence
Copy link
Contributor

james-lawrence commented Dec 8, 2016

the cmd/link documentation's example is rather useless and most of the
examples I've managed to find of using -X all use main.name in there example. It'd be helpful for a more complete example to exist within the documentation.

example 1
example 2

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

go version go1.7.3 linux/amd64

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

GOARCH="amd64"
GOBIN=""
GOEXE=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOOS="linux"

What did you do?

// file is located at src/github.com/james-lawrence/spike/commands/spike/main.go

// note: I've tried `var version string` as well, and it prints the zero value.
const version = "spike"
func main() {
   fmt.Println("version:", version)
}
go install -ldflags "-X github.com/james-lawrence/spike/commands/spike.version=abc" github.com/james-lawrence/spike/commands/...
./bin/spike

What did you expect to see?

abc or an error/warning about not being able to replace the value.

What did you see instead?

spike

@bradfitz bradfitz changed the title ldflags -X needs better documentation. cmd/go: ldflags -X needs better documentation. Dec 8, 2016
@bradfitz bradfitz added this to the Go1.8Maybe milestone Dec 8, 2016
@bradfitz
Copy link
Contributor

bradfitz commented Dec 8, 2016

Just docs, so maybe we can sneak it into 1.8 yet.

@ianlancetaylor
Copy link
Contributor

We tried giving a warning if the -X variable did not exist in the program, but that broke people that use -X all the time but for whom only some programs have the variable in question. That seemed like a reasonable workflow, so we decided that we shouldn't break it.

The problem with your program is that you are using a const. The docs say you must use a "string variable". A const is not a "string variable".

I'm not sure where to put an example. cmd/link/doc.go seems like an odd place for that, as there are no other examples there. Do you have any suggestions?

@ianlancetaylor ianlancetaylor changed the title cmd/go: ldflags -X needs better documentation. cmd/go: ldflags -X needs better documentation Dec 8, 2016
@james-lawrence
Copy link
Contributor Author

if you read my comment right above that I tried var version string to the same result.

Not sure of a better place to put it. maybe an example .go file with a link from the cmd/link/doc?

@ianlancetaylor
Copy link
Contributor

Would a change like https://golang.org/cl/34230 help?

@gopherbot
Copy link

CL https://golang.org/cl/34230 mentions this issue.

@james-lawrence
Copy link
Contributor Author

yes, super helpful actually.

but it also brings up more questions, I'll play with it more tomorrow and make sure what I'm seeing actually works as I expect. but otherwise it looks good.

@rsc
Copy link
Contributor

rsc commented Dec 31, 2016

CL is incorrect and should be reverted.

@rsc rsc reopened this Dec 31, 2016
@james-lawrence
Copy link
Contributor Author

Oh? It worked for my initial tests.

@gopherbot
Copy link

CL https://golang.org/cl/34791 mentions this issue.

gopherbot pushed a commit that referenced this issue Jan 2, 2017
It doesn't work if the package name includes a '.' or a non-ASCII
character (or '%', '"', or a control character).  See #16710 and CL 31970.

Update #18246.

Change-Id: I1487f462a3dc7b0016fce3aa1ea6239b226e6e39
Reviewed-on: https://go-review.googlesource.com/34791
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
@rsc
Copy link
Contributor

rsc commented Jan 3, 2017

@james-lawrence It sounds like the part missing from the docs that would have helped you is that package main's import path is 'main', not the fully-qualified directory name like for other packages. Am I right that that's what you needed? Or do I misunderstand your situation above?

Thanks.

@bradfitz
Copy link
Contributor

bradfitz commented Jan 3, 2017

@ianlancetaylor, now that the docs have been reverted, do you want to say something else there instead?

@rsc
Copy link
Contributor

rsc commented Jan 3, 2017

The sentence I can imagine adding would be something like

The importpath for the top-level package main is "main".

But I'm a little confused because in @james-lawrence's original post explicitly calls out that the examples he found use 'main', so I was expecting a different shortcoming in the docs.

@james-lawrence
Copy link
Contributor Author

@rsc it was both the main package piece. (In retrospect thats fairly obvious and i just missed it) and the types for which it works. I was having issues in regular packages as well, not main ones. i was also surprised by no support for const :)

@james-lawrence
Copy link
Contributor Author

My initial use cases for using this included both main package and any random package.

They were:

  • compile time optimizing of code. Ie set a bool const to false to optimize a code path out. (Build flags are more suited to this in retrospect)
  • setting a version value at build.

@ianlancetaylor
Copy link
Contributor

I've added an example of using -X to https://golang.org/wiki/GcToolchainTricks .

That's the best approach I've been able to come up with. I'm not sure it's worth adding a pointer from the cmd/link page; I hope that search engines will give the Go wiki high relevance as they discover it. I'm going to close this issue.

@golang golang locked and limited conversation to collaborators Jan 7, 2018
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests

5 participants