diff --git a/ohos/docs/03_environment/openharmony-flutter-environment-setup.md b/ohos/docs/03_environment/openharmony-flutter-environment-setup.md index 0cbcacb272d4d3e9495ef5f8b80b0592ae83e37c..16de9ecb64e91e88ce16c1bcea2a9cd9096ad6d2 100644 --- a/ohos/docs/03_environment/openharmony-flutter-environment-setup.md +++ b/ohos/docs/03_environment/openharmony-flutter-environment-setup.md @@ -5,8 +5,7 @@ ### 1. Downloading and Installing the Latest DevEco Studio Development Suite and Its Dependencies #### 1.1 Official Download URL -Official download address of the Harmony development suite: https://developer.huawei.com/consumer/cn/download/ - +Official download address of the OpenHarmony development suite: https://developer.huawei.com/consumer/cn/download/ ``` Note: (1) The development suite is supported in Linux, macOS, and Windows systems. @@ -22,15 +21,13 @@ Official download address of the Harmony development suite: https://developer.hu ![](../media/03_1/img_17_EN.png) -##### (2) Download an emulator in DevEco Studio if no real OpenHarmony device is available. -For details about how to download and install the emulator, see section 2.2 "Install an emulator." +##### (2) Download an Emulator in DevEco Studio if no real OpenHarmony device is available. +For details about how to download and install the Emulator, see section 2.2 "Install an Emulator." ##### (3) Download OpenHarmony Flutter. + Project URL: https://gitee.com/openharmony-sig/flutter_flutter -Project URL: https://gitee.com/openharmony-sig/flutter_flutter - -Use a code editor to download the repository to your local PC and specify the dev or master branch. The dev branch is continuously updated and has more features than the master branch. - + Use a code editor to download the repository to your local PC and specify the dev or master branch. The dev branch is continuously updated and has more features than the master branch. ``` 1 git clone https://gitee.com/openharmony-sig/flutter_flutter.git 2 git checkout -b dev origin/dev @@ -39,17 +36,16 @@ Use a code editor to download the repository to your local PC and specify the de * Building a Flutter project requires the use of **ohos_debug_unopt_arm64** and **ohos_release_arm64**. * Add the `--local-engine=src/out/` to the running parameters of the Flutter Tools instruction to specify the engine to be downloaded. Otherwise, the latest engine on the cloud is used by default. Example: flutter build hap [--local-engine=/Users/admin/Documents/flutter_engine/src/out/ohos_debug_unopt_arm64]. * [Download the build products](https://docs.qq.com/sheet/DUnljRVBYUWZKZEtF?tab=BB08J2). -* The engine path must contain the **src/out** directory. After you decompress the downloaded package of the build products, save it to the local path with the **src/out** directory, for example, **/Users/lihui/Documents/flutter_engine/src/out**. +* The engine's local path must contain the **src/out** directory. After you decompress the downloaded package of the build products, save it to a local path with the **src/out** directory, for example, **/Users/admin/Documents/flutter_engine/src/out**. ![](../media/03_1/img_4_EN.png) #### 1.3 Preinstalled Environment Dependencies -* The OpenHarmony SDK requires the Java environment. You can download JDK 17 from the [Oracle website](https://www.oracle.com/java/technologies/downloads/#java17) or OpenJDK website and set up the environment. +* The OpenHarmony SDK requires the Java environment. You can download JDK 17 from the [Oracle website](https://www.oracle.com/java/technologies/downloads/#java17) or OpenJDK website and set the environment. * Execute the following instruction to check the JDK installation result: - - ```sh - java -version - ``` +```sh +java -version +``` ### 2. How to Install @@ -57,7 +53,7 @@ Use a code editor to download the repository to your local PC and specify the de ![](../media/03_1/img_01.png) -#### 2.2 Install an emulator. +#### 2.2 Install an Emulator. ![](../media/03_1/img_18.png) ![](../media/03_1/img_18_1_EN.png) ![](../media/03_1/img_18_2_EN.png) @@ -67,71 +63,62 @@ Use a code editor to download the repository to your local PC and specify the de #### 2.3 Configure environment variables. * Use the terminal tool to determine the storage path of the actual environment variables in the current system. Execute the following instruction: - - ```sh - echo $SHELL - ``` - +```sh +echo $SHELL +``` * If the output is `/bin/bash`, execute the following instruction to open the **.bash_profile** file: - - ```sh - vi ~/.bash_profile - ``` - +```sh +vi ~/.bash_profile +``` * If the output is `/bin/zsh`, execute the following instruction to open the **.zshrc** file: - - ```sh - vi ~/.zshrc - ``` - +```sh +vi ~/.zshrc +``` * After you get the environment variable storage file, configure the environment variables. For example, open the **bash_profile** file and execute the `vi ~/.bash_profile` instruction. +```sh - ```sh - - # Mirror inside china - export PUB_HOSTED_URL=https://pub.flutter-io.cn - export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn - - # flutter_flutter/bin directory pulled from Flutter pub - export PATH=/Users/admin/ohos/flutter_flutter/bin:$PATH - - # OpenHarmony SDK - export TOOL_HOME=/Applications/DevEco-Studio.app/Contents # macOS environment - export DEVECO_SDK_HOME=$TOOL_HOME/sdk # command-line-tools/sdk - export PATH=$TOOL_HOME/tools/ohpm/bin:$PATH # command-line-tools/ohpm/bin - export PATH=$TOOL_HOME/tools/hvigor/bin:$PATH # command-line-tools/hvigor/bin - export PATH=$TOOL_HOME/tools/node/bin:$PATH # command-line-tools/tool/node/bin - export HDC_HOME=$TOOL_HOME/sdk/default/openharmony/toolchains # (Optional) hdc instruction - - # Optional configuration items (required when using the Android Studio or Visual Studio Code to debug. The JDK version is 17.0.12) - JAVA_HOME=/Users/admin/Documents/JDK/jdk-17.0.12.jdk/Contents/Home - PATH=$JAVA_HOME/bin:$PATH:. - export JAVA_HOME - export PATH - - # Optional configuration item (to prevent the creation of subsequent Flutter projects from being affected by the mismatched environment variable of the Gitee download URL for OpenHarmony Flutter) - export FLUTTER_GIT_URL=https://gitee.com/openharmony-sig/flutter_flutter.git - - # Optional configuration item (required only when there is no node environment in the tool file under the command-line-tools directory) - # export NODE_HOME=/Users/lihui/node/node-18.14.1 - # export PATH=$PATH:$NODE_HOME/bin - ``` - +# Mirror inside China +export PUB_HOSTED_URL=https://pub.flutter-io.cn +export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn + +# flutter_flutter/bin directory pulled from Flutter pub +export PATH=/Users/admin/ohos/flutter_flutter/bin:$PATH + +# OpenHarmony SDK +export TOOL_HOME=/Applications/DevEco-Studio.app/Contents # macOS environment +export DEVECO_SDK_HOME=$TOOL_HOME/sdk # command-line-tools/sdk +export PATH=$TOOL_HOME/tools/ohpm/bin:$PATH # command-line-tools/ohpm/bin +export PATH=$TOOL_HOME/tools/hvigor/bin:$PATH # command-line-tools/hvigor/bin +export PATH=$TOOL_HOME/tools/node/bin:$PATH # command-line-tools/tool/node/bin +export HDC_HOME=$TOOL_HOME/sdk/default/openharmony/toolchains # (Optional) hdc instruction + +# Optional configuration items (required when using the Android Studio or Visual Studio Code to debug. The JDK version is 17.0.12) +JAVA_HOME=/Users/admin/Documents/JDK/jdk-17.0.12.jdk/Contents/Home +PATH=$JAVA_HOME/bin:$PATH:. +export JAVA_HOME +export PATH + +# Optional configuration item (to prevent the creation of subsequent Flutter projects from being affected by the mismatched environment variable of the Gitee download URL for OpenHarmony Flutter) +export FLUTTER_GIT_URL=https://gitee.com/openharmony-sig/flutter_flutter.git + +# Optional configuration item (required only when there is no node environment in the tool file under the command-line-tools directory) +# export NODE_HOME=/Users/admin/node/node-18.14.1 +# export PATH=$PATH:$NODE_HOME/bin +``` * After all required environment variables are configured, execute the following instruction to update the environment configuration for making it take effect: +```sh +source ~/.bash_profile +``` - ```sh - source ~/.bash_profile - ``` - -#### 2.4 Run the emulator. +#### 2.4 Run the Emulator. ![](../media/03_1/m1_EN.png) -Create an emulator. +Create an Emulator. ![](../media/03_1/img.png) -Start the emulator. +Start the Emulator. ![](../media/03_1/m2_EN.png) @@ -171,21 +158,19 @@ Before running the project on a real device, you need to sign the project. Steps #### 3.2 Run the project on a real device. * Execute the `flutter devices` instruction to discover a real device and obtain the device ID. - Method 1: Go to the project directory, compile the HAP in the specified build mode, and install it on the OpenHarmony device. - - ```sh - flutter run --debug -d - ``` - - Method 2: Go to the project root directory, compile the HAP, and install it on the OpenHarmony device. +Method 1: Go to the project directory, compile the HAP in the specified build mode, and install it on the OpenHarmony device. +```sh + flutter run --debug -d +``` - ```sh - flutter build hap --debug - hdc -t install - ``` +Method 2: Go to the project root directory, compile the HAP, and install it on the OpenHarmony device. +```sh + flutter build hap --debug + hdc -t install +``` - Method 3: Use DevEco Studio to set your phone as the real device and start running. - ![](../media/03_1/img12.png) +Method 3: Use DevEco Studio to set your phone as the real device and start running. +![](../media/03_1/img12.png) ### 4. Running the Flutter Project on an Emulator @@ -193,7 +178,7 @@ Before running the project on a real device, you need to sign the project. Steps ![](../media/03_1/open_ohos.png) -#### 4.2 Start the OpenHarmony emulator in DevEco Studio. +#### 4.2 Start the OpenHarmony Emulator in DevEco Studio. ![](../media/03_1/m1_EN.png) @@ -201,7 +186,7 @@ Before running the project on a real device, you need to sign the project. Steps ![](../media/03_1/m3_EN.png) -Switch to the OpenHarmony emulator. +Switch to the OpenHarmony Emulator. ![](../media/03_1/img00_EN.png) @@ -209,21 +194,24 @@ Switch to the OpenHarmony emulator. ![](../media/03_1/img9_EN.png) -![](../media/03_1/img_10_EN.png) +![](../media/03_1/img10.png) ### 5. FAQs on Emulator Running #### 5.1 Unable to Create an Emulator Case 1: Use an account that has passed real-name authentication to sign in. +#### 5.2 Unable to Run the Emulator on Windows or macOS x86 Architecture +Currently, the Emulator supports the macOS ARM architecture, and Flutter has not been adapted to the x86 architecture. Therefore, you cannot run the Emulator on Windows or Mac x86 architecture. ### 6. FAQs on pub upgrade Instruction #### 6.1 Executing the pub upgrade Takes a Long Time -Case 1: A large number of files need to be loaded for the first time. The time required varies greatly depending on the network conditions. Please wait. +Case 1: A large number of files need to be pulled for the first loading. The time required varies according to the network status. If the download fails, check the network connection or replace the proxy, and try again. Case 2: Delete the **flutter_flutter/bin/cache** file and try again. Case 3: Replace the source of the mirror. Example: PUB_HOSTED_URL=https://mirrors.tuna.tsinghua.edu.cn/dart-pub - FLUTTER_STORAGE_BASE_URL=https://mirrors.tuna.tsinghua.edu.cn/flutter \ No newline at end of file + FLUTTER_STORAGE_BASE_URL=https://mirrors.tuna.tsinghua.edu.cn/flutter + diff --git a/ohos/docs/04_development/README_EN.md b/ohos/docs/04_development/README_EN.md index a6705b7f017349fd2b8c2a973dd1e38a2bb733ac..385544537cffd8314f2f8cd406fe1e9c07d76076 100644 --- a/ohos/docs/04_development/README_EN.md +++ b/ohos/docs/04_development/README_EN.md @@ -3,23 +3,22 @@ ## Adding a Flutter Page to Your OpenHarmony Application 1. [Using FlutterPage](./using-flutterpage.md) -2. [Using FlutterEntry](./using-flutterentry.md) +2. [Using FlutterEntry in Hybrid Development](./using-flutterEntry-in-hybrid-development.md) -## Using a Flutter Platform Channel in Your OpenHarmony Application +## Using a Flutter Channel in Your OpenHarmony Application -1. [Using a Flutter Platform Channel](./using-a-flutter-platform-channel.md) +1. [Using a Flutter Channel for Communication Between Flutter and OpenHarmony](./using-a-flutter-channel-for-communication-between-flutter-and-openharmony.md) ## Hybrid Rendering with Native Code 1. [External Texture Adaptation for Flutter](./external-texture-adaptation-for-flutter.md) 2. [Using FlutterEngineGroup](./using-flutterenginegroup.md) 3. [Using a Platform View](./using-a-platform-view.md) -4. [Platform View Same-Layer Rendering Adaptation and Switching](./platform-view-same-layer-rendering-adaptation-and-switching.md) +4. [Platform View Same-Layer Rendering Adaptation and Switching](./platform-view-same-layer-rendering-solution-adaptation-and-switching.md) ## Developing a Flutter Static Library -1. [Developing a Module](./developing-a-module.md) +1. [Using a Module in Hybrid Development](./using-a-module-in-hybrid-development.md) 2. [Developing a Package](./developing-a-package.md) 3. [Developing a Plugin](./developing-a-plugin.md) 4. [Developing an FFI Plugin](./developing-an-ffi-plugin.md) - diff --git a/ohos/docs/04_development/external-texture-adaptation-for-flutter.md b/ohos/docs/04_development/external-texture-adaptation-for-flutter.md index 6d593729ec9a70524e7b49777e33e923ad9e68a2..3a0ddbdd43ce376ed382deaf6a61685120faf150 100644 --- a/ohos/docs/04_development/external-texture-adaptation-for-flutter.md +++ b/ohos/docs/04_development/external-texture-adaptation-for-flutter.md @@ -1,52 +1,49 @@ -# External Texture Adaptation for Flutter +External Texture Adaptation for Flutter Flutter uses external textures on the ohos platform. In the case of camera preview and video playback, the Flutter engine returns a surface ID when a texture is registered. In the case of image display, a texture is registered with the Flutter engine in the form of a PixelMap. -Generally, to facilitate code reuse, the function code for connecting the ohos platform to the Flutter external texture is encapsulated as a module, and the module is registered as a plugin with the Flutter engine. For details, see https://gitee.com/openharmony-sig/flutter_packages/tree/master/packages/video_player/video_player_ohos/ohos. +**NOTE**
1. Generally, to facilitate code reuse, the function code for connecting the ohos platform to the Flutter external texture is encapsulated as a module, and the module is registered as a plugin with the Flutter engine. For details, see [video_player_ohos](https://gitee.com/openharmony-sig/flutter_packages/tree/master/packages/video_player/video_player_ohos/ohos). -## Camera Preview +2. The background color of the external texture is white and cannot be changed. +# Camera Preview -### Demo URL +## Demo URL: [test_camera](https://gitee.com/openharmony-sig/flutter_samples/tree/master/ohos/testcamera) -https://gitee.com/openharmony-sig/flutter_samples/tree/master/ohos/testcamera - -### How to Implement +## How to Implement 1. Obtain **TextureRegistry** from the **FlutterPluginBinding** input parameter in **onAttachedToEngine** to implement the plugin. - ![](../media/04_1/dc15b84a4b97ec7f923ffefe121bd346.png) +![](../media/04_1/dc15b84a4b97ec7f923ffefe121bd346.png) 2. Implement the response method for texture registration in **onMethodCall**. - ![](../media/04_1/3f7a2a6befa3459f00a90b6e796839e4.png) +![](../media/04_1/3f7a2a6befa3459f00a90b6e796839e4.png) - In **registerCameraTexture** used to register a texture, obtain the texture ID, and then register the texture based on the texture ID with the flutter engine to obtain a surface ID. +In **registerCameraTexture** used to register a texture, obtain the texture ID, and then register the texture based on the texture ID with the flutter engine to obtain a surface ID. - ![](../media/04_1/7ea99353820d6640826bf0bd24dd5f8b.png) +![](../media/04_1/7ea99353820d6640826bf0bd24dd5f8b.png) 3. Use the obtained surface ID when starting camera preview. - ![](../media/04_1/614df503f2164dd4e4a4b4a5e5bc9c87_EN.png) - -4. Call **MethodChannel** at the dart layer to trigger texture registration and start camera preview. +![](../media/04_1/614df503f2164dd4e4a4b4a5e5bc9c87_EN.png) - ![](../media/04_1/62bbfe62e6fecbb269ab9f607fb2cfbf.png) +4 . Call **MethodChannel** at the dart layer to trigger texture registration and start camera preview. - Use the obtained texture ID to build a texture widget for image preview. +![](../media/04_1/62bbfe62e6fecbb269ab9f607fb2cfbf.png) - ![](../media/04_1/37b3118e6921ff70b1baf4234fcdaa69.png) +Use the obtained texture ID to build a texture widget for image preview. -## Video Playback +![](../media/04_1/37b3118e6921ff70b1baf4234fcdaa69.png) -### Demo URL +# Video Playback -https://gitee.com/openharmony-sig/flutter_packages/tree/master/packages/video_player/video_player_ohos/example +## Demo URL: [video_player](https://gitee.com/openharmony-sig/flutter_packages/tree/master/packages/video_player/video_player_ohos/example) -### How to Implement +## How to Implement Video playback uses the same way as camera preview in registering a texture. Steps are as follows: -1. Implement the native ohos player AVplayer in the **video_player_ohos** plugin. For details, see **https://docs.openharmony.cn/pages/v4.1/en/application-dev/reference/apis-media-kit/_a_v_player.md**. +1. Implement the native ohos player AVplayer in the **video_player_ohos** plugin. For details, see [Using AVPlayer to Play Audio (ArkTS)](https://docs.openharmony.cn/pages/v5.0/en/application-dev/media/media/using-avplayer-for-playback.md). 2. Obtain **TextureRegistry** from the **FlutterPluginBinding** input parameter in **onAttachedToEngine** to implement the plugin (encapsulated in **FlutterState**). ![](../media/04_1/50312d42df3346723abf740064ea019b.png) @@ -59,19 +56,17 @@ Video playback uses the same way as camera preview in registering a texture. Ste ![](../media/04_1/d7e3f8d50d8970578c1bfc9bdcb1941c.png) -5. When the AVplayer is in the **AvplayerStatus.INITIALIZED** state, the surface ID is assigned to the AVplayer. - - ![](../media/04_1/7f03e4b85c4434de763faf2b3d073a6d.png) +5. When the AVplayer is in the **AvplayerStatus.INITIALIZED** state, the surface ID is assigned to the AVplayer. -When the AVplayer is created in step 3, the texture ID needs to be returned to the dart layer. Then the dart layer can use the external texture to complete rendering in the texture widget. +![](../media/04_1/7f03e4b85c4434de763faf2b3d073a6d.png) -## Image Display +1. When the AVplayer is created in step 3, the texture ID needs to be returned to the dart layer. Then the dart layer can use the external texture to complete rendering in the texture widget. -### Demo URL +# Image Display -https://gitee.com/openharmony-sig/flutter_samples/tree/master/ohos/testpicture +## Demo URL: [test_picture](https://gitee.com/openharmony-sig/flutter_samples/tree/master/ohos/testpicture) -### How to Implement +## How to Implement In the case of image display, no surface is used for connection to the external texture. The texture is registered with the Flutter engine in the form of a PixelMap. diff --git a/ohos/docs/04_development/using-a-flutter-channel-for-communication-between-flutter-and-openharmony.md b/ohos/docs/04_development/using-a-flutter-channel-for-communication-between-flutter-and-openharmony.md new file mode 100644 index 0000000000000000000000000000000000000000..c9e2f527095acf4e4451a98802566f5391094a6f --- /dev/null +++ b/ohos/docs/04_development/using-a-flutter-channel-for-communication-between-flutter-and-openharmony.md @@ -0,0 +1,114 @@ +# Using a Flutter Channel for Communication Between Flutter and OpenHarmony + +This topic describes how to use a Flutter channel in the OpenHarmony Flutter project. + +The following are the key implementation codes. For details about the complete demo, see [channel_demo](https://gitee.com/openharmony-sig/flutter_samples/tree/master/ohos/channel_demo). + +## MethodChannel + +Dart code + +```dart +// Create an instance. +final _platform = const MethodChannel('samples.flutter.dev/battery'); +// Call the getBatteryLevel method. +final result = await _platform.invokeMethod('getBatteryLevel'); +``` + +ets code + +```ts +onAttachedToEngine(binding: FlutterPluginBinding): void { + let that = this; + // Create an instance. + this.channel = new MethodChannel(binding.getBinaryMessenger(), "samples.flutter.dev/battery"); + // Set the callback and call the implementation. + this.channel.setMethodCallHandler({ + onMethodCall(call: MethodCall, result: MethodResult) { + switch (call.method) { + case "getBatteryLevel": + that.api.getBatteryLevel(result); + break; + default: + result.notImplemented(); + break; + } + } + }) +} +``` + +## BasicMessageChannel + +Dart code + +```dart +int count = 0; +// Create an instance. +final _basicChannel = const BasicMessageChannel( + "samples.flutter.dev/basic_channel", StandardMessageCodec()); +// Call a method to obtain the return value from the platform. +String result = await _basicChannel.send(++count) as String; +``` + +ets code + +```ts +onAttachedToEngine(binding: FlutterPluginBinding): void { + // Create an instance. + this.basicChannel = new BasicMessageChannel(binding.getBinaryMessenger(), "samples.flutter.dev/basic_channel", new StandardMessageCodec()); + // Set the callback and call the implementation. + this.basicChannel.setMessageHandler({ + onMessage(message: Any, reply: Reply) { + Log.i(TAG, "message=" + message); + if (message % 2 == 0) { + reply.reply("run with if case."); + } else { + reply.reply("run with else case"); + } + } + }) +} +``` + +## EventChannel + +Dart code + +```dart +// Create an instance. +final _eventChannel = const EventChannel('samples.flutter.dev/event_channel'); +// Enable listening for events. +_eventChannel.receiveBroadcastStream().listen((event) { + setState(() { + message = "EventChannel event=$event"; + }); +}); +``` + +ets code + +```ts +private eventSink?: EventSink; + +onAttachedToEngine(binding: FlutterPluginBinding): void { + let that = this; + // Create an instance. + this.eventChannel = new EventChannel(binding.getBinaryMessenger(), "samples.flutter.dev/event_channel"); + // Set the callback to obtain EventSink. + this.eventChannel.setStreamHandler({ + onListen(args: Any, events: EventSink): void { + that.eventSink = events; + Log.i(TAG, "onListen: " + args); + }, + onCancel(args: Any): void { + that.eventSink = undefined; + Log.i(TAG, "onCancel: " + args); + } + }); +} + +// ... +// After EventSink sends the data, the event listener at the dart layer can receive the sent data. +that.eventSink?.success("Success at " + new Date()); +``` diff --git a/ohos/docs/04_development/using-a-module-in-hybrid-development.md b/ohos/docs/04_development/using-a-module-in-hybrid-development.md new file mode 100644 index 0000000000000000000000000000000000000000..c74d6bbcee5d176ed772af1e4bc93ca70c07febc --- /dev/null +++ b/ohos/docs/04_development/using-a-module-in-hybrid-development.md @@ -0,0 +1,125 @@ +# Using a Module in Hybrid Development + +This topic describes how to reference a flutter_module project in an ohos project. + +- ohos project: a native OpenHarmony project that can be created by DevEco Studio. +- flutter_module project: a Flutter submodule project that can be created by executing Flutter instructions. + +## Environment Setup + +- Use [flutter_flutter](https://gitee.com/openharmony-sig/flutter_flutter) to configure environment variables. +- Use the engine products generated by [flutter_engine](https://gitee.com/openharmony-sig/flutter_engine). + +Use DevEco Studio to create a native OpenHarmony project named **MyApplication**. + +## flutter_module Project Operations + +```sh +# 1. Create a Flutter submodule project. +flutter create -t module my_flutter_module +# 2. Compile and generate flutter_module.har. +cd my_flutter_module +flutter build har --debug +cd - +# 3. Copy EntryAbility.ets and Index.ets to MyApplication. +cp my_flutter_module/.ohos/entry/src/main/ets/entryability/EntryAbility.ets MyApplication/entry/src/main/ets/entryability/EntryAbility.ets +cp my_flutter_module/.ohos/entry/src/main/ets/pages/Index.ets MyApplication/entry/src/main/ets/pages/Index.ets +``` + +## ohos Project Operations + +An ohos project can reference a Flutter project in either of the following ways: + +### Method 1: Referencing the HAR File + +#### 1. Copy the HAR file. + +```sh +cp -r my_flutter_module/.ohos/har/* MyApplication/har/ +``` + +### 2. Modify the **MyApplication/oh-package.json5** file. + +```json +{ + // ... + "dependencies": { + // If the useNormalizedOHMUrl field in the project-level build-profile.json5 file is set to true, the alias used by the dependent package in oh-package.json5 must be the same as the name of oh-package.json5 in the dependent package. Otherwise, an error will be reported during compilation. + "@ohos/flutter_module": "har/flutter_module.har" + }, + "overrides": { + // Conflicts in dependencies need to be eliminated here. + "@ohos/flutter_ohos": "har/flutter.har", + "plugin_xxx": "har/plugin_xxx.har" + } +} +``` + +#### 3. Use DevEco Studio to configure the signature of **MyApplication**. + +#### 4. Run **MyApplication**. + +### Method 2: Directly Referencing the flutter_module Source Code + +#### 1. Copy the flutter_module source code and Flutter-related files. + +```sh +cp -r my_flutter_module/.ohos/flutter_module MyApplication/ +mkdir -p MyApplication/flutter_module/src/main/resources/rawfile +cp -r my_flutter_module/.ohos/flutter_module/src/main/resources/rawfile/flutter_assets MyApplication/flutter_module/src/main/resources/rawfile +cp my_flutter_module/.ohos/har/flutter.har MyApplication/har/flutter.har +``` + +#### 2. Modify the **MyApplication/build-profile.json5** file. + +```json +{ + // ... + "modules": [ + { + "name": "entry", + "srcPath": "./entry", + "targets": [ + { + "name": "default", + "applyToProducts": [ + "default" + ] + } + ] + }, + // The following is the content newly added: + { + "name": "flutter_module", + "srcPath": "./flutter_module", + "targets": [ + { + "name": "default", + "applyToProducts": [ + "default" + ] + } + ] + } + ] +} +``` + +#### 3. Modify the **MyApplication/oh-package.json5** file. + +```json +{ + // ... + "dependencies": { + "flutter_module": "./flutter_module", + "@ohos/flutter_ohos": "./har/flutter.har" + }, + "overrides": { + "@ohos/flutter_ohos": "./har/flutter.har" + } +} +``` + +#### 4. Use DevEco Studio to configure the signature of **MyApplication**. + +#### 5. Run **MyApplication**. diff --git a/ohos/docs/04_development/using-flutterEntry-in-hybrid-development.md b/ohos/docs/04_development/using-flutterEntry-in-hybrid-development.md new file mode 100644 index 0000000000000000000000000000000000000000..872c34558fbd1d37f3c9542f369a9a8d8ba545f0 --- /dev/null +++ b/ohos/docs/04_development/using-flutterEntry-in-hybrid-development.md @@ -0,0 +1,95 @@ +# Using FlutterEntry in Hybrid Development + +## 1. Making the EntryAbility to Inherit from the UIAbility + +```ts +export default class EntryAbility extends UIAbility implements ExclusiveAppComponent { + + detachFromFlutterEngine(): void { + // throw new Error('Method not implemented.'); + } + + getAppComponent(): UIAbility { + return this; + } + + onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { + FlutterManager.getInstance().pushUIAbility(this); + } + + onDestroy(): void | Promise { + FlutterManager.getInstance().popUIAbility(this); + } + + onWindowStageCreate(windowStage: window.WindowStage): void { + windowStage.getMainWindowSync().setWindowLayoutFullScreen(true); + FlutterManager.getInstance().pushWindowStage(this, windowStage); + windowStage.loadContent('pages/Index'); + } + + onWindowStageDestroy() { + FlutterManager.getInstance().popWindowStage(this); + } +} +``` + +## 2. Making the MyFlutterEntry to Inherit from the FlutterEntry and Registering the Plugin + +```ts +export default class MyFlutterEntry extends FlutterEntry { + configureFlutterEngine(flutterEngine: FlutterEngine): void { + super.configureFlutterEngine(flutterEngine); + GeneratedPluginRegistrant.registerWith(flutterEngine); + this.delegate?.addPlugin(new BatteryPlugin()); + } +} +``` + +## 3. Using the FlutterEntry Together with the FlutterView + +```ts +@Entry +@Component +struct Index { + private flutterEntry: FlutterEntry | null = null; + private flutterView?: FlutterView + + aboutToAppear() { + Log.d("Flutter", "Index aboutToAppear==="); + this.flutterEntry = new MyFlutterEntry(getContext(this)) + this.flutterEntry.aboutToAppear() + this.flutterView = this.flutterEntry.getFlutterView() + } + + aboutToDisappear() { + Log.d("Flutter", "Index aboutToDisappear==="); + this.flutterEntry?.aboutToDisappear() + } + + onPageShow() { + Log.d("Flutter", "Index onPageShow==="); + this.flutterEntry?.onPageShow() + } + + onPageHide() { + Log.d("Flutter", "Index onPageHide==="); + this.flutterEntry?.onPageHide() + } + + build() { + Stack() { + FlutterPage({ viewId: this.flutterView?.getId() }) + Button ('Go to page 2') + .onClick(() => { + try { + router.pushUrl({ url: 'pages/Index2', params: { route: '/second' } }) + } catch (err) { + Log.d("Flutter", "Go to page 2 error ===" + JSON.stringify(err)). + } + }) + } + } +} +``` + +For details about the complete demo, see [flutter_page_sample2](https://gitee.com/openharmony-sig/flutter_samples/tree/master/ohos/flutter_page_sample2). diff --git a/ohos/docs/05_performance/README_EN.md b/ohos/docs/05_performance/README_EN.md index 8fc9cafce3cdcef8bd1398adaf9d5f385d27fb5c..6a66e1565f753d341e3188b019eefaf0203d03ee 100644 --- a/ohos/docs/05_performance/README_EN.md +++ b/ohos/docs/05_performance/README_EN.md @@ -1,14 +1,14 @@ -# Performance Tuning +# Performance Optimization For a OpenHarmony Flutter project, you can use DevTools to debug the Dart code. For details, see [Flutter and Dart DevTools](https://docs.flutter.dev/tools/devtools). -[Performance Analysis Demarcation Guide](./performance-delimitation.md) +[Performance Analysis and Issue Demarcation](./performance-delimitation.md) -[The First Step in Performance Analysis – Sorting Out Thread Order](./performance-threads-sequence.md) +[Performance Analysis: Sorting the Thread Sequence](./performance-threads-sequence.md) -[Performance Analysis - Frame Rendering Trace](./performance-frame-rendering-tracking.md) +[Performance Analysis: Frame Rendering Tracing](./performance-frame-rendering-tracking.md) -[Performance Analysis - Scroll Response Latency](./performance-sliding-response-time.md) +[Performance Analysis: Swipe Response Latency](./performance-sliding-response-time.md) ## Environment Configurations diff --git a/ohos/docs/05_performance/performance-delimitation.md b/ohos/docs/05_performance/performance-delimitation.md index ebd21380fc995ff0b3666a3e2ca7d060461c5646..bcab39c247c0686c60986b77fdef19b6e628602a 100644 --- a/ohos/docs/05_performance/performance-delimitation.md +++ b/ohos/docs/05_performance/performance-delimitation.md @@ -1,53 +1,51 @@ -# Performance Analysis Demarcation Guide +# Performance Analysis and Issue Demarcation -## Prerequisites -- OpenHarmony Next system -- A Flutter page running in the foreground -- Analysis tools - [DevEco Studio Profiler](https://developer.huawei.com/consumer/cn/download/) - [SmartPerf](https://gitee.com/openharmony-sig/smartperf) +## Preparations +- OpenHarmony NEXT +- Flutter page running in the foreground +- Analysis Tools + [DevEco Studio Profiler](https://developer.huawei.com/consumer/cn/download/) + [Smartperf](https://gitee.com/openharmony/developtools_smartperf_host) ## Introduction to Flutter Threads +Flutter uses multiple threads to complete its work. Only two of them are displayed in the overlay. All the Dart code you write runs on the UI thread. Although there is no direct access to other threads, your operations on the UI thread may affect the performance of other threads. -Flutter uses multiple threads to complete its necessary work, and the diagram only shows two of them. All the Dart code you write runs on the UI thread. Although you do not have direct access to other threads, your operations on the UI thread can affect the performance of other threads. +- Platform thread +Main thread of the platform, where the plugin code runs. -- Platform Thread - The main thread of the platform, where the plugin code runs. +- UI thread +A thread that executes Dart code in the Dart VM. This thread runs your own code and code generated by the Flutter framework based on application behavior. When an application creates and displays a scenario, the UI thread first creates a layer tree, which is a lightweight object containing device-agnostic rendering commands, and sends the layer tree to the raster thread to be rendered on the device. Do not block this thread. It is displayed at the bottom row of the performance overlay. -- UI Thread - The UI thread executes Dart code in the Dart VM. This includes code written by developers and code generated by the Flutter framework based on application behavior. When the app creates and displays a scene, the UI thread first builds a layer tree, a lightweight object containing device-independent rendering commands, and sends the layer tree to the GPU thread for rendering on the device. **Do not block this thread!** It is displayed in the bottom bar of the performance overlay. +- Raster thread +Also referred to as a GPU thread. This thread obtains the layer tree and delivers it to the GPU. You cannot directly access the raster thread or its data, but if the thread slows down, it must be caused by somewhere in the Dart code. The graphics library Skia runs on this thread, which is displayed on the top of the performance layer. Note that the raster thread rasterizes the GPU, but the thread itself runs on the CPU. -- Raster Thread - The raster thread, also known as the GPU thread. The raster thread takes the layer tree and hands it off to the GPU (Graphics Processing Unit). You cannot directly interact with the GPU thread or its data, but if this thread slows down, it is definitely caused by some part of the developer’s Dart code. The Skia graphics library runs on this thread, which is displayed in the top bar of the performance overlay. Note that the raster thread performs rasterization for the GPU but itself runs on the CPU. +- I/O thread +A thread that executes high-load operations (commonly I/O operations) to avoid blocking UI or raster threads. This thread is not displayed on the performance overlay. -- I/O Thread - Executes high-load operations (commonly I/O) to avoid blocking the UI or raster threads. This thread will not be shown in the performance overlay. +- RenderService thread +Main thread of the RS process. After Flutter renders frames, the RenderService thread combines the frames and sends them for display. In texture mode, the buffer rendered by Flutter and the application main thread are combined and sent for display together. In surface mode, the frames rendered by Flutter are separately sent for display, without being affected by the application main thread. -- RenderService Thread - The main thread of the RS process. After Flutter completes frame rendering, the RS thread performs composition and sends the result to the display. In Texture mode, after the Flutter-rendered buffer is composed with the application’s main thread, it is then sent to display together, and is influenced by the application’s main thread. In Surface mode, the Flutter-rendered frame is sent to display independently and is not affected by the application’s main thread. - -## Problem Demarcation - -In DevEco Studio, click the Profiler tab at the bottom to open the performance tuning tool. After capturing the application’s trace, bookmark the application processes `.ui`, `.raster`, and the main thread of RenderService. +## Issue Demarcation +On the **Profiler** tab page at the bottom of DevEco Studio, use this the Profiler to capture application traces, and mark the UI thread, raster thread, and RenderService thread. ![](../media/05/image-1-301.png) -In the figure above, the missing frames in RenderService occur because the time taken by the UI thread for a single frame is too long, exceeding the duration of one frame (at a 120 fps rate, one frame is 8.33 ms). -![](../media/05/image-1-302.png) -If, in a single frame rendering process, the total duration of `.ui` and `.raster` exceeds the duration of one frame, the performance issue can be identified as a Flutter problem. Further performance analysis is needed for issue localization. +In the preceding figure, the RenderService loses frames because the UI thread consumes too much time for a single frame, which is expected to last approximately 8.33 ms (at the frame rate of 120 fps). +![](../media/05/image-1-302.png) -## Appendix -### Introduction to DevEco Studio Profiler Tool +For single-frame rendering, if the total duration of UI and raster threads exceeds 8.33 ms, the performance issue is caused by Flutter. Further performance analysis is required to demarcate the issue. -[DevEco Studio Profiler](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V2/profiler-introduce-0000001501850508-V2) -### Fluter Performance Tuning Introduction +## Appendix +### Introduction to DevEco Studio Profiler +[DevEco Studio Profiler](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V2/profiler-introduce-0000001501850508-V2) -[Flutter Performance Tuning](https://docs.flutter.cn/perf) \ No newline at end of file +### Flutter Optimization +[Performance](https://docs.flutter.dev/perf) diff --git a/ohos/docs/05_performance/performance-frame-rendering-tracking.md b/ohos/docs/05_performance/performance-frame-rendering-tracking.md index 7570112088fdbd5d48430c0266edd385aac1a083..a5e82e11e2ebcd2470c92996f8e13ae9a508482b 100644 --- a/ohos/docs/05_performance/performance-frame-rendering-tracking.md +++ b/ohos/docs/05_performance/performance-frame-rendering-tracking.md @@ -1,44 +1,40 @@ -# Performance Analysis - Frame Rendering Trace +# Performance Analysis: Frame Rendering Tracing -When performing performance analysis on Flutter applications, it is necessary to capture the application’s trace data using analysis tools and then analyze it. In some cases, it may be necessary to trace the rendering of a single frame, for example when dealing with frame rate stutters or dropped frames. This document introduces a method for tracing individual frame rendering. +When analyzing the performance of a Flutter application, use analysis tools to capture and analyze trace data of the application. Considering that you might need to isolate and track a particular frame, for instance, when dealing with frame freezing or loss, this topic describes how to track individual frames. - ## Analysis Tools +## Analysis Tools +Common analysis tools include [DevEco Studio Profiler](https://developer.huawei.com/consumer/cn/download/) (recommended) and [Smartperf](https://gitee.com/openharmony/developtools_smartperf_host). For details about how to use the Profiler, see [In-depth Capture for Problem Locating](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V5/deep-recording-V5). - Commonly used analysis tools include [DevEco Studio Profiler](https://developer.huawei.com/consumer/cn/download/) and [SmartPerf](https://gitee.com/openharmony-sig/smartperf). It is recommended to use the DevEco Studio Profiler for performance tuning. For more information on using the DevEco Studio Profiler, please refer to the [DevEco Profiler Tool Introduction](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/deep-recording-V5). +## Frame Identifier +The rendering process of a frame is as follows. - ## Frame Identifiers +![](../media/05/image-3-201_EN.png) - A single frame’s rendering process is roughly as follows: - ![](../media/05/image-3-201_EN.png) +It is important to understand the frame rendering process and assign an appropriate frame identifier to each unit to match the rendering process. - It is very important to understand the frame rendering process, and it is equally important to be able to match each unit in the frame rendering process. Finding suitable identifiers for each unit helps correctly match the rendering flow. +### First Identifier: frame_number +**frame_number** is the identifier for matching UI and raster threads. +Mark these two threads, and find the identifier on the traced swimlanes. +- If **frame_number** does not appear in the UI and raster threads, the current frame is not self-rendered by Flutter. In this case, you need to demarcate the performance issue again. - ### First Identifier: frame_number +![](../media/05/image-3-202.png) - The linkage between 1.ui and 1.raster threads is identified by `frame_number`. - By bookmarking these two threads and correlating them for observation, you will find this identifier in the trace. This is the first identifier for Flutter application frame rendering. +### Second Identifier: ReuseBuffer or acquire buffer - - If the `frame_number` identifier does not appear in either 1.ui or 1.raster, it indicates that the current frame is not rendered by Flutter. In that case, you need to re-demarcate the performance problem. +**ReuseBuffer** is the identifier for matching raster and RenderService threads. +During the trace of **flutter::SkCanvas::Flush** in the raster thread, a buffer is applied for from the RS process to store the rendered frame content. Click the trace of **binder transaction** to jump to another thread and view the ID of the corresponding **ReuseBuffer**. - ![](../media/05/image-3-202.png) +![](../media/05/image-3-203.png) - ### Second Identifier: ReuseBuffer/acquire buffer +During the trace of **RSMainThread::DoComposition** in the RenderService thread, the frame memory in the buffer is obtained. The trace of **acquire buffer sequence** shows that the **ReuseBuffer** ID is the same as that applied by the raster thread. - The linkage between 1.raster and render_service threads is identified by `ReuseBuffer`. +![](../media/05/image-3-204.png) - In the `1.raster` thread trace, during the `"flutter::SkCanvas::Flush"` process, the raster thread requests a buffer from the RS process to store the rendered frame content. By clicking on the `"binder transaction"` in the trace, you can jump to another thread and view the corresponding `ReuseBuffer` ID. - ![](../media/05/image-3-203.png) - - In the render_service thread, during the `"RSMainThread::DoComposition"` trace process, the frame buffer memory is acquired. In the `"acquire buffer sequence"` trace, you can see that the `ReuseBuffer` number matches the one requested by the `1.raster` thread. - - ![](../media/05/image-3-204.png) - - - - With the two identifiers shown above, you can identify the frame rendering flow from the Flutter application to the RS process. As for how to recognize subsequent units on the RS process side, there is currently no intuitive trace available. By default, continuous thread traces are considered part of the same frame (i.e., from `render_service` to `RSUniRenderThread`, and then to `RSHardwareThread` are considered continuous). +- Based on the preceding two identifiers, you can identify the frame rendering of a Flutter application on the RS process. However, no trace is provided to identify the subsequent units in the RS process. By default, consecutive thread traces are from the same frame (for example, the traces of **render_service**, **RSUniRenderThread**, and **RSHardwareThread**). diff --git a/ohos/docs/05_performance/performance-sliding-response-time.md b/ohos/docs/05_performance/performance-sliding-response-time.md index bd504e318180a10526a8e4979c4b960885e62fd5..7af47bac4eb2c5127c535a86efba6db911581274 100644 --- a/ohos/docs/05_performance/performance-sliding-response-time.md +++ b/ohos/docs/05_performance/performance-sliding-response-time.md @@ -1,60 +1,61 @@ -# Performance Analysis - Scroll Response Latency +# Performance Analysis: Swipe Response Latency -This article focuses on trace analysis of response latency in scrolling scenarios for Flutter applications. Be sure to read [Performance Analysis Step 1 - Sorting Out Thread Order](./performance-threads-sequence.md) before continuing. +This topic describes how to conduct a trace analysis on the swipe response latency for Flutter applications. You are advised to read [Performance Analysis: Sorting the Thread Sequence](./performance-threads-sequence.md) beforehand. -## Prerequisites +## Preparations -- Understand and be able to use the performance analysis tool [DevEco Studio Profiler](https://developer.huawei.com/consumer/cn/download/) -- Understand thread rendering order ([Performance Analysis Step 1 - Sorting Out Thread Order](./performance-threads-sequence.md)) +- You have learned how to use [DevEco Studio Profiler](https://developer.huawei.com/consumer/cn/download/). +- You have a clear understanding of the thread rendering sequence. For details, see [Performance Analysis: Sorting the Thread Sequence](./performance-threads-sequence.md). -## 1. Finger Down +## 1. Finger Press +Pressing is a prerequisite for all touch or swipe events. The system can receive important information such as the initial position of the finger and the components touched from the events. -A finger-down event is the prerequisite for all tap or scroll events, providing critical information such as the initial coordinates of the finger and which widget is being touched. -The `mmi_service` thread is responsible for triggering multi-modal interaction events, which the Flutter application listens to and responds to. +The mmi_service thread triggers multimodal interaction events, and the Flutter application listens for and responds to touch events. -The finger-down touch event is immediately forwarded to the Flutter application. -In the `mmi_service` thread, after the "package touchEvent" trace, you can see a "service report touchId:xxx, type: down" trace, where `type` is `down`, indicating a finger-down touch event. Meanwhile, on the application’s main thread, there is a "DispatchTouchEvent" trace that shows detailed coordinates and the event type. When `type` has a value of `0`, it means a finger-down touch event. These traces on the two threads correspond to each other. +The touch event of finger press is immediately forwarded to the Flutter application. -![](../media/05/image-4-201.png) +In the mmi_service thread, following the trace of **package touchEvent**, the trace shows the details "service report touchId: number, type: down," where the type **down** indicates the touch event of finger press. In the application main thread, the trace of **DispatchTouchEvent** contains coordinates and the touch event type **0**, indicating the touch event of finger press. The traces on the two threads match. -## 2. Finger Move +![](../media/05/image-4-201.png) -Unlike a finger-down event, a finger-move touch event is not immediately forwarded to the Flutter application. Instead, it is controlled by the vsync-app signal before being sent. -Similar to the finger-down trace, both the `mmi_service` thread and the application’s main thread have corresponding traces, but with a different type. `type = move` corresponds to a value of `2`. +## 2. Finger Swipe +The touch event of finger swipe is not immediately forwarded to Flutter applications. Instead, its sending is controlled by the VSync-app signal. -The finger-move touch event requires a vsync-app signal named `flutterSyncName` to be triggered before it is passed on to the Flutter application’s main thread. Thus, the chronological order is: `mmi_service` → `VSyncGennerator` → `DVSync-app` → Application main thread. The trace order is shown below: -![](../media/05/image-4-301.png) +This touch event has similar traces in the mmi_service thread and the application main thread like that of finger press, yet the type is **move**, corresponding to value **2**. -- Note: The coordinates of the very first finger-move touch event are the same as those of the finger-down event. -## 3. TouchSlop Threshold +The touch event of finger swipe can be passed to the main thread only after being triggered by the VSync-app signal of flutterSyncName. Therefore, the response sequence is as follows: mmi_service > VSyncGennerator > DVSync-app > application main thread. Trace sequence is as follows. + +![](../media/05/image-4-301.png) -TouchSlop is the minimum recognizable scroll distance, essentially a threshold. Users can customize the widget’s scrolling threshold, with a default system value of 18. +- Note: Coordinates of the touch event of the first finger swipe are the same as that of the touch event of finger press. -By checking the touch event coordinates in the application’s main thread traces, you can manually calculate the coordinate offset to see if it meets the scrolling threshold. +## 3. TouchSlop +TouchSlop is the minimum swipe distance that can be identified by the system. This distance is customizable, and the default value is **18**. -## 4. The First Scrolling Frame +With the coordinates of the touch event trace in the application main thread, the system can automatically calculate whether the coordinate offset reaches the . -When the scrolling distance of the finger-move touch event exceeds the set TouchSlop threshold, the Flutter application triggers an `update` operation. However, actual drawing operations must wait for the arrival of the next frame. Therefore, the rendering of the first frame when scrolling begins involves an additional one-frame delay after the touch event conditions are met. -The trace is shown below: +## 4. First Frame of the Swipe Gesture +When the swipe distance of a touch event exceeds the specified distance, the Flutter application triggers an update. However, the rendering action can be executed only after the next frame arrives. Therefore, even though the swipe gesture triggers the touch event, the first frame rendering still waits for one-frame latency. -![](../media/05/image-4-401.png) +Trace sequence is as follows. -## 5. First Frame Rendering +![](../media/05/image-4-401_EN.png) -For a general overview of rendering, see [Performance Analysis - Frame Rendering Tracking](./performance-frame-rendering-tracking.md) to accurately locate corresponding traces. +## 5. First-Frame Rendering +You need to find out the corresponding trace. For details about the rendering process, see [Performance Analysis: Frame Rendering Tracing](./performance-frame-rendering-tracking.md). -The frame rendering ends on the `RSHardwareThread` thread in the RS process. However, in automated testing, the end of frame rendering is identified by the `dpu_gfx_primary` thread. (The `dpu_gfx_primary` thread is just a hardware signal and will not be explained in detail.) +Frame rendering ends on RSHardwareThread of the RS process. However, during the automatic test, the end identifier of frame rendering is the dpu_gfx_primary thread (which is a hardware signal). -The trace is shown below: +Trace sequence is as follows. ![](../media/05/image-4-501.png) -Therefore, the time from the `mmi_service` thread’s finger-down trace to the end of the first scrolling frame rendering is the scroll response latency. +Therefore, the swipe response latency is the duration from the time the trace of finger press is recorded in the mmi_service thread to the time the first frame of the swipe gesture finishes rendering. diff --git a/ohos/docs/05_performance/performance-threads-sequence.md b/ohos/docs/05_performance/performance-threads-sequence.md index 704817aaa34d3fc676fa31ad8cd0eedc0c83404c..49465548fa3e26c0ff76bdf547a80ac3eb1a88af 100644 --- a/ohos/docs/05_performance/performance-threads-sequence.md +++ b/ohos/docs/05_performance/performance-threads-sequence.md @@ -1,74 +1,63 @@ -# The First Step in Performance Analysis – Sorting Out Thread Order +# Performance Analysis: Sorting the Thread Sequence + +When analyzing the performance of a Flutter application, use analysis tools to capture and analyze the application's traces. The rendering process of the Flutter application is closely related to several threads. This topic describes these threads and their sequence in the rendering process. -When performing performance analysis on a Flutter application, it is necessary to use analysis tools to capture the application’s trace and then analyze it. The rendering process of a Flutter application is closely intertwined with several threads. This guide introduces these threads and their order in the rendering process. ## Analysis Tools +Common analysis tools include [DevEco Studio Profiler](https://developer.huawei.com/consumer/cn/download/) (recommended) and [Smartperf](https://gitee.com/openharmony/developtools_smartperf_host). For details about how to use the Profiler, see [In-depth Capture for Problem Locating](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V5/deep-recording-V5). -Common analysis tools include [DevEco Studio Profiler](https://developer.huawei.com/consumer/cn/download/) and [SmartPerf](https://gitee.com/openharmony-sig/smartperf). It is recommended to use the DevEco Studio Profiler for performance tuning. For instructions on how to use the DevEco Studio Profiler, please refer to the [DevEco Profiler Tool Introduction](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/deep-recording-V5). - -## Thread Order - -- Once you understand how to use the analysis tools, you can capture the Flutter application’s trace. The trace contains all threads that ran during the application’s execution. To better analyze Flutter’s performance, you need to first bookmark the threads shown in the figure below and then arrange them in the order indicated by the numbers above them. -- When bookmarking threads in the trace, note that threads added later appear at the top of the favorites list. Therefore, it’s more convenient to bookmark the threads in reverse order as shown in the figure. -- The order of threads is: - 1) VSyncGennerator - 2) DVSync-app - 3) mmi_service - 4) Main application thread - 5) flutter’PointerEvent’ - 6) 1.ui - 7) 1.raster - 8) DVSync-rs - 9) render_service - 10) RSUniRenderThread - 11) RSHardwareThread - 12) dpu_gfx_primary -![](../media/05/image-2-201_EN.png) +## Thread Sequence +- Learning how to use analysis tools can help you capture traces of Flutter applications. The traces contain all threads at the application runtime. Mark and sort the threads in the sequence shown in the figure below to better analyze the Flutter application performance. The thread sequence is shown by the number. +- Because the latest marked thread is displayed on the top of list, it is recommended that you mark threads in reverse order. +- Thread sequence: (1) VSyncGennerator (2) DVSync-app (3) mmi_service (4) Application main thread (5) flutter'PointerEvent' (6) 1.ui (7) 1. raster (8) DVSync-rs (9) render_service (10) RSUniRenderThread (11) RSHardwareThread (12) dpu_gfx_primary -After bookmarking the threads in order, the thread favorites list should look like this: +![](../media/05/image-2-201_EN.png) +After the threads are marked and sorted, the thread list is as follows. ![](../media/05/image-2-202.png) + ![](../media/05/image-2-203.png) + ![](../media/05/image-2-204.png) -## Introduction to the Bookmarked Threads -- **VSyncGennerator** - A software Vsync signal generator that provides the capability to perceive VSync frames. +## Thread List +- VSyncGennerator +VSync signal generator, providing the capability of sensing VSync frames. -- **DVSync-app** - Provides a software Vsync signal to the app application. +- DVSync-app +VSync signal provided for the application. -- **mmi_service** - Handles multi-modal events triggered when the user touches the screen. +- mmi_service +Multimodal event triggered when a finger touches the screen. -- **Main Application Thread** - The thread whose ID matches the application’s process ID and whose name matches the process name. - This is the platform’s main thread, where plugin code runs. +- Application main thread +A main thread whose thread ID is the same as the application process ID and thread name is the same as the process name. +It is the main thread of the platform, where the plugin code runs. -- **flutter'PointerEvent'** - This thread (if it exists) handles the process of sending touch events from the main application thread to the 1.ui thread for processing. +- flutter'PointerEvent' +Procedure from the time the main thread of the Flutter application sends a touch event to the time the UI thread handles the touch event. This thread may not exist. -- **1.ui** - The UI thread, named `.ui`. - The UI thread executes Dart code in the Dart VM. This includes both developer-written code and code generated by the Flutter framework based on application behavior. When the app creates and displays a scene, the UI thread first builds a layer tree—a lightweight object containing device-independent rendering commands—and sends it to the GPU thread for rendering. **Do not block this thread!** In the performance overlay, this thread is displayed at the bottom bar. +- 1.ui +UI thread named **< number >.ui**. +It executes Dart code in the Dart VM. This thread includes your own code and code generated by the Flutter framework based on application behavior. When an application creates and displays a scenario, the UI thread first creates a layer tree, which is a lightweight object containing device-agnostic rendering commands, and sends the layer tree to the raster thread to be rendered on the device. Do not block this thread. It is displayed at the bottom row of the performance overlay. -- **1.raster** - The Raster thread, named `.raster`. - The raster thread receives the layer tree and hands it off to the GPU (Graphics Processing Unit). You cannot directly interact with the GPU thread or its data, but if this thread is slow, it is definitely caused by some part of your Dart code. The Skia graphics library runs on this thread, which is displayed at the top bar of the performance overlay. Note that while the raster thread performs rasterization for the GPU, the thread itself runs on the CPU. +- 1.raster +Raster thread named **< number >.raster**. +This thread obtains the layer tree and delivers it to the GPU. You cannot directly access the raster thread or its data, but if the thread slows down, it must be caused by somewhere in the Dart code. The graphics library Skia runs on this thread, which is displayed on the top of the performance layer. Note that the raster thread rasterizes the GPU, but the thread itself runs on the CPU. -- **DVSync-rs** - Provides a software Vsync signal to the RS process. +- DVSync-rs +VSync signal provided for the RS process. -- **render_service** - The main thread of the RS process, and the first step in RS composition. +- render_service +Main thread of the RS process, which is the first step for sending the frames to RS for display. -- **RSUniRenderThread** - A thread in the RS process, responsible for the second step in RS composition. +- RSUniRenderThread +Thread of the RS process, which is the second step for sending the frames to RS for display. -- **RSHardwareThread** - A thread in the RS process, responsible for the third step in RS composition. +- RSHardwareThread +Thread of the RS process, which is the third step for sending the frames to RS for display. -- **dpu_gfx_primary** - A hardware DPU signal. +- dpu_gfx_primary +Hardware DPU signal. diff --git a/ohos/docs/08_FAQ/README_EN.md b/ohos/docs/08_FAQ/README_EN.md index 2757a7d4d0d52fe9d96bb6a0b22348c359889cd1..51e8680d527c97e5922f5bfa29bdc14005084bdd 100644 --- a/ohos/docs/08_FAQ/README_EN.md +++ b/ohos/docs/08_FAQ/README_EN.md @@ -3,22 +3,22 @@ You can refer to FAQs related to the following aspects during OpenHarmony Flutter development. 1. [Environment](./environment.md) -2. [ohos Engine Product Compilation](./ohos-engine-product-compilation.md) -3. [ohos Application Compilation](./ohos-application-compilation.md) -4. [ohos Code Development](./ohos-code.md) -5. [ohos Program Running](./ohos-run.md) -6. [ohos Development](../04_development/README.md) -7. [Parsing Flutter-Related CppCrash Stacks](./flutter-cppcrash-guideline.md) +2. [ohos Engine Product Compilation](./ohos_engine.md) +3. [ohos Application Compilation](./ohos_hap.md) +4. [ohos Code Development](./ohos_code.md) +5. [ohos Running](./ohos_run.md) +6. [Feature Development](../04_development/README_EN.md) +7. [Analyzing the Cpp Crash Stack Related to Flutter](./flutter_cppcrash_guideline.md) ## Key Information Template for Feedback on Questions Related to OpenHarmony Flutter Application 1. IDE version number. Example: 1. DevEco Studio 5.0.3.300 -2. Device name and system version number of the OpenHarmony device or emulator. You can check them in **Settings** > **About phone**. Example: +2. Device name and system version number of the OpenHarmony device or the Emulator. You can check them in **Settings** > **About phone**. Example: 1. HUAWEI Mate 60 Pro, 3.0.0.22(SP81xxxxxx) 2. Emulator, 3.0.0.22(SP39xxxxxx) 3. Information about the Flutter runtime environment. Example: - 1. `flutter docotr -v` + 1. `flutter doctor -v` 4. Flutter building or running instructions. Example: 1. `flutter build hap --debug` 2. `flutter run -d $DEVICE --debug` @@ -26,9 +26,9 @@ You can refer to FAQs related to the following aspects during OpenHarmony Flutte 1. Building or running logs. Example: 1. `flutter build hap --debug > build.log 2>&1` 2. `flutter run -d $DEVICE --debug > run.log 2>&1` - 2. **hilog** file. + 2. **hilog** file 1. Export the `hdc hilog > hilog.log 2>&1` file by using instructions. - 2. The `hdc` tool is stored in the **toolchains** directory of the HamonyOS SDK. + 2. The `hdc` tool is stored in the **toolchains** directory of the HarmonyOS SDK. 3. Log files recording crashes. 1. You can obtain the log file from DevEco Studio. Steps: **DevEco Studio** > **Log** > **FaultLog** > **app bundle name** > **cppcrash/jscrash** > **Time** > **Right-click to export the log files**. diff --git a/ohos/docs/08_FAQ/environment.md b/ohos/docs/08_FAQ/environment.md index 7ad8dfb33bffbca449ea4148897b8edf84e5ab14..94b6ecd5c06a0a18b8c12461871207926756ece8 100644 --- a/ohos/docs/08_FAQ/environment.md +++ b/ohos/docs/08_FAQ/environment.md @@ -16,20 +16,17 @@ For details about how to set up the Flutter development environment, see https:/ ## Failure in Running flutter pub get in an Offline Environment Solution: - Add the **--offline** parameter. Complete instruction: `flutter pub get --offline`. ## Failure in Building an Application of the Release Version in the macOS Environment Error log: ```log -ProcessPackageException: ProcessException: Found candidates, but lacked sufficient permissions to execute "/Users/xxx/ohos/src/out/ohos_release_arm64/clang_arm4/dart". +ProcessPackageException: ProcessException: Found candidates, but lacked sufficient permissions to excute "/Users/xxx/ohos/src/out/ohos_release_arm64/clang_arm4/dart". Command: /Users/xxx/ohos/src/out/ohos_release_arm64/clang_arm4/dart ``` -Solution: - -Add the execution permission. +Solution:
Add the execution permission. ```sh chmod -R +x /Users/xxx/ohos/src/out/ohos_release_arm64/* @@ -46,9 +43,7 @@ xxx/flutter_flutter/bin/internal/update_dart_sdk.sh: line 156: return: can only curl: (3) Illegal characters found in URL ``` -Problem analysis: - -The newline character on Windows is inconsistent with that on Linux or macOS. +Problem analysis:
The newline character on Windows is inconsistent with that on Linux or macOS. Solution: @@ -88,21 +83,30 @@ strict_ssl=false Problem analysis: -- **FloatingActionButton** is not supported by the emulator. You need to comment out **FloatingActionButton** in **lib/main.dart** before running the application on the emulator. -- Reference: [Differences Between the Emulator and Real Device](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/ide-emulator-specification-0000001839876358-V5). +- **FloatingActionButton** is not supported by the Emulator. You need to comment out **FloatingActionButton** in **lib/main.dart** before running the application on the Emulator. +- Reference:
[Differences Between the Emulator and Real Device](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/ide-emulator-specification-0000001839876358-V5). ## [ios][release] GeneratedPluginRegistrant.m Module Not Found -Problem analysis: +Problem analysis:
A Flutter plugin is added to the **pubspec.yaml** file, but the **pod** reference related to the plugin does not exist in the **Podfile**. -A Flutter plugin is added to the **pubspec.yaml** file, but the **pod** reference related to the plugin does not exist in the **Podfile**. +Solution:
Run the instruction `rm ios/podfile && flutter clean && flutter run -d `. -Solution: +Reference:
[GeneratedPluginRegistrant.m Module not found](https://github.com/flutter/flutter/issues/43986) -Run the instruction `rm ios/podfile && flutter clean && flutter run -d `. +## [Windows] The flutter doctor -v Command Does Not Respond -Reference: +Symptom:
After the environment variables are configured, the system does not respond when the **flutter doctor -v** command is executed. -[GeneratedPluginRegistrant.m Module not found](https://github.com/flutter/flutter/issues/43986) +Cause:
The proxy may not be properly configured. - \ No newline at end of file +Solution: +- Configure **http_proxy**, **https_proxy**, and **no_proxy** in the system environment variables. +- To configure **http_proxy** and **https_proxy**, follow the procedure of the proxy configuration in DevEco Studio. +- To configure **no_proxy**, in addition to following the procedure of the proxy configuration in DevEco Studio, you need to add the following information to the environment variables on the local host: + - localhost + - ::1 + - 127.0.0.1 + +If the execution result contains Flutter and OpenHarmony, it indicates that the basic environment is correctly configured and both platforms are supported on Windows. +![](../media/08/error.png) \ No newline at end of file diff --git a/ohos/docs/08_FAQ/flutter-cppcrash-guideline.md b/ohos/docs/08_FAQ/flutter-cppcrash-guideline.md index a6f6a25e35f36d72ccef66198bae0456fcf47a27..92ec0ee1113c0a384af505eb7e66746a500536f7 100644 --- a/ohos/docs/08_FAQ/flutter-cppcrash-guideline.md +++ b/ohos/docs/08_FAQ/flutter-cppcrash-guideline.md @@ -1,61 +1,53 @@ -# Parsing Flutter-Related CppCrash Stacks +# Analyzing the Cpp Crash Stack Related to Flutter -This document introduces how to parse crash stacks related to the `libflutter.so` library in the Flutter-for-OpenHarmony environment. +This section describes how to analyze the cpp crash stack related to `libflutter.so` of OpenHarmony Flutter. ## 1. Introduction -The `llvm-addr2line` tool can convert instruction addresses and executable images into file names, function names, and corresponding source code line numbers. It is typically used on `.so` libraries that contain symbol information. +llvm-addr2line is a tool that converts the address of a command and an executable image into a file name, a function name, and a specific line in the source code. It is generally applicable to the SO library with the **symbol** information. -## 2. Tool Location +## 2. Location -The `llvm-addr2line` tool is included in the SDK directory of both **DevEco Studio** and **Command Line Tools for OpenHarmony**. The paths are as follows: +llvm-addr2line is stored in the **sdk** directory of DevEco Studio and Command Line Tools for OpenHarmony. The corresponding paths are as follows: -- Windows: `sdk/default/openharmony/native/llvm/bin/llvm-addr2line.exe` -- Linux/Mac: `sdk/default/openharmony/native/llvm/bin/llvm-addr2line` +- Windows: sdk/default/openharmony/native/llvm/bin/llvm-addr2line.exe +- Linux/Mac: sdk/default/openharmony/native/llvm/bin/llvm-addr2line -You can add the `llvm-addr2line` directory to your `PATH` environment variable, for example: +You can configure the directory where llvm-addr2line is located to the environment variable **PATH**. For example: ```sh export PATH=/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/native/llvm/bin:$PATH ``` -## 3. Usage Command +## 3. Executing Commands ```sh llvm-addr2line -f -e so.unstripped/libflutter.so [addr1] [addr2] ``` -## 4. Obtaining a libflutter.so with Symbols +## 4. Obtaining the libflutter.so File Containing Symbol -### 4.1 Using Locally Compiled Engine Artifacts +### 4.1 Using the Locally Built Engine Products -- Debug version: - `src/out/ohos_debug_unopt_arm64/so.unstripped/libflutter.so` +- Debug version + - src/out/ohos_debug_unopt_arm64/so.unstripped/libflutter.so +- Release version + - src/out/ohos_release_arm64/so.unstripped/libflutter.so +- Profile version + - src/out/ohos_profile_arm64/so.unstripped/libflutter.so -- Release version: - `src/out/ohos_release_arm64/so.unstripped/libflutter.so` +### 4.2 Downloading from Cloud Products -- Profile version: - `src/out/ohos_profile_arm64/so.unstripped/libflutter.so` +- Find the commit ID of the `flutter_engine` version in the `flutter_flutter` version. + - Location: `flutter_flutter/bin/internal/engine.ohos.version` +- Download the zip file of **libflutter.so** of the corresponding version based on the commit ID 8ef94277f0029e61ff6a96f630d0f10b60330cd8. + - For debug version: https://flutter-ohos.obs.cn-south-1.myhuaweicloud.com/flutter_infra_release/flutter/8ef94277f0029e61ff6a96f630d0f10b60330cd8/ohos-arm64/symbols.zip + - For release version: https://flutter-ohos.obs.cn-south-1.myhuaweicloud.com/flutter_infra_release/flutter/8ef94277f0029e61ff6a96f630d0f10b60330cd8/ohos-arm64-release/symbols.zip + - For profile version: https://flutter-ohos.obs.cn-south-1.myhuaweicloud.com/flutter_infra_release/flutter/8ef94277f0029e61ff6a96f630d0f10b60330cd8/ohos-arm64-profile/symbols.zip -### 4.2 Downloading from Cloud Artifacts +## 5. Use Cases -- Find the `flutter_engine` commit ID used by the current `flutter_flutter` version. This can be found in the `flutter_flutter/bin/internal/engine.ohos.version` file. - -- For the commit ID `8ef94277f0029e61ff6a96f630d0f10b60330cd8`, you can download the corresponding version of `libflutter.so` as a zip file from: - - - Debug version: - [https://flutter-ohos.obs.cn-south-1.myhuaweicloud.com/flutter_infra_release/flutter/8ef94277f0029e61ff6a96f630d0f10b60330cd8/ohos-arm64/symbols.zip](https://flutter-ohos.obs.cn-south-1.myhuaweicloud.com/flutter_infra_release/flutter/8ef94277f0029e61ff6a96f630d0f10b60330cd8/ohos-arm64/symbols.zip) - - - Release version: - [https://flutter-ohos.obs.cn-south-1.myhuaweicloud.com/flutter_infra_release/flutter/8ef94277f0029e61ff6a96f630d0f10b60330cd8/ohos-arm64-release/symbols.zip](https://flutter-ohos.obs.cn-south-1.myhuaweicloud.com/flutter_infra_release/flutter/8ef94277f0029e61ff6a96f630d0f10b60330cd8/ohos-arm64-release/symbols.zip) - - - Profile version: - [https://flutter-ohos.obs.cn-south-1.myhuaweicloud.com/flutter_infra_release/flutter/8ef94277f0029e61ff6a96f630d0f10b60330cd8/ohos-arm64-profile/symbols.zip](https://flutter-ohos.obs.cn-south-1.myhuaweicloud.com/flutter_infra_release/flutter/8ef94277f0029e61ff6a96f630d0f10b60330cd8/ohos-arm64-profile/symbols.zip) - -## 5. Example Usage - -Below is an example of a partial crash log related to `libflutter.so`: +Some crash logs related to **libflutter.so**: ```log #00 pc 00000000001b5a34 /system/lib/ld-musl-aarch64.so.1(__timedwait_cp+188)(ef860a9c8bd64e964a4dd4ef838876e1) @@ -64,15 +56,15 @@ Below is an example of a partial crash log related to `libflutter.so`: #03 pc 00000000001f21f4 /data/storage/el1/bundle/libs/arm64/libflutter.so(85c51e03a4f191b946582701e79e1be4a0c83959) ``` -After obtaining the symbolized file `so.unstripped/libflutter.so`, you can convert the addresses in the crash stack to specific code lines. +Obtain the `so.unstripped/libflutter.so` file with the symbol to convert the address in the error stack to the specific line in the error code. -Run the command: +Run the following command: ```sh llvm-addr2line -f -e so.unstripped/libflutter.so 00000000001b5a34 00000000001b7a3c 000000000021d450 00000000001f21f4 ``` -The parsed result might look like this: +Result: ```log _ZNSt21_LIBCPP_ABI_NAMESPACE21__libcpp_condvar_waitB6v15004EP14pthread_cond_tP15pthread_mutex_t @@ -81,8 +73,8 @@ _ZN7flutter16PlatformViewOHOS13NotifyChangedERK7SkISize /home/hazy/work/engine_build/engine_daily/src/out/ohos_release_arm64/../../flutter/shell/platform/ohos/platform_view_ohos.cpp:192 ``` -## Additional Resources +## Others -- [Analyzing CppCrash](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/cppcrash-guidelines-V5) +- [Analyzing Cpp Crash](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V5/cppcrash-guidelines-V5) - [flutter_flutter](https://gitee.com/openharmony-sig/flutter_flutter) - [flutter_engine](https://gitee.com/openharmony-sig/flutter_engine) diff --git a/ohos/docs/08_FAQ/ohos-code.md b/ohos/docs/08_FAQ/ohos-code.md index 74155f36a3e496aee628913093e010ad11147656..629ab1f87b3e50dc796fe38cda4eca134145363e 100644 --- a/ohos/docs/08_FAQ/ohos-code.md +++ b/ohos/docs/08_FAQ/ohos-code.md @@ -9,3 +9,73 @@ bool isOhos() { return defaultTargetPlatform == TargetPlatform.ohos; } ``` + + +## Execution of flutter run, flutter build har and flutter attach Fail if Platform.isOhos Exists in the Code +Symptom: +**Platform.isOhos** exists in the Flutter code, as shown in the following: +``` +if (Platform.isAndroid || Platform.isOhos) { + print("test"); +} +``` +When the engine product of the server is depended without specifying the local engine product, the **flutter run**, **flutter build har** and **flutter attach** commands fail to be executed. +Error log: +![](../media/08/code1.png) + +Solution: +Change **Platform.isOhos** to **defaultTargetPlatform == TargetPlatform.ohos**. + + +## Native OpenHarmony Applications Fail to Obtain the Image Resources from Flutter +Question:
When a plugin is used, the object **binding: FlutterPluginBinding** is returned. A native OpenHarmony application cannot use **binding.getFlutterAssets().getAssetFilePathByName('xxxx')** of this object to obtain the image resources from the Flutter library while it can directly use **Image(this.img)** to obtain on the OpenHarmony platform. Is there any other way to obtain the resource? + +Answer:
**binding.getFlutterAssets().getAssetFilePathByName('xxxx')** is used to obtain the resource path. To obtain native image resources, see the code as follows: +![](../media/08/code2_EN.png) +``` +import { image } from '@kit.ImageKit'; +@Component +export struct DemoComponent { + @Prop params: Params + viewManager: DemoView = this.params.platformView as DemoView + image?: string + @State imageSource:image.ImageSource|null=null + + async aboutToAppear() { + let args: HashMap = this.viewManager.args as HashMap + this.image = args.get('src') as string + let rmg = DemoPluginAssetPlugin.binding.getApplicationContext(). resourceManager; + let rawfile = await rmg.getRawFileContent("flutter_assets/${this.image}"); + let buffer = rawfile.buffer.slice(0); + this.imageSource = image.createImageSource(buffer); + } + + build() { + Column(){ + if(this.imageSource){ + Image(this.imageSource.createPixelMapSync()) + } + } + } + + // aboutToAppear(): void { + // let args: HashMap = this.viewManager.args as HashMap + // this.image = args.get('src') as string + // } + + // build() { + // // Todo: critical point + // // Image(this.image) + // Image(DemoPluginAssetPlugin.binding.getFlutterAssets().getAssetFilePathByName (this.image)) + // // Image(DemoPluginAssetPlugin.binding.getFlutterAssets(). getAssetFilePathBySubpath(this.image)) + // } +} +``` +Question:
Why the **build** method is directly triggered when I add a breakpoint to **let rawfile = await rmg.getRawFileContent("flutter_assets/"+this.image );** and continue to execute the breakpoint? + +Answer:
**let rawfile = await rmg.getRawFileContent("flutter_assets/"+this.image );** is a time-consuming operation. During debugging, the remaining code of the current method is not executed until the time-consuming operation returns a result. The **build** method is for rendering only. + +Reference: +[demo](https://onebox.huawei.com/p/b3e5806b9ce3683c8c13b237ec319294) + +Execute files in **demo_plugin_asset\example\ohos** to display pages. Images are displayed in the Flutter image display page while no image is displayed in the native image display page. Related code is stored in **demo_plugin_asset\example\lib\main.dart** and **demo_plugin_asset\ohos\src\main\ets\components\plugin\DemoPluginAssetPlugin.ets**. diff --git a/ohos/docs/08_FAQ/ohos-hap.md b/ohos/docs/08_FAQ/ohos-hap.md new file mode 100644 index 0000000000000000000000000000000000000000..678d1e06c2969e40139b3ff9e4831ac562ad7528 --- /dev/null +++ b/ohos/docs/08_FAQ/ohos-hap.md @@ -0,0 +1,142 @@ +# ohos Application Compilation + +## Configure aliases to simplify compilation instructions during routine development. + +Configure aliases in the configuration file of the environment variables to simplify the instructions used for OpenHarmony Flutter. + +- For Windows, use `Git Bash` to execute common Linux instructions. (How to use: Right-click the blank area in the file manager and choose **Git Bash Here** from the shortcut menu.) +- For Linux, modify `~/.bash_profile`. +- For macOS, modify `~/.bash_profile` and add `source ~/.bash_profile` to `~/.zshrc`. + +```sh +# --The --local-engine parameter is optional and points to the self-compiled engine product. You are advised to use this parameter in the Linux or macOS environment. +export ENGINE_DIR=~/ohos/engine +export ENGINE_DEBUG=$ENGINE_DIR/src/out/ohos_debug_unopt_arm64 +export ENGINE_PROFILE=$ENGINE_DIR/src/out/ohos_profile_arm64 +export ENGINE_RELEASE=$ENGINE_DIR/src/out/ohos_release_arm64 + +alias fbuildD="flutter build hap --local-engine=$ENGINE_DEBUG --debug" +alias fbuildP="flutter build hap --local-engine=$ENGINE_PROFILE --profile" +alias fbuildR="flutter build hap --local-engine=$ENGINE_RELEASE --release" +alias frunD="flutter run -d $(hdc list targets) --local-engine=$ENGINE_DEBUG --debug" +alias frunP="flutter run -d $(hdc list targets) --local-engine=$ENGINE_PROFILE --profile" +alias frunR="flutter run -d $(hdc list targets) --local-engine=$ENGINE_RELEASE --release" +``` + +How to use: + +After the configuration, reopen the terminal window. Now you can use the aliases when compiling or running the project. + +```sh +flutter create hello --platforms ohos +cd hello +# Compile the debug version. +fbuildD +# Run the debug version. +frunD +``` + +## A Flutter application crashes in the release mode, but performs properly in the dev mode. + +Problem analysis: + +The **flutter.har** file of the debug version is used. + +Solution: + +Repackage the **flutter.har** file of the release version. + +## White screen occurs after the application is compiled and installed. + +Error log: + +```log +Reason:Signal:SIGSEGV(SEGV_MAPERR)@0x00000086e3272bf8 +LastFatalMessage:Thread:547846269584[FATAL:flutter/runtime/dart_vm_initializer.cc] Error while initializing the Dart VM: Wrong full snapshot version, expected '8af474944053df1f0a3be6e6165fa7cf' found 'adb4292f3ec25074ca70abcd2d5c7251' +``` + +Problem analysis: + +Engine products mismatch the running mode, causing a white screen. + +Solution: + +In the running or compilation instructions, make sure the engine products match the running mode. Reference: + +```sh +flutter run -d --debug +flutter run -d --release +flutter run -d --profile +``` + +## A Flutter plugin before reconstruction uses the reconstructed plugin library, causing an error in compiling applications. + +Error log: + +```log +Oops; flutter has exited unexpectedly: "type 'Null' is not a subtype of type 'List' in type cast". +``` + +Solution: +Update **flutter_flutter** to the latest version of master or dev.(45bd5e627e1f1e5f4d335f205781565f576acc60, 2024-05-10) + +## Dependency conflicts are reported during the running of flutter pub get. + +Error log: + +```log +Resolving dependencies... +Because flutter_cache_manager >=3.0.0-nullsafety.0 <3.3.2 depends on path_provider from hosted and flutter_cache_manager depends on path_provider from git, flutter_cache_manager >=3.0.0-nullsafety.0 <3.3.2 forbidden. +So bedause xxx depends on flutter_cache_manager 3.3.1, version solving failed. +pub get failed +... +exit code: 1 +``` + +Solution: + +Use `dependency_overrides` to eliminate dependency conflicts. + +```yaml +dependencies: + flutter: + sdk: flutter +dependency_overrides: + path_provider: + git: + url: https://gitee.com/openharmony-sig/flutter_packages.git + path: packages/path_provider/path_provider + path_provider_ohos: + git: + url: https://gitee.com/openharmony-sig/flutter_packages.git + path: packages/path_provider/path_provider_ohos +``` + +## The SDK license agreement is not accepted. + +Error log: + +```log +hvigor install success. +> hvigor ERROR: Cause: The SDK license agreement is not accepted. +``` + +Problem analysis:
The structure of the ohos project is in API version 11, but the SDK used is in API version 12. + +Solution:
Upgrade the ohos project structure to API version 12. + +Steps: +1. DevEco Studio -> Migrate Assistant -> 5.0.0 -> Migrate +2. DevEco Studio -> File -> Project Structure -> Compatible SDK -> 5.0.0(12) + +## The versionName field in the app.json file is reset when the flutter build hap -release command is used to compile the version. +Background: +Check the **versionName** field in the **app.json** file and execute the **flutter build hap -release** command to generate a package. + +Symptom:
The secondary field is reset to **1.0.0** again. + +Cause:
This version number is used by default in build. + +Solution:
Specify **versionName** and **versionCode** in build. + +Reference:
flutter build hap --build-name=4.0.3 --build-number=10000 diff --git a/ohos/docs/08_FAQ/ohos-run.md b/ohos/docs/08_FAQ/ohos-run.md index 892d61e6129b62a3a391461c599039f3e920a7bf..f031d04cfdbfc87286313afd48282711ad1fd164 100644 --- a/ohos/docs/08_FAQ/ohos-run.md +++ b/ohos/docs/08_FAQ/ohos-run.md @@ -1,12 +1,10 @@ -# ohos Program Running +# ohos Running -## Runtime Error Occurring at /data/storage/el1/bundle/entry/ets/modules.abc After Compiling OpenHarmony - -Phenomenon: A runtime error occurs after compiling Flutter on OpenHarmony. - -Error message: +## Runtime Error Occurs After a OpenHarmony Flutter Application Is Compiled +Symptom:
A runtime error occurs after an OpenHarmony Flutter application is compiled. +Error: ``` com.wit.appzoo_flutter_v2 is about to exit due to RuntimeError Error type:ReferenceError @@ -18,7 +16,6 @@ SourceMap is not initialized yet #01 pc 00000000005fd128 /system/lib64/platformsdk/libark_jsruntime.so(5144aa99644b9dba57555adfb9e0ede6) #02 pc 00000000002ac540 /system/lib64/platformsdk/libark_jsruntime.so(5144aa99644b9dba57555adfb9e0ede6) ``` - -Possible causes: -The file /data/storage/el1/bundle/entry/ets/modules.abc may fail to run properly due to an SDK and image mismatch. The root cause is that the SDK tools and the image version are not aligned. It is recommended to use a matching SDK and mobile image version. Please provide the current mobile version and IDE version screenshots. -If the versions match, please provide the complete logs. +Possible causes: +**/data/storage/el1/bundle/entry/ets/modules.abc** may not run properly due to SDK and image version mismatch. In this case, you are advised to use the SDK that matches the mobile phone image version. Provide the current mobile phone version and DevEco Studio version to us so that we can help you fix this issue. +If the versions are matched, provide the complete logs. diff --git a/ohos/docs/media/05/image-4-401_EN.png b/ohos/docs/media/05/image-4-401_EN.png new file mode 100644 index 0000000000000000000000000000000000000000..28ea5999dd41d0c762a4737b955896461b57b77e Binary files /dev/null and b/ohos/docs/media/05/image-4-401_EN.png differ diff --git a/ohos/docs/media/08/code2_EN.png b/ohos/docs/media/08/code2_EN.png new file mode 100644 index 0000000000000000000000000000000000000000..f683ed7a0902f594f2727200e41a78f519b0aa11 Binary files /dev/null and b/ohos/docs/media/08/code2_EN.png differ