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

Comments

@james-lawrence
Copy link
Contributor

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

This comment has been minimized.

Copy link
Member

commented Dec 8, 2016

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

@ianlancetaylor

This comment has been minimized.

Copy link
Contributor

commented Dec 8, 2016

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

This comment has been minimized.

Copy link
Contributor Author

commented Dec 8, 2016

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

This comment has been minimized.

Copy link
Contributor

commented Dec 8, 2016

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

@gopherbot

This comment has been minimized.

Copy link

commented Dec 9, 2016

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

@james-lawrence

This comment has been minimized.

Copy link
Contributor Author

commented Dec 9, 2016

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

This comment has been minimized.

Copy link
Contributor

commented Dec 31, 2016

CL is incorrect and should be reverted.

@rsc rsc reopened this Dec 31, 2016

@james-lawrence

This comment has been minimized.

Copy link
Contributor Author

commented Dec 31, 2016

Oh? It worked for my initial tests.

@gopherbot

This comment has been minimized.

Copy link

commented Jan 2, 2017

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

gopherbot pushed a commit that referenced this issue Jan 2, 2017

cmd/link: don't suggest using nm to find -X name
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

This comment has been minimized.

Copy link
Contributor

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

This comment has been minimized.

Copy link
Member

commented Jan 3, 2017

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

@rsc

This comment has been minimized.

Copy link
Contributor

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

This comment has been minimized.

Copy link
Contributor Author

commented Jan 4, 2017

@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

This comment has been minimized.

Copy link
Contributor Author

commented Jan 4, 2017

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

This comment has been minimized.

Copy link
Contributor

commented Jan 6, 2017

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
5 participants
You can’t perform that action at this time.