Document the Makefile and its variables (#771)

- Adds documentation of the Makefile and its variables with an example
  of how to change build behavior.
- Default Makefile behavior no longer tries to use a private redis build
  cache server
- Changes ARGS and EXT_ARGS to CONTAINER_BUILD_ARGS and
  CONTAINER_TOOL_ARGS respectively for more clarity

Closes https://github.com/kanidm/kanidm/issues/768

DEVELOPER_README.md

@@ -165,3 +165,31 @@ The "developer" profile for kanidmd will automatically use the pkg output in thi
 Setting different developer profiles while building is done by setting the environment variable KANIDM_BUILD_PROFILE to one of the bare filename of the TOML files in `/profiles`. 
 
 For example: `KANIDM_BUILD_PROFILE=release_suse_generic cargo build --release --bin kanidmd`
+
+### Building the development container
+
+Build a development container with the current branch using:
+
+    make <TARGET>
+
+Check `make help` for a list of valid targets.
+
+The following environment variables control the build:
+
+|ENV variable|Definition|
+|-|-|
+|`IMAGE_BASE`|Base location of the container image. Defaults to `kanidm`.|
+|`IMAGE_VERSION`|Determines the container's tag.|
+|`CONTAINER_TOOL_ARGS`|Specify extra options for the container build tool.|
+|`IMAGE_ARCH`|Passed to `--platforms` when the container is built. Defaults to `linux/amd64,linux/arm64`.|
+|`CONTAINER_BUILD_ARGS`|Override default ARG settings during the container build.|
+|`CONTAINER_TOOL`|Use an alternative container build tool. Defaults to `docker`.|
+|`BOOK_VERSION`|Sets version used when building the documentation book. Defaults to `master`.|
+
+Build a development container using `podman`:
+
+    CONTAINER_TOOL=podman make build/kanidmd
+
+Build a development container and specify a redis build cache:
+
+    CONTAINER_BUILD_ARGS="--build-arg "SCCACHE_REDIS=redis://redis.dev.blackhats.net.au:6379"" make build/kanidmd

Makefile

@@ -2,9 +2,9 @@
 
 IMAGE_BASE ?= kanidm
 IMAGE_VERSION ?= devel
-EXT_OPTS ?=
+CONTAINER_TOOL_ARGS ?=
 IMAGE_ARCH ?= "linux/amd64,linux/arm64"
-ARGS ?= --build-arg "SCCACHE_REDIS=redis://redis.dev.blackhats.net.au:6379"
+CONTAINER_BUILD_ARGS ?= 
 CONTAINER_TOOL ?= docker
 
 BOOK_VERSION ?= master
@@ -15,50 +15,50 @@ help:
 
 buildx/kanidmd/x86_64_v3: ## build multiarch server images
 buildx/kanidmd/x86_64_v3:
-	@$(CONTAINER_TOOL) buildx build $(EXT_OPTS) --pull --push --platform "linux/amd64" \
+	@$(CONTAINER_TOOL) buildx build $(CONTAINER_TOOL_ARGS) --pull --push --platform "linux/amd64" \
 		-f kanidmd/Dockerfile -t $(IMAGE_BASE)/server:x86_64_$(IMAGE_VERSION) \
 		--build-arg "KANIDM_BUILD_PROFILE=container_x86_64_v3" \
 		--build-arg "KANIDM_FEATURES=" \
-		$(ARGS) .
+		$(CONTAINER_BUILD_ARGS) .
-	@$(CONTAINER_TOOL) buildx imagetools $(EXT_OPTS) inspect $(IMAGE_BASE)/server:$(IMAGE_VERSION)
+	@$(CONTAINER_TOOL) buildx imagetools $(CONTAINER_TOOL_ARGS) inspect $(IMAGE_BASE)/server:$(IMAGE_VERSION)
 
 buildx/kanidmd: ## build multiarch server images
 buildx/kanidmd:
-	@$(CONTAINER_TOOL) buildx build $(EXT_OPTS) --pull --push --platform $(IMAGE_ARCH) \
+	@$(CONTAINER_TOOL) buildx build $(CONTAINER_TOOL_ARGS) --pull --push --platform $(IMAGE_ARCH) \
 		-f kanidmd/Dockerfile -t $(IMAGE_BASE)/server:$(IMAGE_VERSION) \
 		--build-arg "KANIDM_BUILD_PROFILE=container_generic" \
 		--build-arg "KANIDM_FEATURES=" \
-		$(ARGS) .
+		$(CONTAINER_BUILD_ARGS) .
-	@$(CONTAINER_TOOL) buildx imagetools $(EXT_OPTS) inspect $(IMAGE_BASE)/server:$(IMAGE_VERSION)
+	@$(CONTAINER_TOOL) buildx imagetools $(CONTAINER_TOOL_ARGS) inspect $(IMAGE_BASE)/server:$(IMAGE_VERSION)
 
 buildx/radiusd: ## build multiarch radius images
 buildx/radiusd:
-	@$(CONTAINER_TOOL) buildx build $(EXT_OPTS) --pull --push --platform $(IMAGE_ARCH) \
+	@$(CONTAINER_TOOL) buildx build $(CONTAINER_TOOL_ARGS) --pull --push --platform $(IMAGE_ARCH) \
 		-f kanidm_rlm_python/Dockerfile -t $(IMAGE_BASE)/radius:$(IMAGE_VERSION) kanidm_rlm_python
-	@$(CONTAINER_TOOL) buildx imagetools $(EXT_OPTS) inspect $(IMAGE_BASE)/radius:$(IMAGE_VERSION)
+	@$(CONTAINER_TOOL) buildx imagetools $(CONTAINER_TOOL_ARGS) inspect $(IMAGE_BASE)/radius:$(IMAGE_VERSION)
 
 buildx: buildx/kanidmd buildx/radiusd
 
 build/kanidmd:	## build kanidmd images
 build/kanidmd:
-	@$(CONTAINER_TOOL) build $(EXT_OPTS) -f kanidmd/Dockerfile -t $(IMAGE_BASE)/server:$(IMAGE_VERSION) \
+	@$(CONTAINER_TOOL) build $(CONTAINER_TOOL_ARGS) -f kanidmd/Dockerfile -t $(IMAGE_BASE)/server:$(IMAGE_VERSION) \
 		--build-arg "KANIDM_BUILD_PROFILE=developer" \
 		--build-arg "KANIDM_FEATURES=" \
-		$(ARGS) .
+		$(CONTAINER_BUILD_ARGS) .
 
 build/radiusd:	## build radiusd image
 build/radiusd:
-	@$(CONTAINER_TOOL) build $(EXT_OPTS) -f kanidm_rlm_python/Dockerfile -t $(IMAGE_BASE)/radius:$(IMAGE_VERSION) kanidm_rlm_python
+	@$(CONTAINER_TOOL) build $(CONTAINER_TOOL_ARGS) -f kanidm_rlm_python/Dockerfile -t $(IMAGE_BASE)/radius:$(IMAGE_VERSION) kanidm_rlm_python
 
 build: build/kanidmd build/radiusd
 
 test/kanidmd:	## test kanidmd
 test/kanidmd:
 	@$(CONTAINER_TOOL) build \
-		$(EXT_OPTS) -f kanidmd/Dockerfile \
+		$(CONTAINER_TOOL_ARGS) -f kanidmd/Dockerfile \
 		--target builder \
 		-t $(IMAGE_BASE)/server:$(IMAGE_VERSION)-builder \
-		$(ARGS) .
+		$(CONTAINER_BUILD_ARGS) .
 	@$(CONTAINER_TOOL) run --rm $(IMAGE_BASE)/server:$(IMAGE_VERSION)-builder cargo test
 
 # test/radiusd:	build/radiusd	## test radiusd