Update the builder to use a consistent binary name.

Update the builder to consistently use "ocb" in the name of the command,
version. To avoid needing to be forward compatible with configuration
file names, move the configuration file name from a flag to a command
argument, while deprecating and preserving the original behavior.

This fixes #5581.

Signed-off-by: James Peach <[email protected]>

CHANGELOG.md

@@ -15,6 +15,10 @@
 - Fix Collector panic when disabling telemetry metrics (#5642)
 - Fix Collector panic when featuregate value is empty (#5663)
 
+### 🚩 Deprecations 🚩
+
+- Deprecate the `ocb` flag `--config`. The `ocb` build configuration file should now be passed as an argument. (#5651)
+
 ## v0.55.0 Beta
 
 ### 🛑 Breaking changes 🛑

Makefile

@@ -17,10 +17,6 @@ ALL_MODULES := $(shell find . -type f -name "go.mod" -exec dirname {} \; | sort
 CMD?=
 TOOLS_MOD_DIR := ./internal/tools
 
-GOOS=$(shell $(GOCMD) env GOOS)
-GOARCH=$(shell $(GOCMD) env GOARCH)
-GH := $(shell which gh)
-
 # TODO: Find a way to configure this in the generated code, currently no effect.
 BUILD_INFO_IMPORT_PATH=go.opentelemetry.io/collector/internal/version
 VERSION=$(shell git describe --always --match "v[0-9]*" HEAD)
@@ -205,7 +201,11 @@ otelcorecol:
 
 .PHONY: genotelcorecol
 genotelcorecol:
-	pushd cmd/builder/ && $(GOCMD) run ./ --skip-compilation --config ../otelcorecol/builder-config.yaml --output-path ../otelcorecol && popd
+	pushd cmd/builder/ && $(GOCMD) run ./ --skip-compilation  --output-path ../otelcorecol ../otelcorecol/builder-config.yaml && popd
+
+.PHONY: ocb
+ocb:
+	$(MAKE) -C cmd/builder ocb
 
 DEPENDABOT_PATH=".github/dependabot.yml"
 .PHONY: internal-gendependabot
@@ -411,5 +411,8 @@ endif
 		echo "'gh' command not found, can't submit the PR on your behalf."; \
 		exit 1; \
 	fi
-	gh pr create --title "[chore] prepare release $(RELEASE_CANDIDATE)"
+	$(GH) pr create --title "[chore] prepare release $(RELEASE_CANDIDATE)"
 
+.PHONY: clean
+clean:
+	test -d bin && $(RM) bin/*

Makefile.Common

@@ -10,6 +10,10 @@ GO_ACC=go-acc
 LINT=golangci-lint
 IMPI=impi
 
+GOOS := $(shell $(GOCMD) env GOOS)
+GOARCH := $(shell $(GOCMD) env GOARCH)
+GH := $(shell which gh)
+
 .PHONY: test
 test:
 	$(GOTEST) $(GOTEST_OPT) ./...

cmd/builder/Makefile

@@ -1 +1,5 @@
 include ../../Makefile.Common
+
+.PHONY: ocb
+ocb:
+	GO111MODULE=on CGO_ENABLED=0 $(GOCMD) build -trimpath -o ../../bin/ocb_$(GOOS)_$(GOARCH) .

cmd/builder/README.md

@@ -7,7 +7,7 @@ This program generates a custom OpenTelemetry Collector binary based on a given
 
 ```console
 $ GO111MODULE=on go install go.opentelemetry.io/collector/cmd/builder@latest
-$ cat > ~/.otelcol-builder.yaml <<EOF
+$ cat > otelcol-builder.yaml <<EOF
 exporters:
   - gomod: "github.com/open-telemetry/opentelemetry-collector-contrib/exporter/alibabacloudlogserviceexporter v0.40.0"
   - import: go.opentelemetry.io/collector/exporter/loggingexporter
@@ -21,7 +21,7 @@ processors:
   - import: go.opentelemetry.io/collector/processor/batchprocessor
     gomod: go.opentelemetry.io/collector v0.40.0
 EOF
-$ builder --output-path=/tmp/dist
+$ builder --output-path=/tmp/dist otelcol-builder.yaml
 $ cat > /tmp/otelcol.yaml <<EOF
 receivers:
   otlp:
@@ -54,10 +54,10 @@ Download the binary for your respective platform under the ["Releases"](https://
 
 ## Running
 
-A configuration file isn't strictly required, but the final artifact won't be different than a regular OpenTelemetry Collector. You probably want to specify at least one module (extension, exporter, receiver, processor) to add to your distribution. You can specify them via a configuration file. When no `--config` flag is provided with the location for the configuration file, `${HOME}/.otelcol-builder.yaml` will be used, if available.
+A configuration file isn't strictly required, but the final artifact won't be different than a regular OpenTelemetry Collector. You probably want to specify at least one module (extension, exporter, receiver, processor) to add to your distribution. You can specify them via a configuration file.
 
 ```console
-$ builder --config config.yaml
+$ builder config.yaml
 ```
 
 Use `builder --help` to learn about which flags are available.

cmd/builder/internal/command.go

@@ -15,6 +15,7 @@
 package internal // import "go.opentelemetry.io/collector/cmd/builder/internal"
 
 import (
+	"errors"
 	"fmt"
 	"strings"
 
@@ -38,9 +39,36 @@ var (
 // Command is the main entrypoint for this application
 func Command() (*cobra.Command, error) {
 	cmd := &cobra.Command{
-		Use:  "builder",
-		Long: fmt.Sprintf("OpenTelemetry Collector distribution builder (%s)", version),
+		Use: "ocb [flags] FILE",
+		Long: fmt.Sprintf("OpenTelemetry Collector Builder (%s)", version) + `
+
+ocb generates a custom OpenTelemetry Collector binary using the
+configuration given by the FILE argument. A configuration file
+isn't required, but if it is not provided the final artifact will
+be a regular un-customized OpenTelemetry Collector.
+`,
+		Args: cobra.MaximumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
+			switch len(args) {
+			case 0:
+				// Backwards compatibility. If the user didn't give the
+				// config arg, then apply the default `--config` flag value
+				// from previous releases.
+				if cfgFile == "" {
+					cfgFile = "$HOME/.otelcol-builder.yaml"
+				}
+			case 1:
+				// If the user used both the deprecated `--config` flag
+				// and the argument, force them to resolve the ambiguity.
+				if cfgFile != "" {
+					return errors.New("configuration flag and argument must not both be provided")
+				}
+
+				cfgFile = args[0]
+			default:
+				return errors.New("unrecognized arguments") // Can't happen due to MaximumNArgs.
+			}
+
 			if err := initConfig(); err != nil {
 				return err
 			}
@@ -58,9 +86,15 @@ func Command() (*cobra.Command, error) {
 		},
 	}
 
-	// the external config file
 	cmd.Flags().StringVar(&cfgFile, "config", "", "config file (default is $HOME/.otelcol-builder.yaml)")
 
+	// Since ocb is a compiler, the input file (if present) should
+	// be the first (and only) command argument. This flag is preserved
+	// for backwards compatibility with pre-1.0 releases.
+	if err := cmd.Flags().MarkDeprecated("config", "pass the build configuration as the first argument instead"); err != nil {
+		panic(err) // Only fails if the usage message is empty, which is a programmer error.
+	}
+
 	// the distribution parameters, which we accept as CLI flags as well
 	cmd.Flags().BoolVar(&cfg.SkipCompilation, "skip-compilation", false, "Whether builder should only generate go code with no compile of the collector (default false)")
 	cmd.Flags().StringVar(&cfg.Distribution.Name, "name", "otelcol-custom", "The executable name for the OpenTelemetry Collector distribution")
@@ -82,11 +116,7 @@ func Command() (*cobra.Command, error) {
 }
 
 func initConfig() error {
-	cfg.Logger.Info("OpenTelemetry Collector distribution builder", zap.String("version", version), zap.String("date", date))
-	// use the default path if there is no config file being specified
-	if cfgFile == "" {
-		cfgFile = "$HOME/.otelcol-builder.yaml"
-	}
+	cfg.Logger.Info("OpenTelemetry Collector Builder", zap.String("version", version), zap.String("date", date))
 
 	// load the config file
 	if err := k.Load(file.Provider(cfgFile), yaml.Parser()); err != nil {

cmd/builder/internal/version.go

@@ -28,8 +28,8 @@ var (
 func versionCommand() *cobra.Command {
 	return &cobra.Command{
 		Use:   "version",
-		Short: "Version of opentelemetry-collector-builder",
-		Long:  "Prints the version of opentelemetry-collector-builder binary",
+		Short: "Version of ocb",
+		Long:  "Prints the version of the ocb binary",
 		Run: func(cmd *cobra.Command, args []string) {
 			cmd.Println(fmt.Sprintf("%s version %s", cmd.Parent().Name(), version))
 		},