Makefile: use order-only prereq for podman-remote

podman-remote has a dependency on $(SRCBINDIR), because on
Mac and Windows that's a special dir that may not exist.
But depending on a directory means depending on its mtime,
which changes every time a file in it is updated, which
means running 'make' twice in a row will rebuild podman-remote
for no good reason.

Solution: GNU Make has the concept of "order-only" prerequisites,
precisely for this situation. Use it. Since it's an obscure
feature, document it.

UPDATE: This exposed some nasty duplication wrt podman-remote rules.
Clean those up, and add comments to some confusing sections.

Fixes: #14756

(Also, drive-by edit to remove a stray misdocumented non-option)

Signed-off-by: Ed Santiago <santiago@redhat.com>

3 files changed, 18 insertions, 37 deletions

diff --git a/Makefile b/Makefile
index 27a961574..90c3d98a1 100644
--- a/Makefile
+++ b/Makefile
@@ -146,7 +146,8 @@ CROSS_BUILD_TARGETS := \
 # Dereference variable $(1), return value if non-empty, otherwise raise an error.
 err_if_empty = $(if $(strip $($(1))),$(strip $($(1))),$(error Required variable $(1) value is undefined, whitespace, or empty))
 
-# Podman does not work w/o CGO_ENABLED, except in some very specific cases
+# Podman does not work w/o CGO_ENABLED, except in some very specific cases.
+# Windows and Mac (both podman-remote client only) require CGO_ENABLED=0.
 CGO_ENABLED ?= 1
 # Default to the native OS type and architecture unless otherwise specified
 NATIVE_GOOS := $(shell env -u GOOS $(GO) env GOOS)
@@ -157,9 +158,11 @@ GOARCH ?= $(NATIVE_GOARCH)
 ifeq ($(call err_if_empty,GOOS),windows)
 BINSFX := .exe
 SRCBINDIR := bin/windows
+CGO_ENABLED := 0
 else ifeq ($(GOOS),darwin)
 BINSFX :=
 SRCBINDIR := bin/darwin
+CGO_ENABLED := 0
 else
 BINSFX := -remote
 SRCBINDIR := bin
@@ -302,7 +305,8 @@ endif
 $(SRCBINDIR):
 	mkdir -p $(SRCBINDIR)
 
-$(SRCBINDIR)/podman$(BINSFX): $(SRCBINDIR) $(SOURCES) go.mod go.sum
+# '|' is to ignore SRCBINDIR mtime; see: info make 'Types of Prerequisites'
+$(SRCBINDIR)/podman$(BINSFX): $(SOURCES) go.mod go.sum | $(SRCBINDIR)
 	$(GOCMD) build \
 		$(BUILDFLAGS) \
 		$(GO_LDFLAGS) '$(LDFLAGS_PODMAN)' \
@@ -322,28 +326,13 @@ $(SRCBINDIR)/podman-remote-static: $(SRCBINDIR) $(SOURCES) go.mod go.sum
 .PHONY: podman
 podman: bin/podman
 
+# This will map to the right thing on Linux, Windows, and Mac.
 .PHONY: podman-remote
-podman-remote: $(SRCBINDIR) $(SRCBINDIR)/podman$(BINSFX)  ## Build podman-remote binary
-
-# A wildcard podman-remote-% target incorrectly sets GOOS for release targets
-.PHONY: podman-remote-linux
-podman-remote-linux: ## Build podman-remote for Linux
-	$(MAKE) \
-		CGO_ENABLED=0 \
-		GOOS=linux \
-		GOARCH=$(GOARCH) \
-		bin/podman-remote
+podman-remote: $(SRCBINDIR)/podman$(BINSFX)
 
 PHONY: podman-remote-static
 podman-remote-static: $(SRCBINDIR)/podman-remote-static
 
-.PHONY: podman-remote-windows
-podman-remote-windows: ## Build podman-remote for Windows
-	$(MAKE) \
-		CGO_ENABLED=0 \
-		GOOS=windows \
-		bin/windows/podman.exe
-
 .PHONY: podman-winpath
 podman-winpath: $(SOURCES) go.mod go.sum
 	CGO_ENABLED=0 \
@@ -354,14 +343,6 @@ podman-winpath: $(SOURCES) go.mod go.sum
 		-o bin/windows/winpath.exe \
 		./cmd/winpath
 
-.PHONY: podman-remote-darwin
-podman-remote-darwin: podman-mac-helper ## Build podman-remote for macOS
-	$(MAKE) \
-		CGO_ENABLED=$(DARWIN_GCO) \
-		GOOS=darwin \
-		GOARCH=$(GOARCH) \
-		bin/darwin/podman
-
 .PHONY: podman-mac-helper
 podman-mac-helper: ## Build podman-mac-helper for macOS
 	CGO_ENABLED=0 \
@@ -456,8 +437,10 @@ docdir:
 docs: $(MANPAGES) ## Generate documentation
 
 # docs/remote-docs.sh requires a locally executable 'podman-remote' binary
-# in addition to the target-archetecture binary (if any).
-podman-remote-%-docs: podman-remote-$(call err_if_empty,NATIVE_GOOS)
+# in addition to the target-architecture binary (if different). That's
+# what the NATIVE_GOOS make does in the first line.
+podman-remote-%-docs: podman-remote
+	$(MAKE) podman-remote GOOS=$(NATIVE_GOOS)
 	$(eval GOOS := $*)
 	$(MAKE) docs $(MANPAGES)
 	rm -rf docs/build/remote
@@ -685,9 +668,9 @@ podman-remote-release-%.zip: test/version/version ## Build podman-remote for %=$
 		clean-binaries podman-remote-$(GOOS)-docs
 	if [[ "$(GOARCH)" != "$(NATIVE_GOARCH)" ]]; then \
 		$(MAKE) CGO_ENABLED=0 $(GOPLAT) BUILDTAGS="$(BUILDTAGS_CROSS)" \
-			clean-binaries podman-remote-$(GOOS); \
+			clean-binaries podman-remote; \
 	else \
-		$(MAKE) $(GOPLAT) podman-remote-$(GOOS); \
+		$(MAKE) $(GOPLAT) podman-remote; \
 	fi
 	cp -r ./docs/build/remote/$(GOOS) "$(TMPDIR)/$(SUBDIR)/docs/"
 	cp ./contrib/remote/containers.conf "$(TMPDIR)/$(SUBDIR)/"
@@ -700,7 +683,7 @@ podman-remote-release-%.zip: test/version/version ## Build podman-remote for %=$
 .PHONY: podman.msi
 podman.msi: test/version/version  ## Build podman-remote, package for installation on Windows
 	$(MAKE) podman-v$(call err_if_empty,RELEASE_NUMBER).msi
-podman-v%.msi: test/version/version podman-remote-windows podman-remote-windows-docs podman-winpath win-sshproxy
+podman-v%.msi: test/version/version podman-remote podman-remote-windows-docs podman-winpath win-sshproxy
 	$(eval DOCFILE := docs/build/remote/windows)
 	find $(DOCFILE) -print | \
 		wixl-heat --var var.ManSourceDir --component-group ManFiles \
diff --git a/docs/remote-docs.sh b/docs/remote-docs.sh
index 4c2602f80..f281c19ff 100755
--- a/docs/remote-docs.sh
+++ b/docs/remote-docs.sh
@@ -6,7 +6,9 @@ PLATFORM=$1                         ## linux, windows or darwin
 TARGET=${2}                         ## where to output files
 SOURCES=${@:3}                      ## directories to find markdown files
 
-# Overridden for testing.  Native podman-remote binary expected filepaths
+# This is a *native* binary, one we can run on this host. (This script can be
+# invoked in a cross-compilation environment, so even if PLATFORM=windows
+# we need an actual executable that we can invoke).
 if [[ -z "$PODMAN" ]]; then
     case $(env -i HOME=$HOME PATH=$PATH go env GOOS) in
         windows)
diff --git a/docs/source/markdown/podman-import.1.md b/docs/source/markdown/podman-import.1.md
index 4002f5255..8d482b961 100644
--- a/docs/source/markdown/podman-import.1.md
+++ b/docs/source/markdown/podman-import.1.md
@@ -50,10 +50,6 @@ Shows progress on the import
 
 Set variant of the imported image.
 
-**--verbose**
-
-Print additional debugging information
-
 ## EXAMPLES
 
 ```