Launch a service with waitForDebugger if specified (#1101)

This PR enables launching a service with `waitForDebugger` flag if the
service label matches a given env variable `CONTAINER_DEBUG`.

Author: JaewonHur

BUILDING.md

@@ -119,6 +119,42 @@ To revert to using the Containerization dependency from your `Package.swift`:
     bin/container system start
     ```
 
+## Debug XPC Helpers
+
+Attach debugger to the XPC helpers using their launchd service labels:
+
+1. Find launchd service labels:
+
+   ```console
+   % container system start
+   % container run -d --name test debian:bookworm sleep infinity
+   test
+   % launchd list | grep container
+   27068   0       com.apple.container.container-network-vmnet.default
+   27072   0       com.apple.container.container-core-images
+   26980   0       com.apple.container.apiserver
+   27331   0       com.apple.container.container-runtime-linux.test
+   ```
+
+2. Stop container and start again after setting the environment variable `CONTAINER_DEBUG_LAUNCHD_LABEL` to the label of service to attach debugger. Services whose label starts with the `CONTAINER_DEBUG_LAUNCHD_LABEL` will wait the debugger:
+
+    ```console
+    % export CONTAINER_DEBUG_LAUNCHD_LABEL=com.apple.container.container-runtime-linux.test
+    % container system start # Only the service `com.apple.container.container-runtime-linux.test` waits debugger
+    ```
+
+    ```console
+    % export CONTAINER_DEBUG_LAUNCHD_LABEL=com.apple.container.container-runtime-linux
+    % container system start # Every service starting with `com.apple.container.container-runtime-linux` waits debugger
+    ```
+
+3. Run the command to launch the service, and attach debugger:
+
+    ```console
+    % container run -it --name test debian:bookworm
+    ⠧ [6/6] Starting container [0s] # It hangs as the service is waiting for debugger
+    ```
+
 ## 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`.

Sources/ContainerPlugin/LaunchPlist.swift

@@ -18,6 +18,8 @@
 import Foundation
 
 public struct LaunchPlist: Encodable {
+    static let debugTarget = "CONTAINER_DEBUG_LAUNCHD_LABEL"
+
     public enum Domain: String, Codable {
         case Aqua
         case Background
@@ -61,6 +63,21 @@ public struct LaunchPlist: Encodable {
         case waitForDebugger = "WaitForDebugger"
     }
 
+    static private func getWaitForDebugger(label: String, fromArg: Bool?) -> Bool? {
+        if let fromArg {
+            return fromArg
+        }
+
+        let env = ProcessInfo.processInfo.environment
+        if let debugTarget = env[Self.debugTarget],
+            label == debugTarget || label.starts(with: debugTarget + ".")
+        {
+            return true
+        }
+
+        return nil
+    }
+
     public init(
         label: String,
         arguments: [String],
@@ -93,7 +110,7 @@ public struct LaunchPlist: Encodable {
         self.disabled = disabled
         self.program = program
         self.keepAlive = keepAlive
-        self.waitForDebugger = waitForDebugger
+        self.waitForDebugger = Self.getWaitForDebugger(label: label, fromArg: waitForDebugger)
         if let services = machServices {
             var machServices: [String: Bool] = [:]
             for service in services {