Update the builder to use a consistent binary name. (open-telemetry#5651

)

Update the builder to consistently use "ocb" in the name of the command,
version. Since the builder does not expand environment variables in the
config file pathname, the default value for `--config` does not work,
so we can make this flag required so that users don't silently build an
inoperative collector.

This fixes open-telemetry#5581.

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

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)
@@ -207,6 +203,10 @@ otelcorecol:
 genotelcorecol:
 	pushd cmd/builder/ && $(GOCMD) run ./ --skip-compilation --config ../otelcorecol/builder-config.yaml --output-path ../otelcorecol && popd
 
+.PHONY: ocb
+ocb:
+	$(MAKE) -C cmd/builder ocb
+
 DEPENDABOT_PATH=".github/dependabot.yml"
 .PHONY: internal-gendependabot
 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

@@ -1,4 +1,4 @@
-# OpenTelemetry Collector builder
+# OpenTelemetry Collector Builder (ocb)
 [![CI](https://github.com/open-telemetry/opentelemetry-collector-builder/actions/workflows/go.yaml/badge.svg)](https://github.com/open-telemetry/opentelemetry-collector-builder/actions/workflows/go.yaml?query=branch%3Amain)
 
 This program generates a custom OpenTelemetry Collector binary based on a given configuration.
@@ -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 --config=otelcol-builder.yaml --output-path=/tmp/dist
 $ cat > /tmp/otelcol.yaml <<EOF
 receivers:
   otlp:
@@ -51,23 +51,26 @@ $ /tmp/dist/otelcol-custom --config=/tmp/otelcol.yaml
 ## Installation
 
 Download the binary for your respective platform under the ["Releases"](https://github.com/open-telemetry/opentelemetry-collector/releases/latest) page.
+If install an official release build, the binary is named `ocb`, but if you installed by using `go install`, it will be called `builder`.
 
 ## 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 build configuration file must be provided with the `--config` flag.
+You will need to specify at least one module (extension, exporter, receiver, processor) to add to your distribution.
+To build a default collector configuration, you can use [this](../otelcorecol/builder-config.yaml) build configuration.
 
 ```console
-$ builder --config config.yaml
+$ ocb --config=builder-config.yaml
 ```
 
-Use `builder --help` to learn about which flags are available.
+Use `ocb --help` to learn about which flags are available.
 
 ## Configuration
 
 The configuration file is composed of two main parts: `dist` and module types. All `dist` options can be specified via command line flags:
 
 ```console
-$ builder --name="my-otelcol"
+$ ocb --config=config.yaml --name="my-otelcol"
 ```
 
 The module types are specified at the top-level, and might be: `extensions`, `exporters`, `receivers` and `processors`. They all accept a list of components, and each component is required to have at least the `gomod` entry. When not specified, the `import` value is inferred from the `gomod`. When not specified, the `name` is inferred from the `import`.

cmd/builder/internal/command.go

@@ -38,8 +38,13 @@ 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",
+		Long: fmt.Sprintf("OpenTelemetry Collector Builder (%s)", version) + `
+
+ocb generates a custom OpenTelemetry Collector binary using the
+build configuration given by the "--config" argument.
+`,
+		Args: cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if err := initConfig(); err != nil {
 				return err
@@ -58,8 +63,14 @@ func Command() (*cobra.Command, error) {
 		},
 	}
 
-	// the external config file
-	cmd.Flags().StringVar(&cfgFile, "config", "", "config file (default is $HOME/.otelcol-builder.yaml)")
+	cmd.Flags().StringVar(&cfgFile, "config", "", "build configuration file")
+
+	// A build configuration file is always required, and there's no
+	// default. We can relax this in future by embedding the default
+	// config that is used to build otelcorecol.
+	if err := cmd.MarkFlagRequired("config"); 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)")
@@ -82,11 +93,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))
 		},