@mcesystems/apple-kit 1.0.32 → 1.0.33

package/scripts/README.md

@@ -1,209 +1,209 @@
-# Export Apple Resources Script
-
-This script exports libimobiledevice binaries and their dependencies to a specified target directory. The exported resources can be used by applications that depend on `@mcesystems/apple-kit`.
-
-## Usage
-
-After installing `@mcesystems/apple-kit`:
-
-```bash
-# Using the binary (recommended)
-npx export-apple-resources <target-path>
-
-# Or run the script directly with tsx
-npx tsx node_modules/@mcesystems/apple-kit/scripts/export-resources.ts <target-path>
-```
-
-### Examples
-
-```bash
-# Export to a relative path
-npx tsx export-resources.ts ./my-app/resources/apple-kit
-
-# Export to an absolute path
-npx tsx export-resources.ts /Users/me/projects/my-app/resources
-```
-
-### Output Structure
-
-The script creates the following directory structure:
-
-```
-<target-path>/
-├── bin/
-│   ├── darwin/          # macOS binaries and dylibs
-│   │   ├── idevice_id
-│   │   ├── ideviceinfo
-│   │   ├── iproxy
-│   │   ├── libimobiledevice-1.0.6.dylib
-│   │   └── ... (other tools and dylibs)
-│   └── windows/         # Windows binaries and DLLs
-│       ├── idevice_id.exe
-│       ├── ideviceinfo.exe
-│       ├── iproxy.exe
-│       ├── libimobiledevice-1.0-6.dll
-│       └── ... (other tools and DLLs)
-├── licenses/
-│   └── LGPL-2.1.txt
-└── build-windows.sh     # Windows build script (generated on non-Windows)
-```
-
----
-
-## Platform-Specific Prerequisites
-
-### macOS
-
-#### Prerequisites
-
-1. **Homebrew** installed ([https://brew.sh](https://brew.sh))
-
-2. **libimobiledevice tools** installed via Homebrew:
-   ```bash
-   brew install libimobiledevice ideviceinstaller
-   ```
-
-3. **Node.js 18+** with `tsx` available:
-   ```bash
-   npm install -g tsx
-   # or use npx
-   ```
-
-#### How It Works
-
-On macOS, the script:
-1. Locates Homebrew installation (`/opt/homebrew` for Apple Silicon, `/usr/local` for Intel)
-2. Copies required binaries (`idevice_id`, `ideviceinfo`, `iproxy`, etc.)
-3. Recursively collects all dylib dependencies
-4. Fixes dylib paths using `install_name_tool` to use `@loader_path` (makes binaries portable)
-
-#### Running
-
-```bash
-cd scripts/export-apple-resources
-npx tsx export-resources.ts /path/to/output
-```
-
----
-
-### Windows
-
-#### Prerequisites
-
-1. **MSYS2** installed from [https://www.msys2.org](https://www.msys2.org)
-   - Download and run the installer
-   - Default installation path: `C:\msys64`
-
-2. **Required MSYS2 packages** - Open **MSYS2 MinGW 64-bit** shell and run:
-   ```bash
-   pacman -S base-devel \
-       git \
-       mingw-w64-x86_64-gcc \
-       make \
-       libtool \
-       autoconf \
-       automake-wrapper
-   ```
-
-3. **Apple Mobile Device Support** (for USB communication)
-   - Either install iTunes from [https://www.apple.com/itunes/](https://www.apple.com/itunes/)
-   - Or install just "Apple Mobile Device Support" from the iTunes installer
-
-#### How It Works
-
-On Windows, building libimobiledevice from source is required. The script:
-1. Generates a `build-windows.sh` script in the target directory
-2. The build script downloads the official libimobiledevice build script
-3. Compiles all required libraries and tools from source
-4. Copies the resulting binaries and DLLs to the target directory
-
-#### Running
-
-**Step 1:** Generate the build script (can be done on any platform):
-```bash
-cd scripts/export-apple-resources
-npx tsx export-resources.ts /path/to/output
-```
-
-**Step 2:** Open **MSYS2 MinGW 64-bit** shell (NOT regular MSYS2 shell!)
-- Find it in Start Menu: "MSYS2 MinGW 64-bit"
-
-**Step 3:** Run the build script:
-```bash
-cd /path/to/output
-bash build-windows.sh
-```
-
-> **Note:** The build process may take 10-30 minutes depending on your system.
-
-#### Troubleshooting Windows Build
-
-| Issue | Solution |
-|-------|----------|
-| "gcc not found" | Install packages: `pacman -S mingw-w64-x86_64-gcc` |
-| "This script must be run from MSYS2 MinGW 64-bit shell" | Open the correct shell from Start Menu |
-| Build fails with SSL errors | `pacman -S mingw-w64-x86_64-openssl` |
-| Device not detected | Ensure iTunes or Apple Mobile Device Support is installed |
-
----
-
-## Tools Included
-
-### Required Tools (must be present)
-| Tool | Description |
-|------|-------------|
-| `idevice_id` | List connected iOS devices |
-| `ideviceinfo` | Get device information |
-| `idevicepair` | Manage device pairing/trust |
-| `idevicename` | Get/set device name |
-| `idevicedebug` | Debug applications |
-| `ideviceinstaller` | Install/uninstall apps |
-| `iproxy` | Port forwarding |
-
-### Optional Tools (copied if available)
-| Tool | Description |
-|------|-------------|
-| `ideviceactivation` | Device activation |
-| `idevicesyslog` | View device system log |
-| `idevicescreenshot` | Take screenshots |
-| `idevicediagnostics` | Device diagnostics |
-
----
-
-## Integrating with Your Application
-
-After exporting resources, configure `apple-kit` to use them:
-
-### Option 1: Environment Variable
-
-Set `IDeviceBinPath` to point to the bin directory:
-
-```bash
-# macOS
-export IDeviceBinPath=/path/to/resources/bin/darwin
-
-# Windows (PowerShell)
-$env:IDeviceBinPath = "C:\path\to\resources\bin\windows"
-```
-
-### Option 2: Bundle with Your App
-
-Copy the exported resources into your application's resources folder. The `apple-kit` package will automatically detect binaries in:
-- `<your-app>/resources/bin/darwin/` (macOS)
-- `<your-app>/resources/bin/windows/` (Windows)
-
----
-
-## License
-
-The libimobiledevice tools are licensed under **LGPL-2.1**. When distributing these binaries, you must:
-1. Include the LGPL-2.1 license (automatically included in `licenses/` folder)
-2. Provide access to the source code (links included in the license file)
-
-Source code repositories:
-- https://github.com/libimobiledevice/libimobiledevice
-- https://github.com/libimobiledevice/libusbmuxd
-- https://github.com/libimobiledevice/libplist
-- https://github.com/libimobiledevice/libimobiledevice-glue
-- https://github.com/libimobiledevice/ideviceinstaller
-
+# Export Apple Resources Script
+
+This script exports libimobiledevice binaries and their dependencies to a specified target directory. The exported resources can be used by applications that depend on `@mcesystems/apple-kit`.
+
+## Usage
+
+After installing `@mcesystems/apple-kit`:
+
+```bash
+# Using the binary (recommended)
+npx export-apple-resources <target-path>
+
+# Or run the script directly with tsx
+npx tsx node_modules/@mcesystems/apple-kit/scripts/export-resources.ts <target-path>
+```
+
+### Examples
+
+```bash
+# Export to a relative path
+npx tsx export-resources.ts ./my-app/resources/apple-kit
+
+# Export to an absolute path
+npx tsx export-resources.ts /Users/me/projects/my-app/resources
+```
+
+### Output Structure
+
+The script creates the following directory structure:
+
+```
+<target-path>/
+├── bin/
+│   ├── darwin/          # macOS binaries and dylibs
+│   │   ├── idevice_id
+│   │   ├── ideviceinfo
+│   │   ├── iproxy
+│   │   ├── libimobiledevice-1.0.6.dylib
+│   │   └── ... (other tools and dylibs)
+│   └── windows/         # Windows binaries and DLLs
+│       ├── idevice_id.exe
+│       ├── ideviceinfo.exe
+│       ├── iproxy.exe
+│       ├── libimobiledevice-1.0-6.dll
+│       └── ... (other tools and DLLs)
+├── licenses/
+│   └── LGPL-2.1.txt
+└── build-windows.sh     # Windows build script (generated on non-Windows)
+```
+
+---
+
+## Platform-Specific Prerequisites
+
+### macOS
+
+#### Prerequisites
+
+1. **Homebrew** installed ([https://brew.sh](https://brew.sh))
+
+2. **libimobiledevice tools** installed via Homebrew:
+   ```bash
+   brew install libimobiledevice ideviceinstaller
+   ```
+
+3. **Node.js 18+** with `tsx` available:
+   ```bash
+   npm install -g tsx
+   # or use npx
+   ```
+
+#### How It Works
+
+On macOS, the script:
+1. Locates Homebrew installation (`/opt/homebrew` for Apple Silicon, `/usr/local` for Intel)
+2. Copies required binaries (`idevice_id`, `ideviceinfo`, `iproxy`, etc.)
+3. Recursively collects all dylib dependencies
+4. Fixes dylib paths using `install_name_tool` to use `@loader_path` (makes binaries portable)
+
+#### Running
+
+```bash
+cd scripts/export-apple-resources
+npx tsx export-resources.ts /path/to/output
+```
+
+---
+
+### Windows
+
+#### Prerequisites
+
+1. **MSYS2** installed from [https://www.msys2.org](https://www.msys2.org)
+   - Download and run the installer
+   - Default installation path: `C:\msys64`
+
+2. **Required MSYS2 packages** - Open **MSYS2 MinGW 64-bit** shell and run:
+   ```bash
+   pacman -S base-devel \
+       git \
+       mingw-w64-x86_64-gcc \
+       make \
+       libtool \
+       autoconf \
+       automake-wrapper
+   ```
+
+3. **Apple Mobile Device Support** (for USB communication)
+   - Either install iTunes from [https://www.apple.com/itunes/](https://www.apple.com/itunes/)
+   - Or install just "Apple Mobile Device Support" from the iTunes installer
+
+#### How It Works
+
+On Windows, building libimobiledevice from source is required. The script:
+1. Generates a `build-windows.sh` script in the target directory
+2. The build script downloads the official libimobiledevice build script
+3. Compiles all required libraries and tools from source
+4. Copies the resulting binaries and DLLs to the target directory
+
+#### Running
+
+**Step 1:** Generate the build script (can be done on any platform):
+```bash
+cd scripts/export-apple-resources
+npx tsx export-resources.ts /path/to/output
+```
+
+**Step 2:** Open **MSYS2 MinGW 64-bit** shell (NOT regular MSYS2 shell!)
+- Find it in Start Menu: "MSYS2 MinGW 64-bit"
+
+**Step 3:** Run the build script:
+```bash
+cd /path/to/output
+bash build-windows.sh
+```
+
+> **Note:** The build process may take 10-30 minutes depending on your system.
+
+#### Troubleshooting Windows Build
+
+| Issue | Solution |
+|-------|----------|
+| "gcc not found" | Install packages: `pacman -S mingw-w64-x86_64-gcc` |
+| "This script must be run from MSYS2 MinGW 64-bit shell" | Open the correct shell from Start Menu |
+| Build fails with SSL errors | `pacman -S mingw-w64-x86_64-openssl` |
+| Device not detected | Ensure iTunes or Apple Mobile Device Support is installed |
+
+---
+
+## Tools Included
+
+### Required Tools (must be present)
+| Tool | Description |
+|------|-------------|
+| `idevice_id` | List connected iOS devices |
+| `ideviceinfo` | Get device information |
+| `idevicepair` | Manage device pairing/trust |
+| `idevicename` | Get/set device name |
+| `idevicedebug` | Debug applications |
+| `ideviceinstaller` | Install/uninstall apps |
+| `iproxy` | Port forwarding |
+
+### Optional Tools (copied if available)
+| Tool | Description |
+|------|-------------|
+| `ideviceactivation` | Device activation |
+| `idevicesyslog` | View device system log |
+| `idevicescreenshot` | Take screenshots |
+| `idevicediagnostics` | Device diagnostics |
+
+---
+
+## Integrating with Your Application
+
+After exporting resources, configure `apple-kit` to use them:
+
+### Option 1: Environment Variable
+
+Set `IDeviceBinPath` to point to the bin directory:
+
+```bash
+# macOS
+export IDeviceBinPath=/path/to/resources/bin/darwin
+
+# Windows (PowerShell)
+$env:IDeviceBinPath = "C:\path\to\resources\bin\windows"
+```
+
+### Option 2: Bundle with Your App
+
+Copy the exported resources into your application's resources folder. The `apple-kit` package will automatically detect binaries in:
+- `<your-app>/resources/bin/darwin/` (macOS)
+- `<your-app>/resources/bin/windows/` (Windows)
+
+---
+
+## License
+
+The libimobiledevice tools are licensed under **LGPL-2.1**. When distributing these binaries, you must:
+1. Include the LGPL-2.1 license (automatically included in `licenses/` folder)
+2. Provide access to the source code (links included in the license file)
+
+Source code repositories:
+- https://github.com/libimobiledevice/libimobiledevice
+- https://github.com/libimobiledevice/libusbmuxd
+- https://github.com/libimobiledevice/libplist
+- https://github.com/libimobiledevice/libimobiledevice-glue
+- https://github.com/libimobiledevice/ideviceinstaller
+