# 对鸿蒙构建工程配置构建加速 鸿蒙构建加速通过解析鸿蒙构建工程的内部依赖关系，将其拆解分发至多台机器并发执行，结合增量编译技术，实现对软件编译过程的效率提升，支撑企业研发过程的快速迭代，缩短产品的上市周期。 #### 约束与限制 - 增量编译技术需结合L3级别加速使用。 - 使用鸿蒙构建加速能力需要购买配套构建加速包，购买方法请参考[购买增值特性](https://support.huaweicloud.com/usermanual-devcloud/devcloud_01_0002.html#section5)。 - 该功能目前仅支持"华北-北京四"区域、代码源为CodeArts Repo的C/C++语言构建工程的编译构建加速。 - 本章节配置仅支持鸿蒙L1、L3级别的加速。 - 构建过程中不允许直接覆盖LD_LIBRARY_PATH和LD_PRELOAD环境变量，建议通过追加的方式使用，例如： ``` "export LD_LIBRARY_PATH=new_path:${LD_LIBRARY_PATH}" ``` #### 加速前准备 在一般的构建工程中，其构建过程大致分为构建前准备（工具链、代码仓）、构建依赖件准备（ninja文件生成）、编译构建、构建后操作（打包、检查等）。其中，构建加速介入编译构建阶段，对此前的构建过程中生成的构建依赖件进行解析，并执行编译。 在配置构建加速前，需做如下准备： - 找到构建依赖件准备的节点，以OpenHarmony为例，一个形态的编译命令如下： ``` ./build.sh --product-name rk3568 --build-target make_all --build-target make_test --ccache false -v ``` - 准备好构建使用的docker镜像，基于该docker镜像制作新镜像：在dockerfile中增加"/opt/buildtools"目录供加速工具部署，并确保构建用户对"/opt/buildtools"目录有权限写入。参考命令如下： ``` RUN mkdir -p /opt/buildtools && chmod -R 777 /opt/buildtools ``` #### 通过BuildFlow组织加速构建 构建加速需要结合多任务代码化构建使用，可参考[编写多任务build.yml文件](https://support.huaweicloud.com/usermanual-codeci/codeci_ug_1057.html)中的部分配置。 BuildFlow配置方法如下样例： ``` buildflow: jobs_resolver: # 必配 provider: tbuild_jobs_resolver # 必配，固定值 jobs: # 需要进行编排的任务集 - job: distribute_job # 构建任务名称 build_ref: accelerate.yml # 指定构建加速脚本，脚本名称可自定义 worker: 2 # 指定为16vCPU的倍数，例如2就代表使用了32vCPU进行加速 ``` 参数说明如下： - jobs_resolver：buildflow的子节点，必配。 - provider：此处使用的provider为jobs_resolver的高级选项，意为指定job对应的任务解析器，取值固定为tbuild_jobs_resolver。 - jobs：需要进行编排的任务集，此处的jobs作为jobs_resolver的子节点，与普通构建场景buildflow下的jobs子节点有所区别，配置时请注意缩进。 - job：构建任务名称，可自定义。 - build_ref：该构建任务在构建过程中需要运行的加速构建脚本。 - worker：指定为16vCPU的倍数，例如2就代表使用了32vCPU进行加速。 #### 配置示例1：依赖解析模式 1. 获取json文件。 在分支A编写BuildFlow配置中build_ref指定的accelerate.yml，示例如下： ``` version: 2.0 params: - name: TB_GET_ORI_TRACE value: "1" steps: PRE_BUILD: - checkout: name: "checkout" inputs: scm: "codehub" url: "git@codehub.devcloud.example.example.com:example.git" branch: "master" lfs: false submodule: false BUILD: - tbuild_execute: inputs: image: "swr.example.example.com/buildimage:ohos-x86-v1" command: "cd OpenHarmony && BuildAccelerateL3 -HarmonyOS ./build.sh --product-name rk3568 --build-target make_all --ccache false -v && post_build.sh && mv out/TBTrace_make_all_1.json /example/TB1.json" ``` 2. 执行分布式构建。 在分支B编写BuildFlow配置中build_ref指定的accelerate.yml，示例如下： ``` version: 2.0 params: - name: TB_BUILDTRACE_ALL value: "1" - name: TB_RSYNC value: ${WORKSPACE}/OpenHarmony/:out/rk3568 steps: PRE_BUILD: - checkout: name: "checkout" inputs: scm: "codehub" url: "git@codehub.devcloud.example.example.com:example.git" branch: "master" lfs: false submodule: false BUILD: - tbuild_execute: inputs: image: "swr.example.example.com/buildimage:ohos-x86-v1" command: "mv /example/TB1.json OpenHarmony/TB1.json && cd OpenHarmony && BuildAccelerateL3 -HarmonyOS ./build.sh --product-name rk3568 --build-target make_all --ccache false -v && post_build.sh" ``` #### 配置示例2：产物分类模式 在分支C编写BuildFlow配置中build_ref指定的accelerate.yml，示例如下： ``` version: 2.0 params: - name: TB_RSYNC value: ${WORKSPACE}/OpenHarmony/:out/rk3568 - name: TB_SEARCH_TARGETS_ALL value: "obj/build/ohos/common/generate_src_installed_info.stamp" steps: PRE_BUILD: - checkout: name: "checkout" inputs: scm: "codehub" url: "git@codehub.devcloud.example.example.com:example.git" branch: "master" lfs: false submodule: false BUILD: - tbuild_execute: inputs: image: "swr.example.example.com/buildimage:ohos-x86-v1" command: "cd OpenHarmony && BuildAccelerateL3 -HarmonyOS ./build.sh --product-name rk3568 --build-target make_all --ccache false -v && post_build.sh" ``` #### params参数项详解 params配置项指定了一些使用鸿蒙构建加速必配的参数，参数说明如下： | **参数** | **说明** | |:---|:---| | TB_RSYNC | 需要同步的产物文件目录，":"前为根目录，":"后为若干个以","分隔的子目录，子目录前带"!"代表此目录不同步，不带"!"代表此目录的所有文件会被同步，带"!"的优先级更高。在鸿蒙构建场景下，需要拼接为"${WORKSPACE}/实际目录"。 示例如下： "${WORKSPACE}/OpenHarmony/:out/rk3568,out/kernel,!out/rk3568/exe.unstripped,!out/rk3568/lib.unstripped,!out/rk3568/innerkits,!out/rk3568/.ninja_,!out/rk3568/Makefile,!out/rk3568/NOTICE_FILES,!out/rk3568/clang_x64/exe.unstripped,!out/rk3568/clang_x64/lib.unstripped,!out/rk3568/mingw_x86_64/lib.unstripped,+out/rk3568/obj/base/security/selinux_adapter" | | TB_GET_ORI_TRACE | [配置示例1：依赖解析模式]必填。 依赖解析模式下获取当前工程的依赖json文件开关。 - 1：开启。 - 0：关闭（默认）。 默认值：1。 | | TB_BUILDTRACE_ALL | [配置示例1：依赖解析模式]必填。 依赖解析模式开关，不设置时默认使用[配置示例2：产物分类模式]。 - 1：开启。 - 不设置：关闭（默认为OpenHarmony/harmony.json）。 - 非"1"的其他字符串：开启，字符串视为json文件的自定义路径和名字。 | | TB_SEARCH_TARGETS_ALL | [配置示例2：产物分类模式]必填。 该值填写工程中汇总了各个模块的target，如鸿蒙的： parts_test.stamp 、generate_src_installed_info.stamp。一般这样的target的下一层直接依赖是工程中的多个小模块，如鸿蒙的ark模块、ace模块。这些对应的target在同一个工程里一般不会变化。 默认值："obj/build/ohos/common/generate_src_installed_info.stamp"。 | #### steps参数项详解 steps配置项定义了构建过程，示例中包含如下两个步骤：PRE_BUILD（构建前准备）和BUILD（编译构建）。 - PRE_BUILD 此阶段主要做代码下载，参数解释如下： ``` PRE_BUILD: - checkout: # 代码下载步骤 name: "代码下载" # 步骤名称，可自定义 inputs: # 步骤参数 scm: "codehub " # 代码来源:只支持Repo url: "git@codehub.devcloud.example.example.com:test/python3.git" # 拉取代码的ssh地址。 branch: "master" # 拉取的代码分支。 lfs: false # 选择是否开启Git LFS，false关闭、true开启。构建默认不拉取音视频、图像等大型文件，开启Git LFS后，构建将会全量拉取文件。 submodule: false # false关闭、true开启。开启该功能，系统在构建时会自动拉取子模块仓库的代码。 ``` - BUILD 此阶段主要定义了download_artifact插件、tbuild_execute插件和upload_artifact插件，参数解释如下： ``` BUILD: - tbuild_execute: # 鸿蒙加速场景下固定配置，定义tbuild_execute插件 inputs: # 固定配置 image: "swr.xx-xx-x.myxxcloud.com/buildimage:ohos-x86-v1" # 构建使用的镜像，参考加速前准备章节制作docker镜像。 command: "mv /example/TB1.json OpenHarmony/TB1.json && cd OpenHarmony && BuildAccelerateL3 -HarmonyOS ./build.sh --product-name rk3568 --build-target make_all --ccache false -v && post_build.sh" # command为构建使用的命令，此处将构建分解为两个段落，准备和执行 # mv /example/TB1.json OpenHarmony/TB1.json是依赖解析模式独有的准备步骤，文件名字固定，如果工程中存在多个ninja构建，则文件的下标依次增加，例如TBTrace_target_2.json和TB2.json，以此类推。 # 准备阶段:使用加速前准备章节中获取的./build.sh --product-name rk3568 --build-target make_all --build-only-gn --ccache false -v # 构建阶段:依照加速级别调用加速命令（BuildAccelerateL1 BuildAccelerateL3）的鸿蒙模式（-HarmonyOS）直接执行构建，此处样例取值BuildAccelerateL3 -HarmonyOS # 后处理阶段:以实际工程需要为准，该示例仅使用post_build.sh # 依赖解析模式实际命令最终拼接为"mv /example/TB1.json OpenHarmony/TB1.json && cd OpenHarmony && BuildAccelerateL3 -HarmonyOS ./build.sh --product-name rk3568 --build-target make_all --ccache false -v && post_build.sh" # 产物分类模式实际命令最终拼接为"cd OpenHarmony && BuildAccelerateL3 -HarmonyOS ./build.sh --product-name rk3568 --build-target make_all --ccache false -v && post_build.sh" ``` build.sh样例： ``` source build/envsetup.sh lunch aosp_x86_64-eng make -j64 ``` #### 高级选项 高级选项均为非必填选项，在构建过程中有工程无法执行需要特殊适配或优化性能时配置，若随意配置可能会导致构建失败。 表1通用选项 | **参数** | **说明** | **示例** | |:---|:---|:---| | TB_GET_TRACE | 构建结束后获取依赖json文件文件的开关。 - 1：开启。 - 0：关闭（默认）。 | 1 | | TB_NINJA_RULE_ALL | 分割规则配置，target按数量比值分组。不设置时会自动配置合适值。 | "1:2:3:4" | | TB_TARGETS_LIST_ALL | 人工指定分发的target进行编译，每个英文逗号隔开一个worker的target。使用"\*"分隔多个ninja工程的配置。不设置时会自动配置合适值。 | "harmony_target_1 harmony_target_2,harmony_target_3 harmony_target_4" | | TB_HOOK_LOCK | 对软链接也进行文件同步。若构建过程中发生软链接文件未同步导致的报错，需要开启此选项。 - 1：开启。 - 0：关闭（默认）。 | 1 | | TB_APPEND_PATH | 构建时可向PATH环境变量中追加的参数。 - 1：开启。 - 0：关闭（默认）。 | 1 | | TB_SHUT_DOWN_SAME_TIME | 所有worker都等待主节点执行完毕后再结束构建释放资源。 - 1：开启。 - 0：关闭（默认）。 | 1 | | TB_RSYNC_LOCK | 构建加速的同时worker向构建执行机实时传输文件。开启后效率会进一步提升，但会存在概率性编译失败的情况。 - 1：开启。 - 0：关闭（默认）。 | 1 | | TB_MAKE_J | 设置构建并发数。默认为worker核数。 | 16 | | TB_REFER_NINJA_FILE | 如果存在串行执行一个一模一样的ninja工程时，可以使用此变量优化构建速度 - 1：开启。 - 0：关闭（默认）。 | 1 | | CCACHE_DIR | 自定义编译缓存的本地目录。默认为/tmp/xcache目录。 | ${WORKSPACE}/TBcache | | TB_CACHE_SIZE | 使用自定义执行机自定义编译缓存的本地目录存储大小上限。默认为100G。 | 100G | | CCACHE_MAXSIZE | 自定义编译缓存的本地目录存储大小上限。默认为20G。 | 100G | | TB_ONE_WORKER | 使用自定义执行机且只使用一个worker进行构建时可以使用此变量打开编译缓存开关。 - 1：开启。 - 0：关闭（默认）。 | 1 | | TB_CLIENT | 该变量在主节点client自动设置，可以通过比较此变量是否等于1判断该节点是否为主节点client。 | 不需要配置 | | TB_NET_INTERFACE_NAME | 指定获取IP时读取的网卡名，在多网卡情况下获取IP使用，默认为空，多个网卡名通过逗号分隔，配置在前的网卡名有更高的优先级。 | eth0,eth1 | | TB_ACC_PREPARE | 使用自定义执行机时必须配置此变量。 | false | | TB_OUTPUT_PATH | 自定义产物目录路径，默认设置为out。 | output | | TB_SELF_ENV | worker编译target时使用本地环境变量，不使用client传递的变量。 - 1：开启。 - 0：关闭（默认）。 | 1 | | TB_RSYNC_FLAG | 增加同步文件时rsync命令的参数。 | --ignore-existing -a | | TBUILD_PLUGIN_PKG_TYPE | 指定使用的TBuild版本为snapshot版本还是release版本。不设置时默认使用最新的release版本。 | release | | TBUILD_PLUGIN_PKG_VERSION | 指定使用的TBuild版本号。不设置时默认使用最新的release版本。 | 1.0.1 | 表2依赖解析模式 | **参数项** | **说明** | **示例** | |:---|:---|:---| | TB_CPU_NUM | 分发任务时，所有机器都以此值计算可分配任务量。默认为空。 | 16 | | TB_LOCAL_CONTAIN_PATTERN | 根据关键字指定必须分发在client编译的target，此target生成的产物不需要文件传输回主节点。默认为空。 | file_contexts.bin,com.android.vndk.current.,out/soong/host/linux-x86/bin/fileslist | | TB_LOCAL_NOT_CONTAIN_PATTERN | 根据关键字指定必须不分发在client编译的target。默认为空。 | Bluetooth.so | | TB_CAPACITY_ALL | 单台机器可分配的任务权值上限，单位是分钟，以json文件的时间为参考，此时间为单纯的构建时间，不包括cpu空闲时间，实际构建时间会大于此值。可以指定为小数。超过此上限的target会分发至client，在所有agent编译完成后在本地最后编译。不设置时会根据json文件自动设置。 | 5.5 | | TB_TASK_SIZE_ALL | 人工指定分割多少份target，可以大于机器数量，建议设置的值略大于机器数量，不建议少于机器数量，会导致机器浪费。不设置时会根据机器数量自动设置。 | 8 | 表3ninja文件缓存选项 | **参数项** | **说明** | **示例** | |:---|:---|:---| | TB_CACHE_SERVER_IP | ninja文件缓存开关，和TB_CACHE_ARCHIVE_PATH同时设置时缓存才会开启。 - 非空值：开启，如果开启了远端缓存，该值视为远端服务器IP。 - 空值：关闭（默认）。 | 172.example.example.example | | TB_CACHE_ARCHIVE_PATH | ninja文件缓存本地归档目录，和TB_CACHE_SERVER_IP同时设置时缓存才会开启。 | AOSP/ninja_cache | | TB_CACHE_RECACHE | 本次构建会重新生成ninja文件缓存，不会命中历史缓存。 - 1：开启。 - 0：关闭（默认）。 | 1 | | TB_CACHE_REMOTE | ninja文件缓存远端开关，命中时从远端获取缓存，生成缓存时也会归档至远端。 - 1：开启。 - 0：关闭（默认）。 | 1 | | TB_CACHE_LOCAL | ninja文件缓存本地开关，命中时从本地获取缓存，优先级高于远端缓存，生成缓存时也会归档至本地。 - 1：开启（默认）。 - 0：关闭。 | 1 | | TB_CACHE_DEPENDS | 增加指定的文件作为缓存命中的依赖文件，如果该文件产生变化，会使缓存不命中。默认为空。多个文件使用逗号分隔。 | build.sh,test.sh | | TB_CACHE_VERSION | 为缓存增加指定的版本号，如果版本号产生变化，会使缓存不命中。默认为空。 | 1.0 | | TB_CACHE_EXCLUDE_KEY | 缓存时过滤掉带关键字的文件，多个关键字用逗号分隔，默认设置为".glob"，可以用空字符串重置。 | .so,.glob | | TB_NINJA_FILE_CACHE | 设置被缓存的目录，多个目录使用逗号分隔，默认设置为"out"。 | out,test | | TB_CACHE_NINJA_CACHE_SIZE | ninja文件缓存本地归档目录空间上限，超过此上限会根据算法自动清理历史缓存。默认设置为50，单位是G。 | 100 | | TB_SKIP_TARGET | 归档ninja文件缓存时跳过此target，即使命中ninja文件缓存此target也会重新编译。 | update-api |