Skip to content

Commit 43789ae

Browse files
manusamanusa
authored
chore(build): align Makefile with project conventions (#389)
* chore(build): align Makefile with project conventions Restructure the Makefile to follow the same conventions used in kubernetes-mcp-server, podman-mcp-server, and com.marcnuri.automated-tasks: - Add suva.sh-style `make help` with `##@` category banners (Build / Test / Code Quality / Development / Release) and per-target `##` doc strings. - Switch `clean` to the `CLEAN_TARGETS +=` pattern so per-concern modules can contribute their own paths. - Split `release` into `build/release.mk`, auto-included via `-include build/*.mk` so additional concerns (CI, packaging) can land without churning the top-level Makefile. - Wire `scripts/check-authors.sh` in as a first-class `make check-authors` target so the linter is discoverable via `make help`. `ARGS='--fix'` forwards flags to the script. - Drop `build-native-wasi` — the WASI experiment is abandoned per CLAUDE.md and slated for removal. Update AGENTS.md so the layout table, build & test block, and conventions reference `make help`, the `build/*.mk` includes, and `make check-authors`. * chore(build): keep .PHONY adjacent to build-current-platform rule Place `.PHONY: build-current-platform` above the target-specific `MAVEN_OPTIONS` assignment so `.PHONY` stays adjacent to the target's main rule, matching the convention used elsewhere in the file. Behavior is identical. * chore(ci): wrap mvn deploy in make and extract free-disk-space action Two cross-cutting cleanups across the build/release/snapshots workflows: - Add `make maven-deploy` to `build/release.mk` wrapping `mvn -Prelease clean deploy`, and replace the inline command in release.yml and snapshots.yml. Single source of truth for the Maven Central publish command. - Extract the ~20-line apt-get disk-cleanup shell block (duplicated in 3 workflows) to `.github/actions/free-disk-space` as a composite action. CI-only sudo work belongs in a composite action, not a Makefile target. Update AGENTS.md so `make maven-deploy` is listed and the CI block references both release.yml/snapshots.yml and the new composite action. * chore(build): polish review nits - Move `build-current-platform`'s target-specific `MAVEN_OPTIONS` assignment below the main rule so `.PHONY` is directly adjacent to the rule line. - Rename the composite action's inner step to `Purge preinstalled software` so CI logs don't show `Free up disk space / Free up disk space`.
1 parent 9b20db6 commit 43789ae

7 files changed

Lines changed: 122 additions & 114 deletions

File tree

‎.github/actions/free-disk-space/action.yml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
name: Free up disk space
2+
description: Remove preinstalled software (dotnet, mono, browsers, Android SDK, …) to reclaim disk space on ubuntu-latest runners.
3+
runs:
4+
using: composite
5+
steps:
6+
- name: Purge preinstalled software
7+
shell: bash
8+
run: |
9+
sudo apt-get purge -y \
10+
'aspnetcore.*' \
11+
'dotnet.*' \
12+
'firefox.*' \
13+
'google-chrome.*' \
14+
'mysql.*' \
15+
'php.*' \
16+
'mono-.*' \
17+
'libmono.*' \
18+
'azure-cli' \
19+
'powershell' \
20+
'^llvm-.*' \
21+
'^clang-.*'
22+
sudo apt-get autoremove -y
23+
sudo apt-get clean
24+
# Remove Android SDK
25+
sudo rm -rf /usr/local/lib/android 2>/dev/null || true
26+
# Remove .NET
27+
sudo rm -rf /usr/share/dotnet 2>/dev/null || true
28+
df -h

‎.github/workflows/build.yml‎

Lines changed: 1 addition & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -17,27 +17,7 @@ jobs:
1717
- name: Checkout
1818
uses: actions/checkout@v6
1919
- name: Free up disk space
20-
run: |
21-
sudo apt-get purge -y \
22-
'aspnetcore.*' \
23-
'dotnet.*' \
24-
'firefox.*' \
25-
'google-chrome.*' \
26-
'mysql.*' \
27-
'php.*' \
28-
'mono-.*' \
29-
'libmono.*' \
30-
'azure-cli' \
31-
'powershell' \
32-
'^llvm-.*' \
33-
'^clang-.*'
34-
sudo apt-get autoremove -y
35-
sudo apt-get clean
36-
# Remove Android SDK
37-
sudo rm -rf /usr/local/lib/android 2>/dev/null || true
38-
# Remove .NET
39-
sudo rm -rf /usr/share/dotnet 2>/dev/null || true
40-
df -h
20+
uses: ./.github/actions/free-disk-space
4121
- name: Setup Go
4222
uses: actions/setup-go@v6
4323
with:

‎.github/workflows/release.yml‎

Lines changed: 2 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -16,27 +16,7 @@ jobs:
1616
- name: Checkout
1717
uses: actions/checkout@v6
1818
- name: Free up disk space
19-
run: |
20-
sudo apt-get purge -y \
21-
'aspnetcore.*' \
22-
'dotnet.*' \
23-
'firefox.*' \
24-
'google-chrome.*' \
25-
'mysql.*' \
26-
'php.*' \
27-
'mono-.*' \
28-
'libmono.*' \
29-
'azure-cli' \
30-
'powershell' \
31-
'^llvm-.*' \
32-
'^clang-.*'
33-
sudo apt-get autoremove -y
34-
sudo apt-get clean
35-
# Remove Android SDK
36-
sudo rm -rf /usr/local/lib/android 2>/dev/null || true
37-
# Remove .NET
38-
sudo rm -rf /usr/share/dotnet 2>/dev/null || true
39-
df -h
19+
uses: ./.github/actions/free-disk-space
4020
- name: Setup Go
4121
uses: actions/setup-go@v6
4222
with:
@@ -54,7 +34,7 @@ jobs:
5434
- name: Build
5535
run: make build-all
5636
- name: Maven Release
57-
run: mvn -Prelease clean deploy
37+
run: make maven-deploy
5838
env:
5939
MAVEN_CENTRAL_USERNAME: ${{ secrets.MAVEN_CENTRAL_USERNAME }}
6040
MAVEN_CENTRAL_PASSWORD: ${{ secrets.MAVEN_CENTRAL_PASSWORD }}

‎.github/workflows/snapshots.yml‎

Lines changed: 2 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -16,27 +16,7 @@ jobs:
1616
- name: Checkout
1717
uses: actions/checkout@v6
1818
- name: Free up disk space
19-
run: |
20-
sudo apt-get purge -y \
21-
'aspnetcore.*' \
22-
'dotnet.*' \
23-
'firefox.*' \
24-
'google-chrome.*' \
25-
'mysql.*' \
26-
'php.*' \
27-
'mono-.*' \
28-
'libmono.*' \
29-
'azure-cli' \
30-
'powershell' \
31-
'^llvm-.*' \
32-
'^clang-.*'
33-
sudo apt-get autoremove -y
34-
sudo apt-get clean
35-
# Remove Android SDK
36-
sudo rm -rf /usr/local/lib/android 2>/dev/null || true
37-
# Remove .NET
38-
sudo rm -rf /usr/share/dotnet 2>/dev/null || true
39-
df -h
19+
uses: ./.github/actions/free-disk-space
4020
- name: Setup Go
4121
uses: actions/setup-go@v6
4222
with:
@@ -54,7 +34,7 @@ jobs:
5434
- name: Build
5535
run: make build-all
5636
- name: Maven SNAPSHOT Release
57-
run: mvn -Prelease clean deploy
37+
run: make maven-deploy
5838
env:
5939
MAVEN_CENTRAL_USERNAME: ${{ secrets.MAVEN_CENTRAL_USERNAME }}
6040
MAVEN_CENTRAL_PASSWORD: ${{ secrets.MAVEN_CENTRAL_PASSWORD }}

‎AGENTS.md‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -25,14 +25,17 @@ Multi-module Maven build (parent `pom.xml`) + a sibling Go module under `native/
2525
| `native/internal/test/` | Go test helpers (envtest). |
2626
| `native/wasm/`, `native/out/` | TinyGo/WASI experiment entrypoint (see `lib/wasi/` note); build output for shared libraries. |
2727
| `docs/research/` | Audits and decision records (e.g. native-codebase audit). Snapshots — may be stale; check the date. |
28-
| `scripts/check-authors.sh` | Validates `@author` Javadoc tags. |
29-
| `Makefile` | Build/test/release entrypoints (see [Build & test](#build--test)). |
28+
| `scripts/check-authors.sh` | Validates `@author` Javadoc tags (invoked via `make check-authors`). |
29+
| `Makefile`, `build/*.mk` | Build/test/release entrypoints. Top-level Makefile auto-includes `build/*.mk` (e.g. `build/release.mk`). Run `make help` for the categorized target list. See [Build & test](#build--test). |
3030

3131
## Build & test
3232

3333
The Maven parent has `requireFilesExist` enforcer that needs all 5 native binaries in `native/out/`. Submodule `helm-java` and `lib/api` skip the rule, but a top-level `./mvnw install` will fail without them.
3434

3535
```bash
36+
# Discover all targets (categorized: Build / Test / Code Quality / Development / Release)
37+
make help
38+
3639
# Local dev (current platform only — skips the cross-platform enforcer check)
3740
make build-current-platform # = build-native + mvn clean verify with -Denforcer.skipRules=requireFilesExist
3841

@@ -55,10 +58,15 @@ make test-go # = cd native && go clean -testcache && go te
5558
make build-all # cross-platform natives + Java build
5659
make update-go-deps # bulk-bump non-indirect Go deps
5760
make license # apply license-header.txt to .go/.java files
61+
make check-authors # verify @author tags (ARGS='--fix' suggests additions)
5862
make release V=1.2.3 VS=1.3.0 # tag release and bump to next snapshot (maintainer only)
63+
make maven-deploy # mvn -Prelease clean deploy (CI only; needs Central credentials)
5964
```
6065

61-
CI (`.github/workflows/build.yml`): Linux job runs `make test-go` + `make build-all` on Java 8. Matrix jobs run `make build-current-platform` on Windows/macOS with Java 11.
66+
CI:
67+
- `.github/workflows/build.yml`: Linux job runs `make test-go` + `make build-all` on Java 8. Matrix jobs run `make build-current-platform` on Windows/macOS with Java 11.
68+
- `.github/workflows/release.yml` and `snapshots.yml`: Linux Java 8; run `make build-all` then `make maven-deploy`.
69+
- Shared CI infra: `.github/actions/free-disk-space` (composite action) reclaims runner disk space before Ubuntu builds.
6270

6371
**Don't cancel running tests** that hit Kubernetes — they leak cluster resources.
6472

@@ -91,7 +99,7 @@ Verbs with both forms: `install`, `template`, `show`, `upgrade`. Most others are
9199
**Java**
92100
- Source/target 1.8 — no `var`, no `Map.of(...)`, no Optional in APIs, no records.
93101
- Apache 2.0 header on every `.go` and `.java` file (`make license` enforces).
94-
- `@author` Javadoc tags maintained (`scripts/check-authors.sh`).
102+
- `@author` Javadoc tags maintained (`make check-authors`).
95103
- Tests: JUnit 5 + AssertJ. **No mocking libraries** — use real impls (Testcontainers/KinD for k8s).
96104

97105
**Go**

‎Makefile‎

Lines changed: 58 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,18 @@
1-
CGO_ENABLED=1
2-
LD_FLAGS=-s -w
3-
COMMON_BUILD_ARGS=-ldflags "$(LD_FLAGS)" -buildmode=c-shared
4-
MAVEN_OPTIONS=
5-
LICENSE_FILE=license-header.txt
1+
# If you update this file, please follow
2+
# https://suva.sh/posts/well-documented-makefiles
3+
4+
.DEFAULT_GOAL := help
5+
6+
CGO_ENABLED = 1
7+
LD_FLAGS = -s -w
8+
COMMON_BUILD_ARGS = -ldflags "$(LD_FLAGS)" -buildmode=c-shared
9+
MAVEN_OPTIONS =
10+
LICENSE_FILE = license-header.txt
11+
612
# Detect OS to be able to run build-native target and provide a name
7-
OS_NAME=linux
8-
ARCH=amd64
9-
EXTENSION=so
13+
OS_NAME = linux
14+
ARCH = amd64
15+
EXTENSION = so
1016
ifeq ($(OS), Windows_NT)
1117
OS_NAME := windows-4.0
1218
EXTENSION := dll
@@ -23,64 +29,62 @@ else
2329
endif
2430
NATIVE_NAME := $(OS_NAME)-$(ARCH).$(EXTENSION)
2531

32+
CLEAN_TARGETS :=
33+
CLEAN_TARGETS += native/out/*.h native/out/*.so native/out/*.dylib native/out/*.dll
34+
35+
# The help will print out all targets with their descriptions organized below their categories. The categories are represented by `##@` and the target descriptions by `##`.
36+
# The awk command is responsible for reading the entire set of makefiles included in this invocation, looking for lines of the file as xyz: ## something, and then pretty-format the target and help. Then, if there's a line with ##@ something, that gets pretty-printed as a category.
37+
# More info over the usage of ANSI control characters for terminal formatting: https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_parameters
38+
# More info over awk command: http://linuxcommand.org/lc3_adv_awk.php
39+
#
40+
# Notice that we have a little modification on the awk command to support slash in the recipe name:
41+
# origin: /^[a-zA-Z_0-9-]+:.*?##/
42+
# modified /^[a-zA-Z_0-9\/\.-]+:.*?##/
43+
.PHONY: help
44+
help: ## Display this help
45+
@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n make \033[36m<target>\033[0m\n"} /^[a-zA-Z_0-9\/\.-]+:.*?##/ { printf " \033[36m%-30s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)
46+
2647
.PHONY: clean
27-
clean:
48+
clean: ## Clean up all build artifacts (Go, Maven, native binaries)
2849
cd native && go clean ./...
2950
mvn clean
30-
rm -f native/out/*.h native/out/*.so native/out/*.dylib native/out/*.dll
51+
rm -f $(CLEAN_TARGETS)
3152

32-
.PHONY: test-go
33-
test-go:
34-
cd native && go clean -testcache && go test ./...
53+
##@ Build
3554

3655
.PHONY: build-native
37-
build-native:
56+
build-native: ## Build the native shared library for the current platform
3857
cd native && go build $(COMMON_BUILD_ARGS) -o ./out/helm-$(NATIVE_NAME)
3958

4059
.PHONY: build-native-cross-platform
41-
build-native-cross-platform:
60+
build-native-cross-platform: ## Build native shared libraries for all 5 supported platforms (requires Docker)
4261
go install src.techknowlogick.com/xgo@latest
4362
xgo -image ghcr.io/techknowlogick/xgo:go-1.25.7 $(COMMON_BUILD_ARGS) -out native/out/helm --targets */arm64,*/amd64 ./native
4463

45-
.PHONY: build-native-wasi
46-
build-native-wasi:
47-
#cd native && GOOS=wasip1 GOARCH=wasm go build -o ./out/helm.wasm ./wasm/main.go
48-
# Andrea recommends using TinyGo
49-
# Doesn't work, need to find the right combination of ENV variables
50-
#cd native && GOOS=wasip1 GOARCH=wasm tinygo build -o ./out/helm.wasm
51-
# Working Version:
52-
cd native && tinygo build -target=wasi -o ./out/helm.wasm ./wasm/main.go
53-
5464
.PHONY: build-java
55-
build-java:
65+
build-java: ## Build and verify the Java artifacts (mvn clean verify)
5666
mvn $(MAVEN_OPTIONS) clean verify
5767

5868
.PHONY: build-current-platform
59-
build-current-platform: MAVEN_OPTIONS=-Denforcer.skipRules=requireFilesExist
60-
build-current-platform: build-native build-java
69+
build-current-platform: build-native build-java ## Build native + Java for the current platform (skips cross-platform enforcer)
70+
build-current-platform: MAVEN_OPTIONS = -Denforcer.skipRules=requireFilesExist
6171

6272
.PHONY: build-all
63-
build-all: build-native-cross-platform build-java
73+
build-all: build-native-cross-platform build-java ## Build all 5 native platforms and the Java artifacts
74+
75+
##@ Test
76+
77+
.PHONY: test-go
78+
test-go: ## Run Go tests in native/
79+
cd native && go clean -testcache && go test ./...
6480

6581
.PHONY: test
66-
test: test-go
67-
68-
.PHONY: release
69-
release:
70-
@if [ -z "$(V)" ]; then echo "V is not set"; exit 1; fi
71-
@if [ -z "$(VS)" ]; then echo "VS is not set"; exit 1; fi
72-
@mvn versions:set -DnewVersion=$(V) -DgenerateBackupPoms=false
73-
@git add .
74-
@git commit -m "[RELEASE] Updated project version to v$(V)"
75-
@git tag v$(V)
76-
@git push origin v$(V)
77-
@mvn versions:set -DnewVersion=$(VS)-SNAPSHOT -DgenerateBackupPoms=false
78-
@git add .
79-
@git commit -m "[RELEASE] v$(V) released, prepare for next development iteration"
80-
@git push origin main
82+
test: test-go ## Run all tests
83+
84+
##@ Code Quality
8185

8286
.PHONY: license
83-
license:
87+
license: ## Apply the Apache 2.0 license header to all .go and .java files
8488
@license_len=$$(cat $(LICENSE_FILE) | wc -l) && \
8589
files=$$(git ls-files | grep -E "\.go|\.java") && \
8690
for file in $$files; do \
@@ -89,8 +93,14 @@ license:
8993
( ( cat $(LICENSE_FILE); echo; cat $$file ) > $$file.temp; mv $$file.temp $$file ) \
9094
done
9195

96+
.PHONY: check-authors
97+
check-authors: ## Check Java files for missing @author tags (use ARGS='--fix' to see suggestions)
98+
@./scripts/check-authors.sh $(ARGS)
99+
100+
##@ Development
101+
92102
.PHONY: update-go-deps
93-
update-go-deps:
103+
update-go-deps: ## Update non-indirect Go dependencies and tidy
94104
@echo ">> updating Go dependencies"
95105
@cd native && for m in $$(go list -mod=readonly -m -f '{{ if and (not .Indirect) (not .Main)}}{{.Path}}{{end}}' all); do \
96106
go get $$m; \
@@ -99,3 +109,6 @@ update-go-deps:
99109
ifneq (,$(wildcard native/vendor))
100110
cd native && go mod vendor
101111
endif
112+
113+
# Include additional make targets
114+
-include build/*.mk

‎build/release.mk‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
##@ Release
2+
3+
.PHONY: maven-deploy
4+
maven-deploy: ## Deploy to Maven Central with the release profile (CI; requires credentials and prebuilt native binaries)
5+
mvn -Prelease clean deploy
6+
7+
.PHONY: release
8+
release: ## Release a new version (maintainer only; usage: make release V=1.2.3 VS=1.3.0)
9+
@if [ -z "$(V)" ]; then echo "V is not set"; exit 1; fi
10+
@if [ -z "$(VS)" ]; then echo "VS is not set"; exit 1; fi
11+
@mvn versions:set -DnewVersion=$(V) -DgenerateBackupPoms=false
12+
@git add .
13+
@git commit -m "[RELEASE] Updated project version to v$(V)"
14+
@git tag v$(V)
15+
@git push origin v$(V)
16+
@mvn versions:set -DnewVersion=$(VS)-SNAPSHOT -DgenerateBackupPoms=false
17+
@git add .
18+
@git commit -m "[RELEASE] v$(V) released, prepare for next development iteration"
19+
@git push origin main

0 commit comments

Comments
 (0)