模塊

模塊配置規則

編譯子系統通過模塊、部件和產品三層配置來實現編譯和打包。模塊就是編譯子系統的一個目標，包括（動態庫、靜態庫、配置文件、預編譯模塊等）。模塊要定義屬于哪個部件，一個模塊只能歸屬于一個部件。OpenHarmony使用定制化的Gn模板來配置模塊規則，Gn語法相關的基礎知識請參考

以下是常用的模塊配置規則：

# C/C++模板
ohos_shared_library
ohos_static_library
ohos_executable
ohos_source_set

# 預編譯模板：
ohos_prebuilt_executable
ohos_prebuilt_shared_library
ohos_prebuilt_static_library

#hap模板
ohos_hap
ohos_app_scope
ohos_js_assets
ohos_resources

#rust模板
ohos_rust_executable
ohos_rust_shared_library
ohos_rust_static_library
ohos_rust_proc_macro
ohos_rust_shared_ffi
ohos_rust_static_ffi
ohos_rust_cargo_crate
ohos_rust_systemtest
ohos_rust_unittest
ohos_rust_fuzztest

#其他常用模板
#配置文件
ohos_prebuilt_etc

#sa配置
ohos_sa_profile

ohos開頭的模板與內建模板的差異主要在于：推薦使用ohos定制模板。

C/C++模板示例

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

ohos開頭的模板對應的.gni文件路徑在：openharmony/build/templates/cxx/cxx.gni。

ohos_shared_library示例

import("http://build/ohos.gni")
ohos_shared_library("helloworld") {
  sources = ["file"]
  include_dirs = []             # 如有重復頭文件定義，優先使用前面路徑頭文件。
  cflags = []                   # 如重復沖突定義，后面的參數優先生效，也就是該配置項中優先生效。
  cflags_c = []
  cflags_cc = []
  ldflags = []                  # 如重復沖突定義，前面參數優先生效，也就是ohos_template中預制參數優先生效。
  configs = []
  deps = []                     # 部件內模塊依賴

  external_deps = [             # 跨部件模塊依賴定義
  "part_name:module_name",      # 定義格式為 "部件名:模塊名稱"。
  ]                             # 這里依賴的模塊必須是依賴的部件聲明在inner_kits中的模塊。

  output_name = [string]        # 模塊輸出名
  output_extension = []         # 模塊名后綴
  module_install_dir = ""       # 模塊安裝路徑，缺省在/system/lib64或/system/lib下; 模塊安裝路徑從system/，vendor/后開始指定。
  relative_install_dir = ""     # 模塊安裝相對路徑，相對于/system/lib64或/system/lib；如果有module_install_dir配置時，該配置不生效。

  part_name = ""                # 必選，所屬部件名稱
  output_dir

  # Sanitizer配置，每項都是可選的，默認為false/空。
  sanitize = {
    # 各個Sanitizer開關
    cfi = [boolean]               # 控制流完整性檢測
    cfi_cross_dso = [boolean]     # 開啟跨so調用的控制流完整性檢測
    integer_overflow = [boolean]  # 整數溢出檢測
    boundary_sanitize = [boolean] # 邊界檢測
    ubsan = [boolean]             # 部分ubsan選項
    all_ubsan = [boolean]         # 全量ubsan選項
    ...

    debug = [boolean]             # 調測模式
    blocklist = [string]          # 屏蔽名單路徑
  }

  testonly = [boolean]
  license_as_sources = []
  license_file = []               # 后綴名是.txt的文件
  remove_configs = []
  no_default_deps = []
  install_images = []
  install_enable = [boolean]
  symlink_target_name = []
  version_script = []
  use_exceptions = []
}

ohos_static_library示例

import("http://build/ohos.gni")
ohos_static_library("helloworld") {
  sources = ["file"]            # 后綴名是.c的相關文件
  include_dirs = ["dir"]        # 包含目錄
  configs = []                  # 配置
  deps = []                     # 部件內模塊依賴
  part_name = ""                # 部件名稱
  subsystem_name = ""           # 子系統名稱
  cflags = []

  external_deps = [             # 跨部件模塊依賴定義，
  "part_name:module_name",      # 定義格式為 "部件名:模塊名稱"
  ]                             # 這里依賴的模塊必須是依賴的部件聲明在inner_kits中的模塊。

  lib_dirs = []
  public_configs = []

  # Sanitizer配置，每項都是可選的，默認為false/空
  sanitize = {
    # 各個Sanitizer開關
    cfi = [boolean]               # 控制流完整性檢測
    cfi_cross_dso = [boolean]     # 開啟跨so調用的控制流完整性檢測
    integer_overflow = [boolean]  # 整數溢出檢測
    boundary_sanitize = [boolean] # 邊界檢測
    ubsan = [boolean]             # 部分ubsan選項
    all_ubsan = [boolean]         # 全量ubsan選項
    ...

    debug = [boolean]             # 調測模式
    blocklist = [string]          # 屏蔽名單路徑
  }

  remove_configs = []
  no_default_deps = []
  license_file = []               # 后綴名是.txt的文件
  license_as_sources = []
  use_exceptions = []
}

ohos_executable示例

import("http://build/ohos.gni")
ohos_executable("helloworld") {
  configs = []                       # 配置  
  part_name = ""                     # 部件名稱 
  subsystem_name = ""                # 子系統名稱
  deps = []                          # 部件內模塊依賴

  external_deps = [                  # 跨部件模塊依賴定義，
  "part_name:module_name",           # 定義格式為 "部件名:模塊名稱"
  ]                                  # 這里依賴的模塊必須是依賴的部件聲明在inner_kits中的模塊。
  ohos_test = []
  test_output_dir = []

  # Sanitizer配置，每項都是可選的，默認為false/空
  sanitize = {
    # 各個Sanitizer開關
    cfi = [boolean]               # 控制流完整性檢測
    cfi_cross_dso = [boolean]     # 開啟跨so調用的控制流完整性檢測
    integer_overflow = [boolean]  # 整數溢出檢測
    boundary_sanitize = [boolean] # 邊界檢測
    ubsan = [boolean]             # 部分ubsan選項
    all_ubsan = [boolean]         # 全量ubsan選項
    ...

    debug = [boolean]             # 調測模式
    blocklist = [string]          # 屏蔽名單路徑
  }

  testonly = [boolean]
  license_as_sources = []
  license_file = []                  # 后綴名是.txt的文件
  remove_configs = []
  static_link = []
  install_images = []
  module_install_dir = ""            # 模塊安裝路徑，從system/，vendor/后開始指定
  relative_install_dir = ""
  symlink_target_name = []
  output_dir = [directory]           # 存放輸出文件的目錄
  install_enable = [boolean]
  version_script = []
  use_exceptions = []
}

ohos_source_set示例

import("http://build/ohos.gni")
ohos_source_set("helloworld") {
  sources = ["file"]              # 后綴名是.c的相關文件
  include_dirs = []               # 包含目錄
  configs = []                    # 配置
  public = []                     # .h類型頭文件
  defines = []
  public_configs = []
  part_name = ""                  # 部件名稱
  subsystem_name = ""             # 子系統名稱
  deps = []  # 部件內模塊依賴

  external_deps = [               # 跨部件模塊依賴定義，
  "part_name:module_name",        # 定義格式為 "部件名:模塊名稱"
  ]                               # 這里依賴的模塊必須是依賴的部件聲明在inner_kits中的模塊

  # Sanitizer配置，每項都是可選的，默認為false/空
  sanitize = {
    # 各個Sanitizer開關
    cfi = [boolean]               # 控制流完整性檢測
    cfi_cross_dso = [boolean]     # 開啟跨so調用的控制流完整性檢測
    integer_overflow = [boolean]  # 整數溢出檢測
    boundary_sanitize = [boolean] # 邊界檢測
    ubsan = [boolean]             # 部分ubsan選項
    all_ubsan = [boolean]         # 全量ubsan選項
    ...

    debug = [boolean]             # 調測模式
    blocklist = [string]          # 屏蔽名單路徑
  }

  testonly = [boolean]
  license_as_sources = []
  license_file = []
  remove_configs = []
  no_default_deps = []
  license_file = []               # 后綴名是.txt的文件
  license_as_sources = []
  use_exceptions = []
}

注意 ：

• 只有sources和part_name是必選，其他都是可選的；
• Sanitizer配置詳見：[Sanitizer使用說明]

預編譯模板示例

預編譯模板的.gni相關文件路徑在：openharmony/build/templates/cxx/prebuilt.gni。

ohos_prebuilt_executable示例

import("http://build/ohos.gni")
ohos_prebuilt_executable("helloworld") {
  source = "file"                         # 源
  output = []
  install_enable = [boolean]         

  deps = []                               # 部件內模塊依賴
  public_configs = []
  subsystem_name = ""                     # 子系統名
  part_name = ""                          # 部件名

  testonly = [boolean]
  visibility = []

  install_images = []
  module_install_dir = ""                 # 模塊安裝路徑，從system/，vendor/后開始指定
  relative_install_dir = ""               # 模塊安裝相對路徑，相對于system/etc；如果有module_install_dir配置時，該配置不生效。
  symlink_target_name = []


  license_file = []                       # 后綴名是.txt的文件
  license_as_sources = []
}

ohos_prebuilt_shared_library示例

import("http://build/ohos.gni")
ohos_prebuilt_shared_library("helloworld") {
  source = "file"                      # 一般是后綴為.so的文件
  output = []
  install_enable = [boolean]

  deps = []                            # 部件內模塊依賴
  public_configs = []
  subsystem_name = ""                  # 子系統名
  part_name = ""                       # 部件名

  testonly = [boolean]
  visibility = []

  install_images = []
  module_install_dir = ""              # 模塊安裝路徑，從system/，vendor/后開始指定
  relative_install_dir = ""            # 模塊安裝相對路徑，相對于system/etc；如果有module_install_dir配置時，該配置不生效。
  symlink_target_name = [string]


  license_file = [string]              # 后綴名是.txt的文件
  license_as_sources = []
}

ohos_prebuilt_static_library示例

import("http://build/ohos.gni")
ohos_prebuilt_static_library("helloworld") {
  source = "file"                  # 一般是后綴為.so的文件
  output = []

  deps = []                        # 部件內模塊依賴
  public_configs = []
  subsystem_name = ""              # 子系統名
  part_name = ""                   # 部件名

  testonly = [boolean]
  visibility = []

  license_file = [string]          # 后綴名是.txt的文件
  license_as_sources = []
}

注意 ：只有sources和part_name是必選，其他都是可選的。

Hap模板

hap模板詳見：[ HAP編譯構建指導]

Rust模板

rust模板詳見：[ Rust模塊配置規則和指導]

其他常用模板

ohos_prebuilt_etc示例：

import("http://build/ohos.gni")
ohos_prebuilt_etc("helloworld") {
  # ohos_prebuilt_etc模板最常用屬性:
  source = "file"                          # 指定單個原文件
  module_install_dir = ""                  # 模塊安裝路徑，從system/，vendor/后開始指定
  subsystem_name = ""                      # 子系統名
  part_name = ""                           # 必選，所屬部件名稱
  install_images = []
  relative_install_dir = ""                # 模塊安裝相對路徑，相對于system/etc；如果有module_install_dir配置時，該配置不生效。
  
  # ohos_prebuilt_etc模板不常用屬性:
  deps = []                                # 部件內模塊依賴
  testonly = [boolean]
  visibility = []
  public_configs = []
  symlink_target_name = [string]
  license_file = [string]
  license_as_sources = []
}

ohos_sa_profile示例：

import("http://build/ohos.gni")
ohos_sa_profile("helloworld") {
  sources = [".xml"]                   # xml文件
  part_name = ""                       # 部件名
  subsystem_name = ""                  # 子系統名
}

注意 ：只有sources和part_name是必選，其他都是可選的。

新增并編譯模塊

新建模塊可以分為以下三種情況。主要的添加邏輯如下面的流程圖所示，若沒有子系統則需新建子系統并在該子系統的部件下添加模塊，若沒有部件則需新建部件并在其中添加模塊，否則直接在原有部件中添加模塊即可，需要注意的是芯片解決方案作為特殊部件是沒有對應子系統的。

• 在原有部件中添加一個模塊
• 新建部件并在其中添加模塊
• 新建子系統并在該子系統的部件下添加模塊
  

在原有部件中添加一個模塊

1. 在模塊目錄下配置BUILD.gn，根據模板類型選擇對應的gn模板。

2. 修改bundle.json配置文件。

   {
      "name": "@ohos/< component_name >",                         # HPM部件英文名稱，格式"@組織/部件名稱"
      "description": "xxxxxxxxxxxxxxxxxxx",                     # 部件功能一句話描述
      "version": "3.1",                                         # 版本號，版本號與OpenHarmony版本號一致
      "license": "MIT",                                         # 部件License
      "publishAs": "code-segment",                              # HPM包的發布方式，當前默認都為code-segment
      "segment": {
          "destPath": "third_party/nghttp2"
      },                                                        # 發布類型為code-segment時為必填項，定義發布類型code-segment的代碼還原路徑（源碼路徑）。
      "dirs": {},                                               # HPM包的目錄結構，字段必填內容可以留空
      "scripts": {},                                            # HPM包定義需要執行的腳本，字段必填，值非必填
      "licensePath": "COPYING",
      "readmePath": {
          "en": "README.rst"
      },
      "component": {                                            # 部件屬性
          "name": "< component_name >",                           # 部件名稱
          "subsystem": ,                                        # 部件所屬子系統
          "syscap": [],                                         # 部件為應用提供的系統能力
          "features": [],                                       # 部件對外的可配置特性列表，一般與build中的sub_component對應，可供產品配置。
          "adapted_system_type": [],                            # 輕量(mini)小型(small)和標準(standard)，可以是多個
          "rom": "xxxKB"                                        # ROM基線，沒有基線寫當前值
          "ram": "xxxKB",                                       # RAM基線，沒有基線寫當前值
          "deps": {
              "components": [],                                 # 部件依賴的其他部件
              "third_party": []                                 # 部件依賴的三方開源軟件
          },
   
          "build": {                                            # 編譯相關配置
              "sub_component": [
                  "http://foundation/arkui/napi:napi_packages",      # 原有模塊1
                  "http://foundation/arkui/napi:napi_packages_ndk"   # 原有模塊2
                  "http://foundation/arkui/napi:new"                 # 新增模塊new
              ],                                                # 部件編譯入口，模塊在此處配置
              "inner_kits": [],                                 # 部件間接口
              "test": []                                        # 部件測試用例編譯入口
          }
      }
   }
   

   注意 ：無論哪種方式該bundle.json文件均在對應子系統所在文件夾下。

3. 成功添加驗證：編譯完成后打包到image中去，生成對應的so文件或者二進制文件。

新建部件并在其中添加一個模塊

1. 在模塊目錄下配置BUILD.gn，根據模板類型選擇對應的gn模板。這一步與在原有部件中添加一個模塊的方法基本一致，只需注意該模塊對應BUILD.gn文件中的part_name為新建部件的名稱即可。
2. 新建一個bundle.json文件，bundle.json文件均在對應子系統所在文件夾下。
3. 在vendor/{product_company}/{product-name}/config.json中添加對應的部件，直接添加到原有部件后即可。

   "subsystems": [
         {
           "subsystem": "部件所屬子系統名",
           "components": [
             { "component": "部件名1", "features":[] },         # 子系統下的原有部件1
             { "component": "部件名2", "features":[] },         # 子系統下的原有部件2
             { "component": "部件名new", "features":[] }        # 子系統下的新增部件new
           ]
         },
         .
    ]
   

4. 成功添加驗證：編譯完成后打包到image中去，生成對應的so文件或者二進制文件。

新建子系統并在該子系統的部件下添加模塊

1. 在模塊目錄下配置BUILD.gn，根據模板類型選擇對應的gn模板。這一步與新建部件并在其中添加模塊中對應的步驟并無區別。

2. 在新建的子系統目錄下每個部件對應的文件夾下創建bundle.json文件，定義部件信息。這一步與新建部件并在其中添加模塊中對應的步驟并無區別。

3. 修改build目錄下的subsystem_config.json文件。

   {
    "子系統名1": {                     # 原有子系統1
      "path": "子系統目錄1",
      "name": "子系統名1"
    },
     "子系統名2": {                    # 原有子系統2
      "path": "子系統目錄2",
      "name": "子系統名2"
    },
    "子系統名new": {                   # 新增子系統new
      "path": "子系統目錄new",
      "name": "子系統名new"
    },
   
   }
   

   該文件定義了有哪些子系統以及這些子系統所在文件夾路徑，添加子系統時需要說明子系統path與name，分別表示子系統路徑和子系統名。

4. 在vendor/{product_company}/{product-name}目錄下的產品配置如product-name是hispark_taurus_standard時，在config.json中添加對應的部件，直接添加到原有部件后即可。

"subsystems": [
      {
        "subsystem": "arkui",                      # 原有的子系統名
        "components": [                            # 單個子系統下的所有部件集合
          {
            "component": "ace_engine_standard",    # 原有的部件名
            "features": []
          },
          {
            "component": "napi",                   # 原有的部件名
            "features": []
          }
           {
            "component": "component_new1",         # 原有子系統新增的的部件名component_new1
            "features": []
          }
       ]
      },
      {
        "subsystem": "subsystem_new",              #  新增的子系統名
        "components": [
          {
            "component": "component_new2",         # 新增子系統新增的的部件名component_new2
            "features": []
          }
        ]
      },
     
     ]
     
`HarmonyOS與OpenHarmony鴻蒙文檔籽料：mau123789是v直接拿`

1. 成功添加驗證：編譯完成后打包到image中去，生成對應的so文件或者二進制文件。

編譯模塊

主要有兩種編譯方式，[命令行方式和hb方式]，這里以命令行方式為例。

模塊可以使用“--build-target 模塊名"單獨編譯，編譯命令如下：

./build.sh --build-target 模塊名

也可以編譯相應產品，以編譯hispark_taurus_standard為例，編譯命令如下：

./build.sh --product-name hispark_taurus_standard --build-target 模塊名 --ccache

還可以編譯模塊所在的部件：

./build.sh --product-name hispark_taurus_standard --build-target musl --build-target 模塊名 --ccache

審核編輯 黃宇