關(guān)于deps、external_deps的使用

在添加一個模塊的時候，需要在BUILD.gn中聲明它的依賴，為了便于后續(xù)處理部件間依賴關(guān)系，我們將依賴分為兩種——部件內(nèi)依賴deps和部件間依賴external_deps。

依賴分類

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

如上圖所示，主要分為部件內(nèi)依賴（圖左）和部件間依賴（圖右）。

• 部件內(nèi)依賴： 現(xiàn)有模塊module1屬于部件part1，要添加一個屬于部件part1的模塊module2，module2依賴于module1，這種情況就屬于部件內(nèi)依賴。

• 部件間依賴： 現(xiàn)有模塊module1屬于部件part1，要添加一個模塊module2，module2依賴于module1，module2屬于部件part2。模塊module2與模塊module1分屬于兩個不同的部件，這種情況就屬于部件間依賴。

• 部件內(nèi)依賴示例：

  import("http://build/ohos.gni")
  ohos_shared_library("module1") {
    ……
    part_name = "part1"   # 必選，所屬部件名稱
    ……
  }
  

  import("http://build/ohos.gni")
  ohos_shared_library("module2") {
    ……
    deps = [
      "module1的gn target",
    ……
   ]                        # 部件內(nèi)模塊依賴
  part_name = "part1"       # 必選，所屬部件名稱
  }
  

• 部件間依賴示例：

  import("http://build/ohos.gni")
  ohos_shared_library("module1") {
    ……
    part_name = "part1"   # 必選，所屬部件名稱
    ……
  }
  

  import("http://build/ohos.gni")
  ohos_shared_library("module2") {
    ……
    external_deps = [
      "part1:module1",
    ……
    ]                      # 部件間模塊依賴，這里依賴的模塊必須是依賴的部件聲明在inner_kits中的模塊
    part_name = "part2"    # 必選，所屬部件名稱
  }
  

  注意 ：部件間依賴要寫在external_deps里面，格式為”部件名:模塊名"的形式，并且依賴的模塊必須是依賴的部件聲明在inner_kits中的模塊。

Sanitizer使用說明

在添加模塊時，可選地對該模塊開啟編譯器提供的Sanitizer功能，包括整數(shù)溢出排錯、控制流完整性檢查等。配置的每一項都是可選的，如不指定默認(rèn)為false或者空。Sanitizer配置示例如下所示：

ohos_shared_library("example") {
    sanitize = {
      cfi = true                             # 開啟控制流完整性檢測
      cfi_cross_dso = true                   # 開啟跨so調(diào)用的控制流完整性檢測
      integer_overflow = true                # 開啟整數(shù)溢出檢測
      boundary_sanitize = true               # 開啟邊界檢測
      ubsan = true                           # 開啟部分ubsan選項
      all_ubsan = true                       # 開啟全量ubsan選項
      debug = true                           # 可選，調(diào)測模式，默認(rèn)是不開啟
      blocklist = "./blocklist.txt"          # 可選，屏蔽名單路徑
    }
    ...
  }

支持的Sanitizer類型

目前支持開啟的Sanitizer：

• 整數(shù)溢出排錯：unsigned_integer_overflow/signed_integer_overflow/integer_overflow(同時包括無符號和有符號整數(shù)溢出兩種檢查)
• 控制流完整性：cfi、cfi_cross_dso（跨so的cfi檢查）
• 邊界檢測：boundary_sanitize
• 部分未定義行為檢測：ubsan(bool,integer-divide-by-zero,return,returns-nonnull-attribute,shift-exponent,unreachable,vla-bound等編譯選項)
• 全量未定義行為檢測：all_ubsan(全量undefined behavior sanitizer編譯選項)

發(fā)布、調(diào)測模式

通過debug選項控制使用發(fā)布模式還是調(diào)測模式，默認(rèn)為發(fā)布模式，使用debug = true顯式聲明開啟調(diào)測模式。debug選項僅對Sanitizer生效，且與模塊是否編譯為調(diào)試版本無關(guān)，但在模塊發(fā)布版本的編譯配置中不應(yīng)帶此選項，或顯式地將debug設(shè)置為false，使得Sanitizer處于發(fā)布模式。

• 調(diào)測模式：用于開發(fā)時排查問題。該模式下會輸出產(chǎn)生錯誤相關(guān)的豐富信息來輔助定位錯誤，并且在發(fā)生錯誤后并不會直接中斷程序運(yùn)行，而是會恢復(fù)程序運(yùn)行進(jìn)一步識別后續(xù)的錯誤。
• 發(fā)布模式：保護(hù)程序不發(fā)生錯誤或被惡意攻擊，在產(chǎn)生錯誤后直接中斷程序不會繼續(xù)執(zhí)行。

屏蔽名單

指定該模塊中不受Sanitizer選項影響的函數(shù)或源程序文件名單，用于避免良性行為被識別為錯誤、熱點(diǎn)函數(shù)產(chǎn)生了不合理、不可接受的開銷；該名單需謹(jǐn)慎使用。名單示例如下所示：

[cfi]
fun:*([Tt]est|TEST)*
fun: main

[integer]
src:example/*.cpp

開源軟件Notice收集策略說明

開源軟件Notice是與項目開源相關(guān)的文件，收集這些文件的目的是為了符合開源的規(guī)范。

收集目標(biāo)

只收集打包到鏡像里面的模塊對應(yīng)的License；不打包的都不收集，比如構(gòu)建過程使用的工具（如clang、python、ninja等）都是不收集的。

靜態(tài)庫本身是不會被打包的，一般是作為動態(tài)庫或者可執(zhí)行程序的一部分被打包到系統(tǒng)中的，為了確保完備，靜態(tài)庫的都會收集。

最終合并的NOTICE.txt要體現(xiàn)出鏡像中每個文件都是用了哪些License，模塊和License要有對應(yīng)關(guān)系。

最終合并的NOTICE.txt文件在/system/etc/ 目錄下。

收集規(guī)則

按照優(yōu)先級收集License，以下由1到4，優(yōu)先級依次降低。

1. 模塊在BUILD.gn中直接聲明自己使用的License文件，優(yōu)先級最高。如下示例：

   ohos_shared_library("example") {
       ...
       license_file = "path-to-license-file"
       ...
   }
   

2. 如果模塊沒有顯式聲明，那么編譯腳本會在BUILD.gn所在的當(dāng)前目錄中查找Readme.OpenSource文件，解析該文件，找出該文件中聲明的license，將其作為模塊的License。 如果Readme.OpenSource文件中配置的license文件不存在，直接報錯。
3. 如果Readme.OpenSource文件不存在，編譯腳本會從當(dāng)前目錄開始，向上層目錄尋找（一直找到源碼的根目錄），默認(rèn)查找License、Copyright、Notice三個文件，如果找到，則將其作為模塊的License。
4. 如果上面三種方式都未找到license，則使用默認(rèn)的license作為該模塊的license；默認(rèn)license是Apache2.0 License。

需要注意及檢查的問題

• 三方的開源軟件，比如openssl，icu等，這部分軟件基本上在源碼目錄下都要求配置Readme.OpenSource，要檢查Readme.OpenSource文件是否和BUILD.gn文件在同一個目錄，以及Readme.OpenSource文件中配置的License文件是否存在以及真實(shí)有效。
• 代碼目錄下，如果代碼使用的不是Apache2.0 License，需要在目錄下提供對應(yīng)的License文件，或者直接在模塊中指定license_file。
• 如果BUILD.gn中添加的源碼文件不是當(dāng)前目錄的，需要檢查下源碼文件所在倉下的license是否和BUILD.gn文件所在倉的一致。

加快本地編譯的一些參數(shù)

編譯時，適當(dāng)選擇添加以下的編譯參數(shù)可以加快編譯的過程。

• 添加--ccache參數(shù) :
  • 原理：ccache會緩存c/c++編譯的編譯輸出，下一次在編譯輸入不變的情況下，直接復(fù)用緩存的產(chǎn)物。
  • 安裝：
    • 快速安裝：執(zhí)行sudo apt-get install ccache命令。
    • [官網(wǎng)下載]，下載二進(jìn)制文件，把ccache所在路徑配置到環(huán)境變量。
  • 使用：執(zhí)行./build.sh --product-name 產(chǎn)品名 --ccache命令。
• 添加--fast-rebuild參數(shù)
  • 原理：編譯流程主要分為：preloader->loader->gn->ninja這四個過程，在本地沒有修改gn和產(chǎn)品配置相關(guān)文件的前提下，添加--fast-rebuild會讓你直接從ninja編譯開始。
  • 使用：執(zhí)行./build.sh --product-name 產(chǎn)品名 --fast-rebuild命令。
• 添加enable_notice_collection=false參數(shù)
  • 原理：省略掉收集開源軟件模塊的license的過程。
  • 使用：執(zhí)行./build.sh --product-name 產(chǎn)品名 --gn-args --enable_notice_collection=false --ccache命令。
• 添加--build-target參數(shù)
  • 該參數(shù)用于指定編譯模塊，如何找模塊的名字：
    • 相關(guān)倉下BUILD.gn中關(guān)注group、ohos_shared_library、ohos_executable等關(guān)鍵字。
    • ./build.sh --product-name 產(chǎn)品名 --build-target 模塊名 --build-only-gn生成build.ninja，然后去該文件中查找相關(guān)模塊名。
  • 使用：執(zhí)行./build.sh --product-name 產(chǎn)品名 --build-target ark_js_host_linux_tools_packages命令。

查看NinjaTrace

out/rk3568/.ninja_log文件記錄了每個模塊編譯的開始和結(jié)束時間(ms)，結(jié)束時間和開始時間間隔越短表示模塊的編譯時間越短，編譯性能越高。

從左到右分別表示：start time|end time|mtime|command hash。

圖形化顯示編譯時間。

• 本地打開ninja trace： 解壓out/rk3568/build.trace.gz，將build.trace拖到chrome的trace鏈接chrome://tracing/打開即可。
• 在CI網(wǎng)站ci.openharmony.cn/events上打開ninja trace： CI上每個編譯的輸出里面有build.trace.html可直接打開，具體方法是：
  1. 點(diǎn)擊靜態(tài)檢查下的“成功”；
  2. 點(diǎn)擊輸出列的“輸出”即可在左側(cè)的build_trace列看到build.trace.html文件，單擊該文件即可打開。

定制打包c(diǎn)hip_prod鏡像使用說明

背景

針對同一個芯片解決方案下的子產(chǎn)品的定制能力，將差異能力放到 chip_prod 分區(qū)，因此需要支持對不同子產(chǎn)品生成對應(yīng)的 chip_prod.img。

使用步驟

1. 產(chǎn)品解決方案配置：
   產(chǎn)品解決方案配置文件config.json中添加"chipprod_config_path"配置選項，即"chipprod_config_path":"子產(chǎn)品定義文件所在的路徑"。 其中子產(chǎn)品定義文件的文件名為chip_product_list.gni，文件格式為：chip_product_list = ["productA", "productB", ...] 。
   示例：
   以MyProduct產(chǎn)品定制chipprod鏡像為例，//vendor/產(chǎn)品廠商/MyProduct/config.json配置如下：

   {
        "product_name": "MyProduct",                                 # 產(chǎn)品名稱
        "version": "3.0",                                            # config.json的版本號, 固定"3.0"
        "chipprod_config_path": "",                                  # 存放chipprod配置文件路徑，可選項
    "subsystems": [
          {
            "subsystem": "arkui",                                    # 選擇的子系統(tǒng)
            "components": [
              {
                  "component": "ace_engine",
                  "features":[ "ace_engine_feature_enable_web = true",
                    "ace_engine_feature_enable_accessibility = true" ] }   
            ]
          },
          {
           ......
          }
         ......
         更多子系統(tǒng)和部件
        }
   }
   

2. 模塊編譯配置：
   某個配置文件在不同的子產(chǎn)品中有差異，比如要打包到productA對應(yīng)的chip_prod.img中，則模塊編譯需要配置install_images和module_install_dir。
   以ohos_prebuilt_executable示例：

   ohos_prebuilt_executable("moduleXXX"){
    install_images = [ "chip_prod" ]
    module_install_dir = "productA/etc/***"     # module_install_dir指定的路徑需要以productA開始。
   }
   

3.編譯命令

./build.sh --product-name {product_name} --build-target chip_prod_image
`HarmonyOS與OpenHarmony鴻蒙文檔籽料：mau123789是v直接拿`

4. 打包結(jié)果:
如果定義了子產(chǎn)品productA和productB，即chip_product_list = ["productA", "productB"],并且有模塊安裝到了該產(chǎn)品下，則打包后鏡像輸出路徑如下：

images/productA/chip_prod.img
images/productB/chip_prod.img

審核編輯 黃宇