Makefile

# Copyright © 2025-2026 Apple Inc. and the container project authors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#   https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# Version and build configuration variables
BUILD_CONFIGURATION ?= debug
WARNINGS_AS_ERRORS ?= true
SWIFT_CONFIGURATION := $(if $(filter-out false,$(WARNINGS_AS_ERRORS)),-Xswiftc -warnings-as-errors) -Xswiftc -enable-testing
# Optional runner arguments for `swift test`. CI passes `--no-parallel`
# explicitly so the runner configuration remains stable across SwiftPM defaults.
# Swift Testing schedules suites concurrently by default. Several tests create
# and close real loopback sockets, so keep the project test gate deterministic.
SWIFT_TEST_FLAGS ?= --no-parallel
# Code-coverage instrumentation, layered onto the shared build stages. Empty for
# ordinary builds; the coverage-* targets opt in via a target-specific value so
# only those goals compile instrumented binaries.
COVERAGE_FLAG ?=
CONTAINER_SERVICE_WORKLOADS_PREBUILT ?= false
export RELEASE_VERSION ?= $(shell git describe --tags --always)
export GIT_COMMIT := $(shell git rev-parse HEAD)
export CONTAINERIZATION_SOURCE ?= $(shell python3 -c 'import json; pin=next((p for p in json.load(open("Package.resolved"))["pins"] if p["identity"] == "containerization"), {}); location=pin.get("location", "https://github.com/stephenlclarke/containerization.git"); print(location.removeprefix("https://github.com/").removesuffix(".git"))')
export CONTAINERIZATION_REF ?= $(shell python3 -c 'import json; pin=next((p for p in json.load(open("Package.resolved"))["pins"] if p["identity"] == "containerization"), {}); state=pin.get("state", {}); print(state.get("revision") or state.get("branch") or "main")')

# Commonly used locations
SWIFT := "/usr/bin/swift"
PYTHON3 ?= python3
HAWKEYE ?= $(shell command -v hawkeye 2>/dev/null || printf '%s' .local/bin/hawkeye)
# Shared swift build invocation; callers append --build-tests / --product / etc.
SWIFT_BUILD = $(SWIFT) build -c $(BUILD_CONFIGURATION) $(SWIFT_CONFIGURATION)
DEST_DIR ?= /usr/local/
ROOT_DIR := $(shell git rev-parse --show-toplevel)
# Keep staging on the exact build graph selected by SWIFT_BUILD.  In
# particular, callers that select an isolated SwiftPM scratch path must not
# silently package stale products from the default .build directory.
BUILD_BIN_DIR = $(shell $(SWIFT_BUILD) --show-bin-path)
SEMANTIC_HELPER_BUILD_DIR := $(ROOT_DIR)/.build/container-semantic-helper
SEMANTIC_HELPER_BINARY := $(SEMANTIC_HELPER_BUILD_DIR)/container-semantic-helper
SEMANTIC_HELPER_MANIFEST := $(SEMANTIC_HELPER_BUILD_DIR)/container-semantic-helper.manifest.json
SEMANTIC_HELPER_BUILD_TOOL := Tools/ContainerSemanticHelper/build.py
JOURNALD_SERVICE_BUILD_DIR := $(ROOT_DIR)/.build/container-journald-service
JOURNALD_SERVICE_ARCHIVE := $(JOURNALD_SERVICE_BUILD_DIR)/container-journald-service.oci.tar
JOURNALD_SERVICE_MANIFEST := $(JOURNALD_SERVICE_BUILD_DIR)/container-journald-service.manifest.json
JOURNALD_SERVICE_BUILD_TOOL := Tools/ContainerJournaldService/build.py
JOURNALD_SERVICE_BUILDER_SETUP := scripts/ensure-journald-builder.sh
# SwiftPM owns and may prune $(ROOT_DIR)/.build. Keep sealed service assets
# outside that scratch tree so an exact-path Swift test cannot invalidate the
# staged workload it is validating.
GELF_SERVICE_BUILD_DIR := $(ROOT_DIR)/bin/services/container-gelf-service
GELF_SERVICE_ARCHIVE := $(GELF_SERVICE_BUILD_DIR)/container-gelf-service.oci.tar
GELF_SERVICE_MANIFEST := $(GELF_SERVICE_BUILD_DIR)/container-gelf-service.manifest.json
GELF_SERVICE_BUILD_TOOL := Tools/ContainerGELFService/build.py
GELF_SERVICE_BUILDER_SETUP := scripts/ensure-gelf-builder.sh
STAGING_DIR := bin/$(BUILD_CONFIGURATION)/staging/
PKG_PATH := bin/$(BUILD_CONFIGURATION)/container-installer-unsigned.pkg
DSYM_DIR := bin/$(BUILD_CONFIGURATION)/bundle/container-dSYM
DSYM_PATH := bin/$(BUILD_CONFIGURATION)/bundle/container-dSYM.zip
DEBUG_SYMBOL_BUILD_TOOL := Tools/DebugSymbols/package.py
DEBUG_SYMBOL_PRODUCTS := \
	container \
	container-apiserver \
	container-engine \
	container-core-images \
	container-runtime-linux \
	container-network-vmnet \
	machine-apiserver \
	k8s
HOMEBREW_ARCHIVE ?= bin/$(BUILD_CONFIGURATION)/container-homebrew-$(BUILD_CONFIGURATION)-arm64.tar.gz
CODESIGN_OPTS ?= --force --sign - --timestamp=none


# Conditionally use a temporary data directory for integration tests
SYSTEM_START_OPTS :=
KERNEL_INSTALL ?= true
KERNEL_INSTALL_OPT := $(if $(filter false,$(KERNEL_INSTALL)),--disable-kernel-install,--enable-kernel-install)
ifneq ($(strip $(APP_ROOT)),)
	SYSTEM_START_OPTS += --app-root "$(strip $(APP_ROOT))"
endif
ifneq ($(strip $(LOG_ROOT)),)
	SYSTEM_START_OPTS += --log-root "$(strip $(LOG_ROOT))"
endif

# swift test event-stream JSON output for the concurrent/global integration
# passes, only when LOG_ROOT is set.
CONCURRENT_EVENT_STREAM_OPTS :=
GLOBAL_EVENT_STREAM_OPTS :=
ifneq ($(strip $(LOG_ROOT)),)
	CONCURRENT_EVENT_STREAM_OPTS += --event-stream-output-path "$(strip $(LOG_ROOT))/integration-concurrent.json" --event-stream-version 6.3
	GLOBAL_EVENT_STREAM_OPTS += --event-stream-output-path "$(strip $(LOG_ROOT))/integration-global.json" --event-stream-version 6.3
endif

MACOS_VERSION := $(shell sw_vers -productVersion)
MACOS_MAJOR := $(shell echo $(MACOS_VERSION) | cut -d. -f1)

SUDO ?= sudo
.DEFAULT_GOAL := all

include Protobuf.Makefile

.PHONY: all
all: container
all: init-block

.PHONY: semantic-helper
semantic-helper:
	@echo Building pinned Docker semantic helper...
	@$(PYTHON3) $(SEMANTIC_HELPER_BUILD_TOOL) build --output-directory "$(SEMANTIC_HELPER_BUILD_DIR)"

.PHONY: test-semantic-helper
test-semantic-helper:
	@echo Testing pinned Docker semantic helper...
	@$(PYTHON3) $(SEMANTIC_HELPER_BUILD_TOOL) test --output-directory "$(SEMANTIC_HELPER_BUILD_DIR)"

.PHONY: verify-semantic-helper
verify-semantic-helper: semantic-helper
	@$(PYTHON3) $(SEMANTIC_HELPER_BUILD_TOOL) verify \
		--binary "$(SEMANTIC_HELPER_BINARY)" \
		--manifest "$(SEMANTIC_HELPER_MANIFEST)"

.PHONY: journald-service
journald-service:
	@echo Building pinned Linux journald-service workload...
	@if [ "$(CONTAINER_SERVICE_WORKLOADS_PREBUILT)" = true ]; then \
		test -f "$(JOURNALD_SERVICE_ARCHIVE)" && test -f "$(JOURNALD_SERVICE_MANIFEST)" || { \
			echo "Prebuilt Linux journald-service workload is missing" >&2; \
			exit 1; \
		}; \
		echo "Using verified prebuilt Linux journald-service workload"; \
		$(PYTHON3) $(JOURNALD_SERVICE_BUILD_TOOL) verify \
			--archive "$(JOURNALD_SERVICE_ARCHIVE)" \
			--manifest "$(JOURNALD_SERVICE_MANIFEST)"; \
	else \
		$(JOURNALD_SERVICE_BUILDER_SETUP); \
		$(PYTHON3) $(JOURNALD_SERVICE_BUILD_TOOL) build --output-directory "$(JOURNALD_SERVICE_BUILD_DIR)"; \
	fi

.PHONY: test-journald-service
test-journald-service:
	@echo Testing pinned Linux journald-service workload...
	@$(JOURNALD_SERVICE_BUILDER_SETUP)
	@$(PYTHON3) $(JOURNALD_SERVICE_BUILD_TOOL) test --output-directory "$(JOURNALD_SERVICE_BUILD_DIR)"

.PHONY: test-journald-service-integration
test-journald-service-integration:
	@echo Testing Swift client against packaged Linux journald-service workload...
	@$(JOURNALD_SERVICE_BUILDER_SETUP)
	@$(PYTHON3) $(JOURNALD_SERVICE_BUILD_TOOL) integration

.PHONY: verify-journald-service
verify-journald-service: journald-service
	@$(PYTHON3) $(JOURNALD_SERVICE_BUILD_TOOL) verify \
		--archive "$(JOURNALD_SERVICE_ARCHIVE)" \
		--manifest "$(JOURNALD_SERVICE_MANIFEST)"

.PHONY: gelf-service
gelf-service:
	@echo Building pinned Linux GELF TCP service workload...
	@if [ "$(CONTAINER_SERVICE_WORKLOADS_PREBUILT)" = true ]; then \
		test -f "$(GELF_SERVICE_ARCHIVE)" && test -f "$(GELF_SERVICE_MANIFEST)" || { \
			echo "Prebuilt Linux GELF TCP service workload is missing" >&2; \
			exit 1; \
		}; \
		echo "Using verified prebuilt Linux GELF TCP service workload"; \
		$(PYTHON3) $(GELF_SERVICE_BUILD_TOOL) verify \
			--archive "$(GELF_SERVICE_ARCHIVE)" \
			--manifest "$(GELF_SERVICE_MANIFEST)"; \
	else \
		$(GELF_SERVICE_BUILDER_SETUP); \
		$(PYTHON3) $(GELF_SERVICE_BUILD_TOOL) build --output-directory "$(GELF_SERVICE_BUILD_DIR)"; \
	fi

.PHONY: test-gelf-service
test-gelf-service:
	@echo Testing pinned Linux GELF TCP service workload...
	@$(GELF_SERVICE_BUILDER_SETUP)
	@$(PYTHON3) $(GELF_SERVICE_BUILD_TOOL) test --output-directory "$(GELF_SERVICE_BUILD_DIR)"

.PHONY: test-gelf-service-asset
test-gelf-service-asset: gelf-service
	@echo Testing the installed GELF TCP service asset outside SwiftPM scratch space...
	@./scripts/test-gelf-service-asset.sh --asset-directory "$(GELF_SERVICE_BUILD_DIR)"

.PHONY: verify-gelf-service
verify-gelf-service: gelf-service
	@$(PYTHON3) $(GELF_SERVICE_BUILD_TOOL) verify \
		--archive "$(GELF_SERVICE_ARCHIVE)" \
		--manifest "$(GELF_SERVICE_MANIFEST)"

.PHONY: build
build: semantic-helper
	@echo Building container binaries...
	@$(SWIFT) --version
	@$(SWIFT_BUILD)

.PHONY: build-tests
# Shared build stage for every test target: builds the test bundle (and the
# product binaries) once so the test targets can run with --skip-build. This is
# a distinct target from `build` so `make all test` builds products and tests as
# two separate steps rather than colliding on a single once-built target.
# COVERAGE_FLAG instruments the binaries when set by the coverage-* targets.
build-tests: test-semantic-helper
	@echo Building container binaries and tests...
	@$(SWIFT) --version
	@$(SWIFT_BUILD) --build-tests $(COVERAGE_FLAG)

.PHONY: coverage-all
coverage-all: build-tests
	@"$(MAKE)" BUILD_CONFIGURATION=$(BUILD_CONFIGURATION) DEST_DIR="$(ROOT_DIR)/" SUDO= install

.PHONY: cli
cli:
	@echo Building container CLI...
	@$(SWIFT) --version
	@$(SWIFT_BUILD) --product container
	@echo Installing container CLI to bin/...
	@mkdir -p bin
	@install "$(BUILD_BIN_DIR)/container" "bin/container"

.PHONY: container
# Install binaries under project directory
container: build
	@"$(MAKE)" BUILD_CONFIGURATION=$(BUILD_CONFIGURATION) DEST_DIR="$(ROOT_DIR)/" SUDO= install

.PHONY: release
release: BUILD_CONFIGURATION = release
release: all

.PHONY: init-block
init-block:
	@echo Building initfs if containerization is in edit mode
	@scripts/install-init.sh $(KERNEL_INSTALL_OPT) $(SYSTEM_START_OPTS)

.PHONY: install
install: installer-pkg
	@echo Installing container installer package
	@if [ -z "$(SUDO)" ] ; then \
		temp_dir=$$(mktemp -d) ; \
		xar -xf $(PKG_PATH) -C $${temp_dir} ; \
		(cd "$(DEST_DIR)" && pax -rz -f $${temp_dir}/Payload) ; \
		rm -rf $${temp_dir} ; \
	else \
		$(SUDO) installer -pkg $(PKG_PATH) -target / ; \
	fi

$(STAGING_DIR): semantic-helper journald-service gelf-service
	@echo Installing container binaries from "$(BUILD_BIN_DIR)" into "$(STAGING_DIR)"...
	@rm -rf "$(STAGING_DIR)"
	@mkdir -p "$(join $(STAGING_DIR), bin)"
	@mkdir -p "$(join $(STAGING_DIR), libexec/container/plugins/container-runtime-linux/bin)"
	@mkdir -p "$(join $(STAGING_DIR), libexec/container/plugins/container-network-vmnet/bin)"
	@mkdir -p "$(join $(STAGING_DIR), libexec/container/plugins/container-core-images/bin)"
	@mkdir -p "$(join $(STAGING_DIR), libexec/container/plugins/machine-apiserver/bin)"
	@mkdir -p "$(join $(STAGING_DIR), libexec/container/plugins/machine-apiserver/resources)"
	@mkdir -p "$(join $(STAGING_DIR), libexec/container/helpers)"
	@mkdir -p "$(join $(STAGING_DIR), libexec/container/services/journald)"
	@mkdir -p "$(join $(STAGING_DIR), libexec/container/services/gelf)"
	@mkdir -p "$(join $(STAGING_DIR), libexec/container/plugins/k8s/bin)"
	@mkdir -p "$(join $(STAGING_DIR), libexec/container/plugins/k8s/resources)"

	@install "$(BUILD_BIN_DIR)/container" "$(join $(STAGING_DIR), bin/container)"
	@install "$(BUILD_BIN_DIR)/container-apiserver" "$(join $(STAGING_DIR), bin/container-apiserver)"
	@install "$(BUILD_BIN_DIR)/container-engine" "$(join $(STAGING_DIR), bin/container-engine)"
	@install "$(BUILD_BIN_DIR)/container-runtime-linux" "$(join $(STAGING_DIR), libexec/container/plugins/container-runtime-linux/bin/container-runtime-linux)"
	@install Sources/Plugins/RuntimeLinux/config.toml "$(join $(STAGING_DIR), libexec/container/plugins/container-runtime-linux/config.toml)"
	@install "$(BUILD_BIN_DIR)/container-network-vmnet" "$(join $(STAGING_DIR), libexec/container/plugins/container-network-vmnet/bin/container-network-vmnet)"
	@install Sources/Plugins/NetworkVmnet/config.toml "$(join $(STAGING_DIR), libexec/container/plugins/container-network-vmnet/config.toml)"
	@install "$(BUILD_BIN_DIR)/container-core-images" "$(join $(STAGING_DIR), libexec/container/plugins/container-core-images/bin/container-core-images)"
	@install Sources/Plugins/CoreImages/config.toml "$(join $(STAGING_DIR), libexec/container/plugins/container-core-images/config.toml)"
	@install "$(BUILD_BIN_DIR)/machine-apiserver" "$(join $(STAGING_DIR), libexec/container/plugins/machine-apiserver/bin/machine-apiserver)"
	@install Sources/Plugins/MachineAPIServer/config.toml "$(join $(STAGING_DIR), libexec/container/plugins/machine-apiserver/config.toml)"
	@install Sources/Plugins/MachineAPIServer/Resources/init "$(join $(STAGING_DIR), libexec/container/plugins/machine-apiserver/resources/init)"
	@install Sources/Plugins/MachineAPIServer/Resources/create-user.sh "$(join $(STAGING_DIR), libexec/container/plugins/machine-apiserver/resources/create-user.sh)"
	@install "$(SEMANTIC_HELPER_BINARY)" "$(join $(STAGING_DIR), libexec/container/helpers/container-semantic-helper)"
	@install -m 0644 "$(SEMANTIC_HELPER_MANIFEST)" "$(join $(STAGING_DIR), libexec/container/helpers/container-semantic-helper.manifest.json)"
	@install -m 0644 "$(JOURNALD_SERVICE_ARCHIVE)" "$(join $(STAGING_DIR), libexec/container/services/journald/container-journald-service.oci.tar)"
	@install -m 0644 "$(JOURNALD_SERVICE_MANIFEST)" "$(join $(STAGING_DIR), libexec/container/services/journald/container-journald-service.manifest.json)"
	@$(PYTHON3) $(JOURNALD_SERVICE_BUILD_TOOL) verify \
		--archive "$(join $(STAGING_DIR), libexec/container/services/journald/container-journald-service.oci.tar)" \
		--manifest "$(join $(STAGING_DIR), libexec/container/services/journald/container-journald-service.manifest.json)"
	@install -m 0644 "$(GELF_SERVICE_ARCHIVE)" "$(join $(STAGING_DIR), libexec/container/services/gelf/container-gelf-service.oci.tar)"
	@install -m 0644 "$(GELF_SERVICE_MANIFEST)" "$(join $(STAGING_DIR), libexec/container/services/gelf/container-gelf-service.manifest.json)"
	@$(PYTHON3) $(GELF_SERVICE_BUILD_TOOL) verify \
		--archive "$(join $(STAGING_DIR), libexec/container/services/gelf/container-gelf-service.oci.tar)" \
		--manifest "$(join $(STAGING_DIR), libexec/container/services/gelf/container-gelf-service.manifest.json)"
	@install "$(BUILD_BIN_DIR)/k8s" "$(join $(STAGING_DIR), libexec/container/plugins/k8s/bin/k8s)"
	@install Sources/Plugins/K8s/config.toml "$(join $(STAGING_DIR), libexec/container/plugins/k8s/config.toml)"
	@install Sources/Plugins/K8s/Resources/kindnet.yaml "$(join $(STAGING_DIR), libexec/container/plugins/k8s/resources/kindnet.yaml)"

	@echo Install update script
	@install scripts/update-container.sh "$(join $(STAGING_DIR), bin/update-container.sh)"
	@echo Install uninstaller script
	@install scripts/uninstall-container.sh "$(join $(STAGING_DIR), bin/uninstall-container.sh)"

.PHONY: installer-pkg
installer-pkg: $(STAGING_DIR)
	@echo Signing container binaries...
	@codesign $(CODESIGN_OPTS) --identifier com.apple.container.cli "$(join $(STAGING_DIR), bin/container)"
	@codesign $(CODESIGN_OPTS) --identifier com.apple.container.apiserver "$(join $(STAGING_DIR), bin/container-apiserver)"
	@codesign $(CODESIGN_OPTS) --identifier io.github.stephenlclarke.container.engine "$(join $(STAGING_DIR), bin/container-engine)"
	@codesign $(CODESIGN_OPTS) --prefix=com.apple.container. "$(join $(STAGING_DIR), libexec/container/plugins/container-core-images/bin/container-core-images)"
	@codesign $(CODESIGN_OPTS) --prefix=com.apple.container. --entitlements=signing/container-runtime-linux.entitlements "$(join $(STAGING_DIR), libexec/container/plugins/container-runtime-linux/bin/container-runtime-linux)"
	@codesign $(CODESIGN_OPTS) --prefix=com.apple.container. --entitlements=signing/container-network-vmnet.entitlements "$(join $(STAGING_DIR), libexec/container/plugins/container-network-vmnet/bin/container-network-vmnet)"
	@codesign $(CODESIGN_OPTS) --prefix=com.apple.container. "$(join $(STAGING_DIR), libexec/container/plugins/machine-apiserver/bin/machine-apiserver)"
	@codesign $(CODESIGN_OPTS) --identifier com.apple.container.semantic-helper "$(join $(STAGING_DIR), libexec/container/helpers/container-semantic-helper)"
	@$(PYTHON3) $(SEMANTIC_HELPER_BUILD_TOOL) manifest \
		--binary "$(join $(STAGING_DIR), libexec/container/helpers/container-semantic-helper)" \
		--output "$(join $(STAGING_DIR), libexec/container/helpers/container-semantic-helper.manifest.json)"
	@$(PYTHON3) $(SEMANTIC_HELPER_BUILD_TOOL) verify \
		--binary "$(join $(STAGING_DIR), libexec/container/helpers/container-semantic-helper)" \
		--manifest "$(join $(STAGING_DIR), libexec/container/helpers/container-semantic-helper.manifest.json)"
	@$(PYTHON3) $(JOURNALD_SERVICE_BUILD_TOOL) verify \
		--archive "$(join $(STAGING_DIR), libexec/container/services/journald/container-journald-service.oci.tar)" \
		--manifest "$(join $(STAGING_DIR), libexec/container/services/journald/container-journald-service.manifest.json)"
	@$(PYTHON3) $(GELF_SERVICE_BUILD_TOOL) verify \
		--archive "$(join $(STAGING_DIR), libexec/container/services/gelf/container-gelf-service.oci.tar)" \
		--manifest "$(join $(STAGING_DIR), libexec/container/services/gelf/container-gelf-service.manifest.json)"
	@codesign $(CODESIGN_OPTS) --prefix=com.apple.container. "$(join $(STAGING_DIR), libexec/container/plugins/k8s/bin/k8s)"

	@echo Creating application installer
	@pkgbuild --root "$(STAGING_DIR)" --identifier com.apple.container-installer --install-location /usr/local --version ${RELEASE_VERSION} $(PKG_PATH)
	@rm -rf "$(STAGING_DIR)"

.PHONY: package
package: homebrew-package

.PHONY: homebrew-package
homebrew-package: build $(STAGING_DIR)
	@echo Signing container binaries for Homebrew archive...
	@codesign $(CODESIGN_OPTS) --identifier com.apple.container.cli "$(join $(STAGING_DIR), bin/container)"
	@codesign $(CODESIGN_OPTS) --identifier com.apple.container.apiserver "$(join $(STAGING_DIR), bin/container-apiserver)"
	@codesign $(CODESIGN_OPTS) --identifier io.github.stephenlclarke.container.engine "$(join $(STAGING_DIR), bin/container-engine)"
	@codesign $(CODESIGN_OPTS) --prefix=com.apple.container. "$(join $(STAGING_DIR), libexec/container/plugins/container-core-images/bin/container-core-images)"
	@codesign $(CODESIGN_OPTS) --prefix=com.apple.container. --entitlements=signing/container-runtime-linux.entitlements "$(join $(STAGING_DIR), libexec/container/plugins/container-runtime-linux/bin/container-runtime-linux)"
	@codesign $(CODESIGN_OPTS) --prefix=com.apple.container. --entitlements=signing/container-network-vmnet.entitlements "$(join $(STAGING_DIR), libexec/container/plugins/container-network-vmnet/bin/container-network-vmnet)"
	@codesign $(CODESIGN_OPTS) --prefix=com.apple.container. "$(join $(STAGING_DIR), libexec/container/plugins/machine-apiserver/bin/machine-apiserver)"
	@codesign $(CODESIGN_OPTS) --identifier com.apple.container.semantic-helper "$(join $(STAGING_DIR), libexec/container/helpers/container-semantic-helper)"
	@$(PYTHON3) $(SEMANTIC_HELPER_BUILD_TOOL) manifest \
		--binary "$(join $(STAGING_DIR), libexec/container/helpers/container-semantic-helper)" \
		--output "$(join $(STAGING_DIR), libexec/container/helpers/container-semantic-helper.manifest.json)"
	@$(PYTHON3) $(SEMANTIC_HELPER_BUILD_TOOL) verify \
		--binary "$(join $(STAGING_DIR), libexec/container/helpers/container-semantic-helper)" \
		--manifest "$(join $(STAGING_DIR), libexec/container/helpers/container-semantic-helper.manifest.json)"
	@$(PYTHON3) $(JOURNALD_SERVICE_BUILD_TOOL) verify \
		--archive "$(join $(STAGING_DIR), libexec/container/services/journald/container-journald-service.oci.tar)" \
		--manifest "$(join $(STAGING_DIR), libexec/container/services/journald/container-journald-service.manifest.json)"
	@$(PYTHON3) $(GELF_SERVICE_BUILD_TOOL) verify \
		--archive "$(join $(STAGING_DIR), libexec/container/services/gelf/container-gelf-service.oci.tar)" \
		--manifest "$(join $(STAGING_DIR), libexec/container/services/gelf/container-gelf-service.manifest.json)"
	@codesign $(CODESIGN_OPTS) --prefix=com.apple.container. "$(join $(STAGING_DIR), libexec/container/plugins/k8s/bin/k8s)"
	@install scripts/ensure-container-stopped.sh "$(join $(STAGING_DIR), libexec/ensure-container-stopped.sh)"
	@mkdir -p "$(dir $(HOMEBREW_ARCHIVE))"
	@tar -czf "$(HOMEBREW_ARCHIVE)" -C "$(STAGING_DIR)" .
	@scripts/write-sha256-sidecar.sh "$(HOMEBREW_ARCHIVE)"
	@rm -rf "$(STAGING_DIR)"

.PHONY: dsym
dsym:
	@echo Preparing debug symbols...
	@$(PYTHON3) $(DEBUG_SYMBOL_BUILD_TOOL) \
		--build-directory "$(BUILD_BIN_DIR)" \
		--output-directory "$(DSYM_DIR)" \
		--archive "$(DSYM_PATH)" \
		$(foreach product,$(DEBUG_SYMBOL_PRODUCTS),--product "$(product)")

.PHONY: test test-build-artifact-directory test-create-machine-user test-debug-symbol-packaging test-homebrew-archive-checksum test-install-init test-verify-developer-id-archive
test-build-artifact-directory:
	@bash Tests/ScriptTests/TestBuildArtifactDirectory.sh

test-create-machine-user:
	@Tests/ScriptTests/TestCreateMachineUser.sh

test-debug-symbol-packaging:
	@$(PYTHON3) -m unittest Tools/DebugSymbols/test_package.py

test-homebrew-archive-checksum:
	@Tests/ScriptTests/TestHomebrewArchiveChecksum.sh

test-install-init:
	@Tests/ScriptTests/TestInstallInit.sh

test-verify-developer-id-archive:
	@Tests/ScriptTests/TestVerifyDeveloperIDArchive.sh

test: build-tests test-build-artifact-directory test-create-machine-user test-debug-symbol-packaging test-homebrew-archive-checksum test-install-init test-verify-developer-id-archive
	@$(SWIFT) test --skip-build -c $(BUILD_CONFIGURATION) $(SWIFT_CONFIGURATION) $(SWIFT_TEST_FLAGS) --skip TestCLI --skip IntegrationTests

.PHONY: install-kernel
install-kernel: container
	@echo Stopping system before installing kernel
	@bin/container system stop || true
	@echo Starting system to install kernel
	@bin/container --debug system start --timeout 60 --enable-kernel-install $(SYSTEM_START_OPTS)


# Coverage report generation helpers
# Directory that swift test spits out raw coverage data
COV_DATA_DIR = $(shell $(SWIFT) test --show-coverage-path | xargs dirname)
COV_REPORT_FILE = $(ROOT_DIR)/code-coverage-report
COVERAGE_OUTPUT_DIR := $(ROOT_DIR)/coverage-reports
# SwiftPM through Xcode 26 emits one aggregate test bundle. Xcode 27 emits one
# bundle per test target instead. Prefer the aggregate bundle when it exists;
# otherwise discover every unit-test bundle and give llvm-cov one primary
# object plus the remainder as additional objects. IntegrationTests is covered
# separately by coverage-integration.
TEST_BINARIES = $(shell \
	if [ -x "$(BUILD_BIN_DIR)/containerPackageTests.xctest/Contents/MacOS/containerPackageTests" ]; then \
		printf '%s\n' "$(BUILD_BIN_DIR)/containerPackageTests.xctest/Contents/MacOS/containerPackageTests"; \
	else \
		find "$(BUILD_BIN_DIR)" -type f -path '*/*.xctest/Contents/MacOS/*Tests' \
			! -path '*/IntegrationTests.xctest/Contents/MacOS/IntegrationTests' -perm -111 2>/dev/null | sort; \
	fi)
TEST_BINARY = $(firstword $(TEST_BINARIES))
TEST_OBJECT_FLAGS = $(patsubst %,-object %,$(wordlist 2,999,$(TEST_BINARIES)))
# Xcode 27 emits IntegrationTests as a separate bundle. Unit reports exclude it,
# while integration and combined reports must map its profile counters back to
# the production modules statically linked into that executable.
INTEGRATION_TEST_BINARY = $(shell \
	find "$(BUILD_BIN_DIR)" -type f \
		-path '*/IntegrationTests.xctest/Contents/MacOS/IntegrationTests' \
		-perm -111 2>/dev/null | sort | head -n 1)
INTEGRATION_TEST_OBJECT_FLAGS = $(if $(INTEGRATION_TEST_BINARY),-object $(INTEGRATION_TEST_BINARY))
# All product binaries that may be instrumented for coverage.
# Used as additional -object args to llvm-cov for integration/combined reports.
COV_BINARIES := \
	$(BUILD_BIN_DIR)/container \
	$(BUILD_BIN_DIR)/container-apiserver \
	$(BUILD_BIN_DIR)/container-engine \
	$(BUILD_BIN_DIR)/container-runtime-linux \
	$(BUILD_BIN_DIR)/container-network-vmnet \
	$(BUILD_BIN_DIR)/container-core-images \
	$(BUILD_BIN_DIR)/machine-apiserver
COV_OBJECT_FLAGS := $(patsubst %,-object %,$(COV_BINARIES))
# Set of files we do not want to get caught in the coverage generation
LLVM_COV_IGNORE := \
	--ignore-filename-regex=".build/" \
	--ignore-filename-regex="/Tests/" \
	--ignore-filename-regex="/ContainerTestSupport/" \
	--ignore-filename-regex=".pb.swift" \
	--ignore-filename-regex=".proto" \
	--ignore-filename-regex=".grpc.swift"

# Generate JSON + HTML coverage reports and a coverage-percent.txt from a profdata file.
# $(1) = profdata path, $(2) = tier name (unit/integration/combined), $(3) = additional -object flags (optional)
define GENERATE_COV_REPORTS
	@echo Exporting $(2) coverage JSON...
	@xcrun llvm-cov export --compilation-dir=`pwd` \
		-instr-profile=$(1) \
		$(LLVM_COV_IGNORE) \
		$(TEST_BINARY) $(TEST_OBJECT_FLAGS) $(3) > $(COVERAGE_OUTPUT_DIR)/$(2)/coverage-summary.json
	@echo Generating $(2) coverage HTML report...
	@xcrun llvm-cov show --compilation-dir=`pwd` --format=html \
		-instr-profile=$(1) \
		$(LLVM_COV_IGNORE) \
		-output-dir=$(COVERAGE_OUTPUT_DIR)/$(2)/html \
		$(TEST_BINARY) $(TEST_OBJECT_FLAGS) $(3)
	@echo Extracting $(2) coverage percentages...
	@jq -r '.data[0].totals as $$t | \
		"Coverage summary:", \
		"  lines:     \($$t.lines.percent | . * 100 | round | . / 100)% (\($$t.lines.covered) of \($$t.lines.count))", \
		"  functions: \($$t.functions.percent | . * 100 | round | . / 100)% (\($$t.functions.covered) of \($$t.functions.count))", \
		"  regions:   \($$t.regions.percent | . * 100 | round | . / 100)% (\($$t.regions.covered) of \($$t.regions.count))"' \
		$(COVERAGE_OUTPUT_DIR)/$(2)/coverage-summary.json > $(COVERAGE_OUTPUT_DIR)/$(2)/coverage-percent.txt
	@echo "-- $(2) coverage --"
	@cat $(COVERAGE_OUTPUT_DIR)/$(2)/coverage-percent.txt
endef

# PARALLEL_WIDTH controls --experimental-maximum-parallelization-width for the
# concurrent pass. Each CLI integration test can create a
# Virtualization-backed Linux guest through the single local API server, which
# cannot reliably service overlapping create and stop requests. Use a
# deterministic serial default instead of all host CPU cores. Callers can still
# override this when validating a known-capable environment.
# WARMUP_FILTER, CONCURRENT_FILTER, and SERIAL_FILTER select the three phases.
PARALLEL_WIDTH ?= 1
WARMUP_FILTER = ImageWarmup/

# Concurrent suites: Test*.swift files whose names do NOT end in Serial.
CONCURRENT_TEST_SUITES ?= $(sort $(addsuffix /,$(basename $(notdir \
    $(shell find Tests/IntegrationTests -name 'Test*.swift' \
            ! -name '*Serial.swift' 2>/dev/null)))))
CONCURRENT_FILTER = $(subst $(space),|,$(strip $(CONCURRENT_TEST_SUITES)))

# Serial suites: Test*.swift files whose names end in Serial.
SERIAL_TEST_SUITES ?= $(sort $(addsuffix /,$(basename $(notdir \
    $(shell find Tests/IntegrationTests -name 'Test*Serial.swift' 2>/dev/null)))))
SERIAL_FILTER = $(subst $(space),|,$(strip $(SERIAL_TEST_SUITES)))

INTEGRATION_SWIFT_EXTRA ?=
INTEGRATION_POST_TEST ?=
# Environment prefix applied to the `container system start` invocation. Empty for
# ordinary runs; coverage runs set LLVM_PROFILE_FILE here so launchd-managed helper
# (XPC service) processes emit their own profraw data.
INTEGRATION_PROFILE_ENV ?=
# Integration fixtures use only public GHCR images. Force those hosts through
# the anonymous registry path so an ad-hoc coverage binary never blocks on a
# developer Keychain ACL prompt. Override with an empty value when explicitly
# exercising authenticated GHCR behaviour.
INTEGRATION_ANONYMOUS_REGISTRY_HOSTS ?= ghcr.io
INTEGRATION_REGISTRY_ENV := $(if $(strip $(INTEGRATION_ANONYMOUS_REGISTRY_HOSTS)),CONTAINER_REGISTRY_ANONYMOUS_HOSTS="$(strip $(INTEGRATION_ANONYMOUS_REGISTRY_HOSTS))")
# Keep integration runs independent of a developer's persisted runtime configuration.
# `container system start` snapshots XDG's config file into APP_ROOT, so an inherited
# ~/.config/container/config.toml can otherwise change the builder image under test.
INTEGRATION_CONFIG_HOME ?= $(SCRATCH_ROOT)/xdg-config
# A release gate can provide a candidate-specific namespace so Keychain access
# controls from an older ad-hoc build cannot poison a rebuilt integration run.
# Keep ordinary unit tests in the default namespace; this value is applied only
# inside RUN_INTEGRATION.
INTEGRATION_SERVICE_NAMESPACE ?=
INTEGRATION_NAMESPACE_ENV := $(if $(strip $(INTEGRATION_SERVICE_NAMESPACE)),CONTAINER_SERVICE_NAMESPACE="$(strip $(INTEGRATION_SERVICE_NAMESPACE))")

PRESERVE_KERNELS ?= false
# Default scratch root under the project directory so container build can access context
# subdirectories (macOS restricts access to /var/folders from the container binary).
# Override with SCRATCH_ROOT=/your/path on the command line.
SCRATCH_ROOT ?= $(ROOT_DIR)/.test-scratch

define RUN_INTEGRATION
	@echo Ensuring apiserver stopped before the CLI integration tests...
	@$(INTEGRATION_NAMESPACE_ENV) bin/container system stop && sleep 3
	@if [ -z "$(strip $(INTEGRATION_SERVICE_NAMESPACE))" ]; then scripts/ensure-container-stopped.sh ; fi
	@rm -f "$(INTEGRATION_CONFIG_HOME)/container/config.toml"
	@mkdir -p "$(INTEGRATION_CONFIG_HOME)"
	@if [ -n "$(APP_ROOT)" ]; then \
		mkdir -p $(APP_ROOT) ; \
		if [ "$(PRESERVE_KERNELS)" = "true" ]; then \
			echo "Clearing application data under $(APP_ROOT) (preserving kernels)..." ; \
			find "$(APP_ROOT)" -mindepth 1 -maxdepth 1 ! -name kernels -exec rm -rf {} + ; \
		else \
			echo "Clearing application data under $(APP_ROOT)..." ; \
			find "$(APP_ROOT)" -mindepth 1 -maxdepth 1 -exec rm -rf {} + ; \
		fi ; \
	fi
	@XDG_CONFIG_HOME="$(INTEGRATION_CONFIG_HOME)" $(INTEGRATION_REGISTRY_ENV) $(INTEGRATION_NAMESPACE_ENV) "$(MAKE)" init-block
	@echo Running the integration tests...
	@XDG_CONFIG_HOME="$(INTEGRATION_CONFIG_HOME)" $(INTEGRATION_PROFILE_ENV) $(INTEGRATION_REGISTRY_ENV) $(INTEGRATION_NAMESPACE_ENV) bin/container --debug system start --timeout 60 $(KERNEL_INSTALL_OPT) $(SYSTEM_START_OPTS) && \
	{ \
		if [ -n "$(APP_ROOT)" ]; then CONTAINER_APP_ROOT=$(APP_ROOT) && export CONTAINER_APP_ROOT ; fi ; \
		if [ -n "$(strip $(INTEGRATION_SERVICE_NAMESPACE))" ]; then CONTAINER_SERVICE_NAMESPACE="$(strip $(INTEGRATION_SERVICE_NAMESPACE))" && export CONTAINER_SERVICE_NAMESPACE ; fi ; \
		CLITEST_LOG_ROOT=$(LOG_ROOT) && export CLITEST_LOG_ROOT ; \
		CLITEST_SCRATCH_ROOT=$(SCRATCH_ROOT) && export CLITEST_SCRATCH_ROOT ; \
		CONTAINER_CLI_PATH=$(ROOT_DIR)/bin/container && export CONTAINER_CLI_PATH ; \
		XDG_CONFIG_HOME="$(INTEGRATION_CONFIG_HOME)" && export XDG_CONFIG_HOME ; \
		echo "==> Starting warmup tests" && \
		$(SWIFT) test $(INTEGRATION_SWIFT_EXTRA) -c $(BUILD_CONFIGURATION) $(SWIFT_CONFIGURATION) --filter "$(WARMUP_FILTER)" && \
		echo "==> Starting $(words $(CONCURRENT_TEST_SUITES)) test suites concurrently (width=$(PARALLEL_WIDTH))" && \
		$(SWIFT) test $(INTEGRATION_SWIFT_EXTRA) -c $(BUILD_CONFIGURATION) $(SWIFT_CONFIGURATION) $(CONCURRENT_EVENT_STREAM_OPTS) --experimental-maximum-parallelization-width $(PARALLEL_WIDTH) --filter "$(CONCURRENT_FILTER)" && \
		echo "==> Starting $(words $(SERIAL_TEST_SUITES)) test suites serially" && \
		$(SWIFT) test $(INTEGRATION_SWIFT_EXTRA) -c $(BUILD_CONFIGURATION) $(SWIFT_CONFIGURATION) $(GLOBAL_EVENT_STREAM_OPTS) --experimental-maximum-parallelization-width 1 --filter "$(SERIAL_FILTER)" ; \
		exit_code=$$? ; \
		$(INTEGRATION_POST_TEST) \
		echo Ensuring apiserver stopped after the CLI integration tests ; \
		bin/container system stop >/dev/null 2>&1 || true ; \
		if [ -z "$(strip $(INTEGRATION_SERVICE_NAMESPACE))" ]; then scripts/ensure-container-stopped.sh ; fi ; \
		exit $${exit_code} ; \
	}
endef

.PHONY: integration
# integration uses bin/container from the project install path. RUN_INTEGRATION
# clears APP_ROOT before loading the source-matched init image, so a clean test
# root cannot lose that image and fall back to an external registry pull. Keep
# the target non-parallel while allowing command-line PRESERVE_KERNELS=false
# when a full app-root wipe is needed.
.NOTPARALLEL: integration
integration coverage-integration: PRESERVE_KERNELS = true
integration: container
	@echo "HOSTNAME: $$(hostname)"
	$(RUN_INTEGRATION)

.PHONY: coverage-integration
coverage-integration: INTEGRATION_SWIFT_EXTRA = --skip-build --enable-code-coverage
coverage-integration: INTEGRATION_POST_TEST = cp $(COV_DATA_DIR)/*.profraw $(COVERAGE_OUTPUT_DIR)/integration/ || true ;
# Continuous mode (%c) mmaps the profraw and syncs counters live. The XPC helper
# services are torn down by `launchctl bootout` (SIGTERM/SIGKILL) rather than
# exiting cleanly, so a non-continuous profile (written by an atexit handler that
# never runs on SIGKILL) would lose the helpers' counters. %p-%m keeps each
# process/module profile in its own file so they don't collide.
coverage-integration: INTEGRATION_PROFILE_ENV = LLVM_PROFILE_FILE=$(COVERAGE_OUTPUT_DIR)/integration/%p-%m%c.profraw
coverage-integration: coverage-all
	@echo "HOSTNAME: $$(hostname)"
	@mkdir -p $(COVERAGE_OUTPUT_DIR)/integration
	@rm -f $(COVERAGE_OUTPUT_DIR)/integration/*.profraw
	$(RUN_INTEGRATION)
	@echo Merging integration coverage profdata...
	@xcrun llvm-profdata merge -sparse $(COVERAGE_OUTPUT_DIR)/integration/*.profraw -o $(COVERAGE_OUTPUT_DIR)/integration/default.profdata
	$(call GENERATE_COV_REPORTS,$(COVERAGE_OUTPUT_DIR)/integration/default.profdata,integration,$(INTEGRATION_TEST_OBJECT_FLAGS) $(COV_OBJECT_FLAGS))

empty :=
space := $(empty) $(empty)

# Opt the coverage targets in to instrumentation. The value propagates to the
# shared build-tests target so compilation is instrumented when necessary.
coverage coverage-all coverage-unit coverage-integration: COVERAGE_FLAG = --enable-code-coverage -Xswiftc -DCONTAINER_COVERAGE

.PHONY: coverage
# Merge the per-tier profdata from coverage-unit and coverage-integration into a
# combined report. Each prerequisite target produces its own tier report first.
coverage: coverage-unit coverage-integration
	@echo Merging combined coverage profdata...
	@mkdir -p $(COVERAGE_OUTPUT_DIR)/combined
	@xcrun llvm-profdata merge -sparse \
		$(COVERAGE_OUTPUT_DIR)/unit/default.profdata \
		$(COVERAGE_OUTPUT_DIR)/integration/default.profdata \
		-o $(COVERAGE_OUTPUT_DIR)/combined/default.profdata
	$(call GENERATE_COV_REPORTS,$(COVERAGE_OUTPUT_DIR)/combined/default.profdata,combined,$(INTEGRATION_TEST_OBJECT_FLAGS) $(COV_OBJECT_FLAGS))

.PHONY: coverage-sonar
coverage-sonar: coverage-unit
	@xcrun llvm-cov export --compilation-dir=`pwd` --format=lcov \
		-instr-profile=$(COVERAGE_OUTPUT_DIR)/unit/default.profdata \
		$(LLVM_COV_IGNORE) \
		$(TEST_BINARY) $(TEST_OBJECT_FLAGS) > $(COVERAGE_OUTPUT_DIR)/unit/coverage.lcov
	@$(PYTHON3) scripts/lcov-to-sonarqube-generic.py \
		$(COVERAGE_OUTPUT_DIR)/unit/coverage.lcov coverage.xml

.PHONY: sonar-scan
sonar-scan:
	@test -s coverage.xml || { echo 'coverage.xml is missing; run make coverage-sonar first' >&2; exit 2; }
	@sonar_project_version="$${SONAR_PROJECT_VERSION:-$$(git rev-parse HEAD)}"; \
	echo "$$sonar_project_version" | grep -Eq '^[0-9a-f]{40}$$' || { echo 'SONAR_PROJECT_VERSION must be an exact lowercase commit SHA' >&2; exit 2; }; \
	sonar-scanner -Dsonar.projectVersion="$$sonar_project_version" -Dsonar.qualitygate.wait="$${SONAR_QUALITYGATE_WAIT:-true}"

.PHONY: coverage-unit
coverage-unit: build-tests
	@echo Running unit test coverage...
	@test -n "$(TEST_BINARY)" && test -x "$(TEST_BINARY)" || { \
		echo 'no SwiftPM unit-test coverage binaries were found' >&2; \
		exit 2; \
	}
	@rm -f $(COV_DATA_DIR)/*.profraw
	@mkdir -p $(COVERAGE_OUTPUT_DIR)/unit
	@$(SWIFT) test --skip-build --enable-code-coverage -c $(BUILD_CONFIGURATION) $(SWIFT_CONFIGURATION) $(SWIFT_TEST_FLAGS) --skip TestCLI --skip IntegrationTests
	@echo Merging unit coverage profdata...
	@xcrun llvm-profdata merge -sparse $(COV_DATA_DIR)/*.profraw -o $(COVERAGE_OUTPUT_DIR)/unit/default.profdata
	$(call GENERATE_COV_REPORTS,$(COVERAGE_OUTPUT_DIR)/unit/default.profdata,unit)

.PHONY: fmt
fmt: swift-fmt update-licenses

.PHONY: check
check: swift-fmt-check check-licenses

.PHONY: swift-fmt
SWIFT_SRC = $(shell find . -type f -name '*.swift' -not -path "*/.*" -not -path "*.pb.swift" -not -path "*.grpc.swift" -not -path "*/checkouts/*")
swift-fmt:
	@echo Applying the standard code formatting...
	@$(SWIFT) format --recursive --configuration .swift-format -i $(SWIFT_SRC)

swift-fmt-check:
	@echo Applying the standard code formatting...
	@$(SWIFT) format lint --recursive --strict --configuration .swift-format-nolint $(SWIFT_SRC)

.PHONY: update-licenses
update-licenses:
	@echo Updating license headers...
	@HAWKEYE="$(HAWKEYE)" ./scripts/ensure-hawkeye-exists.sh
	@"$(HAWKEYE)" format --fail-if-unknown --fail-if-updated false

.PHONY: check-licenses
check-licenses:
	@echo Checking license headers existence in source files...
	@HAWKEYE="$(HAWKEYE)" ./scripts/ensure-hawkeye-exists.sh
	@"$(HAWKEYE)" check --fail-if-unknown

.PHONY: pre-commit
pre-commit:
	$(eval HOOKS_DIR := $(shell git rev-parse --git-path hooks))
	cp scripts/pre-commit.fmt $(HOOKS_DIR)/
	touch $(HOOKS_DIR)/pre-commit
	cat $(HOOKS_DIR)/pre-commit | grep -v 'hooks/pre-commit\.fmt' > /tmp/pre-commit.new || true
	echo 'PRECOMMIT_NOFMT=$${PRECOMMIT_NOFMT} $$(git rev-parse --git-path hooks/pre-commit.fmt)' >> /tmp/pre-commit.new
	mv /tmp/pre-commit.new $(HOOKS_DIR)/pre-commit
	chmod +x $(HOOKS_DIR)/pre-commit
	@./scripts/ensure-hawkeye-exists.sh

.PHONY: serve-docs
serve-docs:
	@echo 'to browse: open http://127.0.0.1:8000/container/documentation/'
	@rm -rf _serve
	@mkdir -p _serve
	@cp -a _site _serve/container
	@python3 -m http.server --bind 127.0.0.1 --directory ./_serve

.PHONY: docs
docs:
	@echo Updating API documentation...
	@rm -rf _site
	@scripts/make-docs.sh _site container

.PHONY: cleancontent
cleancontent:
	@bin/container system stop || true
	@echo Cleaning the content...
	@rm -rf ~/Library/Application\ Support/com.apple.container

.PHONY: clean
clean:
	@echo Cleaning build files...
	@rm -rf bin/ libexec/
	@rm -rf _site _serve
	@rm -f $(COV_REPORT_FILE)
	@rm -rf $(COVERAGE_OUTPUT_DIR)
	@$(SWIFT) package clean