build: make native Go builds repeatable

hittyt · Pangjiping · commit d6fe24e1085f · 2026-04-29T13:50:21.000+08:00
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -376,6 +376,49 @@ dotnet build OpenSandbox.CodeInterpreter.sln --configuration Release /warnaserro
 - **Error Messages**: Provide actionable error messages with context
 - **Logging**: Use appropriate log levels (DEBUG, INFO, WARNING, ERROR)
 
+## Build System Standards
+
+OpenSandbox produces native Go binaries for `components/execd`, `components/ingress`,
+`components/egress`, `kubernetes`, and `sdks/sandbox/go`. These build systems must
+preserve caller-provided build flags and only append project-required flags.
+
+### Build Variables
+
+- Go builds pass caller-provided `GOFLAGS` to `go build` and append project flags such as `-trimpath` and `-buildvcs=false`.
+- Go linker builds pass caller-provided `LDFLAGS` to `go build -ldflags` and append project metadata flags.
+- When CGO is enabled, the Go toolchain honors `CC`, `CXX`, `CGO_CFLAGS`, `CGO_CXXFLAGS`, and `CGO_LDFLAGS`. Docker-based builds also accept `CFLAGS` and `CXXFLAGS` as fallbacks for `CGO_CFLAGS` and `CGO_CXXFLAGS`.
+- Docker build scripts forward these variables as build arguments when they are present in the environment.
+
+### Debug Information
+
+Default project builds must not strip debug information. Do not add `strip`,
+`install -s`, or Go linker flags such as `-s -w` to the default build path.
+Distribution-specific packaging may strip binaries only outside the default
+developer and CI build path.
+
+### Build Dependency Graph
+
+Use package-aware build tools instead of recursive independent builds:
+
+- Go packages are built through `go build ./...` or explicit Go package entry points.
+- Kotlin projects use Gradle task dependencies.
+- JavaScript and TypeScript SDKs use pnpm workspace dependencies.
+- C# SDKs use solution/project references through `dotnet build`.
+
+Subdirectory-specific Make targets may delegate to these tools, but they must not
+replace the build tool's dependency graph with independent recursive directory
+builds where cross-directory dependencies exist.
+
+### Repeatable Builds
+
+Native Go binary builds include `-trimpath`, `-buildvcs=false`, and `-ldflags`
+with `-buildid= -B none` so that source paths, VCS metadata, and build IDs or
+Mach-O UUIDs do not make binaries differ. For repeatable release metadata, set `SOURCE_DATE_EPOCH`
+or set `BUILD_TIME`, `VERSION`, and `GIT_COMMIT` explicitly before invoking
+Makefile or Docker build scripts. When `SOURCE_DATE_EPOCH` is set and
+`BUILD_TIME` is unset, build scripts derive `BUILD_TIME` from
+`SOURCE_DATE_EPOCH`.
+
 ## Testing Guidelines
 
 ### Test Coverage Requirements
diff --git a/components/egress/Dockerfile b/components/egress/Dockerfile
@@ -19,6 +19,16 @@ WORKDIR /workspace
 ARG VERSION=dev
 ARG GIT_COMMIT=unknown
 ARG BUILD_TIME=unknown
+ARG GOFLAGS=
+ARG LDFLAGS=
+ARG CGO_ENABLED=0
+ARG CC=
+ARG CXX=
+ARG CFLAGS=
+ARG CXXFLAGS=
+ARG CGO_CFLAGS=
+ARG CGO_CXXFLAGS=
+ARG CGO_LDFLAGS=
 
 # Copy only go mod/sum first for better caching
 COPY components/egress/go.mod components/egress/go.sum ./components/egress/
@@ -27,14 +37,20 @@ COPY components/internal ./components/internal
 
 WORKDIR /workspace/components/egress
 
-# Static-ish build (no cgo) to simplify runtime deps
-ENV CGO_ENABLED=0
+# Static-ish build (no cgo by default) to simplify runtime deps.
 RUN go mod download
 
 # Copy the rest of the egress sources
 COPY components/egress ./
-RUN CGO_ENABLED=0 go build \
-    -ldflags "-X 'github.com/alibaba/opensandbox/internal/version.Version=${VERSION}' \
+RUN if [ -n "${CC}" ]; then export CC; fi; \
+    if [ -n "${CXX}" ]; then export CXX; fi; \
+    export CGO_ENABLED="${CGO_ENABLED}" \
+           CGO_CFLAGS="${CGO_CFLAGS:-${CFLAGS}}" \
+           CGO_CXXFLAGS="${CGO_CXXFLAGS:-${CXXFLAGS}}" \
+           CGO_LDFLAGS="${CGO_LDFLAGS}"; \
+    go build ${GOFLAGS} -trimpath -buildvcs=false \
+    -ldflags "${LDFLAGS} -buildid= -B none \
+              -X 'github.com/alibaba/opensandbox/internal/version.Version=${VERSION}' \
               -X 'github.com/alibaba/opensandbox/internal/version.BuildTime=${BUILD_TIME}' \
               -X 'github.com/alibaba/opensandbox/internal/version.GitCommit=${GIT_COMMIT}'" \
     -o /out/egress .
diff --git a/components/egress/build.sh b/components/egress/build.sh
@@ -15,10 +15,30 @@
 
 set -ex
 
+default_build_time() {
+  if [[ -n "${SOURCE_DATE_EPOCH:-}" ]]; then
+    date -u -d "@${SOURCE_DATE_EPOCH}" +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null ||
+      date -u -r "${SOURCE_DATE_EPOCH}" +"%Y-%m-%dT%H:%M:%SZ"
+  else
+    date -u +"%Y-%m-%dT%H:%M:%SZ"
+  fi
+}
+
+build_arg_if_set() {
+  local name="$1"
+  if [[ -n "${!name+x}" ]]; then
+    BUILD_ARGS+=(--build-arg "${name}=${!name}")
+  fi
+}
+
 TAG=${TAG:-latest}
 VERSION=${VERSION:-$(git describe --tags --always --dirty 2>/dev/null || echo "dev")}
 GIT_COMMIT=${GIT_COMMIT:-$(git rev-parse HEAD 2>/dev/null || echo "unknown")}
-BUILD_TIME=${BUILD_TIME:-$(date -u +"%Y-%m-%dT%H:%M:%SZ")}
+BUILD_TIME=${BUILD_TIME:-$(default_build_time)}
+BUILD_ARGS=()
+for name in GOFLAGS LDFLAGS CGO_ENABLED CC CXX CFLAGS CXXFLAGS CGO_CFLAGS CGO_CXXFLAGS CGO_LDFLAGS; do
+  build_arg_if_set "${name}"
+done
 REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || realpath "$(dirname "$0")/../..")
 cd "${REPO_ROOT}"
 
@@ -37,6 +57,7 @@ docker buildx build \
   -t sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/egress:${TAG} \
   "${LATEST_TAGS[@]}" \
   -f components/egress/Dockerfile \
+  "${BUILD_ARGS[@]}" \
   --build-arg VERSION="${VERSION}" \
   --build-arg GIT_COMMIT="${GIT_COMMIT}" \
   --build-arg BUILD_TIME="${BUILD_TIME}" \
diff --git a/components/execd/Dockerfile b/components/execd/Dockerfile
@@ -19,6 +19,16 @@ WORKDIR /build
 ARG VERSION=dev
 ARG GIT_COMMIT=unknown
 ARG BUILD_TIME=unknown
+ARG GOFLAGS=
+ARG LDFLAGS=
+ARG CGO_ENABLED=0
+ARG CC=
+ARG CXX=
+ARG CFLAGS=
+ARG CXXFLAGS=
+ARG CGO_CFLAGS=
+ARG CGO_CXXFLAGS=
+ARG CGO_LDFLAGS=
 
 # Prepare local modules to satisfy replace directives.
 COPY components/internal/go.mod components/internal/go.sum ./components/internal/
@@ -34,14 +44,22 @@ COPY components/execd ./components/execd
 
 WORKDIR /build/components/execd
 
-RUN CGO_ENABLED=0 go build \
-    -ldflags "-X 'github.com/alibaba/opensandbox/internal/version.Version=${VERSION}' \
+RUN if [ -n "${CC}" ]; then export CC; fi; \
+    if [ -n "${CXX}" ]; then export CXX; fi; \
+    export CGO_ENABLED="${CGO_ENABLED}" \
+           CGO_CFLAGS="${CGO_CFLAGS:-${CFLAGS}}" \
+           CGO_CXXFLAGS="${CGO_CXXFLAGS:-${CXXFLAGS}}" \
+           CGO_LDFLAGS="${CGO_LDFLAGS}"; \
+    go build ${GOFLAGS} -trimpath -buildvcs=false \
+    -ldflags "${LDFLAGS} -buildid= -B none \
+              -X 'github.com/alibaba/opensandbox/internal/version.Version=${VERSION}' \
               -X 'github.com/alibaba/opensandbox/internal/version.BuildTime=${BUILD_TIME}' \
               -X 'github.com/alibaba/opensandbox/internal/version.GitCommit=${GIT_COMMIT}'" \
     -o /build/execd ./main.go
 
-RUN CGO_ENABLED=0 GOOS=windows go build \
-    -ldflags "-X 'github.com/alibaba/opensandbox/internal/version.Version=${VERSION}' \
+RUN CGO_ENABLED=0 GOOS=windows go build ${GOFLAGS} -trimpath -buildvcs=false \
+    -ldflags "${LDFLAGS} -buildid= -B none \
+              -X 'github.com/alibaba/opensandbox/internal/version.Version=${VERSION}' \
               -X 'github.com/alibaba/opensandbox/internal/version.BuildTime=${BUILD_TIME}' \
               -X 'github.com/alibaba/opensandbox/internal/version.GitCommit=${GIT_COMMIT}'" \
     -o /build/execd.exe ./main.go
diff --git a/components/execd/Makefile b/components/execd/Makefile
@@ -28,15 +28,18 @@ golint: fmt install-golint
 
 VERSION ?= $(shell git describe --tags --always --dirty 2>/dev/null || git rev-parse --short HEAD 2>/dev/null || echo "dev")
 GIT_COMMIT ?= $(shell git rev-parse HEAD 2>/dev/null || echo "unknown")
-BUILD_TIME ?= $(shell date -u +"%Y-%m-%dT%H:%M:%SZ")
-LDFLAGS := -X 'github.com/alibaba/opensandbox/internal/version.Version=$(VERSION)' \
+BUILD_TIME ?= $(shell if [ -n "$$SOURCE_DATE_EPOCH" ]; then date -u -d "@$$SOURCE_DATE_EPOCH" +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date -u -r "$$SOURCE_DATE_EPOCH" +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null; else date -u +"%Y-%m-%dT%H:%M:%SZ"; fi)
+PROJECT_GOFLAGS := -trimpath -buildvcs=false
+PROJECT_LDFLAGS := -buildid= -B none -X 'github.com/alibaba/opensandbox/internal/version.Version=$(VERSION)' \
 	-X 'github.com/alibaba/opensandbox/internal/version.BuildTime=$(BUILD_TIME)' \
 	-X 'github.com/alibaba/opensandbox/internal/version.GitCommit=$(GIT_COMMIT)'
+GO_BUILD_FLAGS := $(strip $(GOFLAGS) $(PROJECT_GOFLAGS))
+GO_LDFLAGS := $(strip $(LDFLAGS) $(PROJECT_LDFLAGS))
 
 .PHONY: build
 build: vet ## Build the binary.
 	@mkdir -p bin
-	go build -ldflags "$(LDFLAGS)" -o bin/execd main.go
+	go build $(GO_BUILD_FLAGS) -ldflags "$(GO_LDFLAGS)" -o bin/execd main.go
 
 .PHONY: multi-build
 multi-build: vet ## Cross-compile for linux/windows/darwin amd64/arm64.
@@ -46,6 +49,6 @@ multi-build: vet ## Cross-compile for linux/windows/darwin amd64/arm64.
 			out=bin/execd_$(VERSION)_$${os}_$${arch}; \
 			[ "$${os}" = "windows" ] && out="$${out}.exe"; \
 			echo ">> building $${os}/$${arch} -> $${out}"; \
-			GOOS=$${os} GOARCH=$${arch} CGO_ENABLED=0 go build -ldflags "$(LDFLAGS)" -o "$${out}" main.go || exit $$?; \
+			GOOS=$${os} GOARCH=$${arch} CGO_ENABLED=0 go build $(GO_BUILD_FLAGS) -ldflags "$(GO_LDFLAGS)" -o "$${out}" main.go || exit $$?; \
 		done; \
 	done
diff --git a/components/execd/build.sh b/components/execd/build.sh
@@ -15,10 +15,30 @@
 
 set -ex
 
+default_build_time() {
+  if [[ -n "${SOURCE_DATE_EPOCH:-}" ]]; then
+    date -u -d "@${SOURCE_DATE_EPOCH}" +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null ||
+      date -u -r "${SOURCE_DATE_EPOCH}" +"%Y-%m-%dT%H:%M:%SZ"
+  else
+    date -u +"%Y-%m-%dT%H:%M:%SZ"
+  fi
+}
+
+build_arg_if_set() {
+  local name="$1"
+  if [[ -n "${!name+x}" ]]; then
+    BUILD_ARGS+=(--build-arg "${name}=${!name}")
+  fi
+}
+
 TAG=${TAG:-latest}
 VERSION=${VERSION:-$(git describe --tags --always --dirty 2>/dev/null || echo "dev")}
 GIT_COMMIT=${GIT_COMMIT:-$(git rev-parse HEAD 2>/dev/null || echo "unknown")}
-BUILD_TIME=${BUILD_TIME:-$(date -u +"%Y-%m-%dT%H:%M:%SZ")}
+BUILD_TIME=${BUILD_TIME:-$(default_build_time)}
+BUILD_ARGS=()
+for name in GOFLAGS LDFLAGS CGO_ENABLED CC CXX CFLAGS CXXFLAGS CGO_CFLAGS CGO_CXXFLAGS CGO_LDFLAGS; do
+  build_arg_if_set "${name}"
+done
 
 REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || realpath "$(dirname "$0")/../..")
 cd "${REPO_ROOT}"
@@ -41,6 +61,7 @@ docker buildx build \
   -t sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/execd:${TAG} \
   "${LATEST_TAGS[@]}" \
   -f components/execd/Dockerfile \
+  "${BUILD_ARGS[@]}" \
   --build-arg VERSION="${VERSION}" \
   --build-arg GIT_COMMIT="${GIT_COMMIT}" \
   --build-arg BUILD_TIME="${BUILD_TIME}" \
diff --git a/components/ingress/Dockerfile b/components/ingress/Dockerfile
@@ -19,6 +19,16 @@ WORKDIR /build
 ARG VERSION=dev
 ARG GIT_COMMIT=unknown
 ARG BUILD_TIME=unknown
+ARG GOFLAGS=
+ARG LDFLAGS=
+ARG CGO_ENABLED=0
+ARG CC=
+ARG CXX=
+ARG CFLAGS=
+ARG CXXFLAGS=
+ARG CGO_CFLAGS=
+ARG CGO_CXXFLAGS=
+ARG CGO_LDFLAGS=
 
 COPY kubernetes ./kubernetes
 # Prepare local modules to satisfy replace directives.
@@ -36,8 +46,15 @@ COPY components/ingress/. ./components/ingress
 
 WORKDIR /build/components/ingress
 
-RUN CGO_ENABLED=0 go build \
-    -ldflags "-X 'github.com/alibaba/opensandbox/internal/version.Version=${VERSION}' \
+RUN if [ -n "${CC}" ]; then export CC; fi; \
+    if [ -n "${CXX}" ]; then export CXX; fi; \
+    export CGO_ENABLED="${CGO_ENABLED}" \
+           CGO_CFLAGS="${CGO_CFLAGS:-${CFLAGS}}" \
+           CGO_CXXFLAGS="${CGO_CXXFLAGS:-${CXXFLAGS}}" \
+           CGO_LDFLAGS="${CGO_LDFLAGS}"; \
+    go build ${GOFLAGS} -trimpath -buildvcs=false \
+    -ldflags "${LDFLAGS} -buildid= -B none \
+              -X 'github.com/alibaba/opensandbox/internal/version.Version=${VERSION}' \
               -X 'github.com/alibaba/opensandbox/internal/version.BuildTime=${BUILD_TIME}' \
               -X 'github.com/alibaba/opensandbox/internal/version.GitCommit=${GIT_COMMIT}'" \
     -o /build/ingress ./main.go
diff --git a/components/ingress/Makefile b/components/ingress/Makefile
@@ -28,15 +28,18 @@ golint: fmt install-golint
 
 VERSION ?= $(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
 GIT_COMMIT ?= $(shell git rev-parse HEAD 2>/dev/null || echo "unknown")
-BUILD_TIME ?= $(shell date -u +"%Y-%m-%dT%H:%M:%SZ")
-LDFLAGS := -X 'github.com/alibaba/opensandbox/internal/version.Version=$(VERSION)' \
+BUILD_TIME ?= $(shell if [ -n "$$SOURCE_DATE_EPOCH" ]; then date -u -d "@$$SOURCE_DATE_EPOCH" +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date -u -r "$$SOURCE_DATE_EPOCH" +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null; else date -u +"%Y-%m-%dT%H:%M:%SZ"; fi)
+PROJECT_GOFLAGS := -trimpath -buildvcs=false
+PROJECT_LDFLAGS := -buildid= -B none -X 'github.com/alibaba/opensandbox/internal/version.Version=$(VERSION)' \
 	-X 'github.com/alibaba/opensandbox/internal/version.BuildTime=$(BUILD_TIME)' \
 	-X 'github.com/alibaba/opensandbox/internal/version.GitCommit=$(GIT_COMMIT)'
+GO_BUILD_FLAGS := $(strip $(GOFLAGS) $(PROJECT_GOFLAGS))
+GO_LDFLAGS := $(strip $(LDFLAGS) $(PROJECT_LDFLAGS))
 
 .PHONY: build
 build: vet ## Build the binary.
 	@mkdir -p bin
-	go build -ldflags "$(LDFLAGS)" -o bin/router main.go
+	go build $(GO_BUILD_FLAGS) -ldflags "$(GO_LDFLAGS)" -o bin/router main.go
 
 .PHONY: clean
 clean: ## Clean build artifacts.
diff --git a/components/ingress/build.sh b/components/ingress/build.sh
@@ -15,10 +15,30 @@
 
 set -ex
 
+default_build_time() {
+  if [[ -n "${SOURCE_DATE_EPOCH:-}" ]]; then
+    date -u -d "@${SOURCE_DATE_EPOCH}" +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null ||
+      date -u -r "${SOURCE_DATE_EPOCH}" +"%Y-%m-%dT%H:%M:%SZ"
+  else
+    date -u +"%Y-%m-%dT%H:%M:%SZ"
+  fi
+}
+
+build_arg_if_set() {
+  local name="$1"
+  if [[ -n "${!name+x}" ]]; then
+    BUILD_ARGS+=(--build-arg "${name}=${!name}")
+  fi
+}
+
 TAG=${TAG:-latest}
 VERSION=${VERSION:-$(git describe --tags --always --dirty 2>/dev/null || echo "dev")}
 GIT_COMMIT=${GIT_COMMIT:-$(git rev-parse HEAD 2>/dev/null || echo "unknown")}
-BUILD_TIME=${BUILD_TIME:-$(date -u +"%Y-%m-%dT%H:%M:%SZ")}
+BUILD_TIME=${BUILD_TIME:-$(default_build_time)}
+BUILD_ARGS=()
+for name in GOFLAGS LDFLAGS CGO_ENABLED CC CXX CFLAGS CXXFLAGS CGO_CFLAGS CGO_CXXFLAGS CGO_LDFLAGS; do
+  build_arg_if_set "${name}"
+done
 
 REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || realpath "$(dirname "$0")/../..")
 cd "${REPO_ROOT}"
@@ -41,6 +61,7 @@ docker buildx build \
   -t sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/ingress:${TAG} \
   "${LATEST_TAGS[@]}" \
   -f components/ingress/Dockerfile \
+  "${BUILD_ARGS[@]}" \
   --build-arg VERSION="${VERSION}" \
   --build-arg GIT_COMMIT="${GIT_COMMIT}" \
   --build-arg BUILD_TIME="${BUILD_TIME}" \
diff --git a/kubernetes/Dockerfile b/kubernetes/Dockerfile
@@ -16,6 +16,16 @@
 FROM golang:1.24 AS builder
 ARG TARGETOS
 ARG TARGETARCH
+ARG GOFLAGS=
+ARG LDFLAGS=
+ARG CGO_ENABLED=0
+ARG CC=
+ARG CXX=
+ARG CFLAGS=
+ARG CXXFLAGS=
+ARG CGO_CFLAGS=
+ARG CGO_CXXFLAGS=
+ARG CGO_LDFLAGS=
 
 WORKDIR /workspace
 # Copy the Go Modules manifests
@@ -38,7 +48,15 @@ COPY internal/ internal/
 # by leaving it empty we can ensure that the container and binary shipped on it will have the same platform.
 RUN echo "Building for $TARGETOS/$TARGETARCH"
 ARG PACKAGE=./cmd/controller
-RUN CGO_ENABLED=0 GOOS=${TARGETOS:-linux} GOARCH=${TARGETARCH} go build -o server ${PACKAGE}
+RUN if [ -n "${CC}" ]; then export CC; fi; \
+    if [ -n "${CXX}" ]; then export CXX; fi; \
+    export CGO_ENABLED="${CGO_ENABLED}" GOOS="${TARGETOS:-linux}" GOARCH="${TARGETARCH}" \
+           CGO_CFLAGS="${CGO_CFLAGS:-${CFLAGS}}" \
+           CGO_CXXFLAGS="${CGO_CXXFLAGS:-${CXXFLAGS}}" \
+           CGO_LDFLAGS="${CGO_LDFLAGS}"; \
+    go build ${GOFLAGS} -trimpath -buildvcs=false \
+    -ldflags "${LDFLAGS} -buildid= -B none" \
+    -o server ${PACKAGE}
 
 # Use golang image as base to ensure nsenter (util-linux) is available
 # distroless does not contain shell or nsenter
diff --git a/kubernetes/Makefile b/kubernetes/Makefile
diff --git a/kubernetes/build.sh b/kubernetes/build.sh
diff --git a/sdks/sandbox/go/Makefile b/sdks/sandbox/go/Makefile
