Metadata-Version: 2.4
Name: lupa-cli
Version: 1.0.0
Summary: LUPA Studio Command Line Tools - CLI tools for LUPA embedded development
Author: LUPA Studio Team
License: Apache-2.0
Project-URL: Homepage, https://github.com/lupastudio/lupa-cli
Project-URL: Documentation, https://github.com/lupastudio/lupa-cli
Project-URL: Repository, https://github.com/lupastudio/lupa-cli
Keywords: lupa,embedded,cli,sdk,build
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: Apache Software License
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyserial>=3.5
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Dynamic: license-file

# LUPA Studio CLI Tools

LUPA Studio 명령줄 도구 모음

## 설치 및 사용

### LPC (LUPA Command) - 통합 CLI 도구

`lpc`는 LUPA Studio의 모든 명령줄 도구를 하나의 인터페이스로 통합한 CLI 도구입니다.

#### 설치

```bash
# cli 폴더로 이동
cd lupa-vscode-ide/cli

# 개발 모드로 설치 (editable install)
pip install -e .

# 또는 일반 설치
pip install .
```

설치 후 `lpc` 명령어를 전역적으로 사용할 수 있습니다.

#### Windows PATH 설정

Windows에서 pip으로 설치한 후 `lpc` 명령어를 찾을 수 없다는 오류가 발생할 수 있습니다. 이는 Python Scripts 디렉토리가 PATH에 없기 때문입니다.

**방법 1: PATH에 Scripts 디렉토리 추가 (권장)**

1. 설치 시 출력된 경로 확인 (예: `C:\Users\<username>\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.13_xxx\LocalCache\local-packages\Python313\Scripts`)
2. Windows 시스템 환경 변수에 해당 경로 추가:
   - `Win + X` → 시스템 → 고급 시스템 설정 → 환경 변수
   - 사용자 변수 또는 시스템 변수에서 `Path` 선택 → 편집
   - 새로 만들기 → Scripts 경로 붙여넣기 → 확인
3. 새 터미널을 열고 `lpc --help` 실행

**방법 2: Python 모듈로 실행**

PATH 설정 없이도 사용할 수 있습니다:

```bash
python -m lpc <command> [arguments...]

# 예시
python -m lpc list_sdks --all --json
python -m lpc list_target LUPA251020_1 --filter washer
```

**방법 3: 별칭(Alias) 설정**

PowerShell 프로필에 별칭 추가:

```powershell
# PowerShell 프로필 열기
notepad $PROFILE

# 다음 줄 추가
function lpc { python -m lpc @args }

# PowerShell 재시작 후 사용
lpc --help
```

#### 기본 사용법

```bash
# 도움말 보기
lpc --help
lpc -h

# 사용 가능한 명령어 목록 보기
lpc

# 특정 명령어 실행
lpc <command> [arguments...]

# 명령어별 도움말
lpc <command> --help
```

#### 사용 예시

```bash
# PATH 설정이 된 경우
lpc list_sdks --all --json
lpc list_target LUPA251020_1 --filter washer --pretty
lpc build_project /path/to/project --sdk-path LUPA251020_1
lpc check_uart COM3

# PATH 설정 없이 Python 모듈로 실행
python -m lpc list_sdks --all --json
python -m lpc list_target LUPA251020_1 --filter washer --pretty
python -m lpc build_project /path/to/project --sdk-path LUPA251020_1
python -m lpc check_uart COM3
```

#### 장점

- ✅ **통합 인터페이스**: 모든 CLI 도구를 하나의 명령어로 실행
- ✅ **자동 완성**: 쉘에서 탭 완성 지원
- ✅ **전역 실행**: 어디서든 `lpc` 명령어 사용 가능
- ✅ **확장 가능**: 새로운 Python 스크립트 추가 시 자동으로 명령어로 등록
- ✅ **기존 호환성**: 기존 `python <script>.py` 방식도 여전히 작동

#### 제거

```bash
pip uninstall lupa-cli
```

---

## 개별 스크립트 사용

`lpc`를 설치하지 않고 개별 스크립트를 직접 실행할 수도 있습니다.

### list_sdks.py

LUPA Studio에서 사용 가능한 SDK 목록을 조회하는 스크립트입니다.

### 기능

- **설치된 SDK 목록**: 로컬에 설치된 SDK 조회
- **다운로드 가능한 SDK 목록**: 다운로드 가능한 전체 SDK 조회
- **통합 보기**: 설치 여부를 포함한 전체 SDK 정보 조회
- **JSON 출력**: 프로그램에서 사용하기 쉬운 JSON 형식 출력 지원
- **다국어 지원**: 시스템 언어 자동 감지 및 한국어/영어 출력 지원

### 사용법

```bash
# 설치된 SDK 목록 조회 (기본값)
python list_sdks.py
python list_sdks.py --installed

# 다운로드 가능한 전체 SDK 목록 조회
python list_sdks.py --available

# 모든 SDK 정보 조회 (설치 여부 포함)
python list_sdks.py --all

# JSON 형식으로 출력
python list_sdks.py --all --json

# 언어 설정
python list_sdks.py --lang ko      # 한국어로 출력
python list_sdks.py --lang en      # 영어로 출력
python list_sdks.py --lang auto    # 시스템 언어 자동 감지 (기본값)
```

### 다국어 지원

스크립트는 시스템의 언어 설정을 자동으로 감지하여 적절한 언어로 메시지를 출력합니다.

- **자동 감지**: `--lang auto` (기본값) - 시스템 로케일에 따라 자동 선택
  - 한국어 로케일 (ko_*): 한국어 출력
  - 그 외: 영어 출력
- **수동 설정**: `--lang ko` 또는 `--lang en`으로 언어 강제 지정

**예시:**
```bash
# 시스템 언어로 출력 (자동 감지)
python list_sdks.py --all

# 영어로 강제 출력
python list_sdks.py --all --lang en

# 한국어로 강제 출력
python list_sdks.py --all --lang ko
```

### 출력 예시

#### 설치된 SDK 목록 (한국어)
```
============================================================
설치된 SDK 목록
============================================================
  총 6개의 SDK가 설치되어 있습니다.

  1. LUPA241028_1
  2. LUPA250624
  3. LUPA250708_1
  4. LUPA250804_2
  5. LUPA251002
  6. LUPA251020_1
```

#### 설치된 SDK 목록 (영어)
```
============================================================
Installed SDKs
============================================================
  Total 6 SDK(s) installed.

  1. LUPA241028_1
  2. LUPA250624
  3. LUPA250708_1
  4. LUPA250804_2
  5. LUPA251002
  6. LUPA251020_1
```

#### 다운로드 가능한 SDK 목록 (한국어)
```
============================================================
다운로드 가능한 SDK 목록
============================================================
  총 3개의 SDK를 다운로드할 수 있습니다.

  1. LUPA250624
     최소 지원 버전: >=1.3.0
     호환 에뮬레이터: renode_0.30.8+20241212.zip

  2. LUPA251020_1
     최소 지원 버전: >=1.3.0
     호환 에뮬레이터: renode_0.30.8+20241212.zip
```

#### 다운로드 가능한 SDK 목록 (영어)
```
============================================================
Available SDKs for Download
============================================================
  Total 3 SDK(s) available for download.

  1. LUPA250624
     Minimum supported version: >=1.3.0
     Compatible emulators: renode_0.30.8+20241212.zip

  2. LUPA251020_1
     Minimum supported version: >=1.3.0
     Compatible emulators: renode_0.30.8+20241212.zip
```

#### JSON 출력
```json
{
  "installed_sdks": [
    "LUPA241028_1",
    "LUPA250624",
    "LUPA251020_1"
  ],
  "available_sdks": [
    {
      "name": "LUPA250624",
      "emulator": ["renode_0.30.8+20241212.zip"],
      "supported_version": ">=1.3.0"
    }
  ]
}
```

### 요구사항

- Python 3.6 이상
- LUPA Studio가 설치되어 있어야 함 (`~/.lupastudio` 디렉토리 존재)

### Windows 한글 깨짐 문제 해결

Windows 콘솔에서 한글이 깨져 보이는 경우 다음 방법을 시도하세요:

#### 방법 1: 콘솔 코드페이지 변경 (권장)
PowerShell 또는 CMD에서 실행 전 다음 명령 실행:
```cmd
chcp 65001
```

그 후 스크립트 실행:
```cmd
python list_sdks.py
```

#### 방법 2: 환경 변수 설정
PowerShell에서:
```powershell
$env:PYTHONIOENCODING="utf-8"
python list_sdks.py
```

CMD에서:
```cmd
set PYTHONIOENCODING=utf-8
python list_sdks.py
```

#### 방법 3: Windows Terminal 사용
Windows Terminal을 사용하면 기본적으로 UTF-8을 지원합니다:
- Windows 11: 기본 제공
- Windows 10: Microsoft Store에서 설치

**참고**: 스크립트는 Windows 환경을 자동 감지하여 UTF-8 인코딩을 설정하도록 개선되었습니다.

### 참조

- LUPA Studio Home: `~/.lupastudio` (Windows: `%USERPROFILE%\.lupastudio`)
- 설치된 SDK 경로: `~/.lupastudio/sdk/`
- SDK 목록 파일: `~/.lupastudio/lupa_sdk_emulator.json`

---

## list_target.py

특정 LUPA SDK의 빌드 타겟 목록과 설정 정보를 조회하는 스크립트입니다.

### 기능

- **빌드 타겟 목록 조회**: SDK의 `sdk/sdk_config.json`에서 사용 가능한 모든 빌드 타겟 조회
- **아키텍처 정보**: 각 타겟의 `sdk_architecture` 정보 제공
- **제품 타입 정보**: 각 타겟의 `product_type` 정보 제공 (washer, fridge, aircon 등)
- **디버그 빌드 여부**: `out/` 디렉토리에서 빌드된 타겟 확인하여 `debug_available` 표시
- **타겟 필터링**: 패턴 매칭으로 특정 타겟만 조회
- **JSON 출력**: 머신 리더블한 JSON 형식 출력

### 사용법

```bash
# SDK 이름으로 타겟 목록 조회
python list_target.py LUPA251020_1

# SDK 경로로 타겟 목록 조회
python list_target.py /home/user/lupa251020_1/lupa
python list_target.py C:\Users\admin\.lupastudio\sdk\LUPA251020_1

# 특정 패턴으로 필터링 (예: washer 타겟만)
python list_target.py LUPA251020_1 --filter washer

# 여러 제품 타입 필터링
python list_target.py LUPA251020_1 --filter fridge
python list_target.py LUPA251020_1 --filter aircon

# Pretty print로 보기 좋게 출력
python list_target.py LUPA251020_1 --pretty

# -debug 접미사를 추가하여 타겟 이름 출력
python list_target.py LUPA251020_1 --debug

# SDK 정보 포함하여 출력
python list_target.py LUPA251020_1 --sdk-info --pretty
```

### 출력 형식

기본 JSON 출력 형식:

```json
{
  "targets": [
    {
      "target": "washer.dqc.next_osp",
      "sdk_architecture": "arm-lg8211",
      "product_type": "washer",
      "debug_available": true
    },
    {
      "target": "fridge.dqc.M-Next3_dualice",
      "sdk_architecture": "arm-lg8211a0",
      "product_type": "fridge",
      "debug_available": false
    }
  ],
  "count": 2
}
```

`--sdk-info` 옵션 사용 시:

```json
{
  "targets": [...],
  "count": 150,
  "sdk_location": "/home/user/.lupastudio/sdk/LUPA251020_1",
  "sdk_name": "LUPA251020_1"
}
```

### 동작 방식

1. **SDK 위치 확인**
   - SDK 이름이 입력되면 `~/.lupastudio/sdk/<SDK이름>` 경로 확인
   - 절대 경로가 입력되면 해당 경로 사용

2. **SDK 설정 로드**
   - `<SDK경로>/sdk/sdk_config.json` 파일 읽기
   - 각 키(타겟 이름)에 대해 `sdk_architecture`, `product_type` 추출

3. **디버그 빌드 확인**
   - `<SDK경로>/out/` 디렉토리의 하위 폴더 검사
   - `<타겟이름>-debug` 폴더가 존재하면 `debug_available: true`

4. **정렬 및 출력**
   - `debug_available: true`인 타겟을 먼저 표시
   - 그 다음 알파벳 순으로 정렬
   - JSON 형식으로 출력

### 옵션

| 옵션 | 설명 |
|------|------|
| `sdk` | (필수) SDK 이름 또는 절대 경로 |
| `-f, --filter PATTERN` | 타겟 이름 필터링용 패턴 (대소문자 무관) |
| `-d, --debug` | 타겟 이름에 `-debug` 접미사를 추가 (기본값: 추가하지 않음) |
| `-p, --pretty` | JSON을 들여쓰기하여 보기 좋게 출력 |
| `--sdk-info` | SDK 위치 정보를 출력에 포함 |

### 사용 예시

#### 예시 1: 세탁기 관련 타겟만 조회
```bash
$ python list_target.py LUPA251020_1 --filter washer --pretty
{
  "targets": [
    {
      "target": "washer.dqc.next_osp",
      "sdk_architecture": "arm-lg8211",
      "product_type": "washer",
      "debug_available": true
    },
    ...
  ],
  "count": 52
}
```

#### 예시 2: 빌드 가능한 타겟만 확인
```bash
$ python list_target.py LUPA251020_1 --pretty | jq '.targets[] | select(.debug_available == true)'
```

#### 예시 3: 타겟 이름만 추출
```bash
$ python list_target.py LUPA251020_1 | jq -r '.targets[].target'
```

### 요구사항

- Python 3.6 이상
- 지정된 SDK가 설치되어 있어야 함
- SDK 내에 `sdk/sdk_config.json` 파일이 존재해야 함

### 에러 메시지

- `SDK not found`: SDK 이름 또는 경로가 잘못됨
- `SDK config not found`: `sdk/sdk_config.json` 파일이 없음
- `Error parsing SDK config`: JSON 파일 형식 오류

### TypeScript 원본 함수

이 스크립트는 다음 TypeScript 함수들의 로직을 Python으로 구현한 것입니다:

- `TargetConfigurations.loadSdkConfig()`: SDK 설정 파일 로드
- `TargetConfigurations.getSdkConfigJson()`: 타겟 목록 생성 및 디버그 빌드 확인
- `TargetConfigurations.getTargetArchitecture()`: 타겟 아키텍처 조회
- `TargetConfigurations.getProductType()`: 제품 타입 조회
- `TargetConfigurations.getTargetDirList()`: `out/` 디렉토리 스캔

### 활용 사례

- **CI/CD 파이프라인**: 특정 제품 타입의 타겟만 자동 빌드
- **빌드 검증**: 디버그 빌드가 완료된 타겟 확인
- **문서 생성**: SDK가 지원하는 모든 타겟 목록 자동 생성
- **스크립트 자동화**: JSON 출력을 파싱하여 다른 도구에 전달

---

## build_project.py

LUPA 프로젝트를 자동으로 빌드하는 스크립트입니다. CMake와 Ninja를 사용하여 프로젝트를 구성하고 컴파일합니다.

### 기능

- **자동 타겟 아키텍처 감지**: `.lupaproject` 파일에서 `activeTarget`을 읽어 자동으로 타겟 아키텍처 결정
- **SDK 경로 자동 처리**: SDK 버전 이름 또는 절대 경로를 자동으로 인식
- **통합 빌드 프로세스**: clean, configure, build를 순차적으로 실행하는 `all` 액션 지원
- **개별 액션 실행**: 필요에 따라 clean, configure, build를 개별적으로 실행 가능
- **크로스 플랫폼**: Windows, Linux, macOS 지원

### 사용법

```bash
# 기본 사용법 (clean, configure, build 모두 실행)
python build_project.py /path/to/project --sdk-path LUPA251020_1

# 명시적으로 all 액션 지정
python build_project.py /path/to/project --sdk-path LUPA251020_1 --action all

# 타겟 아키텍처 명시적으로 지정
python build_project.py /path/to/project --sdk-path LUPA251020_1 --arch arm-it986x

# 개별 액션 실행
python build_project.py /path/to/project --action clean
python build_project.py /path/to/project --sdk-path LUPA251020_1 --action configure
python build_project.py /path/to/project --sdk-path LUPA251020_1 --action build

# SDK 절대 경로 사용
python build_project.py /path/to/project --sdk-path /absolute/path/to/sdk/directory

# 커스텀 core 디렉토리 지정
python build_project.py /path/to/project --core-dir /custom/path --sdk-path LUPA251020_1
```

### 옵션

| 옵션 | 설명 |
|------|------|
| `project_dir` | (필수) LUPA 프로젝트 디렉토리 경로 |
| `--sdk-path SDK` | SDK 버전 이름 (예: LUPA251020_1) 또는 SDK 디렉토리의 절대 경로 |
| `--core-dir PATH` | LUPA Studio core 디렉토리 경로 (기본값: ~/.lupastudio) |
| `--arch, --target-architecture ARCH` | 타겟 아키텍처 (생략 시 자동 감지) |
| `--product-type TYPE` | 제품 타입 (선택사항) |
| `--toolchain-path PATH` | 커스텀 툴체인 경로 (선택사항) |
| `--action ACTION` | 실행할 액션: `all`, `configure`, `build`, `clean` (기본값: all) |

### 액션 설명

- **all**: clean → configure → build를 순차적으로 실행 (기본값)
- **configure**: CMake 프로젝트 구성만 수행
- **build**: 프로젝트 빌드만 수행 (configure가 안 되어 있으면 자동 실행)
- **clean**: build 디렉토리 삭제

### 동작 방식

#### 1. SDK 경로 처리
- **버전 이름 입력** (예: `LUPA251020_1`):
  - `~/.lupastudio/sdk/<version>/sdk` 경로로 자동 변환
- **절대 경로 입력** (예: `/path/to/sdk`):
  - 해당 경로를 직접 사용
  - 경로에서 버전 이름 추출 시도 (`.../sdk/<version>/sdk` 패턴)

#### 2. 타겟 아키텍처 자동 감지
1. `.lupaproject` 파일에서 `activeTarget` 읽기
2. `-debug` 접미사 제거
3. `list_target.py` 스크립트 호출하여 해당 타겟 정보 조회
4. `sdk_architecture` 값을 추출하여 사용

예시:
```json
// .lupaproject
{
  "activeTarget": "reference.ite.hdk",
  "activeSdk": "LUPA251020_1"
}
```
→ 자동으로 `arm-it986x` 아키텍처로 빌드

#### 3. 빌드 프로세스 (all 액션)
```
[1/3] Cleaning...
  └─ build/ 디렉토리 삭제

[2/3] Configuring...
  └─ CMake 프로젝트 구성
  └─ CMakeLists.txt 또는 exported_dqc/ 확인
  └─ 툴체인 설정 적용
  └─ 타겟 아키텍처 설정

[3/3] Building...
  └─ Ninja로 컴파일
  └─ .elf, .bin, .lpk 파일 생성
```

### 요구사항

- Python 3.6 이상
- LUPA Studio가 설치되어 있어야 함:
  - CMake: `~/.lupastudio/packages/tool-cmake/`
  - Ninja: `~/.lupastudio/packages/tool-ninja/`
  - Toolchain: `~/.lupastudio/packages/toolchain-gccarmnoneeabi/`
  - SDK: `~/.lupastudio/sdk/<version>/`
- 프로젝트에 `.lupaproject` 파일이 있어야 함 (타겟 자동 감지용)
- CMakeLists.txt 또는 exported_dqc/ 디렉토리가 있어야 함

### 출력 예시

#### 성공적인 빌드 (all 액션)

```
Found activeTarget in .lupaproject: reference.ite.hdk
Executing: python list_target.py LUPA251020_1 --filter reference.ite.hdk
Auto-detected target architecture: arm-it986x

============================================================
Executing ALL actions: clean -> configure -> build
============================================================

[1/3] Cleaning...
============================================================
Clean LUPA project...
============================================================
Removed build directory: /path/to/project/build
Clean project finished.

[2/3] Configuring...
============================================================
Start LUPA project configuration...
============================================================
Build directory: /path/to/project/build

Executing: cmake -G Ninja ...

-- LUPA SDK version: 2.0.255
-- Target architecture: arm-it986x
-- Product type: N/A
-- Configuring done
-- Generating done
-- Build files have been written to: /path/to/project/build

CMake configuration completed successfully.

[3/3] Building...
============================================================
Start LUPA project build...
============================================================

Executing: cmake --build /path/to/project/build

[1/16] Generating resource.h, resource.ini, rsc.bin
[2/16] Building C object ...
...
[16/16] Generating myhello.lpk

Finished LUPA project build.

============================================================
All actions completed successfully!
============================================================
```

#### 타겟 아키텍처 자동 감지 실패

```
Found activeTarget in .lupaproject: reference.ite.hdk
Warning: list_target.py failed: ...
============================================================
Start LUPA project configuration...
============================================================
Error: target_architecture is required but could not be determined
Please specify --arch/--target-architecture explicitly
```

해결 방법: `--arch` 옵션으로 명시적 지정
```bash
python build_project.py /path/to/project --sdk-path LUPA251020_1 --arch arm-it986x
```

### 에러 메시지

| 에러 | 원인 | 해결 방법 |
|------|------|----------|
| `Project directory does not exist` | 잘못된 프로젝트 경로 | 올바른 경로 입력 |
| `SDK path does not exist` | 잘못된 SDK 버전/경로 | `list_sdks.py`로 설치된 SDK 확인 |
| `target_architecture is required` | 자동 감지 실패 | `--arch` 옵션으로 명시적 지정 |
| `There is no exported DQC Code` | CMakeLists.txt 없음 | GuiCreator에서 DQC 코드 export |
| `CMake not found` | CMake가 설치되지 않음 | LUPA Studio 재설치 |
| `Configure failed` | CMake 구성 오류 | 에러 로그 확인 및 SDK 경로 검증 |
| `Build failed` | 컴파일 오류 | 소스 코드 및 에러 메시지 확인 |

### 활용 사례

#### 1. CI/CD 파이프라인

```bash
#!/bin/bash
# 프로젝트 자동 빌드 스크립트

PROJECT_DIR="/path/to/project"
SDK_VERSION="LUPA251020_1"

# 전체 빌드 실행
python build_project.py "$PROJECT_DIR" --sdk-path "$SDK_VERSION"

if [ $? -eq 0 ]; then
    echo "Build successful!"
    # 빌드 결과물을 artifact로 저장
    cp "$PROJECT_DIR/build/output/*.lpk" ./artifacts/
else
    echo "Build failed!"
    exit 1
fi
```

#### 2. 배치 빌드

```python
# 여러 프로젝트를 순차 빌드
import subprocess

projects = [
    "/path/to/project1",
    "/path/to/project2",
    "/path/to/project3"
]

sdk = "LUPA251020_1"

for project in projects:
    print(f"Building {project}...")
    result = subprocess.run([
        "python", "build_project.py",
        project,
        "--sdk-path", sdk
    ])
    if result.returncode != 0:
        print(f"Failed to build {project}")
        break
```

#### 3. 개발 워크플로우

```bash
# 개발 중: 빠른 빌드 (clean 생략)
python build_project.py /path/to/project --sdk-path LUPA251020_1 --action build

# 릴리스: 완전 클린 빌드
python build_project.py /path/to/project --sdk-path LUPA251020_1 --action all

# 빌드 디렉토리만 정리
python build_project.py /path/to/project --action clean
```

### 참조

- 타겟 목록 조회: `list_target.py`
- SDK 목록 조회: `list_sdks.py`
- LUPA Studio Home: `~/.lupastudio`
- 빌드 출력: `<project>/build/output/`
- 생성 파일: `.elf`, `.bin`, `.lpk`
