# 런타임 라이브러리 설치

이 섹션에서는 모빌린트 NPU에서 추론을 수행하기 위해 필요한 런타임 라이브러리 (`qb Runtime`) 설치 방법을 설명합니다.

```{attention}
- ARIES 기기의 경우, 런타임 설치 전에 드라이버 설치를 완료해야 합니다. ARIES 매뉴얼의 {external+aries:doc}`드라이버 설치 <driver-installation>` 문서를 확인해주세요. REGULUS는 드라이버와 런타임이 사전 설치되어 제공됩니다.
- 호환되는 드라이버 및 펌웨어 버전은 ARIES {external+aries:doc}`호환성 문서 <compatibility>`에서, 런타임–MXQ 호환성은 [호환성 정보 확인](compatibility.md)에서 확인해주세요.
```

## 목차

- Linux

    - [방법 1: APT를 통한 설치](#apt)

    - [방법 2: DNF를 통한 설치](#dnf)

    - [방법 3: 다운로드 센터를 통한 수동 설치](#manual-download-install)

        - [방법 3-1: 시스템 전역 설치](#system-wide-install)

        - [방법 3-2: 설치 없이 사용](#without-installation)
    
- Windows

    - [인스톨러를 통한 설치](#windows-install)

    - [삭제](#windows-uninstall)

- Windows, Linux 공용

    - [pip를 통한 파이썬 라이브러리 설치](#pip)

## Linux

(apt)=
### 방법 1: APT를 통한 설치

이 절에서 다루는 설치 방법은 데비안 기반 OS들의 패키지 관리자 `apt`를 활용한 설치방법입니다.

#### 설치 절차

1. 아래 명령을 수행하여 모빌린트 APT 저장소를 시스템에 추가합니다.

    ```{tip}
    드라이버 설치 과정에서 이미 모빌린트 APT 저장소를 추가했다면, 이 과정는 건너뛰어도 됩니다.
    ```

    ```bash
    # Add Mobilint's official GPG key:
    sudo apt update
    sudo apt install ca-certificates curl
    sudo install -m 0755 -d /etc/apt/keyrings
    sudo curl -fsSL https://dl.mobilint.com/apt/gpg.pub -o /etc/apt/keyrings/mblt.asc
    sudo chmod a+r /etc/apt/keyrings/mblt.asc

    # Add the repository to apt sources:
    printf "%s\n" \
        "deb [signed-by=/etc/apt/keyrings/mblt.asc] https://dl.mobilint.com/apt \
        stable multiverse" | \
        sudo tee /etc/apt/sources.list.d/mobilint.list > /dev/null

    # Update available packages
    sudo apt update
    ```

2. apt 패키지 관리자를 통해 설치를 진행합니다.

    ```bash
    sudo apt install mobilint-qb-runtime
    ```

3. 설치를 확인합니다.

    ```bash
    dpkg -L mobilint-qb-runtime
    ```

#### Anaconda 환경에서의 문제 해결

아나콘다 가상 환경을 사용할 경우, 아나콘다의 `libstdc++.so`를 사용하게되어 해당 라이브러리 관련 오류가 발생할 수 있습니다.

```bash
../lib/libstdc++.so.6: version `GLIBCXX_3.4.32' not found
```

이러한 오류는 아나콘다와 함께 설치되는 libstdc++ 라이브러리의 버전 충돌로 인해 발생하는 문제입니다. 이는 사용하는 아나콘다 환경의 `libstdcxx-ng` 등의 라이브러리 버전을 업그레이드하여 해결해야 합니다. 아나콘다 버전 별로 업그레이드 하는 명령이 달라질 수 있기 때문에, 정확한 업그레이드 방법은 온라인에서 관련 정보를 검색하는 것을 권장합니다.

또한, 이러한 충돌을 방지하기 위해 시스템의 `libstdc++`을 사용하는 Python의 기본 제공 가상 환경 (`venv`)을 사용하는 것을 권장합니다.

(dnf)=
### 방법 2: DNF를 통한 설치

이 절에서 다루는 설치 방법은 RedHat 계열 OS의 패키지 관리자 `dnf`를 활용한 설치 방법입니다. 패키지는 glibc 2.28 (EL8) 기준으로 빌드되어 RHEL, Rocky Linux 의 Redhat 계열 OS의 x86_64와 aarch64 아키텍처를 지원합니다.

```{note}
모빌린트 DNF 저장소는 `mobilint-qb-runtime`, `mobilint-cli`와 함께 NPU 드라이버 패키지(`mobilint-aries-driver`)도 제공합니다. RedHat 계열 OS에서의 NPU 드라이버 설치는 ARIES 매뉴얼의 {external+aries:doc}`드라이버 설치 <driver-installation>` 페이지에서 DNF를 통한 설치 방법을 참고해주세요.
```

#### 설치 절차

1. 아래 명령을 수행하여 모빌린트 DNF 저장소를 시스템에 등록합니다.

    ```bash
    # 저장소 등록
    sudo curl -fsSL https://dl.mobilint.com/dnf/mobilint.repo \
         -o /etc/yum.repos.d/mobilint.repo
    ```

2. dnf 패키지 관리자를 통해 설치를 진행합니다.

    ```bash
    # 런타임 라이브러리 설치
    sudo dnf install mobilint-qb-runtime

    # (선택) CLI 유틸리티 설치
    sudo dnf install mobilint-cli
    ```

    ````{note}
    최초 설치 시 `dnf`가 모빌린트 GPG 서명 키의 임포트 여부를 확인합니다. 아래와 같이 안내가 표시되면 `y`를 입력해주세요.

    ```text
    Importing GPG key 0x________:
     Userid     : "Mobilint_RPM (gpg key for dnf - RSA key.) <infra@mobilint.com>"
     Fingerprint: 
     From       : https://dl.mobilint.com/dnf/gpg.pub
    Is this ok [y/N]: y
    ```
    ````

3. 설치를 확인합니다.

    ```bash
    rpm -ql mobilint-qb-runtime
    ```

(manual-download-install)=
### 방법 3: 다운로드 센터를 통한 수동 설치

#### 요구 사항

- 모빌린트의 공식 [다운로드 센터](https://dl.mobilint.com)에서 런타임 라이브러리를 다운받아야 합니다.

#### 설치 절차

1. 다운로드 센터에서 다운받은 런타임 라이브러리 파일의 압축을 해제합니다. 이때 `{RUNTIME_VERSION}` 은 설치할 런타임 라이브러리 버전에 대응되는 문자열입니다.

    ```bash
    tar -xvzf qb-runtime_aries2-v4_v{RUNTIME_VERSION}.tar.gz
    ```

    압축을 해제하면 아래와 같은 폴더 구조를 지니고 있습니다.

    ```bash
    qb-runtime_aries2-v4_v{RUNTIME_VERSION}
    ├── Makefile
    ├── qbruntime
    │   ├── qbruntime
    │   │ ├── include    # include path
    │   │ │   └── qbruntime
    │   │ ├── lib        # library path
    │   │ └── python
    │   └── resnet50
    └── mobilint-cli
    ```

이후 두가지 설치 방법이 존재합니다: **시스템 전역 설치** 혹은 **설치 없이 사용**.

(system-wide-install)=
#### 방법 3-1: 시스템 전역 설치

아래 명령을 통해 시스템 전역에 라이브러리를 설치합니다.

```bash
cd qb-runtime_aries2-v4_v{RUNTIME_VERSION}
sudo make install
```

위 명령으로 설치한 라이브러리는 `sudo make uninstall` 명령을 통해 삭제할 수 있습니다.

(without-installation)=
#### 방법 3-2: 설치 없이 사용

컴파일 과정에서는 `qb-runtime_aries2-v4_v{RUNTIME_VERSION}/qbruntime/qbruntime/include` 의 헤더파일 경로와 `qb-runtime_aries2-v4_v{RUNTIME_VERSION}/qbruntime/qbruntime/lib` 의 라이브러리 경로를 아래와 같이 명시해줍니다.

```bash
g++ -o {output_binary} {source_code} -I{path_to_include} \
    -L{path_to_library} -lqbruntime
```

이후 컴파일된 바이너리를 실행하는 과정에서는 동적 링커에게 런타임 라이브러리 (`*.so`)의 경로를 알려주기 위해 `LD_LIBRARY_PATH`에 해당 경로를 등록하여 사용합니다.

```bash
export LD_LIBRARY_PATH={path_to_library}
```

## Windows

Windows에서 런타임 라이브러리는 인스톨러로 설치합니다. 인스톨러는 런타임 라이브러리와 헤더 파일을 설치하고, 선택한 추가 구성 요소 설치와 환경 변수 등록도 함께 수행합니다. 파이썬 라이브러리만 필요한 경우 [pip를 통한 파이썬 라이브러리 설치](#pip)를 참고해주세요.

```{note}
Windows 인스톨러는 런타임 라이브러리 **1.4.0** 버전부터 제공됩니다.
```

(windows-install)=
### 인스톨러를 통한 설치

#### 요구 사항

- 모빌린트의 공식 [다운로드 센터](https://dl.mobilint.com)에서 Windows 인스톨러 `mobilint-qb-runtime-sdk_v{RUNTIME_VERSION}_setup.exe`를 다운로드합니다. 이때 `{RUNTIME_VERSION}`은 설치할 런타임 라이브러리 버전에 대응되는 문자열입니다.

#### 설치 절차

1. 다운로드한 인스톨러를 실행한 뒤 설치 경로를 지정합니다. 기본 경로는 `C:\Users\{사용자}\AppData\Local\Programs\mobilint-qb-runtime-sdk`이며, **찾아보기**를 눌러 변경할 수 있습니다.

    ![설치 경로 선택 화면](../res/image/windows_installer_install_step1_kr.png "설치 경로 선택")

2. 함께 수행할 추가 작업을 선택합니다. 아래 세 항목은 기본으로 모두 선택되어 있으며, 변경할 이유가 없다면 그대로 두고 진행합니다.

    | 항목 | 설명 |
    | --- | --- |
    | `mobilint-cli` 유틸리티 설치 | NPU 상태 확인, 벤치마크, MXQ 정보 조회 유틸리티를 함께 설치합니다. 사용법은 [유틸리티 사용](utility_usage.md)을 참고해주세요. |
    | 환경변수 `qbruntime_DIR` 등록 | CMake의 `find_package`가 런타임 라이브러리를 찾을 수 있도록 경로를 등록합니다. 사용법은 [C++ 컴파일 - CMake](#compile-cmake)를 참고해주세요. |
    | `bin` 폴더를 `PATH`에 추가 | `mobilint-cli` 실행 파일과 `qbruntime.dll`을 경로 지정 없이 찾을 수 있도록 합니다. |

    ![추가 작업 선택 화면](../res/image/windows_installer_install_step2_kr.png "추가 작업 선택")

3. 요약 화면에서 설치 경로와 추가 작업을 확인한 뒤 **설치**를 클릭합니다.

    ![설치 준비 완료 요약 화면](../res/image/windows_installer_install_step3_kr.png "설치 준비 완료")

4. 설치가 끝나면 완료 화면이 나타납니다. **마침**을 클릭하여 인스톨러를 종료합니다.

    ![설치 완료 화면](../res/image/windows_installer_install_step4_kr.png "설치 완료")

```{note}
환경 변수 변경 사항은 이미 열려 있는 터미널에는 반영되지 않습니다. 설치 후 새 터미널을 열어주세요.
```

설치한 라이브러리를 **Visual Studio** 프로젝트에서 사용하는 방법은 [C++ 컴파일 - Windows](#compile-windows)를, CMake 프로젝트에서 사용하는 방법은 [C++ 컴파일 - CMake](#compile-cmake)를 참고해주세요.

(windows-uninstall)=
### 삭제

두 가지 방법으로 삭제할 수 있습니다.

- **제어판에서 삭제**: 제어판의 **프로그램 및 기능** 또는 Windows 설정의 **앱 > 설치된 앱** 목록에서 `Mobilint qb Runtime SDK`를 선택해 제거합니다.

- **인스톨러 재실행**: 다운로드한 인스톨러를 다시 실행하면 아래와 같이 기존 설치를 처리하는 창이 나타납니다. **제거하기**를 선택하면 설치된 파일이 삭제되고, **다시 설치**를 선택하면 기존 설치를 덮어씁니다.

    ![기존 설치 제거 및 재설치 선택 창](../res/image/windows_installer_remove_kr.png "제거")

## Windows, Linux 공용

(pip)=
### pip를 통한 파이썬 라이브러리 설치

파이썬 라이브러리는 pip를 통해 설치할 수 있으며, Windows와 Linux를 모두 지원합니다.

```bash
pip install mobilint-qb-runtime
```

휠 패키지는 Windows x86-64와 Linux x86-64/aarch64용으로 제공됩니다. 32비트 환경은 지원하지 않습니다.

````{note}
Linux용 휠 패키지는 `manylinux_x_y` 플랫폼 태그를 사용하며, 이 태그를 인식하려면 **pip 20.3 이상**이 필요합니다. 지원되는 파이썬 버전(3.8~3.14)을 사용하고 있음에도 pip가 패키지를 찾지 못하는 경우, pip 버전을 확인하고 필요 시 아래 명령으로 업그레이드해주세요.

```bash
pip install --upgrade pip
```
````