Merge pull request #28 from pqrs-org/service-management

Stop using the legacy /Library/LaunchDaemons

DEVELOPMENT.md

@@ -217,15 +217,3 @@ Implement the actual processing by the following steps.
     ```
 
     The `ExternalMethod` will be called.
-
-### Prepare provision profile
-
-You have to be granted the permission of `com.apple.developer.driverkit.userclient-access` from Apple.
-(e.g. `src/Client/entitlements.plist`)
-
-You have to add a description you want to use `userclient-access` at the DriverKit Entitlement request to Apple.
-<https://developer.apple.com/contact/request/system-extension/>
-
-You can confirm the entitlements on Apple developer portal after you gained the permission.
-
-<img src="docs/images/[email protected]" width="900" alt="Apple developer portal" /><br /><br />

README.md

@@ -11,10 +11,6 @@ Virtual devices (keyboard and mouse) implementation for macOS using DriverKit.
     -   Both Intel-based Macs and Apple Silicon Macs
 -   macOS 13 Ventura
     -   Both Intel-based Macs and Apple Silicon Macs
--   macOS 12 Monterey
-    -   Both Intel-based Macs and Apple Silicon Macs
--   macOS 11 Big Sur
-    -   Both Intel-based Macs and Apple Silicon Macs
 
 ## Status
 
@@ -46,7 +42,13 @@ Virtual devices (keyboard and mouse) implementation for macOS using DriverKit.
     /Applications/.Karabiner-VirtualHIDDevice-Manager.app/Contents/MacOS/Karabiner-VirtualHIDDevice-Manager activate
     ```
 
-4.  Run a client program to test the driver extension.
+4.  Run Karabiner-VirtualHIDDevice-Daemon:
+
+    ```shell
+    sudo '/Library/Application Support/org.pqrs/Karabiner-DriverKit-VirtualHIDDevice/Applications/Karabiner-VirtualHIDDevice-Daemon.app/Contents/MacOS/Karabiner-VirtualHIDDevice-Daemon'
+    ```
+
+5.  Run a client program to test the driver extension.
 
     ```shell
     git clone --depth 1 https://github.com/pqrs-org/Karabiner-DriverKit-VirtualHIDDevice.git
@@ -69,7 +71,6 @@ Virtual devices (keyboard and mouse) implementation for macOS using DriverKit.
 
 -   `/Applications/.Karabiner-VirtualHIDDevice-Manager.app`
 -   `/Library/Application Support/org.pqrs/Karabiner-DriverKit-VirtualHIDDevice`
--   `/Library/LaunchDaemons/org.pqrs.Karabiner-DriverKit-VirtualHIDDeviceClient.plist`
 -   `/Library/Application Support/org.pqrs/tmp`
 -   `/var/log/karabiner`
 
@@ -81,9 +82,8 @@ Virtual devices (keyboard and mouse) implementation for macOS using DriverKit.
 
 System requirements to build Karabiner-Elements:
 
--   macOS 11+
--   Xcode 13.0 (You need to hold Xcode version to 13.0 because Xcode 13.1 generate binary which does not work on macOS 11 Big Sur.)
-    -   Note: The recent macOS cannot open the Xcode 13.0 UI, but it can be operated from the command line. Since only command line operations are necessary for building, there is no problem.
+-   macOS 14+
+-   Xcode 15+
 -   Command Line Tools for Xcode
 -   [XcodeGen](https://github.com/yonaskolb/XcodeGen)
 
@@ -96,56 +96,91 @@ System requirements to build Karabiner-Elements:
 
 2.  Create App IDs on [the Apple Developer site](https://developer.apple.com/account/resources/identifiers/list).
 
-<table>
-    <thead>
-        <tr>
-            <th>Bundle ID</th>
-            <th>Capabilities</th>
-            <th>App Services</th>
-            <th>Additional Capabilities</th>
-        </tr>
-    </thead>
-    <tbody>
-        <tr>
-            <td>org.pqrs.Karabiner-DriverKit-VirtualHIDDevice</td>
-            <td>---</td>
-            <td>---</td>
-            <td>
-                com.apple.developer.driverkit<br/>
-                com.apple.developer.driverkit.family.hid.device<br/>
-                com.apple.developer.driverkit.family.hid.eventservice<br/>
-                com.apple.developer.driverkit.transport.hid<br/>
-                com.apple.developer.hid.virtual.device<br/>
-            </td>
-        </tr>
-        <tr>
-            <td>org.pqrs.Karabiner-DriverKit-VirtualHIDDeviceClient</td>
-            <td>---</td>
-            <td>---</td>
-            <td>---</td>
-        </tr>
-        <tr>
-            <td>org.pqrs.Karabiner-VirtualHIDDevice-Manager</td>
-            <td>
-                System Extension<br/>
-            </td>
-            <td>---</td>
-            <td>---</td>
-        </tr>
-    </tbody>
-</table>
-
-<img src="docs/images/[email protected]" width="921" alt="Additional Capabilities" />
-
-3.  Create a profile corresponding to the App IDs on the Apple Developer site.
-
-4.  Replace the `*.provisionprofile` files in the repository with your own provision profile files.
-
-    -   src/Client/Developer_ID_VirtualHIDDeviceClient.provisionprofile
+    <table>
+        <thead>
+            <tr>
+                <th>Bundle ID</th>
+                <th>Capabilities</th>
+                <th>App Services</th>
+                <th>Additional Capabilities</th>
+            </tr>
+        </thead>
+        <tbody>
+            <tr>
+                <td>org.pqrs.Karabiner-DriverKit-VirtualHIDDevice</td>
+                <td>---</td>
+                <td>---</td>
+                <td>
+                    com.apple.developer.driverkit<br/>
+                    com.apple.developer.driverkit.family.hid.device<br/>
+                    com.apple.developer.driverkit.family.hid.eventservice<br/>
+                    com.apple.developer.driverkit.transport.hid<br/>
+                    com.apple.developer.hid.virtual.device<br/>
+                </td>
+            </tr>
+            <tr>
+                <td>org.pqrs.Karabiner-VirtualHIDDevice-Daemon</td>
+                <td>---</td>
+                <td>---</td>
+                <td>---</td>
+            </tr>
+            <tr>
+                <td>org.pqrs.Karabiner-VirtualHIDDevice-Manager</td>
+                <td>
+                    System Extension<br/>
+                </td>
+                <td>---</td>
+                <td>---</td>
+            </tr>
+        </tbody>
+    </table>
+
+    <img src="docs/images/[email protected]" width="921" alt="Additional Capabilities" />
+
+3.  Grant permission for com.apple.developer.driverkit.userclient-access from Apple
+
+    The entitlement of `com.apple.developer.driverkit.userclient-access` must be applied for from Apple, and unless individually authorized, it cannot be granted to your application.
+    You can apply through the request form: <https://developer.apple.com/contact/request/system-extension/>
+
+4.  Create a profile corresponding to the App IDs on the Apple Developer site.
+
+    <table>
+        <thead>
+            <tr>
+                <th>Profile</th>
+                <th>App ID</th>
+                <th>Entitlements</th>
+            </tr>
+        </thead>
+        <tbody>
+            <tr>
+                <td>Developer ID</td>
+                <td>org.pqrs.Karabiner-DriverKit-VirtualHIDDevice</td>
+                <td>DriverKit and System Extension Template for XXXXXXXX (Developer ID)</td>
+            </tr>
+            <tr>
+                <td>Developer ID</td>
+                <td>org.pqrs.Karabiner-VirtualHIDDevice-Daemon</td>
+                <td>DriverKit and System Extension Template for XXXXXXXX (Developer ID)</td>
+            </tr>
+            <tr>
+                <td>Developer ID</td>
+                <td>org.pqrs.Karabiner-VirtualHIDDevice-Manager</td>
+                <td>Default</td>
+            </tr>
+        </tbody>
+    </table>
+
+    Please ensure that `com.apple.developer.driverkit.userclient-access` appears under Extended Entitlements when you select `DriverKit and System Extension Template` in Entitlements.
+    <img src="docs/images/[email protected]" width="900" alt="entitlements" /><br /><br />
+
+5.  Replace the `*.provisionprofile` files in the repository with your own provision profile files.
+
+    -   src/Daemon/Developer_ID_KarabinerVirtualHIDDeviceDaemon.provisionprofile
     -   src/DriverKit/Developer_ID_KarabinerDriverKitVirtualHIDDevice.provisionprofile
     -   src/Manager/Developer_ID_Karabiner_VirtualHIDDevice_Manager.provisionprofile
 
-5.  Replace `CODE_SIGN_IDENTITY` at `src/scripts/codesign.sh` with yours.
+6.  Replace `CODE_SIGN_IDENTITY` at `src/scripts/codesign.sh` with yours.
 
     Find your codesign identity by executing the following command in Terminal.
 
@@ -170,23 +205,23 @@ System requirements to build Karabiner-Elements:
     readonly CODE_SIGN_IDENTITY=8D660191481C98F5C56630847A6C39D95C166F22
     ```
 
-6.  Replace team identifier, domain and embedded.provisionprofile.
+7.  Replace team identifier, domain and embedded.provisionprofile.
 
     -   Search `G43BCU2T37` and replace them with your team identifier.
 
         ```shell
         git grep G43BCU2T37 src/
         ```
 
-7.  Build by the following command in terminal.
+8.  Build by the following command in terminal.
 
     ```shell
     make package
     ```
 
     `dist/Karabiner-DriverKit-VirtualHIDDevice-X.X.X.pkg` will be generated.
 
-8.  Notarize the pkg.
+9.  Notarize the pkg.
 
     ```shell
     make notarize
@@ -199,20 +234,20 @@ Karabiner-DriverKit-VirtualHIDDevice consists the following components.
 -   Extension Manager (including DriverKit driver)
     -   `/Applications/.Karabiner-VirtualHIDDevice-Manager.app`
     -   It provides a command line interface to activate or deactivate DriverKit driver.
--   VirtualHIDDeviceClient
-    -   `/Library/Application Support/org.pqrs/Karabiner-DriverKit-VirtualHIDDevice/Applications/Karabiner-DriverKit-VirtualHIDDeviceClient.app`
+-   Karabiner-VirtualHIDDevice-Daemon
+    -   `/Library/Application Support/org.pqrs/Karabiner-DriverKit-VirtualHIDDevice/Applications/Karabiner-VirtualHIDDevice-Daemon.app`
     -   It mediates between the client app and the driver.
     -   It allows apps to communicate with the virtual device even if the app is not signed with pqrs.org's code signing identity.
         (The client app must be running with root privileges.)
 -   Client apps
     -   Client apps are not included in the distributed package.
     -   For example, you can build the client app from `examples/virtual-hid-device-service-client` in this repository.
-    -   Client apps can send input events by communicating with VirtualHIDDeviceClient via UNIX domain socket.
+    -   Client apps can send input events by communicating with Karabiner-VirtualHIDDevice-Daemon via UNIX domain socket.
         (`/Library/Application Support/org.pqrs/tmp/rootonly/vhidd_server/*.sock`)
 
 ![components.svg](./docs/plantuml/output/components.svg)
 
-### Version files
+### Versions
 
 Version is defined in `version.json`.
 
@@ -223,5 +258,10 @@ Version is defined in `version.json`.
     -   DriverKit driver internal version.
     -   Increment this when the driver source code is updated.
 -   `client_protocol_version`:
-    -   The version for communication between VirtualHIDDeviceClient and the DriverKit driver.
+    -   The version for communication between Karabiner-VirtualHIDDevice-Daemon and the DriverKit driver.
     -   Increment this when the communication specifications are changed.
+
+### Run Karabiner-VirtualHIDDevice-Daemon via launchd
+
+Karabiner-VirtualHIDDevice-Daemon requires high responsiveness, so it is recommended to run it via launchd with the `ProcessType: Interactive` specified.
+There is an example application for registration with launchd in `examples/SMAppServiceExample`, which you can refer to for registering with launchd.