ACE Tools

簡介

ACE Tools是一套為ArkUI-X項目跨平臺應(yīng)用開發(fā)者提供的命令行工具，支持在Windows/Ubuntu/macOS平臺運(yùn)行，用于構(gòu)建OpenHarmony/HarmonyOS、Android和iOS平臺的應(yīng)用程序，其功能包括開發(fā)環(huán)境檢查，新建項目，編譯打包，安裝調(diào)試等。

注釋： ACE - ArkUI跨平臺運(yùn)行環(huán)境 (ArkUI Cross-platform Environment)。

圖1 ACE Tools命令行工具模塊結(jié)構(gòu)

命令行各平臺使用不同腳本文件做為入口，再通過Node.js執(zhí)行到ace_tools.js文件，使用npm模塊commander解析命令行執(zhí)行各子模塊導(dǎo)出的方法。

目錄結(jié)構(gòu)

ACE Tools工具鏈的代碼在//developtools/ace_tools下，目錄結(jié)構(gòu)如下圖所示：

開發(fā)前請熟悉鴻蒙開發(fā)指導(dǎo)文檔 ：[gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md]

/developtools/ace_tools
├── lib/src/cli                 # 命令相關(guān)
│   ├── ace-build               # 構(gòu)建跨平臺應(yīng)用安裝包
│   ├── ace-check               # 查驗跨平臺應(yīng)用開發(fā)環(huán)境
│   ├── ace-clean               # 清理跨平臺應(yīng)用編譯結(jié)果
│   ├── ace-config              # 設(shè)置ACE工具鏈相關(guān)配置
│   ├── ace-create              # 創(chuàng)建跨平臺應(yīng)用工程及應(yīng)用模塊
│   ├── ace-devices             # 查詢當(dāng)前所有連接的設(shè)備
│   ├── ace-help                # 幫助命令
│   ├── ace-install             # 將跨平臺應(yīng)用安裝到連接的設(shè)備上
│   ├── ace-launch              # 在設(shè)備上運(yùn)行ArkUI跨平臺應(yīng)用
│   ├── ace-log                 # 展示正在運(yùn)行的跨平臺應(yīng)用的日志
│   ├── ace-run                 # 編譯并在設(shè)備上運(yùn)行ArkUI跨平臺應(yīng)用
|   ├── ace-test                # 執(zhí)行跨平臺應(yīng)用包單元測試
│   ├── ace-uninstall           # 將跨平臺應(yīng)用從連接的設(shè)備上卸載
│   └── util                    # 工具模塊
├── lib
│   └── ace_tools.js            # 入口腳本
└── templates                   # 模板相關(guān)
    ├── android                 # Android工程模板
    ├── cpp                     # Native C++配置模板
    ├── cpp_ets_stage           # Stage Native C++開發(fā)模板
    ├── ets_stage               # Stage開發(fā)模板
    ├── framework               # framework工程模板
    ├── ios                     # iOS工程模板
    └── ohos_stage              # ohos Stage工程模板

使用方法

ace config

設(shè)置ACE工具鏈相關(guān)配置，包括OpenHarmony SDK路徑，HarmonyOS SDK路徑、ArkUI-X SDK路徑、Android SDK路徑、Node.js路徑、編譯輸出路徑等。

語法：

ace config [arguments]

• arguments

ace check

查驗跨平臺應(yīng)用開發(fā)環(huán)境。

需要檢查的項：

語法：

ace check [arguments]

• arguments

執(zhí)行結(jié)果參考：

ohos@user ~ % ace check
Check summary (to see all details, run ace check -v)
[√] ArkUI-X (ArkUI-X SDK version 1.0.0.0)
[√] OpenHarmony toolchains - develop for OpenHarmony devices (OpenHarmony SDK version 4.0.10.13)
[√] HarmonyOS toolchains - develop for HarmonyOS devices (HarmonyOS SDK version 3.1.0)
[√] Android toolchains - develop for Android devices (Android SDK version 34.0.0)
[√] DevEco Studio (version 4.0.0.600)
[√] Android Studio (version 2022.3)
[√] Xcode - develop for iOS (Xcode 14.3.1)
Tools info :[√] OpenHarmony hdc installed
            [√] HarmonyOS hdc installed
            [√] adb installed
            [√] ios-deploy installed
[√] Connected device (1 available)
  ?  iPhone 14 Pro Max (1058643C-A725-4E19-AA62-781588C94A7F) [iOS Simulator]

  √ ACE Tools found no issues.

ohos@user ~ % ace check -v
[√] ArkUI-X (ArkUI-X SDK version 1.0.0.0)
  ? ArkUI-X SDK at /Users/ohos/Library/ArkUI-X/Sdk
  ? Node.js (v18.17.1) Runtime Environment at /usr/local/n/versions/node/18.17.1/
  ? libimobiledevice 1.3.0
  ? ios-deploy 1.12.2
[√] OpenHarmony toolchains - develop for OpenHarmony devices (OpenHarmony SDK version 4.0.10.13)
  ? OpenHarmony SDK at /Users/ohos/Library/OpenHarmony/Sdk
  ? Ohpm at /Users/ohos/Library/Huawei/ohpm
  ? Java SDK at /Applications/deveco-studio.app/Contents/jbr/Contents/Home
  ? OpenJDK Runtime Environment JBR-17.0.6+10-829.5-jcef (build 17.0.6+10-b829.5)
[√] HarmonyOS toolchains - develop for HarmonyOS devices (HarmonyOS SDK version 3.1.0)
  ? HarmonyOS SDK at /Users/ohos/Library/Huawei/Sdk
  ? Ohpm at /Users/ohos/Library/Huawei/ohpm
  ? Java SDK at /Applications/deveco-studio.app/Contents/jbr/Contents/Home
  ? OpenJDK Runtime Environment JBR-17.0.6+10-829.5-jcef (build 17.0.6+10-b829.5)
[√] Android toolchains - develop for Android devices (Android SDK version 34.0.0)
  ? Android SDK at /Users/ohos/Library/Android/sdk
  ? Java SDK at /Applications/Android Studio.app/Contents/jbr/Contents/Home
  ? OpenJDK Runtime Environment (build 17.0.6+0-17.0.6b829.9-10027231)
[√] DevEco Studio (version 4.0.3)
  ? DevEco Studio at /Applications/deveco-studio.app
  ? Java SDK at /Applications/deveco-studio.app/Contents/jbr/Contents/Home
  ? OpenJDK Runtime Environment JBR-17.0.6+10-829.5-jcef (build 17.0.6+10-b829.5)
[√] Android Studio (version 2022.3)
  ? Android Studio at /Applications/Android Studio.app
  ? Java SDK at /Applications/Android Studio.app/Contents/jbr/Contents/Home
  ? OpenJDK Runtime Environment (build 17.0.6+0-17.0.6b829.9-10027231)
[√] Xcode - develop for iOS (Xcode 14.3.1)
  ? Xcode at /Applications/Xcode.app
  ? Build version 14E300c
Tools info :[√] OpenHarmony hdc installed
            [√] HarmonyOS hdc installed
            [√] adb installed
            [√] ios-deploy installed
[√] Connected device (1 available)
  ?  iPhone 14 Pro Max (1058643C-A725-4E19-AA62-781588C94A7F) [iOS Simulator]

  √ ACE Tools found no issues.

ace devices

列出當(dāng)前所有連接的設(shè)備，Windows平臺上可以查詢到當(dāng)前連接的Android(包括Android Studio的模擬器)和OpenHarmony/HarmonyOS設(shè)備；Linux平臺上可以查詢到當(dāng)前連接的Android設(shè)備；

Mac平臺上可以查詢到當(dāng)前連接的Android(包括Android Studio的模擬器)，OpenHarmony/HarmonyOS，iOS設(shè)備和Mac自帶的iOS模擬器(可通過命令行open -a Simulator啟動，需要安裝Xcode)。

語法：

ace devices [arguments]

• arguments

執(zhí)行結(jié)果參考：

ohos@user ~ % ace devices
Tools info :[√] OpenHarmony hdc installed
            [√] HarmonyOS hdc installed
            [√] adb installed
            [√] ios-deploy installed
[√] Connected device (2 available)
  ?  sdk_gphone64_x86_64 (emulator-5554) [Android]
  ?  iPhone 14 Pro Max (1058643C-A725-4E19-AA62-781588C94A7F) [iOS Simulator]

ace create project

創(chuàng)建跨平臺應(yīng)用工程。

創(chuàng)建過程中，需要開發(fā)者依次填寫工程名稱和包名稱，如果開發(fā)者不輸入包名稱，默認(rèn)為com.example.工程名。

語法：

ace create < output directory >

• options

• type

在當(dāng)前目錄創(chuàng)建test工程：

ohos@user:~/cli-project$ ace create test
? Enter the project name(test):  # 輸入工程名稱，不輸入默認(rèn)為文件夾名稱
? Enter the bundleName (com.example.test):  # 輸入包名，不輸入默認(rèn)為com.example.工程名
? Enter the runtimeOS (1: OpenHarmony, 2: HarmonyOS): 1 # 輸入RuntimeOS系統(tǒng)

Project created. Target directory:  /home/ohos/cli-project/test.

In order to run your app, type:

    $ cd test
    $ ace run

Your app code is in test/entry.

ace new module

新建跨平臺應(yīng)用模塊(Module)

需要在新建的跨平臺應(yīng)用工程的根目錄下執(zhí)行，提示輸入module名稱：

Enter the module name:

如果此module name已存在，會提示開發(fā)者${module name} already exists.，開發(fā)者修改名稱后，回車確認(rèn)，可以成功新建出跨平臺應(yīng)用模塊(Module)。

ace new ability

新建跨平臺應(yīng)用Ability

需要在新建的跨平臺應(yīng)用工程的根目錄/具體module目錄下執(zhí)行，提示輸入Ability名稱：

Enter the ability name:

如果此ability name已存在，會提示開發(fā)者abilityName name already exists!.，開發(fā)者修改名稱后，回車確認(rèn)，可以成功新建出跨平臺應(yīng)用Ability。

ace build

構(gòu)建跨平臺應(yīng)用安裝包。

語法：

ace build < subCommand > [arguments]

在Windows和Linux平臺上可構(gòu)建Hap和Apk，在Mac平臺上可構(gòu)建Hap、Apk和App。

注：在DevEco Studio中打開要編譯的工程配置自動簽名，單擊File > Project Structure > Project > Signing Configs界面勾選“Automatically generate signature”，等待自動簽名完成即可，再執(zhí)行ace build即可構(gòu)建出簽名hap安裝包；在Mac上編譯App之前需要使用Xcode打開對應(yīng)ios工程，在Build settings的Singing進(jìn)行簽名配置，再執(zhí)行編譯命令；在Linux上無法簽名。

• subCommand

• arguments

構(gòu)建完成，提示包生成路徑:

HAP file built successfully..
File path: /Users/ohos/WorkSpace/demo/ohos/entry/build/default/outputs/default

ace install

將跨平臺應(yīng)用安裝到連接的設(shè)備上。

語法：

ace install [arguments]

在Windows和Linux平臺上可以安裝Hap和Apk應(yīng)用包，在Mac平臺上可以安裝Hap、Apk和App應(yīng)用包。 命令會根據(jù)options提示開發(fā)者選擇對應(yīng)平臺的設(shè)備，如果只有一個設(shè)備連接，會直接安裝到該設(shè)備上。 注：編譯Release版本的Apk需要簽名才能安裝，請通過Android Studio完成簽名或者編譯Debug版本Apk安裝。

• arguments

安裝完成：

ohos@user % ace install
[1]:  iPhone 14 Pro (67B40DC8-111C-4B30-9987-08E3BE30016A) [iOS Simulator]
[2]:  iPhone 14 Pro Max (1058643C-A725-4E19-AA62-781588C94A7F) [iOS Simulator]
? Please choose one (or "q" to quit): 2
iOS APP installed.

ace uninstall

將跨平臺應(yīng)用從連接的設(shè)備上卸載。命令會根據(jù)options提示開發(fā)者選擇對應(yīng)平臺的設(shè)備，如果只有一個設(shè)備連接，會直接卸載該設(shè)備上的應(yīng)用。

語法：

ace uninstall [arguments]

• arguments

卸載完成：

ohos@user % ace uninstall --bundle com.example.${projectName}
[1]:  iPhone 14 Pro (67B40DC8-111C-4B30-9987-08E3BE30016A) [iOS Simulator]
[2]:  iPhone 14 Pro Max (1058643C-A725-4E19-AA62-781588C94A7F) [iOS Simulator]
? Please choose one (or "q" to quit): 2
iOS APP uninstalled.

ace launch

在設(shè)備上運(yùn)行跨平臺應(yīng)用。命令會根據(jù)options提示開發(fā)者選擇對應(yīng)平臺的設(shè)備，如果只有一個設(shè)備連接，會直接運(yùn)行該設(shè)備上的應(yīng)用。需要在設(shè)備上安裝跨平臺應(yīng)用后才能運(yùn)行。

語法：

ace launch [arguments]

• arguments

運(yùn)行完成：

ohos@user % ace launch
[1]:  iPhone 14 Pro (67B40DC8-111C-4B30-9987-08E3BE30016A) [iOS Simulator]
[2]:  iPhone 14 Pro Max (1058643C-A725-4E19-AA62-781588C94A7F) [iOS Simulator]
? Please choose one (or "q" to quit): 2
iOS APP launched.

ace log

滾動展示正在運(yùn)行的跨平臺應(yīng)用的日志。命令會根據(jù)options提示開發(fā)者選擇對應(yīng)平臺的設(shè)備，如果只有一個設(shè)備連接，會直接展示該設(shè)備上的應(yīng)用日志。

默認(rèn)只輸出跨平臺應(yīng)用進(jìn)程相關(guān)日志。

語法：

ace log [arguments]

• arguments

ohos@user % ace log
[1]:  iPhone 14 Pro (67B40DC8-111C-4B30-9987-08E3BE30016A) [iOS Simulator]
[2]:  iPhone 14 Pro Max (1058643C-A725-4E19-AA62-781588C94A7F) [iOS Simulator]
? Please choose one (or "q" to quit): 2

ace run

運(yùn)行跨平臺應(yīng)用包。

ace run 先檢查設(shè)備是否連接，確定設(shè)備類型，然后執(zhí)行跨平臺應(yīng)用構(gòu)建、安裝、啟動、輸出應(yīng)用進(jìn)程log等操作。命令會根據(jù)options提示開發(fā)者選擇對應(yīng)平臺的設(shè)備，如果只有一個設(shè)備連接，應(yīng)用會安裝到該設(shè)備并運(yùn)行。

在Windows平臺上可以構(gòu)建安裝并運(yùn)行Hap和Apk，在Linux平臺上可以構(gòu)建安裝并運(yùn)行Apk，僅能構(gòu)建Hap，在Mac平臺上可以構(gòu)建安裝并運(yùn)行Hap、Apk和App。

語法：

ace run [arguments]

• arguments

ohos@user % ace run
[1]:  iPhone 14 Pro (67B40DC8-111C-4B30-9987-08E3BE30016A) [iOS Simulator]
[2]:  iPhone 14 Pro Max (1058643C-A725-4E19-AA62-781588C94A7F) [iOS Simulator]
? Please choose one (or "q" to quit): 2

ace test

執(zhí)行跨平臺應(yīng)用包單元測試。

ace test 先檢查設(shè)備是否連接，確定設(shè)備類型，然后執(zhí)行跨平臺應(yīng)用構(gòu)建、安裝、啟動、執(zhí)行單元測試、輸出單元測試結(jié)果等操作。

在Windows平臺上可以構(gòu)建安裝并測試Apk，在Linux平臺上可以構(gòu)建安裝并測試Apk，在Mac平臺上可以構(gòu)建安裝并測試Apk和App，暫時不支持iOS模擬器上的單元測試。

語法：

ace test [arguments]

• arguments

ace clean

清理跨平臺應(yīng)用編譯結(jié)果。

語法：

ace clean [arguments]

• arguments

清理完成：

Project cleaned up.

ace help

跨平臺應(yīng)用命令行工具幫助。

語法：

ace help < command >

• command

提示內(nèi)容：

ohos@user % ace help
Manage your ArkUI cross-platform app development.

Common commands:

  ace create
  Create a new ArkUI cross-platform project in the specified directory.

  ace run
  Run your ArkUI cross-platform application on an attached device or in an emulator.

Usage: ace < command > [options]

Options:
  -V, --version          output the version number
  -d, --device < device >  Input device id to specify the device to do something.
  -h, --help             display help for command

Available commands:

Application:
  install                Install an ArkUI cross-platform app on an attached device.
  launch                 Launch your ArkUI cross-platform app on an attached device.
  log                    Show log output for running ArkUI cross-platform apps.
  run                    Run your ArkUI cross-platform app on an attached device.
  test                   Run ArkUI cross-platform unit tests for the current project.
  uninstall              Uninstall an ArkUI cross-platform app on an attached device.

Device:
  devices                List the connected devices.

Environment:
  check                  Show information about the installed tools.
  config                 Configure ArkUI cross-platform settings.

Project:
  build                  Build an executable app or install a bundle.
  clean                  Delete the build/ directories.
  create                 Create a new ArkUI cross-platform project.
  new                    Create a new ability or module for your project.

Run "ace help < command >" for more information about a command.

審核編輯 黃宇