Интеграция

Plugify разработан для легкой интеграции в ваши проекты, будь то платформа для моддинга игр, автономное приложение или система на основе плагинов. Это руководство проведет вас через процесс интеграции Plugify в ваш проект с использованием CMake, охватывая как внешний, так и встроенный методы интеграции.

Методы интеграции

1. Внешняя интеграция

Чтобы использовать Plugify как внешнюю библиотеку, вы можете найти ее напрямую с помощью find_package() в вашем проекте CMake. Этот метод идеален, если вы хотите оставить Plugify в качестве отдельной зависимости.

Пример:

find_package(plugify REQUIRED)
...
add_library(foo ...)
...
target_link_libraries(foo PRIVATE plugify::plugify)

2. Встроенная интеграция

Если вы предпочитаете встраивать Plugify непосредственно в ваш проект, вы можете включить все дерево исходного кода как подкаталог. Этот метод полезен, если вы хотите настроить или расширить функциональность Plugify.

Пример:

# Disable tests for third-party libraries
set(PLUGIFY_BUILD_TESTS OFF CACHE INTERNAL "")

# Add Plugify as a subdirectory
add_subdirectory(plugify)
...
add_library(foo ...)
...
target_link_libraries(foo PRIVATE plugify::plugify)

3. Встроенная интеграция с FetchContent

Для проектов, использующих CMake 3.11 или новее, вы можете использовать модуль FetchContent для автоматической загрузки и интеграции Plugify во время конфигурации.

Пример:

include(FetchContent)

FetchContent_Declare(
plugify
URL https://github.com/untrustedmodders/plugify/releases/download/v1.0.0/plugify.tar.xz
)
FetchContent_MakeAvailable(plugify)

target_link_libraries(foo PRIVATE plugify::plugify)

Примечание: Подход с URL рекомендуется для стабильных релизов. Для получения дополнительной информации см. документацию FetchContent.

4. Поддержка как внешней, так и встроенной интеграции

Если вы хотите, чтобы ваш проект поддерживал как внешнюю, так и встроенную интеграцию, вы можете использовать следующий шаблон:

Верхний уровень

project(FOO)
...
option(FOO_USE_EXTERNAL_PLUGIFY "Use an external Plugify library" OFF)
...
add_subdirectory(thirdparty)
...
add_library(foo ...)
...
target_link_libraries(foo PRIVATE plugify::plugify)

Thirdparty

if(FOO_USE_EXTERNAL_PLUGIFY)
    find_package(plugify REQUIRED)
else()
    add_subdirectory(plugify)
endif()

В этой конфигурации thirdparty/plugify должен содержать полную копию дерева исходного кода Plugify.

Пример: Инициализация Plugify в вашем приложении

После интеграции вы можете инициализировать Plugify в вашем приложении следующим образом:

int main() {
    auto result = plugify::MakePlugify("./app");
    if (!result) {
        std::cerr << "Failed to create Plugify: " << result.error().message << std::endl;
        return 1;
    }

    auto plugify = result.value();
    if (auto initResult = plugify->Initialize(); !initResult) {
        std::cerr << "Failed to initialize: " << initResult.error().message << std::endl;
        return 1;
    }

    // Load extensions
    const auto& manager = plugify->GetManager();
    manager->Initialize();

    // Main loop
    bool running = true;
    while (running) {
        plugify->Update();
        // Your application logic here
    }

    plugify->Terminate();
    return 0;
}

Рекомендации

1. Используйте одинаковые среды сборки:
   • Убедитесь, что Plugify и ваш проект собираются с одним и тем же компилятором и версией C++, чтобы избежать проблем с совместимостью.
2. Отключайте ненужные функции:
   • Если вам не нужны тесты или документация, отключите их с помощью опций CMake, таких как PLUGIFY_BUILD_TESTS и PLUGIFY_BUILD_DOCS.
3. Корректно обрабатывайте ошибки:
   • Всегда проверяйте возвращаемые значения функций инициализации и управления Plugify для эффективной обработки ошибок.
4. Используйте FetchContent для стабильных релизов:
   • При использовании FetchContent предпочитайте загружать стабильные релизы с GitHub для обеспечения совместимости и надежности.

Устранение неполадок

• Отсутствующие пакеты: Если менеджер пакетов сообщает об отсутствующих пакетах, убедитесь, что необходимые пакеты доступны в настроенных каталогах или репозиториях.
• Конфликтующие пакеты: Разрешите конфликты, удалив или обновив конфликтующие пакеты.
• Ошибки сборки: Убедитесь, что ваша конфигурация CMake соответствует требованиям Plugify (например, C++20, совместимые компиляторы).