Aspose.PDF FOSS
C++
Troubleshooting

Troubleshooting

Build thất bại với lỗi C++20

Aspose.PDF FOSS cho C++ yêu cầu một trình biên dịch C++20 — clang 16+, gcc 13+, hoặc MSVC 2022 17.5+. Nếu quá trình biên dịch của bạn gặp lỗi như “designated initializers only allowed in C++20” hoặc “concepts require ‘-std=c++20’”, dự án đang sử dụng không bật chuẩn C++20.

Đặt chuẩn một cách rõ ràng trước khi thêm thư viện dưới dạng thư mục con:

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)

Trên dòng lệnh, điều này tương ứng với -std=c++20 (clang/gcc) hoặc /std:c++20 (MSVC).

Cấu hình CMake thất bại — Phiên bản quá cũ

Dự án yêu cầu CMake 3.22 trở lên. Chạy một phiên bản CMake cũ hơn sẽ gây ra lỗi tương tự như:

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

Kiểm tra phiên bản đã cài đặt và nâng cấp thay vì chỉnh sửa CMakeLists.txt đã được tích hợp:

cmake --version

Cài đặt phiên bản hiện tại từ cmake.org hoặc trình quản lý gói của bạn — phiên bản tối thiểu phản ánh các tính năng trình tạo và ngôn ngữ mà bản dựng thực sự sử dụng, không phải một ngưỡng tùy ý.

FetchContent Không tải xuống được kho lưu trữ

Nếu bạn đưa thư viện vào vendor bằng FetchContent thay vì add_subdirectory thủ công, các lỗi trong thời gian cấu hình thường là vấn đề mạng chứ không phải vấn đề 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 chạy git clone trong quá trình cấu hình CMake. Khi ở sau một proxy doanh nghiệp hoặc tường lửa, hoặc trên một runner CI không có kết nối mạng, việc này sẽ thất bại với Failed to clone repository. Để khắc phục:

  • Đặt HTTPS_PROXY/HTTP_PROXY cho bước cấu hình CMake, hoặc
  • Tiền-clone kho lưu trữ một lần và chỉ định FETCHCONTENT_SOURCE_DIR_ASPOSE_PDF_FOSS tới bản sao cục bộ để FetchContent tái sử dụng thay vì tải về qua mạng, hoặc
  • Đưa nguồn trực tiếp vào vendor và sử dụng add_subdirectory(), không có phụ thuộc mạng ở thời điểm cấu hình.

Tham chiếu không xác định / Ký hiệu bên ngoài chưa được giải quyết tại thời điểm liên kết

Quá trình biên dịch thành công nhưng liên kết thất bại với undefined reference to Aspose::Pdf::Document::... (gcc/clang) hoặc lỗi unresolved external symbol (MSVC). Điều này hầu hết luôn là một trong hai nguyên nhân:

  1. Bước liên kết bị thiếu — target_link_libraries(your_app PRIVATE aspose_pdf_foss) được thiếu hoặc viết sai. add_subdirectory() một mình chỉ làm cho các tiêu đề hiển thị; nó không liên kết thư viện tĩnh.
  2. Sự không khớp giữa thư viện thời gian chạy / kiểu dựng trên MSVC — liên kết một Release-được xây dựng aspose_pdf_foss.lib thành một Debug tệp thực thi (hoặc ngược lại) trộn lẫn các thư viện runtime C không tương thích và thất bại với LNK2038 sự không khớp. Xây dựng thư viện và ứng dụng của bạn với cùng một CMAKE_BUILD_TYPE (hoặc cùng một /MD//MDd cài đặt thư viện runtime).

Kiểm tra Kiểu Siêu dữ liệu XMP luôn trả về Sai

XmpValue — kiểu giá trị được trả về từ các mục Document.Metadata() — cung cấp các hàm trợ giúp kiểm tra kiểu IsDateTime(), IsField(), IsNamedValue(), IsRaw(), IsNamedValues(), và IsStructure(). Trong bản phát hành hiện tại, sáu phương pháp này là stub và luôn trả về false, vì vậy mã dựa vào chúng để phân biệt các loại giá trị XMP luôn đi theo nhánh “false”.

Sử dụng các kiểm tra đã được triển khai thay thế — IsString(), IsInteger(), IsDouble(), IsArray() — hoặc gọi trực tiếp accessor tương ứng (ToStringValue(), ToInteger(), ToDouble(), ToArray()) khi loại giá trị đã được biết từ ngữ cảnh. Một số ít các kiểu nội bộ cấp thấp (BitmapInfo có hàm khởi tạo mặc định, và các kiểu nội bộ Encoding và Value được sử dụng bởi mô hình đối tượng PDF) cũng chứa các thân stub không được thực thi trong mã xử lý tài liệu thông thường.

Xem thêm

 Tiếng Việt