Flutter SDK Repository

Source of the original repository: https://github.com/flutter/flutter

Repository Description

This repository is an extension of the Flutter SDK for compatibility with OpenHarmony. It allows DevEco Studio IDE or terminals to use Flutter Tools instructions to compile and build OpenHarmony applications.

Flutter OH version evolution planning and branching strategy

You can learn more about our adaptation of Flutter for OpenHarmony in the Flutter OH version evolution planning and branching strategy.

Development Documentation

Flutter_samples

Environment Dependencies

• Development system

  Linux, macOS, or Windows that supports the Flutter Tools instructions.

• Development restrictions

  For Windows, the Flutter project and the dependent plugin project must be in the same disk.

• Environment configuration Download the supporting development kits from OpenHarmony SDK. For Unix-like systems (Linux and macOS), you can refer to the environment variable configuration below. For Windows, set environment variables by following the instructions provided in "Edit System Environment Variables."

  1. Configure the OpenHarmony SDK and the environment variables.
  • API 18, DevEco Studio 5.1, or command-line-tools-5.1.
  • Download JDK 17 and configure environment variables.

  # macOS environment
  export JAVA_HOME=<JAVA_HOME path>/Contents/Home
  export PATH=$JAVA_HOME/bin:$PATH
  
  # Windows environment
  JAVA_HOME = <JAVA_HOME path>
  PATH=%JAVA_HOME%\bin
  

  • Configure the environment variables (SDK, node, ohpm, and hvigor).

  # macOS environment
  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
  
  # Windows environment
  TOOL_HOME = D:\devecostudio-windows\DevEco Studio
  DEVECO_SDK_HOME=%TOOL_HOME%\sdk
  PATH=%TOOL_HOME%\tools\ohpm\bin
  PATH=%TOOL_HOME%\tools\hvigor\bin
  PATH=%TOOL_HOME%\tools\node
  

  2. Use a code editor to download the current repository code by running git clone https://gitcode.com/openharmony-tpc/flutter_flutter.git, specify the dev or master branch, and set up the environment.

  export PUB_CACHE=D:/PUB
  export PATH=<flutter_flutter path>/bin:$PATH
  export PUB_HOSTED_URL=https://pub.flutter-io.cn
  export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn
  

  3. The code snippet below shows how to configure all the preceding environment variables. Use the actual username and code paths in practice.

  #Dependency cache
  export PUB_CACHE=D:/PUB (custom path)
  
  # 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 gitcode
  export PATH=/home/<user>/ohos/flutter_flutter/bin:$PATH
  
  # HamonyOS 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
  

How to Build

1. Run flutter doctor -v to check whether the environment variable configuration is correct. The check results for both Flutter and OpenHarmony should be ok. If there are any prompts indicating missing environment variable configuration, follow the prompts to configure the environment.

2. Create a project.

   # Create a project.
   flutter create --platforms ohos <projectName>
   

3. Build the HAP file. The build product is stored in <projectName>/ohos/entry/build/default/outputs/default/entry-default-signed.hap.

   # Enter the root directory of the project and build the project.
   # Example: flutter build hap [--target-platform ohos-arm64] --release
   flutter build hap --release
   

4. Install the application. Execute flutter devices instruction to discover a real device and install the application on the real device.

   Method 1: Go to the build product directory and install the application on the device.

   hdc -t <deviceId> install <hap file path>
   

   Method 2: Go to the project directory and run the application to install it on the device.

   flutter run --debug -d <deviceId>
   

5. Build the application using the following instruction:

   # Example: flutter build app --release
   flutter build app --release
   

Instruction List Compatible with OpenHarmony

Instruction	Description	How to Use
doctor	Detects the environment.	flutter doctor
config	Configures the environment.	flutter config --<key> <value>
create	Creates a project.	flutter create --platforms ohos,android,ios --org <org> <appName>
create	Creates a module template.	flutter create -t module <module_name>
create	Creates a plugin template.	flutter create -t plugin --platforms ohos,android,ios <plugin_name>
create	Creates a plugin_ffi template.	flutter create -t plugin_ffi --platforms ohos,android,ios <plugin_name>
devices	Searches for connected devices.	flutter devices
install	Installs an application.	flutter install -t <deviceId> <hap file path>
assemble	Pack resources.	flutter assemble
build	Builds the test application.	flutter build hap --debug [--target-platform ohos-arm64]
build	Builds the formal application.	flutter build hap --release [--target-platform ohos-arm64]
run	Runs the application.	flutter run
attach	Enters debug mode.	flutter attach
screenshot	Takes a screenshot.	flutter screenshot
pub	Obtains the dependencies.	flutter pub get
clean	Clears the project dependencies.	flutter clean
cache	Clears global cache data.	flutter pub cache clean

Appendix: Flutter Third-Party Library Adaptation Program

FAQs

1. The emulator can be only debugged on macOS (ARM64) and Windows (x86).

2. After switching to FLUTTER_STORAGE_BASE_URL, you need to delete the <flutter>/bin/cache directory and execute flutter clean in the project before running the project.

3. The message Error: The hvigor depends on the npmrc file. Configure the npmrc file first. is displayed when building the HAP.

   Solution: Create the .npmrc file in the ~ directory. For details about the configuration, see DevEco Studio User Guide. The file content is as follows:

   registry=https://repo.huaweicloud.com/repository/npm/
   @ohos:registry=https://repo.harmonyos.com/npm/
   

4. Logs are lost. Solution: Disable global logging and enable logging of your own domain.

   Step 1: Disable logging in all domains. (Printing for some special logs cannot be disabled.)
   hdc shell hilog -b X
   Step 2: Enable logging of your own domain.
   hdc shell hilog <level> -D <domain> 
   In the preceding instruction, \<level> indicates the log levels such as D, I, W, E, and F; \<domain> indicates the number before tag.
   Example:
   To print A00000/XComFlutterOHOS_Native logs, set `hdc shell hilog -b D -D A00000`.
   Note: The preceding settings become invalid after the device is restarted. If you want to continue using the settings, configure them again.
   

5. If the application with the debug signature cannot be started on a device of API 11 Beta1, replace the debug signature with a formal signature or enable the developer mode on the device. (Steps: Go to Settings > General > Developer mode.)

6. Updated ROM of Beta2 no longer supports anonymous memory with the execution permission. As a result, debugging crashes.

   1. Solution: Update flutter_flutter to a version later than a44b8a6d (2024-07-25).
   2. Key logs:

   #20 at attachToNative (oh_modules/.ohpm/@ohos+flutter_ohos@g8zhdaqwu8gotysbmqcstpfpcpy=/oh_modules/@ohos/flutter_ohos/src/main/ets/embedding/engine/FlutterNapi.ets:78:32)
   #21 at attachToNapi (oh_modules/.ohpm/@ohos+flutter_ohos@g8zhdaqwu8gotysbmqcstpfpcpy=/oh_modules/@ohos/flutter_ohos/src/main/ets/embedding/engine/FlutterEngine.ets:144:5)
   #22 at init (oh_modules/.ohpm/@ohos+flutter_ohos@g8zhdaqwu8gotysbmqcstpfpcpy=/oh_modules/@ohos/flutter_ohos/src/main/ets/embedding/engine/FlutterEngine.ets:133:7)
   

7. After the environment is configured, crash occurs when execute the flutter instruction.

   1. Solution: Add the Git environment variable configuration to the Windows environment.

   export PATH=<git path>/cmd:$PATH
   

8. The flutter pub cache clean instruction is executed successfully, but an error is reported when the flutter clean instruction is executed. In this case, executing the update instruction according to the error message does not take effect.

   1. Solution: Add comment to the configuration in the build.json5 file. For example, "modules": [{ // Delete the entire object corresponding to the error}].
   2. Error message:

   #Parse ohos module. json5 error: Exception: Cannot found module.json5 at
   #D:\pub_cache\git\flutter_packages-b00939bb44d018f0710d1b080d91dcf4c34ed06\packages\video_player\video_player_ohos\ohossrc\main\module.json5.
   #You need to update the Flutter plugin project structure.
   #See
   #https://gitcode.com/openharmony-tpc/flutter_samples/blob/master/ohos/docs/09_specifications/update-flutter-plugin-structure.md
   

9. In the .ohos project, errors are reported when the flutter clean and the flutter pub get instructions are executed.

   1. Solution: Delete the .ohos folder and execute the flutter pub get instruction again.
   2. Error message:

   Oops; flutter has exited unexpectedly: "PathNotFoundException: Cannot open file, path = 'D:\code\.ohos\build-profile.json5' (OS Error: Specified file not found, error = 2)".
   A crash report has been written to D:\code\flutter_01.log.
   

10. In the version on the shelves, a crash occurred with the CppCrash error message: Reason: Signal: SIGABRT(SI_TKILL).

The error occurred because the developer used anonymous memory and failed to apply for executable permission for the memory, resulting in an exception.

Solution: Check whether the code uses mmap or if the plugin uses methods such as Pointer.fromFunction and dart ffi.

Error message: Reason:Signal:SIGABRT(SI_TKILL)@0x01317b310000fc96 from:64662:20020017 LastFatalMessage:../../third_party/dart/runtime/vm/virtual_memory_posix.cc: 74: error: mmap failed: 22 (Invalid argument) Fault thread info: Tid:64662, Name:xxxx

Reference: [FAQs] (https://gitcode.com/openharmony-tpc/flutter_samples/blob/master/ohos/docs/08_FAQ/README_EN.md)