cross-compile-matrix

Name: cross-compile-matrix
Author: zakelfassi

17stars0forks

How to install cross-compile-matrix?

zakelfassi/skills-driven-development/cross-compile-matrix

$npx -y skills add zakelfassi/skills-driven-development --skill cross-compile-matrix

Installs into the current project.

Summary

Add a new target triple to the shipctl cross-platform build matrix — CI YAML, Makefile, and a smoke test. Use when adding support for a new OS/architecture, when a user requests a new platform binary, or when a target triple is missing from the release artifacts.

Files · 1

View on GitHub

SKILL.md

1	# Cross-Compile Matrix
2
3	Add a new target triple to the build matrix so CI produces a binary for the new platform.
4
5	## Inputs
6	- Target triple (e.g., `aarch64-apple-darwin`, `x86_64-pc-windows-gnu`)
7	- Cross-compiler image (Docker image or `native` if the runner natively supports the target)
8	- Smoke test command (a simple invocation to verify the binary works, e.g., `shipctl --version`)
9
10	## Steps
11
12	1. Verify the triple is valid
13	```bash
14	rustup target list \| grep {triple}
15	```
16	For Go: check `go tool dist list \| grep {os}/{arch}`.
17
18	2. Add the target to the CI matrix
19	Edit `.github/workflows/release.yml` — add the triple to the `matrix.target` array:
20	```yaml
21	strategy:
22	matrix:
23	include:
24	- target: {triple}
25	runner: ubuntu-latest # or macos-latest, windows-latest
26	cross: true # false if runner supports the target natively
27	image: ghcr.io/cross-rs/{triple}:latest # omit if cross: false
28	```
29
30	3. Add the Makefile target
31	```makefile
32	build-{safe-triple}:
33	cargo build --release --target {triple}
34	mkdir -p dist
35	cp target/{triple}/release/shipctl dist/shipctl-{triple}
36	```
37	`{safe-triple}` replaces `-` with `_` in Make target names.
38
39	4. Register the rustup target (Rust only)
40	```bash
41	rustup target add {triple}
42	```
43	For CI: add to the `rustup target add` step in the workflow.
44
45	5. Add a smoke test step in the workflow:
46	```yaml
47	- name: Smoke test ({triple})
48	run: ./dist/shipctl-{triple} --version
49	if: matrix.target == '{triple}'
50	```
51	If cross-testing is not feasible (e.g., Windows binary on a Linux runner), document this in a comment.
52
53	6. Test locally (if the host supports the target)
54	```bash
55	make build-{safe-triple}
56	./dist/shipctl-{triple} --version
57	```
58
59	7. Update the release notes template
60	Add a row to `docs/install.md`:
61	```markdown
62	\| {OS} \| {Arch} \| `{triple}` \| `shipctl-{version}-{triple}.tar.gz` \|
63	```
64
65	## Conventions
66	- Target naming in artifacts: `shipctl-{version}-{triple}.tar.gz`
67	- Windows targets produce `.exe` and are archived as `.zip` instead of `.tar.gz`
68	- `musl` targets are preferred for Linux binaries to avoid glibc dependency issues
69	- All targets are smoke-tested in CI before a release is published
70
71	## Edge Cases
72	- Cross-compilation fails with linker errors: Switch to the `cross-rs` Docker image for that triple; add the `image:` field in the matrix.
73	- Target is tier 3 (Rust): Add a comment noting reduced support guarantees; test manually before each release.
74	- macOS arm64 on amd64 runner: Use `--target aarch64-apple-darwin` with Rosetta or a self-hosted arm64 runner; document in the workflow.
75	- Windows MSVC vs GNU: Prefer `x86_64-pc-windows-msvc` for best compatibility; GNU works but requires MinGW on the runner.

People who liked this also viewed

6 picks

Type

cross-compile-matrix

17stars0forks

View on GitHub

How to install cross-compile-matrix?

zakelfassi/skills-driven-development/cross-compile-matrix

$npx -y skills add zakelfassi/skills-driven-development --skill cross-compile-matrix

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Cross-Compile Matrix
2
3	Add a new target triple to the build matrix so CI produces a binary for the new platform.
4
5	## Inputs
6	- Target triple (e.g., `aarch64-apple-darwin`, `x86_64-pc-windows-gnu`)
7	- Cross-compiler image (Docker image or `native` if the runner natively supports the target)
8	- Smoke test command (a simple invocation to verify the binary works, e.g., `shipctl --version`)
9
10	## Steps
11
12	1. Verify the triple is valid
13	```bash
14	rustup target list \| grep {triple}
15	```
16	For Go: check `go tool dist list \| grep {os}/{arch}`.
17
18	2. Add the target to the CI matrix
19	Edit `.github/workflows/release.yml` — add the triple to the `matrix.target` array:
20	```yaml
21	strategy:
22	matrix:
23	include:
24	- target: {triple}
25	runner: ubuntu-latest # or macos-latest, windows-latest
26	cross: true # false if runner supports the target natively
27	image: ghcr.io/cross-rs/{triple}:latest # omit if cross: false
28	```
29
30	3. Add the Makefile target
31	```makefile
32	build-{safe-triple}:
33	cargo build --release --target {triple}
34	mkdir -p dist
35	cp target/{triple}/release/shipctl dist/shipctl-{triple}
36	```
37	`{safe-triple}` replaces `-` with `_` in Make target names.
38
39	4. Register the rustup target (Rust only)
40	```bash
41	rustup target add {triple}
42	```
43	For CI: add to the `rustup target add` step in the workflow.
44
45	5. Add a smoke test step in the workflow:
46	```yaml
47	- name: Smoke test ({triple})
48	run: ./dist/shipctl-{triple} --version
49	if: matrix.target == '{triple}'
50	```
51	If cross-testing is not feasible (e.g., Windows binary on a Linux runner), document this in a comment.
52
53	6. Test locally (if the host supports the target)
54	```bash
55	make build-{safe-triple}
56	./dist/shipctl-{triple} --version
57	```
58
59	7. Update the release notes template
60	Add a row to `docs/install.md`:
61	```markdown
62	\| {OS} \| {Arch} \| `{triple}` \| `shipctl-{version}-{triple}.tar.gz` \|
63	```
64
65	## Conventions
66	- Target naming in artifacts: `shipctl-{version}-{triple}.tar.gz`
67	- Windows targets produce `.exe` and are archived as `.zip` instead of `.tar.gz`
68	- `musl` targets are preferred for Linux binaries to avoid glibc dependency issues
69	- All targets are smoke-tested in CI before a release is published
70
71	## Edge Cases
72	- Cross-compilation fails with linker errors: Switch to the `cross-rs` Docker image for that triple; add the `image:` field in the matrix.
73	- Target is tier 3 (Rust): Add a comment noting reduced support guarantees; test manually before each release.
74	- macOS arm64 on amd64 runner: Use `--target aarch64-apple-darwin` with Rosetta or a self-hosted arm64 runner; document in the workflow.
75	- Windows MSVC vs GNU: Prefer `x86_64-pc-windows-msvc` for best compatibility; GNU works but requires MinGW on the runner.

People who liked this also viewed

6 picks

Type