Aspose.PDF FOSS
C++
Troubleshooting

Troubleshooting

빌드가 C++20 오류로 실패함

Aspose.PDF FOSS for C++는 C++20 컴파일러가 필요합니다 — clang 16+, gcc 13+, 또는 MSVC 2022 17.5+. 빌드가 “designated initializers only allowed in C++20” 또는 “concepts require ‘-std=c++20’“와 같은 오류로 실패한다면, 해당 프로젝트가 C++20 표준을 활성화하여 컴파일하고 있지 않은 것입니다.

라이브러리를 서브디렉터리로 추가하기 전에 표준을 명시적으로 설정하세요:

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
add_subdirectory(aspose.pdf-foss-for-cpp)
target_link_libraries(your_app PRIVATE aspose_pdf_foss)

명령줄에서는 이것이 -std=c++20 (clang/gcc) 또는 /std:c++20 (MSVC)에 해당합니다.

CMake 구성 실패 — 버전이 너무 낮음

이 프로젝트는 CMake 3.22 이상이 필요합니다. 오래된 CMake를 실행하면 다음과 유사한 오류가 발생합니다:

CMake Error at CMakeLists.txt:1 (cmake_minimum_required):
  CMake 3.22 or higher is required.  You are running version 3.16.3

vendored CMakeLists.txt를 수정하기보다 설치된 버전을 확인하고 업그레이드하세요:

cmake --version

현재 릴리스를 다음에서 설치하십시오 cmake.org 또는 패키지 관리자를 사용하십시오 — 최소 버전은 빌드가 실제로 사용하는 생성기 및 언어 기능을 반영하며, 임의의 기준이 아닙니다.

FetchContent 저장소 다운로드 실패

수동 add_subdirectory 대신 FetchContent 로 라이브러리를 벤더링하는 경우, 설정 시 발생하는 실패는 대개 CMake 문제보다는 네트워크 문제입니다:

include(FetchContent)
FetchContent_Declare(
    aspose_pdf_foss
    GIT_REPOSITORY https://github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-Cpp.git
    GIT_TAG        main
)
FetchContent_MakeAvailable(aspose_pdf_foss)
target_link_libraries(your_app PRIVATE aspose_pdf_foss)

FetchContent_MakeAvailable은(는) CMake 설정 중에 git clone을(를) 실행합니다. 기업 프록시나 방화벽 뒤에 있거나, 네트워크가 차단된 CI 러너에서 실행하면 Failed to clone repository 오류가 발생합니다. 해결 방법:

  • CMake 설정 단계에서 HTTPS_PROXY/HTTP_PROXY을(를) 설정하거나,
  • 저장소를 한 번 미리 클론하고 FETCHCONTENT_SOURCE_DIR_ASPOSE_PDF_FOSS을(를) 로컬 체크아웃으로 지정하여 FetchContent이 네트워크를 통해 가져오는 대신 재사용하도록 하거나,
  • 소스를 직접 벤더링하고 add_subdirectory()을(를) 사용하세요. 이는 설정 시 네트워크 의존성이 없습니다.

링크 단계에서 정의되지 않은 참조 / 해결되지 않은 외부 심볼

컴파일은 성공하지만 링크 단계에서 undefined reference to Aspose::Pdf::Document::... (gcc/clang) 오류 또는 unresolved external symbol 오류 (MSVC)가 발생합니다. 이는 거의 항상 두 가지 원인 중 하나입니다:

  1. 링크 단계 누락 — target_link_libraries(your_app PRIVATE aspose_pdf_foss) 가 누락되었거나 잘못 표기되었습니다. add_subdirectory() 단독으로는 헤더만 보이게 하며, 정적 라이브러리를 링크하지 않습니다.
  2. MSVC에서 런타임 라이브러리 / 빌드 유형 불일치 — 링크 a Release-빌드된 aspose_pdf_foss.lib 로 Debug 실행 파일(또는 그 반대) 은 호환되지 않는 C 런타임 라이브러리를 혼합하고 실패합니다 LNK2038 불일치가 발생합니다. 라이브러리와 애플리케이션을 동일한 CMAKE_BUILD_TYPE (또는 동일한 /MD//MDd 런타임 라이브러리 설정).

XMP 메타데이터 타입 검사는 항상 false를 반환합니다

XmpValue — Document.Metadata() 항목에서 반환되는 값 타입 — 은 타입 검사 헬퍼 IsDateTime(), IsField(), IsNamedValue(), IsRaw(), IsNamedValues(), IsStructure()을 제공합니다. 현재 릴리스에서는 이 여섯 메서드가 스텁으로, 무조건 false을 반환하므로 XMP 값 종류를 구분하기 위해 이 메서드들에 분기하는 코드는 항상 “false” 경로를 택합니다.

대신 구현된 검사를 사용하십시오 — IsString(), IsInteger(), IsDouble(), IsArray() — 또는 값의 종류가 컨텍스트에서 이미 알려진 경우 일치하는 접근자(ToStringValue(), ToInteger(), ToDouble(), ToArray())를 직접 호출하십시오. 소수의 저수준 내부 타입(BitmapInfo의 기본 생성자와 PDF 객체 모델에서 사용되는 내부 Encoding 및 Value 타입)도 스텁 구현을 가지고 있어 일반적인 문서 처리 코드에서는 사용되지 않습니다.

참조

 한국어