Document `--<lang>_opt` flags in protogen docs

[cha-king]

👋 Hello! Very minor issue here, but I was hitting a bit of confusion trying to figure out if I should be using --<lang>_opt or --<lang>_out to pass a custom flag to a protogen plugin.

The current info in the godoc specifies the latter, which I believe is legacy. Maybe the opt equivalent should be documented there instead/as well?

Code for reference:
https://github.com/protocolbuffers/protobuf-go/blob/32018e9a48fe1fb3addef57cd8b745ade54fc0d7/compiler/protogen/protogen.go#L128-L150

Thanks!

[neild]

+1

For historical context (assuming my memory holds): protoc passes code generator parameters in the CodeGeneratorRequest message. It used to take parameters from the --<lang>_out flag, splitting the flag on : and passing everything after the colon as parameters. At some point, it added support for --<lang>_opt as well.

There's no difference between using --<lang>_out=...:<param> and --<lang>_opt=<param>, but obviously --<lang_opt> is simpler and cleaner and everyone should use it. The other approach is just a historical curiosity at this point.

[aktau]

Thanks for reporting, and thanks Damien for commenting. I tried doing a search-and-replace, but get errors:

    integration_test.go:435: executing (go generate ./internal/cmd/generate-protos): exit status 1
        executing: protoc --plugin=protoc-gen-go=/tmp/go-build3557462532/b001/exe/generate-protos --experimental_allow_proto3_optional --experimental_editions -I/home/aktau/gob/go/protobuf/src -I/home/aktau/gob/go/protobuf/.cache/protobuf-31.0/src -I/home/aktau/gob/go/protobuf --go_opt=module=google.golang.org/protobuf,Mcmd/protoc-gen-go/testdata/nopackage/nopackage.proto=google.golang.org/protobuf/cmd/protoc-gen-go/testdata/nopackage,annotate_code:/home/aktau/gob/go/protobuf/tmp193353960 /home/aktau/gob/go/protobuf/cmd/protoc-gen-go/testdata/annotations/annotations.proto
        Missing output directives.

        panic: exit status 1

        goroutine 1 [running]:
        main.check(...)
                /home/aktau/gob/go/protobuf/internal/cmd/generate-protos/main.go:731
        main.protoc({0xc0001cb6f0, 0x5, 0xc000329e5d?})
                /home/aktau/gob/go/protobuf/internal/cmd/generate-protos/main.go:522 +0x477
        main.generateLocalProtos.func1({0xc000329e30, 0x65}, {0x100?, 0x0?}, {0x0?, 0xc0001cb880?})
                /home/aktau/gob/go/protobuf/internal/cmd/generate-protos/main.go:402 +0xc1a
        path/filepath.walk({0xc000329e30, 0x65}, {0x831708, 0xc000355930}, 0xc0001cbe40)
                /home/aktau/gob/go/protobuf/.cache/go1.24.2/src/path/filepath/path.go:345 +0x105
        path/filepath.walk({0xc0003366c0, 0x53}, {0x831708, 0xc0003556c0}, 0xc0001cbe40)
                /home/aktau/gob/go/protobuf/.cache/go1.24.2/src/path/filepath/path.go:369 +0x254
        path/filepath.walk({0xc000324370, 0x47}, {0x831708, 0xc0003555f0}, 0xc0001cbe40)
                /home/aktau/gob/go/protobuf/.cache/go1.24.2/src/path/filepath/path.go:369 +0x254
        path/filepath.Walk({0xc000324370, 0x47}, 0xc0001cbe40)
                /home/aktau/gob/go/protobuf/.cache/go1.24.2/src/path/filepath/path.go:427 +0x66
        main.generateLocalProtos()
                /home/aktau/gob/go/protobuf/internal/cmd/generate-protos/main.go:358 +0x42c
        main.main()
                /home/aktau/gob/go/protobuf/internal/cmd/generate-protos/main.go:109 +0x16f
        exit status 2
        internal/cmd/generate-protos/main.go:5: running "go": exit status 1
--- FAIL: TestIntegration (105.13s)

Then I checked what protoc itself says:

$ ./.cache/bin/protoc

This does mention the <lang>_out options, but not the <lang>_opt versions you mention.

What am I doing wrong?

[neild]

Missing output directives.

I'm not certain, but I'm going to guess that your search-and-replace removed the --go_out directive entirely.

What you'd want to change is (for example) --go_out=module=google.golang.org/protobuf,annotate_code:/path/to/output into --go_opt=module=google.golang.org/protobuf --go_opt=annotate_code --go_out/path/to/output. (I'm pretty sure multiple --go_opt flags work as desired, but maybe that needs to be a single --go_opt with comma-separated options.)

[aktau]

Thanks Damien, that may be it. I won't have time for this in the near future. Anyone in the community feel free to pick it up. I'll find time to review it if so