Doc/go tool for builder #12990
Doc/go tool for builder #12990
Conversation
|
|
| @@ -42,3 +42,5 @@ retract ( | |||
| v0.57.1 // Release failed, use v0.57.2 | |||
| v0.57.0 // Release failed, use v0.57.2 | |||
| ) | |||
|
|
|||
| tool go.opentelemetry.io/collector/cmd/builder | |||
There was a problem hiding this comment.
Does it makes sense to add OCB as a tool in its own mod file? My assumption is that this would only be useful if we use the builder to build the builder.
There was a problem hiding this comment.
i don't have enough knowledge about OTEL to answer that question.
It's my first time using the OCB, i was fighting for a couple hours with binary versions and when i though about go tool and noticed how good the experience was i came here to open an issue and a PR.
This should be discussed separately i think
There was a problem hiding this comment.
BTW about your other comment about running the go get --tool,
i've cleaned up all my deps and my cache just in case and it's working just fine.
i'm using:
go version go1.24.0 darwin/arm64go version go1.24.2 linux/amd64
There was a problem hiding this comment.
I see. I tried creating a brand new Go project and go get --tools works, whereas it doesn't work in my existing project. It seems like the existing dependencies can interfere with it; maybe we should call this out?
There was a problem hiding this comment.
Regarding this line, I think we should remove it from the PR. The tool directive only makes sense in the module where we plan to use the tool.
cmd/builder/README.md
Outdated
| ### `go get --tool` (go version >= 1.24) | ||
|
|
||
| You need to have a `go` compiler in your PATH as well as a go project. | ||
|
|
||
| Run the following command to register the `builder` CLI as a go tool. | ||
|
|
||
| ```console | ||
| go get --tool go.opentelemetry.io/collector/cmd/builder | ||
| ``` | ||
|
|
||
| If Installed through this method, the binary can be called with `go tool builder` (only accessible from within your go project) | ||
|
|
||
| The upside of using `go get --tool` over the other aforementioned method is that the go toolchain manages the binary like any other dependency. | ||
|
|
||
| This has a couple upsides: | ||
|
|
||
| - Your imports of otel libraries such as otel-core within your code will use the same version used to build the `builder` binary ensuring compatibility. | ||
| - Different go projects using different versions will use different `builder` managed automatically instead of forcing the user to download multiple versions of the binary. |
There was a problem hiding this comment.
Nitpick: A few formatting suggestions:
| ### `go get --tool` (go version >= 1.24) | |
| You need to have a `go` compiler in your PATH as well as a go project. | |
| Run the following command to register the `builder` CLI as a go tool. | |
| ```console | |
| go get --tool go.opentelemetry.io/collector/cmd/builder | |
| ``` | |
| If Installed through this method, the binary can be called with `go tool builder` (only accessible from within your go project) | |
| The upside of using `go get --tool` over the other aforementioned method is that the go toolchain manages the binary like any other dependency. | |
| This has a couple upsides: | |
| - Your imports of otel libraries such as otel-core within your code will use the same version used to build the `builder` binary ensuring compatibility. | |
| - Different go projects using different versions will use different `builder` managed automatically instead of forcing the user to download multiple versions of the binary. | |
| ### `go get --tool` (Go version >= 1.24) | |
| You need to have a `go` compiler in your PATH, as well as a Go project containing a `go.mod` file. | |
| Run the following command to register the `builder` CLI as a Go tool. | |
| ```console | |
| go get --tool go.opentelemetry.io/collector/cmd/builder | |
| ``` | |
| If Installed through this method, the binary can be called with `go tool builder`. Note that it will only be accessible from within your Go project. | |
| The upside of using `go get --tool` over the other aforementioned method is that the Go toolchain manages the binary like any other dependency. | |
| This has a couple upsides: | |
| - Imports of OTel libraries such as opentelemetry-collector within your code will use the same version used to build the `builder` binary, ensuring compatibility. | |
| - Different Go projects using different versions will use different `builder` managed automatically instead of forcing the user to download multiple versions of the binary. |
There was a problem hiding this comment.
go get --tool(Go version >= 1.24)
i meant go version as like writting in your terminal go version so i think i'd like to keep it as it is i think ? ( no strong opinion though, feel free to request a change nonetheless if you disagree).
i'm fine with your other points :)
There was a problem hiding this comment.
Sure, that works. Maybe put it in an inline monospace block to emphasize the fact that it's a command?
|
This may be a setup issue on my part, but I tried running |
- Use the method - Updated the versions of the libs to the latest current version
- wording in go install section - Moved the ocb --help line to the released binary section
DoppleDankster
force-pushed
the
doc/go-tool-for-builder
branch
from
ab9826d to
387a016
Compare
|
i've pushed your change requests, if you have further comments please go ahead :) |
| If Installed through this method, the binary can be called with `go tool builder`. Note that it will only be accessible from within your Go project. | ||
|
|
||
| The upside of using `go get --tool` over the other aforementioned method is that the go toolchain manages the binary like any other dependency. |
There was a problem hiding this comment.
Two more suggestions, to make clear what "managed like any other dependency" means.
| If Installed through this method, the binary can be called with `go tool builder`. Note that it will only be accessible from within your Go project. | |
| The upside of using `go get --tool` over the other aforementioned method is that the go toolchain manages the binary like any other dependency. | |
| If installed through this method, the binary can be called with `go tool builder`. Note that it will only be accessible from within your Go project. | |
| The upside of using `go get --tool` over the other aforementioned method is that the go toolchain manages the binary like any other dependency: a `tool` directive will be added to your `go.mod` file. |
|
Thank you for the changes, this seems almost ready! In the meantime, could you please make sure to sign the CLA? |
Description
go get --tool`added with go 1.24 helps ensuring compatibility between the builder CLI and the libs imported in a go project using OTEL.
Issue Link
Resolves #12973
Testing
create a simple OTEL extension and compile it with
go tool builder --config=builder-config.yamlDocumentation
Updated Documentation with mention of the
go get --tooladded with go 1.24.