From 396ce1cdcce78b4f5f8db6bd02b0c96416215eaf Mon Sep 17 00:00:00 2001 From: yardencuriel <259054981+splint-disk-8i@users.noreply.github.com> Date: Fri, 13 Mar 2026 18:09:31 +0200 Subject: [PATCH 1/3] docs: add troubleshooting section to building guide --- BUILDING.md | 83 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) diff --git a/BUILDING.md b/BUILDING.md index 8f80dd11d..8a3e65c5c 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -189,3 +189,86 @@ Attach debugger to the XPC helpers using their launchd service labels: ## Pre-commit hook Run `make pre-commit` to install a pre-commit hook that ensures that your changes have correct formatting and license headers when you run `git commit`. + +## Troubleshooting + +### Build fails with missing Xcode or developer tools + +If you see errors about missing compilers or developer tools, make sure the active developer directory is pointed at a full Xcode installation: + +```bash +xcode-select --print-path +``` + +If it points at `/Library/Developer/CommandLineTools` instead of an Xcode app, switch it: + +```bash +sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer +``` + +On macOS 26, use the latest Xcode version: + +```bash +sudo xcode-select --switch /Applications/Xcode-latest.app/Contents/Developer +``` + +### Swift version mismatch + +The project requires Swift 6.1 or later. Verify your version: + +```bash +swift --version +``` + +If you have multiple toolchains installed, Swift Package Manager uses whatever `swift` resolves to in your `$PATH`. Make sure the correct toolchain is first in your path, or set `DEVELOPER_DIR` before building: + +```bash +DEVELOPER_DIR=/Applications/Xcode-latest.app/Contents/Developer make all +``` + +### Permission errors during install + +`make install` creates a `.pkg` and uses `sudo installer` to place binaries under `/usr/local`. If you can't use sudo or prefer a local install: + +```bash +DEST_DIR=~/.local/ SUDO= make install +``` + +Then add `~/.local/bin` to your `$PATH`. + +### Integration tests fail with network errors + +The integration tests create lightweight VMs that need outbound network access. If you're behind a corporate proxy, set the proxy exclusion variables before running tests: + +```bash +export NO_PROXY="${NO_PROXY},192.168.0.0/16,fe80::/10" +export no_proxy="${no_proxy},192.168.0.0/16,fe80::/10" +make test integration +``` + +### Kernel installation hangs or times out + +The `install-kernel` target starts the container system and waits for the kernel to install. If it times out: + +1. Stop any running container system first: `bin/container system stop` +2. Wait a few seconds for launchd services to fully stop +3. Run with increased timeout: `bin/container --debug system start --timeout 120` +4. Try `make install-kernel` again + +If the system still won't start, check for stale launchd services: + +```bash +launchctl list | grep com.apple.container +``` + +Remove any leftover services with `scripts/ensure-container-stopped.sh -a`. + +### vmnet network creation fails under Documents or Desktop + +There is a known bug in the `vmnet` framework on macOS 26 that causes network creation to fail if the project or helper binaries are located under `~/Documents` or `~/Desktop`. Move your project elsewhere: + +```bash +mv ~/Documents/container ~/projects/container +``` + +Or use `make install` to place binaries under `/usr/local`, which is not affected. From db7202866a1ef75954060e1e1aa15509525aad55 Mon Sep 17 00:00:00 2001 From: yardencuriel <259054981+splint-disk-8i@users.noreply.github.com> Date: Fri, 13 Mar 2026 18:09:31 +0200 Subject: [PATCH 2/3] chore: add editorconfig for consistent code style --- .editorconfig | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 .editorconfig diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 000000000..cc1690152 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,33 @@ +# EditorConfig helps maintain consistent coding styles across editors +# https://editorconfig.org + +root = true + +[*] +indent_style = space +indent_size = 4 +end_of_line = lf +charset = utf-8 +trim_trailing_whitespace = true +insert_final_newline = true + +[Makefile] +indent_style = tab + +[*.Makefile] +indent_style = tab + +[*.md] +trim_trailing_whitespace = false + +[*.yml] +indent_size = 2 + +[*.yaml] +indent_size = 2 + +[*.json] +indent_size = 2 + +[*.toml] +indent_size = 2 From 962a13d3ebaaa073ad618d693d9d4eadcccbc213 Mon Sep 17 00:00:00 2001 From: yardencuriel <259054981+splint-disk-8i@users.noreply.github.com> Date: Sun, 15 Mar 2026 13:09:55 +0200 Subject: [PATCH 3/3] docs: move troubleshooting to its own file, add issue references --- BUILDING.md | 81 +------------------------------------------- TROUBLESHOOTING.md | 84 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 85 insertions(+), 80 deletions(-) create mode 100644 TROUBLESHOOTING.md diff --git a/BUILDING.md b/BUILDING.md index 8a3e65c5c..19e014de0 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -192,83 +192,4 @@ Run `make pre-commit` to install a pre-commit hook that ensures that your change ## Troubleshooting -### Build fails with missing Xcode or developer tools - -If you see errors about missing compilers or developer tools, make sure the active developer directory is pointed at a full Xcode installation: - -```bash -xcode-select --print-path -``` - -If it points at `/Library/Developer/CommandLineTools` instead of an Xcode app, switch it: - -```bash -sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer -``` - -On macOS 26, use the latest Xcode version: - -```bash -sudo xcode-select --switch /Applications/Xcode-latest.app/Contents/Developer -``` - -### Swift version mismatch - -The project requires Swift 6.1 or later. Verify your version: - -```bash -swift --version -``` - -If you have multiple toolchains installed, Swift Package Manager uses whatever `swift` resolves to in your `$PATH`. Make sure the correct toolchain is first in your path, or set `DEVELOPER_DIR` before building: - -```bash -DEVELOPER_DIR=/Applications/Xcode-latest.app/Contents/Developer make all -``` - -### Permission errors during install - -`make install` creates a `.pkg` and uses `sudo installer` to place binaries under `/usr/local`. If you can't use sudo or prefer a local install: - -```bash -DEST_DIR=~/.local/ SUDO= make install -``` - -Then add `~/.local/bin` to your `$PATH`. - -### Integration tests fail with network errors - -The integration tests create lightweight VMs that need outbound network access. If you're behind a corporate proxy, set the proxy exclusion variables before running tests: - -```bash -export NO_PROXY="${NO_PROXY},192.168.0.0/16,fe80::/10" -export no_proxy="${no_proxy},192.168.0.0/16,fe80::/10" -make test integration -``` - -### Kernel installation hangs or times out - -The `install-kernel` target starts the container system and waits for the kernel to install. If it times out: - -1. Stop any running container system first: `bin/container system stop` -2. Wait a few seconds for launchd services to fully stop -3. Run with increased timeout: `bin/container --debug system start --timeout 120` -4. Try `make install-kernel` again - -If the system still won't start, check for stale launchd services: - -```bash -launchctl list | grep com.apple.container -``` - -Remove any leftover services with `scripts/ensure-container-stopped.sh -a`. - -### vmnet network creation fails under Documents or Desktop - -There is a known bug in the `vmnet` framework on macOS 26 that causes network creation to fail if the project or helper binaries are located under `~/Documents` or `~/Desktop`. Move your project elsewhere: - -```bash -mv ~/Documents/container ~/projects/container -``` - -Or use `make install` to place binaries under `/usr/local`, which is not affected. +If you run into build or runtime issues, check the [troubleshooting guide](TROUBLESHOOTING.md). diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md new file mode 100644 index 000000000..57b684267 --- /dev/null +++ b/TROUBLESHOOTING.md @@ -0,0 +1,84 @@ +# Troubleshooting + +Known issues and workarounds. If your problem isn't listed here, check the [open issues](https://github.com/apple/container/issues) or file a new one. + +## Xcode or developer tools not found + +Build errors about missing compilers usually mean `xcode-select` is pointing at the Command Line Tools instead of a full Xcode installation: + +```bash +xcode-select --print-path +``` + +If this returns `/Library/Developer/CommandLineTools`, switch it to Xcode: + +```bash +sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer +``` + +On macOS 26 you'll want the latest Xcode: + +```bash +sudo xcode-select --switch /Applications/Xcode-latest.app/Contents/Developer +``` + +## Wrong Swift version + +Swift 6.1+ is required. Check with `swift --version`. + +If you have multiple toolchains, SPM picks whatever `swift` is first in `$PATH`. You can also just set `DEVELOPER_DIR` before building: + +```bash +DEVELOPER_DIR=/Applications/Xcode-latest.app/Contents/Developer make all +``` + +## Permission errors during install + +`make install` builds a `.pkg` and runs `sudo installer` to put binaries in `/usr/local`. If you don't have sudo or prefer a different location: + +```bash +DEST_DIR=~/.local/ SUDO= make install +``` + +Don't forget to add `~/.local/bin` to your `$PATH` afterwards. + +See also [#1281](https://github.com/apple/container/issues/1281) for Homebrew-specific permission issues. + +## Network errors in integration tests + +Integration tests spin up VMs that need outbound network access. Corporate proxies can interfere — try excluding the local ranges: + +```bash +export NO_PROXY="${NO_PROXY},192.168.0.0/16,fe80::/10" +export no_proxy="${no_proxy},192.168.0.0/16,fe80::/10" +make test integration +``` + +VPN can also cause issues, see [#1307](https://github.com/apple/container/issues/1307). + +## Kernel install hangs + +The `install-kernel` target starts the container system and waits for the kernel to finish installing. If it times out: + +1. Stop the system: `bin/container system stop` +2. Give launchd a few seconds to clean up +3. Try again with a longer timeout: `bin/container --debug system start --timeout 120` +4. Run `make install-kernel` again + +Still stuck? Check for stale launchd services: + +```bash +launchctl list | grep com.apple.container +``` + +You can clean these up with `scripts/ensure-container-stopped.sh -a`. See [#1280](https://github.com/apple/container/issues/1280) and [#1306](https://github.com/apple/container/issues/1306) for related issues. + +## vmnet fails under ~/Documents or ~/Desktop + +macOS 26 has a bug in the `vmnet` framework — network creation fails if the project or helper binaries sit under `~/Documents` or `~/Desktop`. Move the project somewhere else: + +```bash +mv ~/Documents/container ~/projects/container +``` + +Alternatively, `make install` puts binaries in `/usr/local` which isn't affected.