代碼工程及構(gòu)建介紹

背景

ArkUI作為OpenHarmony的默認(rèn)開發(fā)框架，在本項(xiàng)目（ArkUI-X）中需要做到一套代碼同時(shí)支持多平臺(tái)構(gòu)建，所以會(huì)采取共倉(cāng)開發(fā)的方式，部分倉(cāng)直接指向OpenHarmony相關(guān)開源倉(cāng)。

代碼結(jié)構(gòu)及倉(cāng)庫(kù)結(jié)構(gòu)

代碼工程的目錄結(jié)構(gòu)如下：

├── arkcompiler                 // 方舟編譯器
├── base                        // 基礎(chǔ)能力
├── build                       // 項(xiàng)目構(gòu)建和配置腳本
├── build_plugins               // 跨平臺(tái)構(gòu)建插件
├── commonlibrary               // 公共基礎(chǔ)庫(kù)
├── community                   // 社區(qū)相關(guān)
├── developtools                // 開發(fā)者工具
├── docs                        // 配套文檔
├── foundation
│   ├── appframework            // 應(yīng)用框架兼容適配層
│   ├── arkui                   // ArkUI引擎
│   ├── communication           // 通信能力
│   ├── distributeddatamgr      // 分布式數(shù)據(jù)管理
│   ├── filemanagement          // 文件管理
│   ├── graphic                 // 圖形引擎
│   └── multimedia              // 多媒體
├── interface                   // 接口聲明
├── plugins                     // 插件管理與實(shí)現(xiàn)
├── prebuilts                   // 預(yù)編譯目錄
├── productdefine               // 產(chǎn)品形態(tài)配置
├── samples                     // 示例代碼
├── test                        // 測(cè)試框架與用例
└── third_party                 // 三方庫(kù)

`HarmonyOS與OpenHarmony鴻蒙文檔籽料：mau123789是v直接拿`

具體的代碼結(jié)構(gòu)及指向，見(jiàn)下表：

分支同步策略

OpenHarmony相關(guān)代碼倉(cāng)，指向OpenHarmony master分支的固定tag點(diǎn)，定期同步，默認(rèn)按照OpenHarmony的Weekly分支頻率進(jìn)行同步。

ArkUI引擎核心代碼倉(cāng)目錄結(jié)構(gòu)

ArkUI引擎核心代碼倉(cāng) ace_engine 的目錄結(jié)構(gòu)以及每個(gè)目錄的內(nèi)容如下：

foundation/arkui/ace_engine
├── ace_config.gni      // 全局配置文件
├── adapter             // 平臺(tái)適配層
│   ├── android         // Android平臺(tái)適配，獨(dú)立倉(cāng)
│   │   ├── build
│   │   ├── capability
│   │   ├── entrance
│   │   ├── stage
│   │   └── osal
│   ├── ios             // iOS平臺(tái)適配，獨(dú)立倉(cāng)
│   │   ├── build
│   │   ├── capability
│   │   ├── entrance
│   │   ├── stage
│   │   └── osal
│   ├── ohos            // OpenHarmony平臺(tái)適配
│   └── preview         // 預(yù)覽器平臺(tái)適配
├── build               // 編譯配置
│   ├── ace_gen_obj.gni
│   ├── ace_lib.gni
│   ├── BUILD.gn
│   ├── search.py
│   └── tools
├── BUILD.gn            // 全局編譯配置
├── frameworks          // 引擎框架層
│   ├── base            // base庫(kù)
│   ├── bridge          // 前端橋接
│   └── core            // 引擎核心實(shí)現(xiàn)
├── interfaces          // 通用對(duì)外接口
│   └── napi
│       └── kits
├── LICENSE
├── OAT.xml
├── README.md
├── README_zh.md
└── test                // 測(cè)試相關(guān)

編譯構(gòu)建流程

為了支持一套代碼在OpenHarmony和其它平臺(tái)同時(shí)構(gòu)建，需要根據(jù)代碼結(jié)構(gòu)動(dòng)態(tài)對(duì)編譯配置進(jìn)行調(diào)整，因?yàn)閷?duì)外依賴可能不同，并且不同環(huán)境下可能依賴的外部源碼都有差異，所以必須對(duì)編譯目標(biāo)(targets)都進(jìn)行動(dòng)態(tài)的定義，否則無(wú)法保持一致。

• 編譯入口： OpenHarmony的編譯入口為bundle.json，這里定義了子系統(tǒng)的部件以及對(duì)外的接口，放在對(duì)應(yīng)子系統(tǒng)根目錄下，ArkUI的其它平臺(tái)構(gòu)建暫不需要，使用固定模塊名“ace_packages”作為入口。

• 全局配置： 根目錄下的BUILD.gn以及ace_config.gni為全局的配置，其中BUILD.gn下定義了全局使用的“ace_config”、“ace_test_config”，其中ace_config.gni分別定義了以下配置：

  • 全局的變量配置，如“enable_ace_debug”，通過(guò)開關(guān)進(jìn)行編譯控制。
  • 全局的路徑定義，如“ace_napi“，配置路徑的變量。
  • 工具鏈相關(guān)的配置，如“windows_buildtool”。
  • 在“ace_config”中使用的全局宏的定義，如“ace_common_defines”。
  • 生成平臺(tái)相關(guān)的配置項(xiàng)“ace_platforms”，這一步是動(dòng)態(tài)定義目標(biāo)的關(guān)鍵，見(jiàn)如下代碼：

  ace_platforms = []
  
  # 通過(guò)搜索adapter下的目錄，生成所有的adapter目錄名
  _ace_adapter_dir = rebase_path("$ace_root/adapter", root_build_dir)
  _adapters = exec_script("build/search.py", [ _ace_adapter_dir ], "list lines")
  
  # 導(dǎo)入每個(gè)adapter下的platform.gni，生成platform的定義配置，加入到ace_platforms中
  foreach(item, _adapters) {
  import_var = {}
  import_var = {
    import("$ace_root/adapter/$item/build/platform.gni")
  }
  
  if (defined(import_var.platforms)) {
    foreach(platform, import_var.platforms) {
    if (defined(platform.name)) {
      ace_platforms += [ platform ]
    }
    }
  }
  }
  

• 平臺(tái)配置： 每個(gè)adapter下的build目錄存放平臺(tái)相關(guān)的配置

  ├── BUILD.gn      // 入口目標(biāo)定義，如"ace_packages"
  ├── config.gni    // 平臺(tái)配置
  ├── bundle.json   // 部件配置，非OpenHarmony平臺(tái)暫不需要
  └── platform.gni  // 平臺(tái)定義
  

  其中，單個(gè)config.gni的配置類似如下：

  defines = [
  "OHOS_PLATFORM",
  "OHOS_STANDARD_SYSTEM",
  ]
  
  js_engines = []
  ark_engine = {
  engine_name = "ark"
  engine_path = "jsi"
  engine_defines = [ "USE_ARK_ENGINE" ]
  }
  js_engines += [ ark_engine ]
  
  disable_gpu = true
  use_external_icu = "shared"
  use_curl_download = true
  ohos_standard_fontmgr = true
  sk_use_hilog = true
  accessibility_support = false
  rich_components_support = true
  advance_components_support = false
  form_components_support = false
  
  if (disable_gpu) {
  defines += [ "GPU_DISABLED" ]
  }
  
  cflags_cc = [
  "-Wno-thread-safety-attributes",
  "-Wno-thread-safety-analysis",
  ]
  
  platform_deps = [
  "http://foundation/arkui/ace_engine/adapter/ohos/entrance:ace_ohos_standard_entrance",
  "http://foundation/arkui/ace_engine/adapter/ohos/osal:ace_osal_ohos",
  ]
  

  這個(gè)文件定義了該平臺(tái)的所有差異化配置，如宏、cflags、平臺(tái)特有的依賴，以及一些功能性的開關(guān)。在具體的模塊定義中，宏、cflags這一類編譯配置直接從config引入，其它差異需要定義為功能性的開關(guān)，如上述的“use_curl_download”，使模塊gn及特性的定義更清晰。

• 動(dòng)態(tài)目標(biāo)定義： 基于上述平臺(tái)的配置，就可以實(shí)現(xiàn)動(dòng)態(tài)的定義目標(biāo)，以base模塊為例：

  import("http://build/ohos.gni")
  import("http://foundation/arkui/ace_engine/ace_config.gni")
  
  template("ace_base_source_set") {
    forward_variables_from(invoker, "*")
  
    ohos_source_set(target_name) {
      # 引入平臺(tái)config中的define和cflags
      defines += invoker.defines
      cflags_cc = []
      cflags_cc += invoker.cflags_cc
  
      deps = [
        "$ace_root/build/third_party/cJSON:third_party_cjson",
        "i18n:ace_base_i18n_$platform",
        "resource:ace_resource",
      ]
  
      configs = [ "$ace_root:ace_config" ]
  
      # add base source file here
      sources = [
        "geometry/animatable_dimension.cpp",
        "geometry/animatable_matrix4.cpp",
        "geometry/matrix4.cpp",
        "geometry/quaternion.cpp",
        "geometry/transform_util.cpp",
        "json/json_util.cpp",
        "log/ace_trace.cpp",
        "log/dump_log.cpp",
        "memory/memory_monitor.cpp",
        "thread/background_task_executor.cpp",
        "utils/base_id.cpp",
        "utils/date_util.cpp",
        "utils/resource_configuration.cpp",
        "utils/string_utils.cpp",
        "utils/time_util.cpp",
      ]
  
    # 通過(guò)platform變量來(lái)進(jìn)行區(qū)別配置
      if (platform != "windows") {
        # add secure c API
        include_dirs = [ "http://utils/native/base/include" ]
  
        sources += [
          "http://utils/native/base/src/securec/memset_s.c",
          "http://utils/native/base/src/securec/securecutil.c",
          "http://utils/native/base/src/securec/secureprintoutput_a.c",
          "http://utils/native/base/src/securec/snprintf_s.c",
          "http://utils/native/base/src/securec/sprintf_s.c",
          "http://utils/native/base/src/securec/strcat_s.c",
          "http://utils/native/base/src/securec/strcpy_s.c",
          "http://utils/native/base/src/securec/vsnprintf_s.c",
          "http://utils/native/base/src/securec/vsprintf_s.c",
        ]
      }
  
      # 通過(guò)平臺(tái)的config決定是否依賴和編譯curl
      if (defined(config.use_curl_download) && config.use_curl_download) {
        configs += [ "http://third_party/curl:curl_config" ]
        sources += [ "$ace_root/frameworks/base/network/download_manager.cpp" ]
        deps += [ "http://third_party/curl:curl" ]
      }
    }
  }
  
  # 根據(jù)ace_platforms動(dòng)態(tài)定義目標(biāo)：假設(shè)里面包含三個(gè)平臺(tái)"ohos"、"windows"、"mac",則會(huì)定義三個(gè)target，
  # 分別為：ace_base_ohos,ace_base_windows,ace_base_mac
  foreach(item, ace_platforms) {
    ace_base_source_set("ace_base_" + item.name) {
      # 從platform中導(dǎo)入變量
      platform = item.name
      defines = []
      cflags_cc = []
      config = {
      }
  
      if (defined(item.config)) {
        config = item.config
      }
  
      if (defined(config.defines)) {
        defines = config.defines
      }
  
      if (defined(config.cflags_cc)) {
        cflags_cc = config.cflags_cc
      }
    }
  }
  

• 模塊定義： 根據(jù)目錄結(jié)構(gòu)，盡量分成一個(gè)個(gè)小模塊來(lái)定義，每個(gè)模塊定義明確，如果涉及平臺(tái)差異，使用上述方法定義，內(nèi)部配置差異盡量使用特性來(lái)區(qū)分

• 依賴關(guān)系： 依賴關(guān)系盡量清楚，按層次依賴，不可反向依賴

• 開發(fā)前請(qǐng)熟悉鴻蒙開發(fā)指導(dǎo)文檔 ：gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md點(diǎn)擊或者復(fù)制轉(zhuǎn)到。

開發(fā)原則

• 所有功能實(shí)現(xiàn)遵循分層設(shè)計(jì)
• frameworks目錄下的所有模塊都是平臺(tái)無(wú)關(guān)的，不能依賴adapter目錄下的模塊，不能依賴除JS引擎相關(guān)的其它子系統(tǒng)
• 平臺(tái)相關(guān)的代碼都必須放到adapter目錄對(duì)應(yīng)的平臺(tái)下，如果需要在frameworks中引用相關(guān)，需要進(jìn)行適當(dāng)?shù)慕涌诔橄?/li>
• 非OpenHarmony的adapter中不能依賴OpenHarmony其它子系統(tǒng)的模塊（例外：該子系統(tǒng)有跨平臺(tái)計(jì)劃并且通用）
• frameworks/core不允許依賴frameworks/bridge下的模塊
• 新增代碼不可直接依賴skia接口，使用graphic_2d提供的drawing接口
• 修改OpenHarmony倉(cāng)中的內(nèi)容要保證各平臺(tái)都能編譯通過(guò)，功能正常