Интеграция

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() {
   // Create a Plugify instance
   std::shared_ptr<plugify::IPlugify> instance = plugify::MakePlugify();
   if (instance) {
       // Set up logging
       auto logger = std::make_shared<CustomLogger>();
       instance->SetLogger(logger);
       logger->SetSeverity(plugify::Severity::Debug);

         // Initialize Plugify
         if (!instance->Initialize()) {
             std::cerr << "Failed to initialize Plugify!" << std::endl;
             return EXIT_FAILURE;
         }
       
         // Access the Package Manager
         if (auto packageManager = instance->GetPackageManager().lock()) {
             packageManager->Initialize();
       
             // Handle missing or conflicted packages
             if (packageManager->HasMissedPackages()) {
                 std::cerr << "Plugin manager has missing packages." << std::endl;
                 packageManager->InstallMissedPackages();
             }
             if (packageManager->HasConflictedPackages()) {
                 std::cerr << "Plugin manager has conflicted packages." << std::endl;
                 packageManager->UninstallConflictedPackages();
            }
         }
       
         // Access the Plugin Manager
         if (auto pluginManager = instance->GetPluginManager().lock()) {
            pluginManager->Initialize();
        }
    }
    return EXIT_SUCCESS;
}

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

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

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

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