Merge pull request #75 from imjasonh/claude/update-docs-readme-td3LL

CLAUDE.md

@@ -204,7 +204,7 @@ Convenience wrapper that combines `resolve` with `kubectl apply`:
 Potential enhancements identified:
 1. ~~Registry authentication support~~ ✓ Implemented (supports Docker credential helpers)
 2. ~~YAML resolution for Kubernetes deployments~~ ✓ Implemented (`krust resolve`)
-3. Multi-platform image manifests
+3. ~~Multi-platform image manifests~~ ✓ Implemented (OCI image index with concurrent builds)
 4. ~~Build caching~~ ✓ Implemented (persistent `target/krust/` directory)
 5. Image layer optimization
 6. Support for custom Dockerfile-like configs

README.md

@@ -7,7 +7,7 @@ A container image build tool for Rust applications, inspired by [`ko`](https://k
 ## Overview
 
 krust builds container images for Rust applications without requiring Docker. It:
-- Executes `cargo build` to compile your Rust application as a static binary using musl libc
+- Uses [`cargo-zigbuild`](https://github.com/rust-cross/cargo-zigbuild) to compile your Rust application as a static binary using musl libc
 - Packages the resulting binary into a minimal container image layer
 - Pushes images to OCI-compliant registries by default (use `--no-push` to skip)
 - Creates truly static binaries by default for maximum portability and security
@@ -15,6 +15,10 @@ krust builds container images for Rust applications without requiring Docker. It
 ## Quick Start
 
 ```bash
+# Install prerequisites
+cargo install cargo-zigbuild
+# Also install zig: brew install zig (macOS) or see https://ziglang.org/download/
+
 # Install krust
 cargo install --path .
 
@@ -33,7 +37,7 @@ cargo install --path .
 
 ### Prerequisites
 
-Install [`cargo-zigbuild`](https://github.com/rust-cross/cargo-zigbuild) for cross-compilation (recommended):
+krust requires [`cargo-zigbuild`](https://github.com/rust-cross/cargo-zigbuild) and [Zig](https://ziglang.org/) for cross-compilation:
 
 ```bash
 # Install zig (cargo-zigbuild's cross-compilation backend)
@@ -46,7 +50,7 @@ sudo snap install zig --classic --beta  # or via your package manager
 cargo install cargo-zigbuild
 ```
 
-krust will automatically install the required rustup targets when building. If `cargo-zigbuild` is not installed, krust falls back to `cargo build` and will attempt to find a system cross-linker.
+krust will automatically install the required rustup targets when building, but `cargo-zigbuild` and `zig` must be installed beforehand.
 
 Note: krust builds fully static binaries by default using musl libc, ensuring maximum portability across different Linux distributions and container environments.
 
@@ -138,7 +142,7 @@ krust builds your Rust application and packages it into a container image:
 
 1. **Target installation** - Automatically installs the required rustup target if missing
 2. **Static compilation** - Builds with `RUSTFLAGS="-C target-feature=+crt-static"` for musl targets
-3. **Cross-compilation** - Uses `cargo-zigbuild` for seamless cross-compilation (falls back to `cargo build` with system linkers)
+3. **Cross-compilation** - Uses `cargo-zigbuild` for seamless cross-compilation to any supported platform
 4. **Cached builds** - Uses `target/krust/` as the build directory, so incremental compilation works across runs
 5. **Container creation** - Packages the binary into a minimal OCI image
 
@@ -147,7 +151,7 @@ krust builds your Rust application and packages it into a container image:
 krust builds fully static binaries by default using:
 - musl libc for Linux targets
 - `RUSTFLAGS="-C target-feature=+crt-static"` for static linking
-- Distroless static base image (`gcr.io/distroless/static:nonroot`)
+- Distroless static base image (`cgr.dev/chainguard/static:latest`)
 
 This ensures your applications work across all Linux distributions without dependency issues.
 
@@ -289,13 +293,14 @@ Arguments:
   [CARGO_ARGS]...  Additional cargo build arguments
 
 Options:
-  -i, --image <IMAGE>        Target image reference (overrides KRUST_REPO)
-      --platform <PLATFORM>  Target platform [default: linux/amd64]
+      --platform <PLATFORM>  Target platforms (comma-separated, auto-detected from base image if not specified)
       --no-push              Skip pushing the image to registry
       --tag <TAG>            Tag to apply to the image (e.g., latest, v1.0.0)
-      --repo <REPO>          Repository prefix (uses KRUST_REPO env var)
-  -v, --verbose              Enable verbose logging
+      --repo <REPO>          Repository prefix (defaults to KRUST_REPO env var)
   -h, --help                 Print help
+
+Global Options:
+  -v, --verbose              Enable verbose logging
 ```
 
 ### Resolve Command
@@ -310,10 +315,12 @@ Arguments:
 
 Options:
       --platform <PLATFORM>  Target platforms (comma-separated)
-      --repo <REPO>          Repository prefix (uses KRUST_REPO env var)
+      --repo <REPO>          Repository prefix (defaults to KRUST_REPO env var)
       --tag <TAG>            Tag to apply to built images
-  -v, --verbose              Enable verbose logging
   -h, --help                 Print help
+
+Global Options:
+  -v, --verbose              Enable verbose logging
 ```
 
 #### Usage Examples
@@ -374,10 +381,12 @@ Arguments:
 
 Options:
       --platform <PLATFORM>  Target platforms (comma-separated)
-      --repo <REPO>          Repository prefix (uses KRUST_REPO env var)
+      --repo <REPO>          Repository prefix (defaults to KRUST_REPO env var)
       --tag <TAG>            Tag to apply to built images
-  -v, --verbose              Enable verbose logging
   -h, --help                 Print help
+
+Global Options:
+  -v, --verbose              Enable verbose logging
 ```
 
 #### Usage Examples
@@ -399,17 +408,25 @@ The `apply` command is equivalent to:
 krust resolve -f deployment.yaml | kubectl apply -f -
 ```
 
+### Version Command
+
+```
+krust version
+```
+
+Prints the current krust version.
+
 ## Troubleshooting
 
 ### "linking with `cc` failed" or linker errors
 
-Install `cargo-zigbuild` for seamless cross-compilation:
+Ensure `cargo-zigbuild` and `zig` are installed:
 ```bash
 cargo install cargo-zigbuild
+# macOS: brew install zig
+# Linux: sudo snap install zig --classic --beta
 ```
 
-If you prefer not to use zigbuild, install the appropriate system cross-linker for your target platform.
-
 ### Platform mismatch warning when running images
 
 This is normal when building linux/amd64 images on Apple Silicon. The images will still run correctly under emulation.
@@ -488,7 +505,7 @@ make test-e2e          # End-to-end tests only
 cargo test -- --test-threads=1
 
 # Run with verbose output
-make test-verbose
+cargo test --verbose -- --test-threads=1
 ```
 
 ## License