lupa-cli 1.0.0

LUPA Studio Command Line Tools - CLI tools for LUPA embedded development

LUPA Studio CLI Tools

LUPA Studio 명령줄 도구 모음

설치 및 사용

LPC (LUPA Command) - 통합 CLI 도구

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

설치

# 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 설정 없이도 사용할 수 있습니다:

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 프로필 열기
notepad $PROFILE

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

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

기본 사용법

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

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

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

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

사용 예시

# 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 방식도 여전히 작동

제거

pip uninstall lupa-cli

---

개별 스크립트 사용

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

list_sdks.py

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

기능

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

사용법

# 설치된 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으로 언어 강제 지정

예시:

# 시스템 언어로 출력 (자동 감지)
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 출력

{
  "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에서 실행 전 다음 명령 실행:

chcp 65001

그 후 스크립트 실행:

python list_sdks.py

방법 2: 환경 변수 설정

PowerShell에서:

$env:PYTHONIOENCODING="utf-8"
python list_sdks.py

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 형식 출력

사용법

# 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 출력 형식:

{
  "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 옵션 사용 시:

{
  "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: 세탁기 관련 타겟만 조회

$ 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: 빌드 가능한 타겟만 확인

$ python list_target.py LUPA251020_1 --pretty | jq '.targets[] | select(.debug_available == true)'

예시 3: 타겟 이름만 추출

$ 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 지원

사용법

# 기본 사용법 (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 값을 추출하여 사용

예시:

// .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 옵션으로 명시적 지정

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 파이프라인

#!/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. 배치 빌드

# 여러 프로젝트를 순차 빌드
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. 개발 워크플로우

# 개발 중: 빠른 빌드 (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