Миграция с версии 3.29.2 на 3.32.7

Необходимо использовать инструкции ниже, чтобы подготовить проект для работы с новой версией. Этот раздел предназначен для миграции Flutter плагинов и приложений с версии 3.29.2 на 3.32.7.

• Миграция приложения
  • Подготовка к миграции приложения
  • Миграция приложения через create
  • Ручная миграция приложения
• Использование File Selector
• Использование Image Picker
• Изменения в Aurora Devices
• Миграция плагина
  • Подготовка к миграции плагина
  • Миграция плагина через create
  • Ручная миграция плагина
• Распространённые проблемы

Миграция приложения

Подготовка к миграции приложения

Следует добавить поля description, organization и version в файл pubspec.yaml, если их ещё нет:

name: example_app
+description: "Example app description"
+organization: "ru.example"
+version: 0.1.0
publish_to: 'none'

Они предоставляют ОС информацию о пакете (данные автоматически добавляются в файлы aurora/rpm/*.spec и aurora/desktop/*.desktop).

Следует исключить генерируемые файлы из системы контроля версий. Чтобы это сделать, нужно изменить файл aurora/.gitignore следующим образом:

/flutter

+/rpm/requires.inc
+/rpm/defines.inc

В новой версии Flutter файлы aurora/rpm/*.spec и aurora/desktop/*.desktop пересоздаются при каждой сборке проекта, это нужно для автоматической подстановки значений BuildRequires и Permissions. Чтобы этого избежать, нужно удалить или не добавлять строку в начале файла:

1. aurora/rpm/*.spec

   -%dnl This file will be recreated at the next build. To avoid this, delete this line.
   

2. aurora/desktop/*.desktop

   -# This file will be recreated at the next build. To avoid this, delete this line.
   

   В переменной %requires аккумулируются BuildRequires из всех плагинов, указанных в pubspec.yaml.

   -BuildRequires: cmake
   -BuildRequires: ninja
   +%requires
   

3. Если в aurora/CMakeLists.txt требуется дополнительная логика, нужно удалить или не добавлять строку в начале файла:

   -# This file will be recreated at the next build. To avoid this, delete this line.
   

Миграция приложения через create

Плагин может мигрировать на новую версию Flutter с помощью flutter-aurora create. Для этого необходимо удалить директорию aurora внутри директории с проектом, после чего выполнить следующую команду в корневой директории проекта:

flutter-aurora create --platform=aurora --org={organization} .

Если приложению требуется поддержка сигналов и слотов Qt, то после выполнения flutter-aurora create следует вернуть директивы, отвечающие за поддержку Qt:

#include "generated_plugin_registrant.h"
+#include <flutter/flutter_compatibility_qt.h>

int main(int argc, char* argv[]) {
    aurora::FlutterApp app(argc, argv);
+   aurora::EnableQtCompatibility();
    return app.exec();
}

Ручная миграция приложения

Для выполнения миграции вручную необходимо внести следующие изменения в файлы проекта:

1. aurora/CMakeLists.txt:

   +# This file will be recreated at the next build. To avoid this, delete this line.
   
   # CMAKE_SYSTEM_PROCESSOR - CPU architecture name (armv7l, aarch64, x86_64)
   # CMAKE_BUILD_TYPE       - Build mode (debug, profile, release)
   # PSDK_VERSION           - Build psdk exact version
   set(CMAKE_CXX_FLAGS_RELEASE "-O3")
   set(CMAKE_SKIP_RPATH OFF)
   set(CMAKE_INSTALL_RPATH "\$ORIGIN/../share/${BINARY_NAME}/lib")
   
   -find_package(PkgConfig REQUIRED)
   -pkg_check_modules(FlutterEmbedder REQUIRED IMPORTED_TARGET flutter-embedder)
   -
   -add_executable(${BINARY_NAME} main.cpp ${FLUTTER_DIR}/generated_plugin_registrant.cpp)
   -target_link_libraries(${BINARY_NAME} PRIVATE PkgConfig::FlutterEmbedder)
   -target_include_directories(${BINARY_NAME} PRIVATE ${FLUTTER_DIR})
   +add_executable(${BINARY_NAME} main.cpp)
   
   include(flutter/generated_plugins.cmake)
   +target_link_libraries(${BINARY_NAME} PRIVATE aurora_embedder::aurora_embedder)
   target_include_directories(${BINARY_NAME} PRIVATE ${FLUTTER_DIR})
   
   set(PACKAGE_INSTALL_DIR    ${CMAKE_INSTALL_DATADIR}/${BINARY_NAME})
   set(DESKTOP_INSTALL_DIR    ${CMAKE_INSTALL_DATADIR}/applications)
   set(ICONS_INSTALL_ROOT_DIR ${CMAKE_INSTALL_DATADIR}/icons/hicolor)
   
   -add_custom_command(TARGET ${BINARY_NAME} POST_BUILD
   -                   COMMAND ${CMAKE_COMMAND} -E copy
   -                   ${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_LIBDIR}/libflutter-embedder.so
   -                   ${PROJECT_BINARY_DIR}/bundle/lib/libflutter-embedder.so)
   
   install(FILES     ${PROJECT_BINARY_DIR}/bundle/icudtl.dat     DESTINATION ${PACKAGE_INSTALL_DIR})
   install(DIRECTORY ${PROJECT_BINARY_DIR}/bundle/flutter_assets DESTINATION ${PACKAGE_INSTALL_DIR})
   install(DIRECTORY ${PROJECT_BINARY_DIR}/bundle/lib            DESTINATION ${PACKAGE_INSTALL_DIR})
   

2. aurora/main.cpp:

   -#include <flutter/flutter_aurora.h>
   #include "generated_plugin_registrant.h"
   
   int main(int argc, char *argv[]) {
   -  aurora::Initialize(argc, argv);
   -  aurora::RegisterPlugins();
   -  aurora::Launch();
   -  return 0;
   +  aurora::FlutterApp app(argc, argv);
   +  return app.exec();
   }
   

3. aurora/rpm/*.spec:

   +%dnl This file will be recreated at the next build. To avoid this, delete this line.
   ...
   

4. aurora/desktop/*.desktop:

   +# This file will be recreated at the next build. To avoid this, delete this line.
   ...
   

Использование File Selector

Если в проекте используется плагин File Selector, в проект необходимо внести некоторые изменения.

1. main.dart:

   - import 'package:file_selector_aurora/file_selector_aurora.dart';
   
   - final navigatorKey = GlobalKey<NavigatorState>();
   
   void main() {
   - // Put navigatorKey to FileSelectorAuroraKeyContainer
   - FileSelectorAuroraKeyContainer.navigatorKey = navigatorKey;
   + WidgetsFlutterBinding.ensureInitialized();
     runApp(const MyApp());
   }
   
   @override
   Widget build(BuildContext context) {
     return MaterialApp(
   -    navigatorKey: navigatorKey,
     );
   }
   

2. pubspec.yaml:

   dependencies:
   -  file_selector_aurora: ^0.2.0
   

Использование Image Picker

Если в проекте используется плагин Image Picker, то в проект необходимо внести изменения.

1. main.dart:

   - import 'package:image_picker_aurora/image_picker_aurora.dart';
   
   - final navigatorKey = GlobalKey<NavigatorState>();
   
   void main() {
   - setUpDefaultAuroraCameraDelegate(navigatorKey);
     runApp(const MyApp());
   }
   
   @override
   Widget build(BuildContext context) {
     return MaterialApp(
   -    navigatorKey: navigatorKey,
     );
   }
   

2. pubspec.yaml:

   dependencies:
   -  image_picker_aurora: ^1.0.0
   

Изменения в Aurora Devices

Конфигурация устройств была обновлена. Для того чтобы различать устройства по типу подключения (attached или wireless), необходимо их удалить и заново добавить.

Для получения списка устройств и их id следует использовать команду:

flutter-aurora aurora-devices list

Для удаления устройства следует использовать команду:

flutter-aurora aurora-devices delete -d device_id

• Строку device_id следует заменить на id устройства.

Для добавления устройства следует использовать команду:

flutter-aurora aurora-devices add

Подробнее о настройке устройств можно пожно почитать в разделе Настройка устройств.

Миграция плагина

Для миграции примера в плагине можно воспользоваться пунктом Миграция приложения.

Подготовка к миграции плагина

При разработке плагинов список пакетов, необходимых для сборки, нужно указывать в pubspec.yaml плагина через ключ buildRequires:

flutter:
  plugin:
    implements: camera
    platforms:
      aurora:
        pluginClass: CameraAuroraPlugin
        dartPluginClass: CameraAurora
+       buildRequires:
+         - pkgconfig(Qt5Core)
+         - pkgconfig(glesv2)
+         - pkgconfig(runtime-manager-qt5)

Аналогичным образом список разрешений, необходимых для приложений, использующих плагин, указывается в pubspec.yaml через ключ permissions:

flutter:
  plugin:
    implements: camera
    platforms:
      aurora:
        pluginClass: CameraAuroraPlugin
        dartPluginClass: CameraAurora
+       permissions:
+          - Audio
+          - UserDirs

Полный список разрешений можно посмотреть в документации.

Миграция плагина через create

Миграция плагина через flutter-aurora create производится аналогично обновлению плагина, нужно удалить директорию aurora, после чего выполнить команду:

flutter-aurora create --template=plugin --platform=aurora --org={organization} .

Поле {organization} необходимо заменить на название организации, например ru.example.

После выполнения команды нативная логика будет удалена (например, aurora/lib/). Можно воспользоваться системой контроля версий, чтобы вернуть файлы.

Если в aurora/CMakeLists.txt есть дополнительная логика, нужно восстановить блоки кода, оставив при этом изменения новой версии (см. Ручная миграция плагина).

Альтернативой является ручное редактирование файлов проекта по инструкции ниже.

Ручная миграция плагина

Для выполнения перехода на новую версию вручную необходимо изменить файл aurora/CMakeLists.txt следующим образом:

set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_FLAGS "-Wall -Wextra -Wno-psabi")
set(CMAKE_CXX_FLAGS_RELEASE "-O3")

-find_package(PkgConfig REQUIRED)
-pkg_check_modules(FlutterEmbedder REQUIRED IMPORTED_TARGET flutter-embedder)

add_library(${PLUGIN_NAME} SHARED
    test_plugin.cc
    test_plugin_impl.cc
    test_plugin_impl.h
)

set_target_properties(${PLUGIN_NAME} PROPERTIES CXX_VISIBILITY_PRESET hidden)
-target_link_libraries(${PLUGIN_NAME} PRIVATE PkgConfig::FlutterEmbedder)
+target_link_libraries(${PLUGIN_NAME} PRIVATE aurora_embedder::aurora_embedder)

target_include_directories(${PLUGIN_NAME} PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include)
target_compile_definitions(${PLUGIN_NAME} PRIVATE PLUGIN_IMPL)

Распространённые проблемы

Если при запуске приложения возникает ошибка со следующим текстом:

[libflutter-embedder.so] Dependency is not allowed

Это означает, что в проекте используется плагин с несовместимой версией Flutter.