docs: document javaexec binary and source/git buildpack path

Author: stokpop

docs/DEVELOPING.md

@@ -97,6 +97,7 @@ Build the buildpack binaries:
 This creates executables in the `bin/` directory:
 - `bin/supply` - Staging phase binary (downloads and installs dependencies)
 - `bin/finalize` - Finalization phase binary (configures runtime)
+- `bin/javaexec` - Shell-free JVM launcher (tokenizes `JAVA_OPTS` without `eval`)
 
 ## Project Structure
 
@@ -118,6 +119,7 @@ java-buildpack/
 │   ├── jres/                           # JRE implementations (7 providers)
 │   ├── supply/cli/                     # Supply phase entrypoint
 │   ├── finalize/cli/                   # Finalize phase entrypoint
+│   ├── javaexec/cli/                   # Shell-free JVM launcher entrypoint
 │   ├── resources/                      # Resource configuration files
 │   └── integration/                    # Integration tests
 ├── scripts/                            # Build and test scripts
@@ -156,6 +158,7 @@ Build for the default platform (Linux):
 ```
 -----> Building supply for linux
 -----> Building finalize for linux
+-----> Building javaexec for linux
 -----> Build complete
 ```
 
@@ -193,6 +196,25 @@ go build -mod vendor -o bin/supply src/java/supply/cli/main.go
 
 # Build finalize
 go build -mod vendor -o bin/finalize src/java/finalize/cli/main.go
+
+# Build javaexec (shell-free JVM launcher, required at runtime)
+go build -mod vendor -o bin/javaexec src/java/javaexec/cli/main.go
+```
+
+### Source/Git Buildpack Usage
+
+When deploying with a git URL (`cf push -b https://github.com/.../java-buildpack.git`),
+Cloud Foundry runs `bin/finalize` directly from the cloned source. In that mode
+`bin/javaexec` does not exist (only packaged buildpacks have it). `bin/finalize`
+therefore builds `javaexec` into a temp directory alongside the finalize binary
+and passes the path via the `JAVAEXEC_BINARY_PATH` environment variable.
+`InstallJavaexecLauncher()` prefers this override and falls back to
+`bin/javaexec` for packaged buildpacks.
+
+To verify this path locally (no CF required):
+
+```bash
+bash scripts/test-javaexec-source-path.sh
 ```
 
 ## Running Tests

docs/design.md

@@ -186,6 +186,12 @@ During the finalize phase (`bin/finalize`), the buildpack:
 1. **Finalizes JRE**: Configures JVM options, memory calculator
 2. **Finalizes Frameworks**: Adds agent paths, system properties
 3. **Finalizes Container**: Generates launch command
+4. **Installs `javaexec`**: Copies the shell-free JVM launcher into
+   `$DEPS_DIR/<idx>/bin/javaexec`. The generated start command invokes it
+   instead of `eval "exec java $JAVA_OPTS ..."` so that `JAVA_OPTS` is
+   tokenized without shell interpretation. For source/git buildpack usage
+   `bin/finalize` builds `javaexec` on the fly and passes its path via
+   `JAVAEXEC_BINARY_PATH` (see [DEVELOPING.md](DEVELOPING.md#sourcegit-buildpack-usage)).
 
 Components can:
 - Read installed dependencies from `$DEPS_DIR/<idx>/`

scripts/test-javaexec-source-path.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+# Manual smoke test for the bin/finalize source/git buildpack path.
+# Simulates what bin/finalize does: build javaexec into a temp dir and pass
+# the path via JAVAEXEC_BINARY_PATH. Verifies the binary builds and that
+# InstallJavaexecLauncher picks up the override (unit tests cover the logic;
+# this confirms the wiring end-to-end on this machine).
+set -euo pipefail
+
+BUILDPACK_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+cd "$BUILDPACK_DIR"
+
+tmpdir=$(mktemp -d)
+trap 'rm -rf "$tmpdir"' EXIT
+
+echo "==> [1/3] Build javaexec from source (as bin/finalize now does)"
+go build -mod=vendor -o "$tmpdir/javaexec" ./src/java/javaexec/cli
+echo "    OK: $tmpdir/javaexec ($(wc -c < "$tmpdir/javaexec") bytes)"
+
+echo ""
+echo "==> [2/3] Build finalize from source"
+go build -mod=vendor -o "$tmpdir/finalize" ./src/java/finalize/cli
+echo "    OK: $tmpdir/finalize"
+
+echo ""
+echo "==> [3/3] Unit tests: InstallJavaexecLauncher with JAVAEXEC_BINARY_PATH override"
+go test ./src/java/finalize/ -count=1 -v -run "javaexec launcher" 2>&1 | grep -E "PASS|FAIL|RUN|---"
+
+echo ""
+echo "PASS: source/git buildpack path works."
+echo "      bin/finalize builds javaexec and passes it via JAVAEXEC_BINARY_PATH."

src/integration/README.md

@@ -151,6 +151,12 @@ property that must hold in a real container launch:
 - **The `javaexec` launcher actually starts the JVM** for the affected containers,
   including `Play` (previously `eval exec java $JAVA_OPTS ...`).
 
+**Source/git buildpack path** (`bin/finalize` building `javaexec` on the fly) is
+**not covered** by integration tests here: they use a packaged zip where `bin/javaexec`
+is pre-built by `scripts/build.sh`. The source/git path is covered by unit tests in
+[`../java/finalize/finalize_test.go`](../java/finalize/finalize_test.go) and can be
+verified locally with `bash scripts/test-javaexec-source-path.sh`.
+
 ## Writing New Tests
 
 To add a new test: