# Migration from Static Libraries/Static Frameworks to Dynamic Frameworks in Epson ePOS SDK

## Overview
This chapter explains how to migrate from the conventional static libraries and static frameworks in **Epson ePOS SDK for iOS** to the new **dynamic framework (`libepos2.xcframework`)**.

In previous versions, `libepos2.xcframework` was provided as a **static framework**.  
From this version onward, the same `libepos2.xcframework` is provided as a **dynamic framework**,  
and the former static framework has been renamed to **`libepos2-static.xcframework`**.

This change allows static and dynamic frameworks to be clearly separated within the same SDK.

---

## Changes in Provided Formats

| Type | Name | Linkage | Availability | Description |
|------|------|----------|---------------|--------------|
| Dynamic Framework | libepos2.xcframework | Dynamic | Included | Newly provided. Supports the standard iOS dynamic linking mechanism. Recommended format. |
| Static Framework | libepos2-static.xcframework | Static | Included | Inherits the existing static linking structure. For backward compatibility. |
| Static Library | libepos2.a | Static | **Not included** | Legacy format supporting only a single architecture. No longer included in the current SDK. |

---

## Migration Types

| Type | Description |
|------|--------------|
| **1. Migration to Dynamic Framework (Recommended)** | Use the new `libepos2.xcframework` and link it dynamically in your application. |
| **2. Continue Using the Static Framework (Backward Compatibility)** | Continue using `libepos2-static.xcframework` in existing applications if required. |
| **3. Use of the old `.a` library** | Not included in the current SDK. Please migrate to the dynamic framework. |

---

## Migration Procedure

### 1. Remove the Old Framework
Remove the following files from your existing project:

- `libepos2.a` (not included in the current SDK)  
- Old `libepos2.xcframework` (static framework)  
- `ePOS2.h` (use the header included in the new dynamic framework)

> **Note:**  
> The old `libepos2.xcframework` is a static framework.  
> Using it alongside the new dynamic framework may result in linker conflicts.

---

### 2. Add the New Framework
1. Add **`libepos2.xcframework` (dynamic)** included in the Epson SDK package to your project.  
2. In **Build Settings** > **Framework Search Paths**, specify the SDK path.  
   - This setting is used **at build time (link time)** to locate the framework.  
   - Required if the SDK is placed outside the project directory (e.g., shared SDK directory).  
3. In **General** > **Frameworks, Libraries, and Embedded Content**, set it to **Embed & Sign**.  
   - This setting is used **at runtime** to load the framework inside the app bundle.  
   - When embedding is configured, Xcode automatically sets the **runtime path (Runpath Search Paths)**.

> 💡 **Note:**  
> - `Framework Search Paths` are used only at link time.  
> - At runtime, **`LD_RUNPATH_SEARCH_PATHS` (Runpath Search Paths)** are used.  
> - These are separate settings.

---

### 3. Change Import Definitions
Previous code:
```objective-c
#import "ePOS2.h"
```

New code (for dynamic framework):
```objective-c
#import "libepos2/ePOS2.h"
```

---

## Code Example

### Previous Configuration (Static Framework / Static Library)
```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];
```

### New Configuration (Dynamic Framework)
```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];
```

---

## Continuing to Use the Static Framework (libepos2-static.xcframework)

If it is necessary to maintain the existing static linking structure, you can continue to use **`libepos2-static.xcframework`**.

### Setup Steps
1. Add `libepos2-static.xcframework` to the project.  
2. In **Build Settings**, specify the SDK path in **Framework Search Paths**.  
3. Embedding is unnecessary because static linking does not require runtime loading.

### Limitations
- The static framework is planned to enter maintenance mode in future releases.

---

## Notes

- **The settings used at link time and runtime are different.**  
  - `Framework Search Paths` are used at link time.  
  - `LD_RUNPATH_SEARCH_PATHS` (Runpath Search Paths) are used at runtime.  
  - Be careful not to confuse these settings.  
- Do **not** link both `libepos2.xcframework` (dynamic) and `libepos2-static.xcframework` (static) simultaneously.  

---

## Troubleshooting

| Issue | Cause | Solution |
|--------|--------|-----------|
| “framework not found libepos2” | Framework Search Paths not configured | Add the SDK path. |
| Undefined symbols for architecture arm64 | Old static libraries remain | Remove old link settings. |
| “dyld: Library not loaded” | Missing Embed setting or incorrect Runpath configuration | Verify **Embed & Sign**. |
