編譯構(gòu)建指導(dǎo)

概述

OpenHarmony編譯子系統(tǒng)是以GN和Ninja構(gòu)建為基座，對(duì)構(gòu)建和配置粒度進(jìn)行部件化抽象、對(duì)內(nèi)建模塊進(jìn)行功能增強(qiáng)、對(duì)業(yè)務(wù)模塊進(jìn)行功能擴(kuò)展的系統(tǒng)，該系統(tǒng)提供以下基本功能：

• 以部件為最小粒度拼裝產(chǎn)品和獨(dú)立編譯。
• 支持輕量、小型、標(biāo)準(zhǔn)三種系統(tǒng)的解決方案級(jí)版本構(gòu)建，以及用于支撐應(yīng)用開發(fā)者使用IDE開發(fā)的SDK開發(fā)套件的構(gòu)建。
• 支持芯片解決方案廠商的靈活定制和獨(dú)立編譯。

適用范圍

本指導(dǎo)適用于輕量、小型、標(biāo)準(zhǔn)三種系統(tǒng)。[芯片解決方案配置規(guī)則]與[新增并編譯芯片解決方案]主要和輕量系統(tǒng)、小型系統(tǒng)相關(guān)，其他內(nèi)容都是通用的。

基本概念及包含關(guān)系

在了解編譯構(gòu)建子系統(tǒng)的能力前，應(yīng)了解如下基本概念：

• 平臺(tái)：開發(fā)板和內(nèi)核的組合，不同平臺(tái)支持的子系統(tǒng)和部件不同。
• 產(chǎn)品：產(chǎn)品是包含一系列部件的集合，編譯后產(chǎn)品的鏡像包可以運(yùn)行在不同的開發(fā)板上。
• 子系統(tǒng)：OpenHarmony整體遵從分層設(shè)計(jì)，從下向上依次為：內(nèi)核層、系統(tǒng)服務(wù)層、框架層和應(yīng)用層。系統(tǒng)功能按照“系統(tǒng) > 子系統(tǒng) > 部件”逐級(jí)展開，在多設(shè)備部署場景下，支持根據(jù)實(shí)際需求裁剪某些非必要的子系統(tǒng)或部件。子系統(tǒng)是一個(gè)邏輯概念，它具體由對(duì)應(yīng)的部件構(gòu)成。
• 部件：對(duì)子系統(tǒng)的進(jìn)一步拆分，可復(fù)用的軟件單元，它包含源碼、配置文件、資源文件和編譯腳本；能獨(dú)立構(gòu)建，以二進(jìn)制方式集成，具備獨(dú)立驗(yàn)證能力的二進(jìn)制單元。需要注意的是下文中的芯片解決方案本質(zhì)是一種特殊的部件。
• 模塊：模塊就是編譯子系統(tǒng)的一個(gè)編譯目標(biāo)，部件也可以是編譯目標(biāo)。
• 特性：特性是部件用于體現(xiàn)不同產(chǎn)品之間的差異。
• GN：Generate Ninja的縮寫，用于產(chǎn)生Ninja文件。
• Ninja：Ninja是一個(gè)專注于速度的小型構(gòu)建系統(tǒng)。
• hb：OpenHarmony的命令行工具，用來執(zhí)行編譯命令。

基于以上概念，編譯子系統(tǒng)通過配置來實(shí)現(xiàn)編譯和打包，該子系統(tǒng)主要包括：模塊、部件、子系統(tǒng)、產(chǎn)品。

圖1 產(chǎn)品、子系統(tǒng)、部件和模塊間關(guān)系

圖1體現(xiàn)了編譯子系統(tǒng)的各部分關(guān)系，主要體現(xiàn)為：

• 子系統(tǒng)是某個(gè)路徑下所有部件的集合，一個(gè)部件只能屬于一個(gè)子系統(tǒng)。
• 部件是模塊的集合，一個(gè)模塊只能歸屬于一個(gè)部件。
• 通過產(chǎn)品配置文件配置一個(gè)產(chǎn)品包含的部件列表，部件不同的產(chǎn)品配置可以復(fù)用。
• 部件可以在不同的產(chǎn)品中實(shí)現(xiàn)有差異，通過變體或者特性feature實(shí)現(xiàn)。
• 模塊就是編譯子系統(tǒng)的一個(gè)編譯目標(biāo)，部件也可以是編譯目標(biāo)。

運(yùn)作機(jī)制

編譯構(gòu)建可以編譯產(chǎn)品、部件和模塊，但是不能編譯子系統(tǒng)。編譯構(gòu)建流程如下圖所示，主要分設(shè)置和編譯兩步：

圖2 編譯構(gòu)建流程

1. hb set: 設(shè)置要編譯的產(chǎn)品。
2. hb build: 編譯產(chǎn)品、開發(fā)板或者部件。編譯主要過程如下：
   1. 讀取編譯配置：根據(jù)產(chǎn)品選擇的開發(fā)板，讀取開發(fā)板config.gni文件內(nèi)容，主要包括編譯工具鏈、編譯鏈接命令和選項(xiàng)等。
   2. 調(diào)用GN：調(diào)用gn gen命令，讀取產(chǎn)品配置生成產(chǎn)品解決方案out目錄和Ninja文件。
   3. 調(diào)用Ninja：調(diào)用ninja -C out/board/product啟動(dòng)編譯。
   4. 系統(tǒng)鏡像打包：將部件編譯產(chǎn)物打包，設(shè)置文件屬性和權(quán)限，制作文件系統(tǒng)鏡像。

約束限制

編譯環(huán)境目前主要支持Ubuntu18.04和Ubuntu20.04（Ubuntu22.04暫不支持）。

環(huán)境配置

安裝編譯所需的程序包。 安裝命令：

• 安裝方式一：使用腳本，在當(dāng)前工程目錄執(zhí)行

  ./build/build_scripts/env_setup.sh
  

• 安裝方式二：apt-get和pip3 install命令安裝

  apt-get update -y 
  apt-get install -y  
  # 如果是ubuntu20.04系統(tǒng)請直接安裝python3.9，如果是ubuntu18.04請改為安裝python3.8
  apt-get install -y apt-utils binutils bison flex bc build-essential make mtd-utils gcc-arm-linux-gnueabi u-boot-tools python3.9 python3-pip git zip unzip curl wget gcc g++ ruby dosfstools mtools default-jre default-jdk scons python3-distutils perl openssl libssl-dev cpio git-lfs m4 ccache zlib1g-dev tar rsync liblz4-tool genext2fs binutils-dev device-tree-compiler e2fsprogs git-core gnupg gnutls-bin gperf lib32ncurses5-dev libffi-dev zlib* libelf-dev libx11-dev libgl1-mesa-dev lib32z1-dev xsltproc x11proto-core-dev libc6-dev-i386 libxml2-dev lib32z-dev libdwarf-dev 
  apt-get install -y grsync xxd libglib2.0-dev libpixman-1-dev kmod jfsutils reiserfsprogs xfsprogs squashfs-tools  pcmciautils quota ppp libtinfo-dev libtinfo5 libncurses5 libncurses5-dev libncursesw5 libstdc++6  gcc-arm-none-eabi vim ssh locales doxygen
  apt-get install -y libxinerama-dev libxcursor-dev libxrandr-dev libxi-dev
  # python需要安裝以下模塊，repo文件在上一章節(jié)約束與限制的源碼獲取中得到。
  chmod +x /usr/bin/repo 
  pip3 install --trusted-host https://repo.huaweicloud.com -i https://repo.huaweicloud.com/repository/pypi/simple requests setuptools pymongo kconfiglib pycryptodome ecdsa ohos-build pyyaml prompt_toolkit==1.0.14 redis json2html yagmail python-jenkins 
  pip3 install esdk-obs-python --trusted-host pypi.org 
  pip3 install six --upgrade --ignore-installed six
  #還需要安裝llvm，hc-gen，gcc_riscv32，Ninja，node-v14.15.4-linux-x64，GN，如果用戶使用的shell環(huán)境不是bash或者zsh的配置，則需要配置以下環(huán)境變量：
  # export PATH=/home/tools/llvm/bin:$PATH
  # export PATH=/home/tools/hc-gen:$PATH
  # export PATH=/home/tools/gcc_riscv32/bin:$PATH
  # export PATH=/home/tools/ninja:$PATH
  # export PATH=/home/tools/node-v12.20.0-linux-x64/bin:$PATH
  # export PATH=/home/tools/gn:$PATH
  # export PATH=~/.local/bin:$PATH
  

  注意 ：上述安裝ohos-build的過程中會(huì)安裝編譯工具h(yuǎn)b，但有時(shí)會(huì)出現(xiàn)hb安裝不成功的情況，若安裝不成功，則按照[hb安裝]重新安裝。

配置規(guī)則

為了實(shí)現(xiàn)芯片解決方案、產(chǎn)品解決方案與OpenHarmony是解耦的、可插拔的，子系統(tǒng)、產(chǎn)品、部件、芯片解決方案、模塊、特性和系統(tǒng)能力需遵循一定的規(guī)則，具體配置規(guī)則見如下鏈接：

• [產(chǎn)品配置規(guī)則]
• [子系統(tǒng)配置規(guī)則]
• [部件配置規(guī)則]
• [模塊配置規(guī)則])
• [Rust模塊配置規(guī)則]
• [芯片解決方案配置規(guī)則]
• [特性配置規(guī)則]
• [系統(tǒng)能力配置規(guī)則]

編譯構(gòu)建使用指導(dǎo)

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

/build                            # 編譯構(gòu)建主目錄

├── __pycache__                   
├── build_scripts/                # 編譯相關(guān)的python腳本
├── common/                       
├── config/                       # 編譯相關(guān)的配置項(xiàng)
├── core
│   ├── gn/                       # 編譯入口BUILD.gn配置
    └── build_scripts/            
├── docs                          
gn_helpers.py*                    
lite/                             # hb和preloader入口                      
misc/
├── ohos                          # OpenHarmony編譯打包流程配置
│   ├── kits                      # kits編譯打包模板和處理流程
│   ├── ndk                       # ndk模板和處理流程
│   ├── notice                    # notice模板和處理流程
│   ├── packages                  # 版本打包模板和處理流程
│   ├── sa_profile                # sa模板和處理流程
│   ├── sdk                       # sdk模板和處理流程，包括sdk中包含的模塊配置
│   └── testfwk                   # 測試相關(guān)的處理
├── ohos.gni*                     # 匯總了常用的gni文件，方便各個(gè)模塊一次性import
├── ohos_system.prop              
├── ohos_var.gni*                 
├── prebuilts_download.sh*        
├── print_python_deps.py*         
├── scripts/                      
├── subsystem_config.json         
├── subsystem_config_example.json 
├── templates/                    # c/c++編譯模板定義
├── test.gni*                     
├── toolchain                     # 編譯工具鏈配置
├── tools                         # 常用工具
├── version.gni                   
├── zip.py*

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

編譯命令

首先，在源碼根目錄下執(zhí)行prebuilts腳本進(jìn)行預(yù)編譯，安裝編譯器及二進(jìn)制工具。

bash build/prebuilts_download.sh

接著，使用命令行方式或hb方式執(zhí)行編譯命令。

1.命令行方式

• 代碼根目錄下執(zhí)行全量版本的編譯命令：
  Release版本 :

  ./build.sh --product-name {product_name}
  

  Debug版本 :

  ./build.sh --product-name {product_name} --gn-args is_debug=true
  

  注意： Debug全版本因鏡像大小限制，全量編譯可能無法燒錄，建議單模塊編譯Debug二進(jìn)制。使用如下命令單獨(dú)編譯模塊：

  ./build.sh --product-name {product_name} --gn-args is_debug=true --build-target {target_name}
  

  {product_name}為當(dāng)前版本支持的平臺(tái)。比如：hispark_taurus_standard等。
  編譯完成后，結(jié)果鏡像保存在 out/{device_name}/packages/phone/images/ 目錄下。

• 編譯命令支持選項(xiàng)：./build.sh

  -h, --help                                        # 顯示幫助信息并退出
  --source-root-dir=SOURCE_ROOT_DIR                 # 指定路徑
  --product-name=PRODUCT_NAME                       # 指定產(chǎn)品名
  --device-name=DEVICE_NAME                         # 指定裝置名稱
  --target-cpu=TARGET_CPU                           # 指定CPU
  --target-os=TARGET_OS                             # 指定操作系統(tǒng)
  -T BUILD_TARGET, --build-target=BUILD_TARGET      # 指定編譯目標(biāo)，可以指定多個(gè)
  --gn-args=GN_ARGS                                 # GN參數(shù)，支持指定多個(gè)
  --ninja-args=NINJA_ARGS                           # Ninja參數(shù)，支持指定多個(gè)
  -v, --verbose                                     # 生成時(shí)顯示所有命令行
  --keep-ninja-going                                # 讓Ninja持續(xù)到1000000個(gè)工作失敗
  --jobs=JOBS
  --export-para=EXPORT_PARA
  --build-only-gn                                   # 只做GN解析，不運(yùn)行Ninja
  --ccache                                          # 可選  如果使用ccache，需要本地安裝ccache
  --fast-rebuild                                    # 快速重建，默認(rèn)值為False
  --log-level=LOG_LEVEL                             # 指定編譯期間的日志級(jí)別'，'三個(gè)級(jí)別可選：debug, info and error，default='info'
  --device-type=DEVICE_TYPE                         # 指定設(shè)備類型，默認(rèn)值為'default'
  --build-variant=BUILD_VARIANT                     # 指定設(shè)備操作模式，默認(rèn)值為'user'
  

2.hb方式

hb是OpenHarmony的命令行工具，用來執(zhí)行編譯命令。以下對(duì)hb的常用命令進(jìn)行說明。

hb set

設(shè)置要編譯的產(chǎn)品

hb set -h
usage: hb set [-h] [-root [ROOT_PATH]] [-p]

optional arguments:
  -h, --help            show this help message and exit
  -root [ROOT_PATH], --root_path [ROOT_PATH]
                        Set OHOS root path
  -p, --product         Set OHOS board and kernel

• hb set 后無參數(shù)，進(jìn)入默認(rèn)設(shè)置流程
• hb set -root dir可直接設(shè)置代碼根目錄
• hb set -p設(shè)置要編譯的產(chǎn)品

hb env

查看當(dāng)前設(shè)置信息

hb env
[OHOS INFO] root path: xxx
[OHOS INFO] board: hispark_taurus
[OHOS INFO] kernel: liteos
[OHOS INFO] product: ipcamera
[OHOS INFO] product path: xxx/vendor/hisilicon/ipcamera
[OHOS INFO] device path: xxx/device/hisilicon/hispark_taurus/sdk_linux_4.19

hb build

編譯產(chǎn)品、部件、模塊或芯片解決方案。

hb build -h
usage: hb build [-h] [-b BUILD_TYPE] [-c COMPILER] [-t [TEST [TEST ...]]] [-cpu TARGET_CPU] [--dmverity] [--tee]
                [-p PRODUCT] [-f] [-n] [-T [TARGET [TARGET ...]]] [-v] [-shs] [--patch] [--compact-mode]
                [--gn-args GN_ARGS] [--keep-ninja-going] [--build-only-gn] [--log-level LOG_LEVEL] [--fast-rebuild]
                [--device-type DEVICE_TYPE] [--build-variant BUILD_VARIANT]
                [component [component ...]]

positional arguments:
  component             name of the component, mini/small only

optional arguments:
  -h, --help            show this help message and exit
  -b BUILD_TYPE, --build_type BUILD_TYPE
                        release or debug version, mini/small only
  -c COMPILER, --compiler COMPILER
                        specify compiler, mini/small only
  -t [TEST [TEST ...]], --test [TEST [TEST ...]]
                        compile test suit
  -cpu TARGET_CPU, --target-cpu TARGET_CPU
                        select cpu
  --dmverity            enable dmverity
  --tee                 Enable tee
  -p PRODUCT, --product PRODUCT
                        build a specified product with {product_name}@{company}
  -f, --full            full code compilation
  -n, --ndk             compile ndk
  -T [TARGET [TARGET ...]], --target [TARGET [TARGET ...]]
                        compile single target
  -v, --verbose         show all command lines while building
  -shs, --sign_haps_by_server
                        sign haps by server
  --patch               apply product patch before compiling
  --compact-mode        compatible with standard build system set to false if we use build.sh as build entrance
  --gn-args GN_ARGS     specifies gn build arguments, eg: --gn-args="foo="bar" enable=true blah=7"
  --keep-ninja-going    keeps ninja going until 1000000 jobs fail
  --build-only-gn       only do gn parse, do not run ninja
  --log-level LOG_LEVEL
                        specifies the log level during compilationyou can select three levels: debug, info and error
  --fast-rebuild        it will skip prepare, preloader, gn_gen steps so we can enable it only when there is no change
                        for gn related script
  --device-type DEVICE_TYPE
                        specifies device type
  --build-variant BUILD_VARIANT
                        specifies device operating mode

• hb build后無參數(shù)，會(huì)按照設(shè)置好的代碼路徑、產(chǎn)品進(jìn)行編譯，編譯選項(xiàng)使用與之前保持一致。-f 選項(xiàng)將刪除當(dāng)前產(chǎn)品所有編譯產(chǎn)品，等同于hb clean + hb build.
• hb build {component_name}：基于設(shè)置好的產(chǎn)品對(duì)應(yīng)的單板、內(nèi)核，單獨(dú)編譯部件（e.g.：hb build kv_store)。
• hb build -p ipcamera@hisilicon：免set編譯產(chǎn)品，該命令可以跳過set步驟，直接編譯產(chǎn)品。
• 在device/board/device_company下單獨(dú)執(zhí)行hb build會(huì)進(jìn)入內(nèi)核選擇界面，選擇完成后會(huì)根據(jù)當(dāng)前路徑的單板、選擇的內(nèi)核編譯出僅包含內(nèi)核、驅(qū)動(dòng)的鏡像。

hb clean

清除out目錄對(duì)應(yīng)產(chǎn)品的編譯產(chǎn)物，僅保留args.gn、build.log。清除指定路徑可輸入路徑參數(shù)：hb clean out/board/product，默認(rèn)將清除當(dāng)前hb set的產(chǎn)品對(duì)應(yīng)out路徑。

hb clean
usage: hb clean [-h] [out_path]

positional arguments:
  out_path    clean a specified path.

optional arguments:
  -h, --help  show this help message and exit

說明：

• 設(shè)備開發(fā)過程中詳細(xì)的編譯環(huán)境搭建及編譯步驟請參考[快速入門中的環(huán)境搭建及編譯章節(jié)。]
• OpenHarmony還為開發(fā)者提供了Docker編譯環(huán)境，可以省略編譯工具的安裝，具體使用請參考[Docker編譯指導(dǎo)。]

新增并編譯不同配置

根據(jù)上一節(jié)的配置規(guī)則新增相應(yīng)配置并進(jìn)行編譯，主要包含產(chǎn)品、部件、芯片解決方案和模塊四個(gè)粒度。具體如下：

• [新增并編譯產(chǎn)品]
• [新增并編譯部件]
• [新增并編譯模塊]
• [新增并編譯芯片解決方案]

常見問題

• [常見編譯問題和解決方法]

參考信息

• [關(guān)于deps、external_deps的使用]
• [Sanitizer使用說明]
• [開源軟件Notice收集策略說明]
• [加快本地編譯的一些參數(shù)]
• [查看NinjaTrace]
• [定制打包c(diǎn)hip_prod鏡像使用說明]

審核編輯 黃宇