鸿蒙Harmony开辟：编译构建系统编码最佳规范实践

概述

gn是generate ninja的缩写，它是一个元编译系统（meta-build system）,是ninja的前端，gn和ninja联合起来，完成OpenHarmony操作系统的编译使命。
gn简介

• 现在接纳gn的大型软件系统有：Chromium，Fuchsia和OpenHarmony。
  
• gn语法自设计之初就自带局限性，比如不能求list的长度，不支持通配符等。这些局限性源于其 有所为有所不为 的设计哲学。 所以在利用gn的过程中，如果发现某件事变用gn实现起来很复杂，请先停下来思考这件事变是否真的必要做。
  
• 关于gn的更多详情见gn官方文档。
  

本文的目标读者和覆盖范围

目标读者为OpenHarmony的开辟者。本文主要讨论gn的编码风格和利用gn过程中轻易出现的题目，不讨论gn的语法，如需相识gn基础知识，见gn reference文档。
总体原则

在包管功能可用的前提下，脚本必要满足易于阅读，便于维护，良好的扩展性和性能等要求。
代码风格

定名

总体上遵循Linux kernel的定名风格，即小写字母+下划线的定名风格。
局部变量

我们这里对局部变量的定义为：在某作用域内，且不向下传递的变量。
为了更好的区别于全局变量，局部变量统一接纳下划线开头。

1. # 例1
2. action("some_action") {
3.   ...
4.   # _output是个局部变量，所以使用下划线开头
5.   _output = "${target_out_dir}/${target_name}.out"
6.   outputs = [ _output ]
7.   args = [
8.     ...
9.       "--output",
10.       rebase_path(_output, root_build_dir),
11.       ...
12.   ]
13.   ...
14. }

复制代码

全局变量

全局变量利用小写字母开头。
如果变量值可以被gn args修改，则必要利用declare_args来声明，否则不要利用declare_args。

1. # 例2
2. declare_args() {
3.   # 可以通过gn args来修改some_feature的值
4.   some_feature = false
5. }

复制代码

目标定名

目标定名接纳小写字母+下划线的定名方式。
模板中的子目标定名方式接纳"${target_name}+双下划线+后缀"的定名方式。如许做有两点利益：

• 加入"${target_name}"可以防止子目标重名。
  
• 加入双下划线可以很方便地区分出子目标属于哪一个模块，方便在出现题目时快速定位。
  
  1. # 例3
  2. template("ohos_shared_library") {
  3.   # "{target_name}"(主目标名)+"__"(双下划线)+"notice"(后缀)
  4.   _notice_target = "${target_name}__notice"
  5.   collect_notice(_notice_target) {
  6.     ...
  7.   }
  8.   shared_library(target_name) {
  9.     ...
  10.   }
  11. }

  复制代码

自定义模板的定名

保举接纳动宾短语的情势来定名。

1. # 例4
2. # Good
3. template("compile_resources") {
4.   ...
5. }

复制代码

格式化

gn脚本在提交之前必要实行格式化。格式化可以包管代码对齐，换行等风格的统一。利用gn自带的format工具即可。命令如下：

1. $ gn format path-to-BUILD.gn

复制代码

gn format会按照字母序对import文件做排序，如果想包管import的顺序，可以添加空解释行。
假设原来的import顺序为：

1. # 例5
2. import("//b.gni")
3. import("//a.gni")

复制代码

经过format之后变为：

1. import("//a.gni")
2. import("//b.gni")

复制代码

如果想包管原有的import顺序，可以添加空解释行。

1. import("//b.gni")
2. # Comment to keep import order
3. import("//a.gni")

复制代码

编码实践

实践原则

编译脚本实质上完成了两件工作：

• 描述模块之间依赖关系（deps）
  实践过程中，最常出现的题目是依赖关系缺失。
  
• 描述模块编译的规则(rule)
  实践过程中，轻易出现的题目是输入和输出不明确。
  

依赖缺失会导致两个题目：

• 概率性编译错误
  
  1. # 例6
  2. # 依赖关系缺失，导致概率性编译出错
  3. shared_library("a") {
  4.   ...
  5. }
  6. shared_library("b") {
  7.   ...
  8.   ldflags = [ "-la" ]
  9.   deps = []
  10.   ...
  11. }
  12. group("images") {
  13.   deps = [ ":b" ]
  14. }

  复制代码
  上面的例子中，libb.so在链接的时候会链接liba.so，实质上构成b依赖a，但是b的依赖列表（deps）却没有声明对a的依赖。由于编译是并发实行的，如果libb.so在链接的时候liba.so还没有编译出来，就会出现编译错误。
  由于liba.so也有可能在libb.so之前编译出来，所以依赖缺失导致的编译错误是概率性的。
  
• 依赖关系缺失导致模块没有参与编译
  还是上面的例子，如果我们指定ninja编译目标为images，由于images仅仅依赖b，所以a不会参与编译。由于b实质上依赖a, 这时b在链接时会出现必现错误。
  

有一种不太常见的题目是过多的依赖。过多的依赖会降低并发，导致编译变慢。见下面的例子:
_compile_js_target不必要依赖 _compile_resource_target，增加这层依赖，会导致 _compile_js_target在 _compile_resource_target编译完成之后才能开始编译。

1. # 例7
2. # 过多的依赖导致编译变慢
3. template("too_much_deps") {
4.   ...
5.   _gen_resource_target = "${target_name}__res"
6.   action(_gen_resource_target) {
7.     ...
8.   }
10.   _compile_resource_target = "${target_name}__compile_res"
11.   action(_compile_resource_target) {
12.     deps = [":$_gen_resource_target"]
13.     ...
14.   }
16.   _compile_js_target = "${target_name}__js"
17.   action(_compile_js_target) {
18.     # 这个deps不需要
19.     deps = [":$_compile_resource_target"]
20.   }
21. }

复制代码

输入不明确会导致：

• 代码修改了，但增量编译时却没有参与编译。
  
• 当利用缓存时，代码发生变革，但是缓存仍然命中。
  

下面的例子中，foo.py引用了bar.py中的函数。bar.py实质上是foo.py的输入，必要将bar.py添加到implict_input_action的input或者depfile中去。否则，修改bar.py，模块implict_input_action将不会重新编译。

1. # 例8
2. action("implict_input_action") {
3.   script = "//path-to-foo.py"
4.   ...
5. }

复制代码

1. #!/usr/bin/env
2. # Contents of foo.py
3. import bar
4. ...
5. bar.some_function()
6. ...

复制代码

输出不明确会导致：

• 隐式的输出
  
• 当利用缓存时，隐式输出无法从缓存中获得
  

下面的例子中，foo.py会生成两个文件，a.out和b.out，但是implict_output_action的输出只声明白a.out。这种环境下，b.out实质上就是一个隐式输出。缓存中只会存储a.out，不会存储b.out，当缓存命中时，b.out就编译不出来了。

1. # 例9
2. action("implict_output_action") {
3.   outputs = ["${target_out_dir}/a.out"]
4.   script = "//path-to-foo.py"
5.   ...
6. }

复制代码

1. #!/usr/bin/env
2. # Contents of foo.py
3. ...
4. write_file("b.out")
5. write_file("a.out")
6. ...

复制代码

模板

不要利用gn的原生模板，利用编译子系统提供的模板
所谓gn原生模板，是指source_set，shared_library, static_library, action, executable，group这六个模板。
不保举利用原生模板的原因有二：

• 原生模板是最小功能模板，无法提供external_deps的解析，notice网络，安装信息生成等的额外功能，这些额外功能最好是随着模块编译时同时生成，所以必须对原生模板做额外的扩展才能满足实际的需求。
  
• 当输入文件依赖的文件发生变革时，gn原生的action模板不能自动感知到这种变革，无法重新编译。见例8
  原生模板和编译子系统提供的模板之间的对应关系:
  

编译子系统提供的模板原生模板ohos_shared_libraryshared_libraryohos_source_setsource_setohos_executableexecutableohos_static_librarystatic_libraryaction_with_pydepsactionohos_groupgroup 利用python脚本

action中的script保举利用python脚本，不保举利用shell脚本。相比于shell脚本，python脚本：

• python语法友好，不会因为少写一个空格就导致奇怪的错误。
  
• python脚本有很强的可读性。
  
• 可维护性强，可调试。
  
• OpenHarmony对python使命做了缓存，可以加速编译速度。
  

rebase_path

• 仅在向action的参数列表中（args）调用rebase_path。
  
  1. # 例10
  2. template("foo") {
  3.   action(target_name) {
  4.     ...
  5.     args = [
  6.       # 仅在args中调用rebase_path
  7.       "--bar=" + rebase_path(invoker.bar, root_build_dir),
  8.       ...
  9.     ]
  10.     ...
  11.   }
  12. }
  14. foo("good") {
  15.   bar = something
  16.   ...
  17. }

  复制代码
• 同一变量做两次rebase_path会出现意想不到的结果。
  
  1. # 例11
  2. template("foo") {
  3.   action(target_name) {
  4.     ...
  5.     args = [
  6.       # bar被执行了两次rebase_path, 传递的bar的值已经不对了
  7.       "--bar=" + rebase_path(invoker.bar, root_build_dir),
  8.       ...
  9.     ]
  10.     ...
  11.   }
  12. }
  14. foo("bad") {
  15.   # 不要在这里调用rebase_path
  16.   bar = rebase_path(some_value，root_build_dir)
  17.   ...
  18. }

  复制代码

模块间数据分享

模块间数据分享是很常见的事变，比如A模块想要知道B模块的输出和deps。

• 同一BUILD.gn之间数据分享
  同一BUILD.gn之间数据可以通过定义全局变量的方式来共享。
  下面的例子中，模块a的输出是模块b的输入，可以通过定义全局变量的方式来共享给b
  
  1. # 例12
  2. _output_a = get_label_info(":a", "out_dir") + "/a.out"
  3. action("a") {
  4.   outputs = _output_a
  5.   ...
  6. }
  7. action("b") {
  8.   inputs = [_output_a]
  9.   ...
  10. }

  复制代码
• 差别BUILD.gn之间数据分享
  差别BUILD.gn之间传递数据，最好的办法是将必要共享的数据保存成文件，然后差别模块之间通过文件来传递和共享数据。这种场景比较复杂，读者可以参照OpenHarmony的hap编译过程的write_meta_data。
  

forward_variable_from

• 自定义模板必要起首将testonly传递（forward）进来。因为该模板的target有可能被testonly的目标依赖。
  
  1. # 例13
  2. # 自定义模板首先要传递testonly
  3. template("foo") {
  4.   forward_variable_from(invoker, ["testonly"])
  5.   ...
  6. }

  复制代码
• 不保举利用*来forward变量，必要的变量应该显式地，一个一个地被forward进来。
  
  1. # 例14
  2. # Bad，使用*forward变量
  3. template("foo") {
  4.   forward_variable_from(invoker, "*")
  5.   ...
  6. }
  8. # Good， 显式地，一个一个地forward变量
  9. template("bar") {
  10.   #
  11.   forward_variable_from(invoker, [
  12.                                      "testonly",
  13.                                      "deps",
  14.                                      ...
  15.                                    ])
  16.   ...
  17. }

  复制代码

target_name

target_name会随着作用域变革而变革，利用时必要注意。

1. # 例15
2. # target_name会随着作用域变化而变化
3. template("foo") {
4.   # 此时打印出来的target_name为"${target_name}"
5.   print(target_name)
6.   _code_gen_target = "${target_name}__gen"
7.   code_gen(_code_gen_target) {
8.     # 此时打印出来的target_name为"${target_name}__gen"
9.     print(target_name)
10.     ...
11.   }
12.   _compile_gen_target = "${target_name}__compile"
13.   compile(_compile_gen_target) {
14.     # 此时打印出来的target_name为"${target_name}__compile"
15.     print(target_name)
16.     ...
17.   }
18.   ...
19. }

复制代码

public_configs

如果模块必要向外export头文件，请利用public_configs。

1. # 例16
2. # b依赖a，会同时继承a的headers
3. config("headers") {
4.   include_dirs = ["//path-to-headers"]
5.   ...
6. }
7. shared_library("a") {
8.   public_configs = [":headers"]
9.   ...
10. }
11. executable("b") {
12.   deps = [":a"]
13.   ...
14. }

复制代码

template

自定义模板中必须有一个子目标的名字是target_name。该子目标会作为template的主目标。其他子目标都应该被主目标依赖，否则子目标不会被编译。

1. # 例17
2. # 自定义模板中必须有一个子目标的名字是target_name
3. template("foo") {
4.   _code_gen_target = "${target_name}__gen"
5.   code_gen(_code_gen_target) {
6.     ...
7.   }
8.   _compile_gen_target = "${target_name}__compile"
9.   compile(_compile_gen_target) {
10.     # 此时打印出来的target_name为"${target_name}__compile"
11.     print(target_name)
12.     ...
13.   }
14.   ...
15.   group(target_name) {
16.     deps = [
17.     # 由于_compile_gen_target依赖了_code_gen_target，所以主目标只需要依赖_compile_gen_target即可。
18.       ":$_compile_gen_target"
19.     ]
20.   }
21. }

复制代码

set_source_assignment_filter

set_source_assignment_filter除了可以过滤sources，还可以用来过滤其他变量。过滤完成跋文得将过滤器和sources置空。

1. # 例18
2. # 使用set_source_assignment_filter过滤依赖, 挑选label符合*:*_res的添加到依赖列表中
3. _deps = []
4. foreach(_possible_dep, invoker.deps) {
5.   set_source_assignment_filter(["*:*_res"])
6.   _label = get_label_info(_possible_dep, "label_no_toolchain")
7.   sources = []
8.   sources = [ _label ]
9.   if (sources = []) {
10.     _deps += _sources
11.   }
12. }
13. sources = []
14. set_source_assignment_filter([])

复制代码

最新版本上set_source_assignment_filter被filter_include和filter_exclude取代。
部件内依赖接纳deps，跨部件依赖接纳external_deps

• 部件在OpenHarmony上指能提供某个能力的一组模块。
  
• 在模块定义的时候可以声明part_name，用来表明当前模块属于哪个部件。
  
• 每个部件会声明其inner_kits，供其他部件调用。部件inner_kits的声明见源码中的bundle.json。
  
• 部件间依赖只能依赖inner_kits，不能依赖非inner_kits的模块。
  
• 如果a模块和b模块的part_name相同，那么a、b模块属于同一个部件，a，b模块之间的依赖关系可以用deps来声明。
  
• 如果a、b模块的part_name差别，那么a、b模块不属于同一个部件，a、b模块之间的依赖关系必要通过external_deps来声明，依赖方式为"部件名:模块名"的方式。见例19。
  
  1. # 例19
  2. shared_library("a") {
  3.   ...
  4.   external_deps = ["part_name_of_b:b"]
  5.   ...
  6. }

  复制代码

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。