# Epson ePOS SDK における静的ライブラリ／静的フレームワークから動的フレームワークへのマイグレーション


## 概要
本章では、Epson ePOS SDK for iOS において、従来の静的ライブラリおよび静的フレームワークから、新しい **動的フレームワーク（libepos2.xcframework）** へ移行する方法を説明します。

従来のバージョンでは、libepos2.xcframework が **静的リンク用フレームワーク** として提供されていました。
今回のバージョンより、**同名の libepos2.xcframework が動的フレームワークとして提供**され、
旧静的フレームワークは新名称 **libepos2-static.xcframework** に変更されます。

これにより、同一SDK内で静的／動的フレームワークを明確に区別して利用できるようになります。

---

## 提供形態の変更点

| 提供形式 | 名称 | 種類 | 提供状況 | 説明 |
|-----------|------|------|----------|------|
| 動的フレームワーク | libepos2.xcframework | 動的 | 同梱 | 新規提供。iOS標準の動的リンク方式に対応。推奨形式。 |
| 静的フレームワーク | libepos2-static.xcframework | 静的 | 同梱 | 従来の静的リンク構成を継承。後方互換用。 |
| 静的ライブラリ | libepos2.a | 静的 | **非同梱** | 旧来の単一アーキテクチャ向け形式。現行SDKでは提供していません。 |

---

## マイグレーションの種類

| 種類 | 概要 |
|------|------|
| **1. 動的フレームワークへの移行（推奨）** | 新しい `libepos2.xcframework` を使用し、動的リンクでアプリケーションに組み込みます。 |
| **2. 静的フレームワークの継続利用（後方互換）** | 既存アプリケーションで `libepos2-static.xcframework` を使用し続けることができます。 |
| **3. 旧 `.a` ライブラリの利用** | 現行SDKには同梱されていません。動的フレームワークへの移行をお願いします。|

---

## マイグレーション手順

### 1. 旧フレームワークの削除
既存プロジェクトから以下のファイルを削除します。

- libepos2.a（※現行SDKでは非同梱）
- 旧 libepos2.xcframework（静的フレームワーク）
- ePOS2.h（※追加する動的フレームワーク内のヘッダを利用してください）

> **注意:**  
> 旧 libepos2.xcframework は静的フレームワークです。  
> 新バージョンで同名の動的フレームワークと混在させるとリンカ競合が発生します。

---

### 2. 新フレームワークの追加
1. Epson SDK パッケージに含まれる **libepos2.xcframework（動的）** をプロジェクトに追加します。  
2. 「Build Settings」>「Framework Search Paths」に SDK のパスを指定します。  
   - これは **ビルド時（リンク時）にフレームワークを探索するための設定**です。  
   - プロジェクト外（例：共通SDKディレクトリ）に配置している場合は必須です。  
3. 「General」>「Frameworks, Libraries, and Embedded Content」で **Embed & Sign** を選択します。
   - これは **実行時にアプリ内でフレームワークをロードするための設定**です。  
   - Embed 設定を行うと、Xcodeが自動的に **実行時パス（Runpath Search Paths）** を設定します。

> 💡 **補足:**  
> - `Framework Search Paths` はリンク時にのみ参照されます。  
> - 実行時には **`LD_RUNPATH_SEARCH_PATHS`（Runpath Search Paths）** が使用されます。  
> - 両者は異なる設定項目です。

---

### 3. インポート定義の変更
旧記述：
```objective-c
#import "ePOS2.h"
```

新記述（動的フレームワーク）：
```objective-c
#import "libepos2/ePOS2.h"
```

---

## コード修正例

### 旧構成（静的フレームワーク・静的ライブラリ）
```objective-c
#import "ePOS2.h"
Epos2Printer *printer = [[Epos2Printer alloc] initWithPrinterSeries:EPOS2_TM_T88 lang:EPOS2_MODEL_ANK];
[printer connect:@"TCP:192.168.192.168" timeout:EPOS2_PARAM_DEFAULT];
```

### 新構成（動的フレームワーク）
```objective-c
#import "libepos2/ePOS2.h"
Epos2Printer *printer = [[Epos2Printer alloc] initWithPrinterSeries:EPOS2_TM_T88 lang:EPOS2_MODEL_ANK];
[printer connect:@"TCP:192.168.192.168" timeout:EPOS2_PARAM_DEFAULT];
```

---

## 静的フレームワーク（libepos2-static.xcframework）を使い続ける場合

従来の静的リンク構成を維持する必要がある場合は、**libepos2-static.xcframework** を利用できます。

### 設定手順
1. プロジェクトに libepos2-static.xcframework を追加。  
2. 「Build Settings」で「Framework Search Paths」にSDKパスを指定します。  
3. Embed 設定は不要です（静的リンクのため）。

### 制約事項
- 将来的にはメンテナンスモードとなる予定です。

---

## 注意事項

- **リンク時と実行時では参照される設定が異なります。**  
  - `Framework Search Paths` はリンク時に使用されます。  
  - `LD_RUNPATH_SEARCH_PATHS`（Runpath Search Paths）は実行時に使用されます。  
  - 両者を混同しないようにしてください。  
- libepos2.xcframework（動的）と libepos2-static.xcframework（静的）を**同時にリンクしないでください。**  

---

## トラブルシューティング

| 問題 | 原因 | 対処 |
|------|------|------|
| “framework not found libepos2” | Framework Search Paths未設定 | SDKパスを追加 |
| Undefined symbols for architecture arm64 | 旧静的ライブラリが残存 | 古いリンク設定を削除 |
| “dyld: Library not loaded” | Embed設定不足またはRunpath設定ミス | Embed & Signを確認 |

