From 144c8fadf331493f623bd6355b072b2a046d509e Mon Sep 17 00:00:00 2001 From: xuchang Date: Wed, 27 Dec 2023 10:45:16 +0800 Subject: [PATCH] =?UTF-8?q?IssueNo:=20#I8RDIM=20=E6=9B=B4=E6=96=B0?= =?UTF-8?q?=E8=AF=B4=E6=98=8E=E6=96=87=E6=A1=A3=20Sig:=20OpenHarmony-SIG/f?= =?UTF-8?q?lutter-flutter=20Feature=20or=20Bugfix:=20Feature=20Binary=20So?= =?UTF-8?q?urce:=20No?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: xuchang --- README.en.md | 263 ++++++++++++++++++++++++++------------------------- README.md | 256 +++++++++++++++++++++++++------------------------ 2 files changed, 265 insertions(+), 254 deletions(-) diff --git a/README.en.md b/README.en.md index 87cec4393b..10b4ed164d 100644 --- a/README.en.md +++ b/README.en.md @@ -3,69 +3,64 @@ Flutter SDK repository Original warehouse source: https://github.com/flutter/flutter -## Warehouse description: -This warehouse is based on the compatible extension of flutter sdk for OpenHarmony, and can support the use of flutter tools instructions to compile and build OpenHarmony applications. +## Warehouse description +This repository is a compatible extension of Flutter SDK for the OpenHarmony platform, and can support IDE or terminal use of Flutter Tools instructions to compile and build OpenHarmony applications. -## Build instructions: +## Environment dependencies -* Build environment: - The flutter tools command supports use on Linux/Mac/Windows. +* development system -* Build dependencies: - Depend on [flutter engine](https://github.com/flutter/engine) to build products: `ohos_debug_unopt_arm64` and `ohos_release_arm64`, please add: `--local-engine=<engine product in the running parameters of the flutter tools command Directory>` + Flutter Tools commands are currently supported on Linux, Mac and Windows. -* Building steps: +* Environment configuration - **For Windows environment, please set environment variables in Environment Variables Dialog** + **For the following environment variable configuration, you can directly refer to the configuration under Unix-like systems (Linux, Mac). For environment variable configuration under Windows, please set it in ‘Edit System Environment Variables’** - 1. Download [command line tool](https://developer.harmonyos.com/cn/develop/deveco-studio#download_cli), and configure the environment variables ohpm and sdkmanager. After the download is complete, execute `ohpm/bin/init` to install ohpm. Refer to the guidance document: [ohpm usage guide](https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/ide-command-line-ohpm-0000001490235312-V3). + 1. Download [ohpm command line tool](https://developer.harmonyos.com/cn/develop/deveco-studio#download_cli), and configure the environment variables ohpm and sdkmanager. After the download is completed, execute `bin/init in the ohpm directory `Initialize ohpm. Refer to the guidance document: [ohpm usage guide](https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/ide-command-line-ohpm-0000001490235312-V3). ``` export OHPM_HOME=/home//ohos/oh-command-line-tools/ohpm/ - export PATH=/home//ohos/oh-command-line-tools/sdkmanager/bin:$PATH - export PATH=$PATH:$OHPM_HOME/bin + export PATH=$PATH:$OHPM_HOME/bin:$OHPM_HOME/sdkmanager/bin ``` - 2. Download SDK and configure environment variables, please refer to [ohsdkmgr usage guide](https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/ide-command-line-ohsdkmgr-0000001545647965-V3 ) Use the command to download OpenHarmony sdk (below API9), AP10 needs to download ohos-full-sdk from [Daily Build](http://ci.openharmony.cn/workbench/cicd/dailybuild/detail/component), please keep the sdk The directory structure is as follows. (To compile in mac environment, please download mac-sdk-full or mac-sdk-m1-full) + 2. Download OpenHarmony SDK and configure environment variables + * API9 SDK download: Please refer to [ohsdkmgr usage guide](https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/ide-command-line-ohsdkmgr-0000001545647965-V3) Use the command to download SDK below API9; + *API10 SDK needs to be downloaded from [Daily Build](http://ci.openharmony.cn/workbench/cicd/dailybuild/detail/component) (download `ohos-full-sdk` for Linux and Windows, please download `mac for Mac -sdk-full` or `mac-sdk-m1-full`), please keep the SDK directory structure as follows after decompression: + + ``` + /SDK + ├── 10 + │ └── ets + │ └── js + │ └── native + │ └── previewer + │ └── toolchains + ├── 9 + ... + ``` + + * Configure environment variables + + ``` + export OHOS_SDK_HOME=/home//env/sdk + export HDC_HOME=/home//env/sdk/10/toolchains + export PATH=$PATH:$HDC_HOME + + # Configure HarmonyOS SDK + export HOS_SDK_HOME= + ``` + + 3. Download the current warehouse code `git clone https://gitee.com/openharmony-sig/flutter_flutter.git` through the code tool, and configure the environment ``` - export OHOS_SDK_HOME=/home//env/sdk - export HDC_HOME=/home//env/sdk/10/toolchains - export PATH=$PATH:$HDC_HOME - # for HarmonyOS sdk - export HOS_SDK_HOME=/home//env/{HarmonyOS sdk} - ``` - - ``` - /SDK - ├── 10 - │ └── ets - │ └── js - │ └── native - │ └── previewer - │ └── toolchains - ├── 9 - ... - ``` - - 3. Configure Gradle: Download `gradle 7.3` and unzip it, configure it into environment variables: - - ``` - # grade - export PATH=/home//env/gradle-7.3/bin:$PATH - ``` - - 4. Download Flutter and configure the environment after the download is complete: + export PATH=/bin:$PATH - ``` - git clone https://gitee.com/openharmony-sig/flutter_flutter.git - - export PATH=/home//ohos/flutter_flutter/bin:$PATH + # Flutter pub domestic mirror export PUB_HOSTED_URL=https://pub.flutter-io.cn export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn ``` - 5. The signature tool requires the following configuration: + 4. Configure the signing tool - Download [Signature Tool](https://gitee.com/openharmony/developtools_hapsigner) and configure the environment variable SIGN_TOOL_HOME. @@ -73,7 +68,7 @@ This warehouse is based on the compatible extension of flutter sdk for OpenHarmo export SIGN_TOOL_HOME=/home//ohos/developtools_hapsigner/autosign ``` - - Execute the following command to compile hap-sign-tool.jar and make sure it is in the directory: ./hapsigntool/hap_sign_tool/build/libs/hap-sign-tool.jar. + - Execute the gradle command to compile and obtain hap-sign-tool.jar. Make sure it is in the directory: ./hapsigntool/hap_sign_tool/build/libs/hap-sign-tool.jar. (gradle version recommended 7.x) ``` gradle build @@ -85,7 +80,7 @@ This warehouse is based on the compatible extension of flutter sdk for OpenHarmo sign.profile.inFile=profile_tmp.json ``` - - In the autosign directory, execute the command `chmod 777 *.sh`（There is no need to execute this command in Windows environment）, and add the `profile_tmp_template.json` file, edit it as follows: + - In the autosign directory (the command `chmod 777 *.sh` must be executed first in linux and mac environments, and there is no need to execute this command in Windows environment), add the `profile_tmp_template.json` file and edit it as follows: ``` { @@ -100,7 +95,7 @@ This warehouse is based on the compatible extension of flutter sdk for OpenHarmo "type": "release", "bundle-info": { "developer-id": "OpenHarmony", - "distribution-certificate": "-----BEGIN CERTIFICATE-----\nMIICSTCCAc+gAwIBAgIFAJV7uNUwCgYIKoZIzj0EAwIwYzELMAkGA1UEBhMCQ04x\nFDASBgNVBAoMC09wZW5IYXJtb255MRkwFwYDVQQLDBBPcGVuSGFybW9 ueSBUZWFt\nMSMwIQYDVQQDDBpPcGVuSGFybW9ueSBBcHBsaWNhdGlvbiBDQTAeFw0yMjAxMjkw\nNTU0MTRaFw0yMzAxMjkwNTU0MTRaMGgxCzAJBgNVBAYTAkNOMRQwEgYDVQQKDAtP\ncGVuSGFyb W9ueTEZMBcGA1UECwwQT3Blbkhhcm1vbnkgVGVhbTEoMCYGA1UEAwwf\nT3Blbkhhcm1vbnkgQXBwbGljYXRpb24gUmVsZWFzZTBZMBMGByqGSM49AgEGCCqG\nSM49AwEHA0IABAW8pFu7tHGUuWtddD5wvaz c1qN8ts9UPZH4pecbb/bSFWKh7X7R\n/eTVaRrCTSSdovI1dhoV5GjuFsKW+jT2TwSjazBpMB0GA1UdDgQWBBScyywAaAMj\nI7HcuIS42lvZx0Lj+zAJBgNVHRMEAjAAMA4GA1UdDwEB/wQEAwIHgDA TBgNVHSUE\ nDDAKBggrBgEFBQcDAzAYBgwrBgEEAY9bAoJ4AQMECDAGAgEBCgEAMAoGCCqGSM49\nBAMCA2gAMGUCMFfNidGo6uK6KGT9zT1T5bY1NCHTH3P3muy5X1xudOgxWoOqIbnk\ntmQYB78dxWEHLQIxANfApAlXAD /0hnyNC8RDzfLOPEeay6jU9FXJj3AoR90rwZpR\noN9sYD6Oks4VGRw6yQ==\n-----END CERTIFICATE-----\n", + "distribution-certificate": "-----BEGIN CERTIFICATE-----\nMIICSTCCAc+gAwIBAgIFAJV7uNUwCgYIKoZIzj0EAwIwYzELMAkGA1UEBhMCQ04x\nFDASBgNVBAoMC09wZW5IYXJtb255MRkwFwYDVQQLDBBPcGVuSGFybW9ueS BUZWT ZMBcGA1UECwwQT3Blbkhhcm1vbnkgVGVhbTEoMCYGA1UEAwwf\nT3Blbkhhcm1vbnkgQXBwbGljYXRpb24gUmVsZWFzZTBZMBMGByqGSM49AgEGCCqG\nSM49AwEHA0IABAW8pFu7tHGUuWtddD5wvazc1qN8t s9UPZH4pecbb/bSFWKh7X7R\n/eTVaRrCTSSdovI1dhoV5GjuFsKW+jT2TwSjazBpMB0GA1UdDgQWBBScyywAaAMj\nI7HcuIS42lvZx0Lj+zAJBgNVHRMEAjAAMA4GA1UdDwEB/wQEAwIHgDATBgNVHSUE\ nDDAKBggrBgEFBQcDAzAYBgwrBgEEAY9bAoJ4AQMECDAGAgEBCgEAMAoGCCqGSM49\nBAMCA2gAMGUCFfNidGo6uK6KGT9zT1T5bY1NCHTH3P3muy5X1xudOgxWoOqIbnk\ntmQYB78dxWEHLQIxANfApAlXAD/0 hnyNC8RDzfLOPEeay6jU9FXJj3AoR90rwZpR\noN9sYD6Oks4VGRw6yQ==\n-----END CERTIFICATE-----\n", "bundle-name": "{{ohosId}}", "apl": "normal", "app-feature": "hos_normal_app" @@ -117,107 +112,99 @@ This warehouse is based on the compatible extension of flutter sdk for OpenHarmo } ``` - 6. If the `.npmrc` configuration is not created in the `~/` directory, an error may be reported when building hap: Error: The hvigor depends on the npmrc file. Configure the npmrc file first. Please configure the npmrc file first in the user directory` Create the file `.npmrc` under ~/`. For this configuration, you can also refer to [Official Documentation](https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/environment_config- 0000001052902427-V3), the edited content is as follows: + 5. The application build relies on [Flutter Engine](https://github.com/flutter/engine) to build products: `ohos_debug_unopt_arm64` and `ohos_release_arm64`. Please add: `--local-engine= in the Flutter Tools command running parameters. \` - ``` - registry=https://repo.huaweicloud.com/repository/npm/ - @ohos:registry=https://repo.harmonyos.com/npm/ - ``` - - For the configuration of all the above environment variables, please refer to the following example (Please replace user and specific code path with the actual path. For Windows environment, please set environment variables in Environment Variables Dialog): + For the configuration of all the above environment variables (for environment variable configuration under Windows, please set it in 'Edit System Environment Variables'), you can refer to the following example (please replace user and specific code path with the actual path): -``` -#flutter env start ===> + ``` + #flutter env start ===> -# Domestic mirror -export PUB_HOSTED_URL=https://pub.flutter-io.cn -export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn + # Domestic mirror + export PUB_HOSTED_URL=https://pub.flutter-io.cn + export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn -# flutter_flutter directory pulled from Gitee -export FLUTTER_HOME=/home//ohos/flutter_flutter -export PATH=$PATH:$FLUTTER_HOME/bin + # The flutter_flutter directory pulled from Gitee + export FLUTTER_HOME=/home//ohos/flutter_flutter + export PATH=$PATH:$FLUTTER_HOME/bin -# Unzip the commandline/ohcommandline tools mac-2.1.3.6.zip file in the DevEco Studio installation package, which includes the ohpm directory -export OHPM_HOME=/home//ohos/oh-command-line-tools/ohpm -export PATH=$PATH:$OHPM_HOME/bin + # Unzip the ohpm subdirectory after commandline/ohcommandline-tools-mac-2.1.3.6.zip in the DevEco Studio installation package + export OHPM_HOME=/home//ohos/oh-command-line-tools/ohpm + export PATH=$PATH:$OHPM_HOME/bin -# Unzip the commandline/ohcommandline tools mac-2.1.3.6.zip file in the DevEco Studio installation package, which includes the sdkmanager directory -export PATH=/home//ohos/oh-command-line-tools/sdkmanager/bin:$PATH + # Unzip the sdkmanager subdirectory after commandline/ohcommandline-tools-xxx.zip in the DevEco Studio installation package + export PATH=/home//ohos/oh-command-line-tools/sdkmanager/bin:$PATH -# HarmonyOS SDK, Unzip the sdk/X86SDK.zip or M1SDK.zip file in the DevEco Studio installation package, whick contains three direct subdirectories: openharmony, hmscore, and licenses -export HOS_SDK_HOME=/home//ohos/sdk + # HarmonyOS SDK, unzip the directory after sdk/X86SDK.zip or M1SDK.zip in the DevEco Studio installation package. There are three direct subdirectories under HOS_SDK_HOME: openharmony, hmscore, and licenses + export HOS_SDK_HOME=/home//ohos/sdk -# OpenHarmony SDK, Unzip the sdk/X86SDK.zip or M1SDK.zip file in the DevEco Studio installation package, which includes the openharmony directory -export OHOS_SDK_HOME=/home//ohos/sdk/openharmony + # OpenHarmony SDK, unzip the openharmony subdirectory after sdk/X86SDK.zip or M1SDK.zip in the DevEco Studio installation package + export OHOS_SDK_HOME=/home//ohos/sdk/openharmony -# HDC Home, directory 10/toolchains under OHOS_SDK_HOME -export HDC_HOME=/home//ohos/sdk/openharmony/10/toolchains -export PATH=$PATH:$HDC_HOME + # HDC Home, 10/toolchains subdirectory under the OHOS_SDK_HOME directory + export HDC_HOME=/home//ohos/sdk/openharmony/10/toolchains + export PATH=$PATH:$HDC_HOME -# Signature tool -export SIGN_TOOL_HOME=/home//ohos/developtools_hapsigner/autosign + # Signature tool + export SIGN_TOOL_HOME=/home//ohos/developtools_hapsigner/autosign -# grade -export PATH=/home//env/gradle-7.3/bin:$PATH -#nodejs -export NODE_HOME=/home//env/node-v14.19.1-linux-x64 -export PATH=$NODE_HOME/bin:$PATH + # grade + export PATH=/home//env/gradle-7.3/bin:$PATH -#flutter env end <=== -``` + #nodejs + export NODE_HOME=/home//env/node-v14.19.1-linux-x64 + export PATH=$NODE_HOME/bin:$PATH -- Construct + #flutter env end <=== + ``` -1. Run `flutter doctor -v` to check whether the environment variable configuration is correct. **Futter** and **Openharmony** should both be ok. If the two prompts indicate that the environment is missing, just follow the prompts to fill in the corresponding environment. +## Build steps -2. Create the project and compile the command. The compiled product is under flutter_demo/ohos/entry/build/default/outputs/default/entry-default-signed.hap. +1. Run `flutter doctor -v` to check whether the environment variable configuration is correct. **Futter** and **OpenHarmony** should both be ok. If the two prompts indicate that the environment is missing, just follow the prompts to fill in the corresponding environment. + +2. Create the project and compile the command. The compiled product is under \/ohos/entry/build/default/outputs/default/entry-default-signed.hap. ``` # Create project - flutter create --platforms ohos flutter_demo - # Enter the project root directory to compile, the `src/out` in `--local-engine` shoud be preserved. - flutter build hap --local-engine=/home//ohos/engine/src/out/ohos_release_arm64 --release - flutter build hap --local-engine=/home//ohos/engine/src/out/ohos_debug_unopt_arm64 --debug - ``` + flutter create --platforms ohos -3. After flutter devices discover the ohos device, use `hdc -t install ` to install it. + # Enter the project root directory to compile + # Example: flutter build hap --target-platform ohos-arm64 --local-engine-src-path=/home/user/code/flutter/engine_make/src --local-engine=ohos_release_arm64 + flutter build hap --target-platform ohos-arm64 --local-engine-src-path= --local-engine=ohos_release_arm64 + ``` -## About how to connect and debug OpenHarmony devices for Linux virtual machines under Windows +3. After discovering the ohos device through the `flutter devices` command, use `hdc -t install ` to install it. -* Problem: Linux virtual machine cannot directly discover OpenHarmony devices through hdc -* Solution: In the Windows host, open the hdc server. The specific instructions are as follows: -``` -hdc kill -hdc -s serverIP:8710 -m +4. You can also directly use the following command to run: ``` -Configure environment variables in linux: -``` -HDC_SERVER= -HDC_SERVER_PORT=8710 + # Example: flutter run --local-engine=/home/user/code/flutter/engine_make/src/out/ohos_debug_unopt_arm64 + flutter run --local-engine= ``` -After the configuration is completed, the flutter sdk can complete the device connection through the hdc server. You can also refer to [official guidance](https://docs.openharmony.cn/pages/v4.0/zh-cn/device-dev/subsystems/subsys-toolchain -hdc-guide.md/#hdc-client%E5%A6%82%E4%BD%95%E8%BF%9C%E7%A8%8B%E8%AE%BF%E9%97%AEhdc-server) -## Compatible command list developed by OpenHarmony: -| Command name | Command description | Instructions for use | -| ------------ | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| doctor | environment detection | flutter doctor | -| config | environment configuration | flutter config --<key> <value> | -| create | Create a new project | flutter create --platforms ohos,android --org <org> <appName> | -| devices | Connected device discovery | flutter devices | -| install | application installation | flutter install -t <deviceId> <hap file path> | -| assemble | resource packaging | flutter assemble | -| build | Test application build | flutter build hap --debug --local-engine=<debug engine product path compatible with ohos> \[--target-platform ohos-arm64\] | -| build | Formal application build | flutter build hap --release --local-engine=<ohos-compatible release engine product path> \[--target-platform ohos-arm64\] | -| run | application run | flutter run --local-engine=<ohos-compatible engine product path> | -| attach | debug mode | flutter attach | -| screenshot | catch screen | flutter screenshot | +## Compatible command list developed by OpenHarmony + +| Command name | Command description | Instructions for use | +| ------- | ------- |-------------------------------------------------------------------| +| doctor | environment detection | flutter doctor | +| config | environment configuration | flutter config --\ \ | +| create | Create a new project | flutter create --platforms ohos,android,ios --org \ \ | +| create | Create module template | flutter create -t module \ | +| create | Create plugin template | flutter create -t plugin --platforms ohos,android,ios \ | +| create | Create plugin_ffi template | flutter create -t plugin_ffi --platforms ohos,android,ios \ | +| devices | Connected device discovery | flutter devices | +| install | application installation | flutter install -t \ \ | +| assemble | resource packaging | flutter assemble | +| build | Test application build | flutter build hap --target-platform ohos-arm64 --debug --local-engine=\ | +| build | Formal application build | flutter build hap --target-platform ohos-arm64 --release --local-engine=\ | +| run | application run | flutter run --local-engine=\ | +| attach | debug mode | flutter attach | +| screenshot | screenshot | flutter screenshot | -Prompt: [Flutter third-party library adaptation plan](https://docs.qq.com/sheet/DVVJDWWt1V09zUFN2) +Attachment: [Flutter third-party library adaptation plan](https://docs.qq.com/sheet/DVVJDWWt1V09zUFN2) -## common problem: +## Common Problem -1. Recommended ohos sdk version: `4.0.10.3`, which can be downloaded around August 20 when it is built daily. If there are problems related to the SDK version during the compilation process, you can try to replace this version of the SDK. +1. Recommended version of OpenHarmony SDK: `4.0.10.3`, which can be downloaded around August 20 when it is built daily. If there are problems related to the SDK version during the compilation process, you can try to replace this version of the SDK. 2. If an error message appears: `The SDK license agreement is not accepted`, please execute the following command and compile again: @@ -229,16 +216,36 @@ Prompt: [Flutter third-party library adaptation plan](https://docs.qq.com/sheet/ 4. If `flutter docker -v` prompts that ohpm cannot be found, but the environment variables are detected correctly, please ensure that you have executed the `ohpm/bin/init` command to install ohpm and check again. -5. If you encounter the error Unsupported class file major version 61 when compiling the signature tool, it means that the current JDK version does not support it. You can command to display all JDK versions in the current system and select the required version. Enter the number and confirm the selection to compile again. +5. If you encounter the error Unsupported class file major version 61 when compiling the signature tool, it means that the current JDK version does not support it. Please lower the Java SDK version and try again. + +6. If you are using the Beta version of DevEco Studio and encounter the error "must have required property 'compatibleSdkVersion', location: demo/ohos/build-profile.json5:17:11" when compiling the project, please refer to "DevEco Studio" Modify the hvigor/hvigor-config.json5 file in the '6 Creating Projects and Running Hello World' [Configuration Plug-in] chapter in "Environment Configuration Guide.docx". + +7. If you are prompted with an installation error: `fail to verify pkcs7 file`, please execute the command ``` - sudo update-alternatives --config java + hdc shell param set persist.bms.ohCert.verify true ``` +8. Linux virtual machine cannot directly discover OpenHarmony devices through hdc -6. If you are using the Beta version of DevEco Studio and encounter the error "must have required property 'compatibleSdkVersion', location: demo/ohos/build-profile.json5:17:11" when compiling the project, please refer to "DevEco Studio" Modify the hvigor/hvigor-config.json5 file in the '6 Creating Projects and Running Hello World' [Configuration Plug-in] chapter in "Environment Configuration Guide.docx". + Solution: In the Windows host, open the hdc server. The specific instructions are as follows: + ``` + hdc kill + hdc -s serverIP:8710 -m + ``` + Configure environment variables in linux: + ``` + HDC_SERVER= + HDC_SERVER_PORT=8710 + ``` -7. If an installation error is prompted: `fail to verify pkcs7 file`, please execute + After the configuration is completed, the flutter sdk can complete the device connection through the hdc server. You can also refer to [official guidance](https://docs.openharmony.cn/pages/v4.0/zh-cn/device-dev/subsystems/subsys-toolchain -hdc-guide.md/#hdc-client%E5%A6%82%E4%BD%95%E8%BF%9C%E7%A8%8B%E8%AE%BF%E9%97%AEhdc-server) . - ``` - hdc shell param set persist.bms.ohCert.verify true - ``` \ No newline at end of file +9. An error occurred when building the Hap task: Error: The hvigor depends on the npmrc file. Configure the npmrc file first. + + + Please create the file `.npmrc` in the user directory `~`. For this configuration, please refer to [DevEco Studio official documentation](https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/environment_config -0000001052902427-V3), the edited content is as follows: + + ``` + registry=https://repo.huaweicloud.com/repository/npm/ + @ohos:registry=https://repo.harmonyos.com/npm/ + ``` \ No newline at end of file diff --git a/README.md b/README.md index 8ea7821179..8ee6acfd40 100644 --- a/README.md +++ b/README.md @@ -3,70 +3,64 @@ Flutter SDK 仓库 原始仓来源：https://github.com/flutter/flutter -## 仓库说明： -本仓库是基于flutter sdk对于OpenHarmony的兼容拓展，可支持使用flutter tools指令编译和构建OpenHarmony应用程序。 +## 仓库说明 +本仓库是基于Flutter SDK对于OpenHarmony平台的兼容拓展，可支持IDE或者终端使用Flutter Tools指令编译和构建OpenHarmony应用程序。 -## 构建说明： +## 环境依赖 -* 构建环境： - flutter tools指令支持Linux、Mac和Windows下使用。 +* 开发系统 -* 构建依赖： - 依赖[flutter engine](https://github.com/flutter/engine)构建产物：`ohos_debug_unopt_arm64` 与 `ohos_release_arm64`，请在flutter tools指令运行参数中添加：`--local-engine=<engine产物目录>` + Flutter Tools指令目前已支持在Linux、Mac和Windows下使用。 -* 构建步骤： +* 环境配置 - **Windows环境请通过编辑Windows下的“环境变量”页面设置环境变量** + **下列环境变量配置，类Unix系统（Linux、Mac）下可直接参照配置，Windows下环境变量配置请在‘编辑系统环境变量’中设置** - 1. 下载[命令行工具](https://developer.harmonyos.com/cn/develop/deveco-studio#download_cli)，并配置环境变量ohpm与sdkmanager，下载完成后执行`ohpm/bin/init`安装ohpm。参照指导文档：[ohpm使用指导](https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/ide-command-line-ohpm-0000001490235312-V3)。 + 1. 下载[ohpm命令行工具](https://developer.harmonyos.com/cn/develop/deveco-studio#download_cli)，并配置环境变量ohpm与sdkmanager，下载完成后执行ohpm目录下`bin/init`初始化ohpm。参照指导文档：[ohpm使用指导](https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/ide-command-line-ohpm-0000001490235312-V3)。 ``` export OHPM_HOME=/home//ohos/oh-command-line-tools/ohpm/ - export PATH=/home//ohos/oh-command-line-tools/sdkmanager/bin:$PATH - export PATH=$PATH:$OHPM_HOME/bin + export PATH=$PATH:$OHPM_HOME/bin:$OHPM_HOME/sdkmanager/bin ``` - 2. 下载sdk并配置环境变量，可参考[ohsdkmgr使用指导](https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/ide-command-line-ohsdkmgr-0000001545647965-V3) 使用命令下载OpenHarmony sdk（API9以下），AP10需要从[每日构建](http://ci.openharmony.cn/workbench/cicd/dailybuild/detail/component)下载ohos-full-sdk，请保持sdk目录结构如下。(mac环境编译，请下载mac-sdk-full或者mac-sdk-m1-full) + 2. 下载OpenHarmony SDK并配置环境变量 + * API9 SDK下载：可参考[ohsdkmgr使用指导](https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/ide-command-line-ohsdkmgr-0000001545647965-V3) 使用命令下载API9以下SDK； + * API10 SDK需要从[每日构建](http://ci.openharmony.cn/workbench/cicd/dailybuild/detail/component)下载（Linux和Windows下载`ohos-full-sdk`，Mac请下载`mac-sdk-full`或者`mac-sdk-m1-full`），解压后请保持SDK目录结构如下： + + ``` + /SDK + ├── 10 + │ └── ets + │ └── js + │ └── native + │ └── previewer + │ └── toolchains + ├── 9 + ... + ``` + + * 配置环境变量 + + ``` + export OHOS_SDK_HOME=/home//env/sdk + export HDC_HOME=/home//env/sdk/10/toolchains + export PATH=$PATH:$HDC_HOME + + # 配置HarmonyOS SDK + export HOS_SDK_HOME= + ``` + + 3. 通过代码工具下载当前仓库代码`git clone https://gitee.com/openharmony-sig/flutter_flutter.git`，并配置环境 ``` - export OHOS_SDK_HOME=/home//env/sdk - export HDC_HOME=/home//env/sdk/10/toolchains - export PATH=$PATH:$HDC_HOME + export PATH=/bin:$PATH - # 配置HarmonyOS sdk - export HOS_SDK_HOME=/home//env/{HarmonyOS sdk} - ``` - - ``` - /SDK - ├── 10 - │ └── ets - │ └── js - │ └── native - │ └── previewer - │ └── toolchains - ├── 9 - ... - ``` - - 3. 配置Gradle：下载 `gradle 7.3` 并解压，配置到环境变量中： - - ``` - # grade - export PATH=/home//env/gradle-7.3/bin:$PATH - ``` - - 4. 下载Flutter，下载完成后配置环境： - - ``` - git clone https://gitee.com/openharmony-sig/flutter_flutter.git - - export PATH=/home//ohos/flutter_flutter/bin:$PATH + # Flutter pub国内镜像 export PUB_HOSTED_URL=https://pub.flutter-io.cn export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn ``` - 5. 签名工具需进行下列配置： + 4. 配置签名工具 - 下载[签名工具](https://gitee.com/openharmony/developtools_hapsigner)，并配置环境变量SIGN_TOOL_HOME。 @@ -74,7 +68,7 @@ Flutter SDK 仓库 export SIGN_TOOL_HOME=/home//ohos/developtools_hapsigner/autosign ``` - - 执行以下命令编译得到hap-sign-tool.jar，确保其在目录：./hapsigntool/hap_sign_tool/build/libs/hap-sign-tool.jar。 + - 执行gradle命令编译得到hap-sign-tool.jar，确保其在目录：./hapsigntool/hap_sign_tool/build/libs/hap-sign-tool.jar。(gradle版本推荐7.x) ``` gradle build @@ -86,7 +80,7 @@ Flutter SDK 仓库 sign.profile.inFile=profile_tmp.json ``` - - 在autosign目录下，执行命令`chmod 777 *.sh` (Windows环境下无需执行此命令)，新增`profile_tmp_template.json`文件，编辑如下： + - 在autosign目录下（ linux和mac环境下须先执行命令 `chmod 777 *.sh` ，Windows环境下无需执行此命令 ），新增`profile_tmp_template.json`文件，编辑如下： ``` { @@ -118,110 +112,100 @@ Flutter SDK 仓库 } ``` - 6. 若`~/`目录下未创建`.npmrc`配置，构建hap时可能报错：Error: The hvigor depends on the npmrc file. Configure the npmrc file first，届时请在用户目录`~`下创建文件`.npmrc`，该配置也可参考[官方文档](https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/environment_config-0000001052902427-V3)，编辑内容如下： + 5. 应用构建依赖[Flutter Engine](https://github.com/flutter/engine)构建产物：`ohos_debug_unopt_arm64` 与 `ohos_release_arm64`，请在Flutter Tools指令运行参数中添加：`--local-engine=\` - ``` - registry=https://repo.huaweicloud.com/repository/npm/ - @ohos:registry=https://repo.harmonyos.com/npm/ - ``` + 上述所有环境变量的配置（Windows下环境变量配置请在‘编辑系统环境变量’中设置），可参考下面的示例（其中user和具体代码路径请替换成实际路径）： + ``` + #flutter env start ===> -上述所有环境变量的配置，可参考下面的示例（其中user和具体代码路径请替换成实际路径，Windows环境请通过编辑Windows下的“环境变量”页面配置环境变量）： + # 国内镜像 + export PUB_HOSTED_URL=https://pub.flutter-io.cn + export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn -``` -#flutter env start ===> + # 从Gitee拉取下来的flutter_flutter目录 + export FLUTTER_HOME=/home//ohos/flutter_flutter + export PATH=$PATH:$FLUTTER_HOME/bin -# 国内镜像 -export PUB_HOSTED_URL=https://pub.flutter-io.cn -export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn + # 解压DevEco Studio安装包中 commandline/ohcommandline-tools-mac-2.1.3.6.zip 之后 ohpm 子目录 + export OHPM_HOME=/home//ohos/oh-command-line-tools/ohpm + export PATH=$PATH:$OHPM_HOME/bin -# 从Gitee拉取下来的flutter_flutter目录 -export FLUTTER_HOME=/home//ohos/flutter_flutter -export PATH=$PATH:$FLUTTER_HOME/bin + # 解压DevEco Studio安装包中 commandline/ohcommandline-tools-xxx.zip 之后的 sdkmanager 子目录 + export PATH=/home//ohos/oh-command-line-tools/sdkmanager/bin:$PATH -# 解压DevEco Studio安装包中 commandline/ohcommandline-tools-mac-2.1.3.6.zip 之后 ohpm 子目录 -export OHPM_HOME=/home//ohos/oh-command-line-tools/ohpm -export PATH=$PATH:$OHPM_HOME/bin + # HarmonyOS SDK，解压DevEco Studio安装包中 sdk/X86SDK.zip 或 M1SDK.zip 之后的目录，HOS_SDK_HOME下有 openharmony、hmscore、licenses 三个直接子目录 + export HOS_SDK_HOME=/home//ohos/sdk -# 解压DevEco Studio安装包中 commandline/ohcommandline-tools-xxx.zip 之后的 sdkmanager 子目录 -export PATH=/home//ohos/oh-command-line-tools/sdkmanager/bin:$PATH + # OpenHarmony SDK，解压DevEco Studio安装包中 sdk/X86SDK.zip 或 M1SDK.zip 之后的 openharmony 子目录 + export OHOS_SDK_HOME=/home//ohos/sdk/openharmony -# HarmonyOS SDK，解压DevEco Studio安装包中 sdk/X86SDK.zip 或 M1SDK.zip 之后的目录，HOS_SDK_HOME下有 openharmony、hmscore、licenses 三个直接子目录 -export HOS_SDK_HOME=/home//ohos/sdk + # HDC Home，OHOS_SDK_HOME目录下的 10/toolchains 子目录 + export HDC_HOME=/home//ohos/sdk/openharmony/10/toolchains + export PATH=$PATH:$HDC_HOME -# OpenHarmony SDK，解压DevEco Studio安装包中 sdk/X86SDK.zip 或 M1SDK.zip 之后的 openharmony 子目录 -export OHOS_SDK_HOME=/home//ohos/sdk/openharmony + # 签名工具 + export SIGN_TOOL_HOME=/home//ohos/developtools_hapsigner/autosign -# HDC Home，OHOS_SDK_HOME目录下的 10/toolchains 子目录 -export HDC_HOME=/home//ohos/sdk/openharmony/10/toolchains -export PATH=$PATH:$HDC_HOME + # grade + export PATH=/home//env/gradle-7.3/bin:$PATH -# 签名工具 -export SIGN_TOOL_HOME=/home//ohos/developtools_hapsigner/autosign + # nodejs + export NODE_HOME=/home//env/node-v14.19.1-linux-x64 + export PATH=$NODE_HOME/bin:$PATH -# grade -export PATH=/home//env/gradle-7.3/bin:$PATH + #flutter env end <=== + ``` -# nodejs -export NODE_HOME=/home//env/node-v14.19.1-linux-x64 -export PATH=$NODE_HOME/bin:$PATH -#flutter env end <=== -``` - -- 构建 +## 构建步骤 -1. 运行 `flutter doctor -v` 检查环境变量配置是否正确，**Futter**与**Openharmony**应都为ok标识，若两处提示缺少环境，按提示补上相应环境即可。 +1. 运行 `flutter doctor -v` 检查环境变量配置是否正确，**Futter**与**OpenHarmony**应都为ok标识，若两处提示缺少环境，按提示补上相应环境即可。 -2. 创建工程与编译命令，编译产物在flutter_demo/ohos/entry/build/default/outputs/default/entry-default-signed.hap下。 +2. 创建工程与编译命令，编译产物在\/ohos/entry/build/default/outputs/default/entry-default-signed.hap下。 ``` # 创建工程 - flutter create --platforms ohos flutter_demo - # 进入工程根目录编译，`--local-engine` 中的 `src/out` 需要保留 - flutter build hap --local-engine=/home//ohos/engine/src/out/ohos_release_arm64 --release - flutter build hap --local-engine=/home//ohos/engine/src/out/ohos_debug_unopt_arm64 --debug - ``` + flutter create --platforms ohos -3. flutter devices发现ohos设备之后，使用 `hdc -t install `进行安装。 + # 进入工程根目录编译 + # 示例：flutter build hap --target-platform ohos-arm64 --local-engine-src-path=/home/user/code/flutter/engine_make/src --local-engine=ohos_release_arm64 + flutter build hap --target-platform ohos-arm64 --local-engine-src-path= --local-engine=ohos_release_arm64 + ``` -## 关于windows下linux虚拟机如何连接和调试OpenHarmony设备 +3. 通过`flutter devices`指令发现ohos设备之后，使用 `hdc -t install `进行安装。 -* 问题：linux虚拟机通过hdc无法直接发现OpenHarmony设备 -* 解决方案：在windows宿主机中，开启hdc server，具体指令如下： +4. 也可直接使用下列指令运行： ``` -hdc kill -hdc -s serverIP:8710 -m -``` -在linux中配置环境变量： -``` -HDC_SERVER= -HDC_SERVER_PORT=8710 + # 示例：flutter run --local-engine=/home/user/code/flutter/engine_make/src/out/ohos_debug_unopt_arm64 + flutter run --local-engine= ``` -配置完成后flutter sdk可以通过hdc server完成设备连接，也可参考[官方指导](https://docs.openharmony.cn/pages/v4.0/zh-cn/device-dev/subsystems/subsys-toolchain-hdc-guide.md/#hdc-client%E5%A6%82%E4%BD%95%E8%BF%9C%E7%A8%8B%E8%AE%BF%E9%97%AEhdc-server) - -## 已兼容OpenHarmony开发的指令列表： -| 指令名称 | 指令描述 | 使用说明 | -| ---------- | -------------- | -------------------------------------------------------------------------------------------------------------------- | -| doctor | 环境检测 | flutter doctor | -| config | 环境配置 | flutter config --<key> <value> | -| create | 创建新项目 | flutter create --platforms ohos,android --org <org> <appName> | -| devices | 已连接设备查找 | flutter devices | -| install | 应用安装 | flutter install -t <deviceId> <hap文件路径> | -| assemble | 资源打包 | flutter assemble | -| build | 测试应用构建 | flutter build hap --debug --local-engine=<兼容ohos的debug engine产物路径> \[--target-platform ohos-arm64\] | -| build | 正式应用构建 | flutter build hap --release --local-engine=<兼容ohos的release engine产物路径> \[--target-platform ohos-arm64\] | -| run | 应用运行 | flutter run --local-engine=<兼容ohos的engine产物路径> | -| attach | 调试模式 | flutter attach | -| screenshot | 截屏 | flutter screenshot | + +## 已兼容OpenHarmony开发的指令列表 +| 指令名称 | 指令描述 | 使用说明 | +| ------- | ------- |-------------------------------------------------------------------| +| doctor | 环境检测 | flutter doctor | +| config | 环境配置 | flutter config --\ \ | +| create | 创建新项目 | flutter create --platforms ohos,android,ios --org \ \ | +| create | 创建module模板 | flutter create -t module \ | +| create | 创建plugin模板 | flutter create -t plugin --platforms ohos,android,ios \ | +| create | 创建plugin_ffi模板 | flutter create -t plugin_ffi --platforms ohos,android,ios \ | +| devices | 已连接设备查找 | flutter devices | +| install | 应用安装 | flutter install -t \ \ | +| assemble | 资源打包 | flutter assemble | +| build | 测试应用构建 | flutter build hap --target-platform ohos-arm64 --debug --local-engine=\<兼容ohos的debug engine产物路径\> | +| build | 正式应用构建 | flutter build hap --target-platform ohos-arm64 --release --local-engine=\<兼容ohos的release engine产物路径\> | +| run | 应用运行 | flutter run --local-engine=\<兼容ohos的engine产物路径\> | +| attach | 调试模式 | flutter attach | +| screenshot | 截屏 | flutter screenshot | 附：[Flutter三方库适配计划](https://docs.qq.com/sheet/DVVJDWWt1V09zUFN2) -## 常见问题： +## 常见问题 -1. ohos sdk版本推荐: `4.0.10.3`，可在每日构建的8月20号左右下载，若在编译过程中存在SDK版本相关问题，可尝试更换该版本SDK。 +1. OpenHarmony SDK版本推荐: `4.0.10.3`，可在每日构建的8月20号左右下载，若在编译过程中存在SDK版本相关问题，可尝试更换该版本SDK。 2. 若出现报错：`The SDK license agreement is not accepted`，参考执行以下命令后再次编译： @@ -233,11 +217,7 @@ HDC_SERVER_PORT=8710 4. 如果`flutter docker -v`提示ohpm无法找到，但是检测环境变量无误，请确保已执行`ohpm/bin/init`命令安装ohpm后再次检查。 -5. 若在编译签名工具时遇到错误Unsupported class file major version 61，说明当前JDK版本不支持，可以命令展示当前系统中所有JDK版本并选择所需版本，输入编号后确认选择再次编译。 - - ``` - sudo update-alternatives --config java - ``` +5. 若在编译签名工具时遇到错误Unsupported class file major version 61，说明当前JDK版本不支持，请降低Java SDK版本重试。 6. 如果你使用的是DevEco Studio的Beta版本，编译工程时遇到“must have required property 'compatibleSdkVersion', location: demo/ohos/build-profile.json5:17:11"错误，请参考《DevEco Studio环境配置指导.docx》中的‘6 创建工程和运行Hello World’【配置插件】章节修改 hvigor/hvigor-config.json5文件。 @@ -245,4 +225,28 @@ HDC_SERVER_PORT=8710 ``` hdc shell param set persist.bms.ohCert.verify true + ``` +8. linux虚拟机通过hdc无法直接发现OpenHarmony设备 + + 解决方案：在windows宿主机中，开启hdc server，具体指令如下： + ``` + hdc kill + hdc -s serverIP:8710 -m + ``` + 在linux中配置环境变量： + ``` + HDC_SERVER= + HDC_SERVER_PORT=8710 + ``` + + 配置完成后flutter sdk可以通过hdc server完成设备连接，也可参考[官方指导](https://docs.openharmony.cn/pages/v4.0/zh-cn/device-dev/subsystems/subsys-toolchain-hdc-guide.md/#hdc-client%E5%A6%82%E4%BD%95%E8%BF%9C%E7%A8%8B%E8%AE%BF%E9%97%AEhdc-server)。 + +9. 构建Hap任务时报错：Error: The hvigor depends on the npmrc file. Configure the npmrc file first. + + + 请在用户目录`~`下创建文件`.npmrc`，该配置也可参考[DevEco Studio官方文档](https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/environment_config-0000001052902427-V3)，编辑内容如下： + + ``` + registry=https://repo.huaweicloud.com/repository/npm/ + @ohos:registry=https://repo.harmonyos.com/npm/ ``` \ No newline at end of file -- Gitee