Fix relative path resolution in entrypoint

[ParkSeongGeun]

• Fixes [Bug]: relative path in 'entrypoint' is not accepted #962

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update

Motivation and Context

• When using a relative path in --entrypoint (e.g., ./rustc), the container fails with "failed to find target executable". This change resolves relative paths against the working directory, matching the behavior of Docker and Podman.
• Changes in Relative Path Resolution: Updated the parser to detect if the entrypoint or command starts with a relative path and automatically resolve it using the workingDir.
• Changes in Path Normalization: Integrated URL.standardized.path to ensure that paths containing ./ or ../ are converted into clean, absolute strings before being passed to the runtime.
  • Code Refactoring: Extracted resolveExecutablePath private helper to eliminate code duplication.

Testing

• Tested locally
• Added/updated tests
• Added/updated docs

Verification Scenarios

Verified the fix on macOS 26.0 (Target: arm64-apple-macosx26.0) with the following integration tests

1. Bare command: container run --rm -w / --entrypoint ls alpine

   • Result: Kept as 'ls' for PATH lookup and executed successfully.

2. Relative path with ./: container run --rm --workdir /bin --entrypoint ./ls alpine

   • Result: Resolved to /bin/ls and executed successfully.

3. Relative path without prefix: container run --rm --entrypoint bin/ls alpine

   • Result: Kept as 'bin/ls', kernel resolves against workingDir.

4. Absolute path (Regression): container run --rm --entrypoint /bin/ls alpine

   • Result: Remained unchanged and worked as expected.

5. Path Normalization: Verified that complex paths like ../bin/ls are standardized correctly via URL.standardized.

Unit Tests

Ran swift test --filter ProcessEntrypoint to confirm all logic cases in ParserTest.swift pass.

[jglogan]

@ParkSeongGeun Thanks! It's a good start but a few things:

• Please rebase against main to resolve conflicts from the ContainerClient refactor.
• Extract your resolution code into a private function.
• Add handling for just command with no slashes at all (see comment with example that fails in this branch with container but works with the Docker CLI in Colima).

[jglogan]

Looks like we're repeating the same code in three places - extract method?

[ParkSeongGeun]

@jglogan This is my mistake. I've refactored the path resolution logic into a private helper function called resolveExecutablePath

[jglogan]

This doesn't cover all cases. Please add handling for bare commands:

% container run --rm -w / --entrypoint ls alpine
Error: internalError: "failed to find target executable /ls"

% docker run --rm -w / --entrypoint ls alpine   
bin
dev
etc

[ParkSeongGeun]

@jglogan Thank you for catching this case.

I've updated the logic to ensure that bare commands (those without any slashes) are not resolved against the working directory.

[ParkSeongGeun]

@jglogan Thanks for the thorough review

I've rebased the branch on the latest main and addressed all the feedback.

1. Refactored the path resolution logic into a helper function.
2. Added handling for bare commands to be resolved via PATH (executables without slashes are now ignored by the resolver).
3. Updated unit tests to cover these scenarios.

[jglogan]

@ParkSeongGeun I think this works, but I'm curious as to the root cause for this error in your original failure case:

% container run -it --rm -w /bin --entrypoint ./uname alpine:latest
Error: internalError: "failed to find target executable ./uname"

We might be able to address this down in containerization instead, such that we don't need to modify the path in the Bundle that gets generated. I feel that that is the cleaner approach.

Let me know if you're interested in looking at that. The bit of vmexec where the failure occurs is https://github.com/apple/containerization/blob/main/vminitd/Sources/vmexec/vmexec.swift#L74.

It might be as simple as pointing an AI assistant at a context of container, containerization, a failing command example, and this line of code and letting it crank out an answer for you. Or, troubleshoot it the old school way!

In either case see https://github.com/apple/container/blob/main/BUILDING.md for how to build container using a local copy of the containerization repo. I also noticed that the instructions for getting container to use your locally built init filesystem isn't there (you need this to see any changes that you make to vminitd or vmexec), so I filed #1030 to describe that procedure while I fix the docs.

[ParkSeongGeun]

@jglogan I agree that fixing this problem in containerization (vmexec) is more cleaner approach.

I'll set up the local environment settings and wait for your guidance in #1030 on how to use a custom init filesystem.

It's interesting to dive deeper into the root cause.

Thanks for your detailed explanation!

[jglogan]

@ParkSeongGeun The missing instructions were in the PR. I just merged them into BUILDING.md.

TL;DR:

1. Check out a copy of containerization.
2. From your container project: `swift package edit --path /path/to/your/containerization containerization
3. container system property set image.init vminit:latest
4. In your container project: make all install
5. container system stop ; container system start

When you build container in step 4, the build runs scripts/install-init.sh that will do make init in your containerization project and install the resulting init image into your container content store.

The system property change tells container to use that local init filesystem image instead of the release image hosted on GHCR.

Don't forget to unedit the package and clear the system property to get back to using the normal containerization dependency and init fs.