LVRS Storyboard Frame

build.svx

Path: build.svx

Last modified:

빌드 및 런타임 설정

빠른 설치

./install.sh

설치기는 bootstrap_lvrs_all 를 호스트 우선 기본 플랫폼으로 설정하여 실행합니다. 기본적으로 호스트 플랫폼 패키지 만 부트스트랩/설치됩니다. 추가 런타임 플랫폼을 명시적으로 포함하려면 ./install.sh --platforms linux,android,wasm (쉼표/분호 목록) 를 사용하세요. 설치된 패키지는 <prefix>/platforms/<platform> ( macos , linux , windows , ios , android , wasm ) 에 기록된 후 호스트 플랫폼 경로는 CMake 사용자 패키지 레지스트리에 등록됩니다. 설치기는 이전 빌드 디렉토리와 설치된 LVRS 아티팩트 경로를 제거하여 구성하기 전에 항상 깨끗한 재설치를 수행합니다. install.sh 는 기본적으로 호스트 빌드에서 예제/테스트를 구성하며, --without-examples --without-tests 를 전달하여 이를 비활성화할 수 있습니다.

구성

cmake -S . -B build

빌드

cmake --build build -j

실행

cmake -S . -B build \
  -DLVRS_BUILD_EXAMPLES=ON \
  -DLVRS_BUILD_TESTS=ON
cmake --build build --target LVRSExampleVisualCatalog
./build/bin/LVRSExampleVisualCatalog

시각 카탈로그 예제 대상(LVRSExampleVisualCatalog)은 실행 파일을 build/bin/LVRSExampleVisualCatalog로 출력합니다. 프레임워크 라이브러리 대상(LVRSCore) 자체는 실행 가능한 앱을 생성하지 않습니다.

테스트

ctest --test-dir build --output-on-failure

빌드 옵션

  • LVRS_BUILD_EXAMPLES (OFF): 실행 가능한 예제를 빌드합니다.
  • LVRS_BUILD_TESTS (OFF): 테스트를 빌드하고 등록합니다.
  • LVRS_INSTALL_QML_MODULE(ON): <prefix>/lib/qt6/qml/LVRS 아래에 QML 모듈 아티팩트(qmldir, qmltypes, 플러그인, QML 파일)를 설치합니다.
  • LVRS_ENFORCE_VULKAN ( ON): 고정 그래픽 백엔드 Qt 기능 요구 사항이 누락된 경우 CMake 구성 실패.
  • LVRS_ENABLE_PLATFORM_BUILD_OPTIMIZATIONS (ON): 플랫폼별 릴리스/relwithdebinfo/minsizerel 컴파일+링크 최적화 플래그를 적용합니다.
  • LVRS_ENABLE_IPO(ON): 툴체인 지원이 가능할 때 릴리스와 유사한 구성에 대해 절차간 최적화(LTO)를 활성화합니다.
  • LVRS_SANITIZER(none): 소독제 계측(none, address, thread, undefined).
  • LVRS_FORCE_X86_QT_TOOLS(OFF): 필요한 경우 Rosetta를 통해 Qt 호스트 도구를 실행합니다.
  • LVRS_ENABLE_FRAMEWORK_BOOTSTRAP_TARGETS (ON): bootstrap_lvrs_* 프레임워크 다중 플랫폼 대상을 생성합니다.
  • LVRS_BOOTSTRAP_INSTALL_ROOT (<build>/lvrs-install): bootstrap_lvrs_*에서 사용하는 설치 루트입니다.

하위 소비 측 CMake 통합

먼저 접두사에 LVRS를 설치합니다.

cmake -S . -B build \
  -DLVRS_BUILD_EXAMPLES=OFF \
  -DLVRS_BUILD_TESTS=OFF \
  -DCMAKE_INSTALL_PREFIX=/path/to/lvrs-prefix
cmake --build build -j
cmake --install build

그런 다음 Qt Quick 프로젝트에서 다음을 수행합니다.

find_package(Qt6 6.5 REQUIRED COMPONENTS Quick QuickControls2)
find_package(LVRS CONFIG REQUIRED)

lvrs_add_qml_app(
    TARGET MyApp
    URI MyApp
    QML_FILES
        Main.qml
)

설치 루트 ( /path/to/lvrs-prefix ) 에 CMAKE_PREFIX_PATH 를 설정하여 하위 소비 측 프로젝트를 구성합니다. lvrs_configure_qml_app() 는 설치된 패키지 소비를 위해 QT_QML_IMPORT_PATH 를 설정하고, 설정되지 않은 경우 기본 실행 가능 출력 디렉토리 ( <build>/bin ) 를 적용하며, 정적 패키지 빌드를 위해 정적 QML 플러그인 아티팩트 LVRS 를 자동으로 링크/가입합니다. LV.ApplicationWindow 는 모바일/데스크톱 재순서를 위한 적응형 레이아웃 정책 API 를 제공합니다.

  • scaffoldLayoutMode (auto, mobile, desktop)
  • scaffoldLayoutPlatform 오버라이드 (기본값 Qt.platform.os)
  • scaffoldForceDesktopOnLargeMobile + scaffoldMobileDesktopMinWidth
  • scaffoldPreferBottomNavigation + scaffoldBottomNavigationMaxItems
  • scaffoldCompactSpacingEnabled + scaffoldCompactSpacingBreakpoint
  • scaffoldNavRailMaxWidthRatio + scaffoldDrawerMarginSafety
  • 런타임 상태 플래그: adaptiveMobileLayout, adaptiveDesktopLayout, adaptiveRailNavigation, adaptiveDrawerNavigation, adaptiveBottomNavigation
  • matchesMedia() 토큰: mobile-layout, desktop-layout, rail-nav, drawer-nav, bottom-nav 상태는 페이지 스택 라우팅 ( LV.PageRouter ) 을 사용하고, 배치 는 RowLayout / ColumnLayout 플렉스 레이아웃을 LV.ApplicationWindow 내부에서 사용합니다. LV.ApplicationWindow 페이지 스택 API : pageRoutes , pageInitialPath , useInternalPageStack , activePageRouter , pageStackNavigated , pageStackNavigationFailed 입니다. 기본 auto 모드는 android / ios 에 대해 모바일 우선이며, 명시적으로 구성되지 않는 한 넓은 화면 모바일 창을 데스크톱 레일 레이아웃으로 강제로 설정하는 것을 방지합니다. desktop-compact 프로필 또한 항목 수가 설정된 제한에 맞을 때 하단 내비게이션을 선택합니다. 또한 런타임 타겟을 자동으로 생성합니다:
  • run_<target>_macos
  • run_<target>_linux
  • run_<target>_windows
  • run_<target>_ios
  • run_<target>_android
  • run_<target>_wasm 호스트 데스크탑 대상은 즉시 실행되는 반면, 호스트가 아닌 대상은 CMAKE_SYSTEM_NAME 재구성 힌트를 인쇄합니다. 또한 크로스 플랫폼 부트스트랩 대상을 생성합니다.
  • bootstrap_<target>_macos
  • bootstrap_<target>_linux
  • bootstrap_<target>_windows
  • bootstrap_<target>_ios
  • bootstrap_<target>_android
  • bootstrap_<target>_wasm
  • bootstrap_<target>_all 또한 실행/내보내기 편의 대상을 생성합니다.
  • launch_<target>_ios
  • launch_<target>_android
  • launch_<target>_wasm
  • export_<target>_xcodeproj
  • export_<target>_android_studio
  • export_<target>_wasm_site bootstrap_<target>_all 는 모든 플랫폼 부트스트랩 작업을 한 번의 빌드 호출에서 실행합니다. 데스크톱 부트스트랩 타겟은 실행 가능 아티팩트를 생성합니다. iOS 부트스트랩 는 기본적으로 Xcode 프로젝트를 생성하고 xcrun simctl 를 통해 시뮬레이터 앱을 설치합니다. Android 부트스트랩 는 기본적으로 Android 스튜디오 (Gradle) 프로젝트를 생성하고 adb 를 통해 APK 를 설치합니다. WASM 부트스트랩 는 브라우저 아티팩트를 방출하고 wasm 부트스트랩 빌드 트리에 LVRSWasmArtifact.cmake 엔트리 메타데이터를 작성합니다. launch_<target>_wasm 는 로컬 정적 HTTP 서버를 통해 wasm 빌드 트리를 제공하며 브라우저를 자동으로 열 수 있습니다. export_<target>_wasm_site 는 재귀적으로 wasm 웹 자산을 수집 (중첩 레이아웃 안전) 하고 감지된 엔트리에 대한 index.html 리디렉션을 생성합니다. 툴체인 /prefix 오버라이드:
  • LVRS_BOOTSTRAP_QT_PREFIX_<PLATFORM>
  • LVRS_BOOTSTRAP_QT_HOST_PREFIX (호스트 Qt 접두사를 위한 Android 배포 툴링 조회)
  • LVRS_BOOTSTRAP_TOOLCHAIN_FILE_<PLATFORM>
  • LVRS_BOOTSTRAP_GENERATOR_<PLATFORM>
  • LVRS_BOOTSTRAP_GENERATE_IOS_XCODE_PROJECT(iOS 부트스트랩의 경우 기본 ON)
  • LVRS_BOOTSTRAP_GENERATE_ANDROID_STUDIO_PROJECT(Android 부트스트랩의 경우 기본 ON)
  • LVRS_ANDROID_STUDIO_PROJECT_DIR(기본값: <platform-build>/android-studio)
  • LVRS_BOOTSTRAP_ANDROIDDEPLOYQT(androiddeployqt에 대한 명시적 경로 재정의)
  • LVRS_BOOTSTRAP_ANDROID_SDK_ROOT / LVRS_BOOTSTRAP_ANDROID_NDK (Android SDK/NDK 명시적 재정의)
  • LVRS_BOOTSTRAP_WASM_HOST / LVRS_BOOTSTRAP_WASM_PORT / LVRS_BOOTSTRAP_WASM_OPEN_BROWSER (WASM 실행 서버/브라우저 동작)
  • LVRS_IOS_SIMULATOR_NAME(기본값: iPhone 17 Pro)
  • LVRS_ANDROID_EMULATOR_SERIAL(기본값: emulator-5554)
  • LVRS_BOOTSTRAP_LVRS_ENABLE_PLATFORM_BUILD_OPTIMIZATIONS(LVRS_ENABLE_PLATFORM_BUILD_OPTIMIZATIONS를 부트스트랩 재구성으로 전파)
  • LVRS_BOOTSTRAP_LVRS_ENABLE_IPO(LVRS_ENABLE_IPO를 부트스트랩 재구성으로 전파) LVRS_DIR 및 패키지 레지스트리 정책(CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY, CMAKE_FIND_USE_PACKAGE_REGISTRY)은 호스트 구성 캐시에서 플랫폼별 부트스트랩 재구성으로 자동으로 전파됩니다. LVRS 패키지 구성 내보내기 플랫폼/ 툴체인 스크립트용 힌트 변수:
  • LVRS_LAYOUT_VERSION
  • LVRS_ACTIVE_PLATFORM
  • LVRS_ACTIVE_PREFIX
  • LVRS_QT_HOST_PREFIX_HINT
  • LVRS_QT_IOS_PREFIX_HINT
  • LVRS_QT_ANDROID_PREFIX_HINT
  • LVRS_QT_WASM_PREFIX_HINT
  • LVRS_ANDROID_SDK_HINT
  • LVRS_ANDROID_NDK_HINT
  • LVRS_EMSDK_HINT 예시 일회성 부트스트랩 명령:
cmake --build build --target bootstrap_MyApp_all

이 동작을 비활성화하려면 lvrs_configure_qml_app(<target> NO_PLATFORM_RUNTIME_TARGETS)를 사용하십시오. lvrs_add_qml_app()는 SOURCES가 생략되면 실행 준비된 진입점을 자동으로 생성할 수 있습니다. lvrs_configure_project_defaults()를 사용하여 Apple 번들/plist/자격, Android 패키지 소스 디렉터리/패키지 ID 및 iOS 플러그인 제외 기본값을 중앙 집중화합니다.

프레임워크 전용 부트스트랩 대상은 프로젝트 루트에서 생성됩니다.

  • bootstrap_lvrs_macos
  • bootstrap_lvrs_linux
  • bootstrap_lvrs_windows
  • bootstrap_lvrs_ios
  • bootstrap_lvrs_android
  • bootstrap_lvrs_wasm
  • bootstrap_lvrs_all bootstrap_lvrs_all는 <build>/lvrs-bootstrap/framework/<platform> 아래에 설정된 선택된 프레임워크 부트스트랩 플랫폼을 구축하고, LVRSCore를 빌드한 뒤 ${LVRS_BOOTSTRAP_INSTALL_ROOT}/<platform>에 설치합니다. 기본 프레임워크 부트스트랩 플랫폼 세트는 LVRS_BOOTSTRAP_FRAMEWORK_PLATFORMS가 제공되지 않는 한 해당 호스트에만 적용되는입니다. LVRS_BOOTSTRAP_INSTALL_PREFIX_<PLATFORM>를 사용하여 플랫폼별 설치 경로를 재정의하십시오. 크로스 호스트 플랫폼의 경우, LVRS_BOOTSTRAP_QT_PREFIX_<PLATFORM> 및 LVRS_BOOTSTRAP_TOOLCHAIN_FILE_<PLATFORM>를 통해 일치하는 Qt 키트/툴체인을 제공하십시오.

렌더링 백엔드 적용

구성 시 LVRS_ENFORCE_VULKAN=ON가 다음과 같은 경우:

  • macOS/iOS는 Qt Metal 지원(QT_FEATURE_metal >= 0)을 제공해야 합니다.
  • Windows/Android는 Qt Vulkan 지원(QT_FEATURE_vulkan >= 0)을 제공해야 합니다.
  • Vulkan::Vulkan는 Vulkan 고정 대상에 대해 검색 가능한 경우 사용되지만 구성 시 부재는 경고로 처리되고 대신 런타임 로더 검색이 사용됩니다.

런타임에서:

  • macOS/iOS는 Metal로 고정됩니다.
  • Windows/Android는 Vulkan로 고정됩니다.
  • Linux는 Qt 기본 백엔드 선택을 사용합니다.
  • 다른 플랫폼은 Qt 기본 백엔드 선택을 대체 경로로 사용합니다.
  • 고정된 백엔드를 초기화할 수 없으면 시작이 빠르게 실패합니다.

메모

  • Qt 6.5+와 Quick 및 QuickControls2가 필요합니다.
  • 백엔드 Qt 기능 검사가 CMakeLists.txt에서 발생하도록 수정되었습니다.
  • 백엔드 선택 로직은 backend/runtime/vulkanbootstrap.cpp에 있습니다.
  • 하위 소비 측 앱 부트스트랩 템플릿은 main.cpp에서 제공됩니다(기본적으로 빌드되지 않음).
  • 권장되는 재사용 가능한 부트스트랩 API는 backend/runtime/appbootstrap.h입니다.

CI 빌드 파이프라인 예시

최소 CI 파이프라인은 일반적으로 다음 시퀀스를 실행합니다.

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release
ctest --test-dir build --output-on-failure

테스트 대상이 없는 경우 ctest를 유지하되 테스트 통과 의미 없음을 허용하거나 프로젝트 옵션 뒤에 게이트를 지정하세요.

P4 품질 자동화 명령

P4 품질 자동화 스크립트는 tests/ci/ 아래에 제공됩니다.

# PR 통과 기준(성능 + 시각적 검증)
./tests/ci/run_p4_quality.sh

# Sanitizer 조합
./tests/ci/run_p4_sanitizers.sh address
./tests/ci/run_p4_sanitizers.sh undefined

# 장시간 지속 실행 묶음
LVRS_SOAK_ITERATIONS=5000 ./tests/ci/run_p4_soak.sh

자세한 계약 및 임계값은 docs/quality-automation-p4.md에 문서화되어 있습니다.

포장 체크리스트

LVRS 기반 바이너리를 배송하는 경우:

  1. 대상 OS에 대한 Qt 런타임 배포를 확인합니다.
  2. 패키지된 아티팩트에서 아이콘/글꼴 리소스를 사용할 수 있는지 확인하세요.
  3. 대상 머신의 그래픽 백엔드 요구 사항(Metal/Vulkan)을 확인하세요.
  4. 운영자를 위해 환경 재정의 확인(LVRS_APP_*)이 문서화되어 있습니다.

런타임 연기 테스트 스크립트

릴리스 후보의 경우 다음을 확인하는 스모크 테스트를 실행하세요.

  • 백엔드 부트스트랩 오류 없이 앱 프로세스가 시작됩니다.
  • 루트 QML가 성공적으로 로드되었습니다.
  • 경로 탐색은 적어도 하나의 정적 경로와 하나의 동적 경로에 대해 작동합니다.
  • input/런타임 이벤트는 창과 상호 작용할 때 캡처됩니다.