Add container support to stellar contract build

[fnando]

What

Adds stellar contract build --image <ref>, which builds a contract inside a container image instead of compiling locally. The working tree is bind-mounted at /source, the image's own stellar contract build runs there, and the resulting wasm lands on the host — including copies to --out-dir when set. Any tag or digest ref is accepted.

It reuses the existing container-engine abstraction, so --engine, --docker-host, and the default engine set by stellar container use all apply, along with resource limits (--cpus, --memory). Workspaces with several cdylibs build each package, sharing one container.

Before forwarding flags, the image is probed once (a single throwaway container) for the CLI binary name (soroban vs stellar), its version, and the default rustup toolchain. Forwarded flags (--locked, --optimize, --optimize=false) are gated by the image's version so an older image doesn't fail on an unknown flag, and RUSTUP_TOOLCHAIN is pinned to the image's own toolchain so a rust-toolchain.toml in the mounted source can't redirect the build. --no-image-pull builds against an image already present locally (offline/air-gapped, digest-pinned, or never pushed), and --print-commands-only emits a copy-pasteable reproduce line.

On Linux the build container is deliberately run as the invoking user's uid:gid (--user), so wasm written into the bind-mounted target/ is owned by that user rather than root. Docker Desktop (macOS) and Apple's container already map ownership to the host user, so this is Linux-only. It assumes the image keeps CARGO_HOME/RUSTUP_HOME writable by non-root users, as the official image does.

Why

Lets you build a contract inside a container image with a fixed CLI and Rust toolchain, without needing a matching Rust build toolchain locally — no local wasm target and no pinned rustc. A local cargo is still used for workspace discovery (package selection and locating the workspace root); fully removing that dependency by running discovery inside the image is left as a follow-up.

Known limitations

The combined image probe requires /bin/sh and rustup in the image (as the official rust-based image provides). With --print-commands-only nothing is probed, so the reproduce line assumes a current stellar image and omits the toolchain pin. Running an arbitrary image with root-owned toolchain dirs may fail the Linux uid:gid build.

[Copilot]

Pull request overview

Adds containerized contract builds using Docker-compatible or Apple container engines.

Changes:

• Adds image-based builds, probing, resource limits, artifact collection, and interruption handling.
• Integrates asynchronous builds with deploy/upload flows.
• Adds CLI documentation, dependencies, and tests.

Reviewed changes

Copilot reviewed 10 out of 11 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
FULL_HELP_DOCS.md	Documents container build options.
cmd/soroban-cli/src/commands/mod.rs	Adds the container options heading.
cmd/soroban-cli/src/commands/contract/upload.rs	Awaits automatic builds.
cmd/soroban-cli/src/commands/contract/mod.rs	Awaits contract builds.
cmd/soroban-cli/src/commands/contract/deploy/wasm.rs	Awaits deploy-time builds.
cmd/soroban-cli/src/commands/contract/build/container.rs	Implements containerized builds.
cmd/soroban-cli/src/commands/contract/build.rs	Adds container flags and routing.
cmd/soroban-cli/src/commands/container/shared.rs	Extends shared engine helpers.
cmd/soroban-cli/Cargo.toml	Adds Linux UID/GID support.
cmd/crates/soroban-test/tests/it/build.rs	Tests generated container commands.
Cargo.lock	Locks the new dependency.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.