From 3e14ee97d8ad49b112e6df2a6a1521d7cdac4402 Mon Sep 17 00:00:00 2001
From: James Peach <jpeach@apache.org>
Date: Sat, 23 Jul 2022 00:30:52 +1000
Subject: [PATCH] Update the builder to use a consistent binary name. (#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 #5581.

Signed-off-by: James Peach <jpeach@cloudflare.com>
---
 Makefile                        | 13 ++++++++-----
 Makefile.Common                 |  4 ++++
 cmd/builder/Makefile            |  4 ++++
 cmd/builder/README.md           | 17 ++++++++++-------
 cmd/builder/internal/command.go | 25 ++++++++++++++++---------
 cmd/builder/internal/version.go |  4 ++--
 6 files changed, 44 insertions(+), 23 deletions(-)

diff --git a/Makefile b/Makefile
index a5315964189..53652d14390 100644
--- a/Makefile
+++ b/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/*
diff --git a/Makefile.Common b/Makefile.Common
index 2b31c5d405e..a5aa1c7dbf8 100644
--- a/Makefile.Common
+++ b/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) ./...
diff --git a/cmd/builder/Makefile b/cmd/builder/Makefile
index ded7a36092d..59bde934421 100644
--- a/cmd/builder/Makefile
+++ b/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) .
diff --git a/cmd/builder/README.md b/cmd/builder/README.md
index 6f8eec5a7c9..efe32f3db67 100644
--- a/cmd/builder/README.md
+++ b/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`.
diff --git a/cmd/builder/internal/command.go b/cmd/builder/internal/command.go
index 3dee3a6e586..33f7611e778 100644
--- a/cmd/builder/internal/command.go
+++ b/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 {
diff --git a/cmd/builder/internal/version.go b/cmd/builder/internal/version.go
index e2ee5887ff8..78a00c549fd 100644
--- a/cmd/builder/internal/version.go
+++ b/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))
 		},