1## 编译构建框架简介
2编译构建框架以gn+ninja作为基础构建系统,针对产品需要和部件化功能,在gn阶段前增加了preloader和loader的预加载过程。
3
41. preloader: 产品信息预加载。根据编译产品名称,加载对应的配置文件(config.json)并解析,将解析结果以文本方式输出到指定目录下。
52. loader:子系统、部件和模块信息加载。以编译产品名称和preloader的输出作为输入,加载对应的subsystem、component、module/part等配置信息,以文本文件方式输出结果文件和gn的编译任务。
63. gn: gn是一种编译构建工具,用于产生编译目标之间的图状编译依赖。在编译流程中,编译文件生成阶段负责构建参数赋值,执行gn gen编译命令,产生的build.ninja文件可以类比与makefile文件。
74. ninja:ninja是一种接近汇编级的编译构建工具。语法规则简单,构建速度快。在编译流程中,根据编译规则完成对所有编译目标的编译过程。
8
9
10## 新增编译选项
11当前的编译参数通过统一的文本文件管理,保证参数功能独立,并一一映射对应的参数实现函数。
12在编译过程中,为了明确参数具体的作用时间,根据编译的preloader,loader,gn,ninja四个基础过程,人为划分了9个编译阶段。分别为:
13    ```
14
15    PRE_BUILD                   # 编译预处理相关参数,如--full-compilation,--log-level
16    PRE_LOAD                    # preloader前置设置参数
17    LOAD                        # loader前置设置参数,如--scalable-build,--build-xts
18    PRE_TARGET_GENERATE         # gn前置设置参数,如--gn-args
19    TARGET_GENERATE             # gn阶段参数
20    POST_TARGET_GENERATE        # gn后置设置参数
21    PRE_TARGET_COMPILATION      # ninja前置设置参数,如--ninja-arg
22    TARGET_COMPILATION          # ninja阶段参数
23    POST_TARGET_COMPILATION     # ninja后置设置参数,如--generate-ninja-trace
24    POST_BUILD                  # 编译后处理参数,如--clean-args
25    ```
26
27为编译框架添加一个编译选项主要分为两步:
28
291. 在参数管理的json文件中对参数进行注册
302. 针对参数的实际使能方式为参数添加参数实现函数。
31
32## 示例
33### 新增一个--ccache选项,默认为false,用于调用ccache编译缓存,加快编译速度。
341. 参数注册:
35该参数在编译前开启,在build/hb/resources/args/default/buildargs.json中进行注册,文件添加以下配置:
36```
37    "ccache": {
38    "arg_name": "--ccache",
39    "argDefault": false,
40    "arg_help": "Default:True. Help:Enable ccache, this option could improve compilation speed. --stat-ccache can summary the cache data",
41    "arg_phase": "prebuild",
42    "arg_type": "gate",
43    "arg_attribute": {},
44    "resolve_function": "resolve_ccache",
45    "testFunction": "testCCache"
46  },
47```
48
492. 参数实现:
50build/hb/resolver/build_args_resolver.py中添加相应的实现函数(代码仅为简单示例):
51```
52    @staticmethod
53    def resolve_ccache(target_arg: Arg, build_module: BuildModuleInterface):
54        """resolve '--ccache' arg
55        :param target_arg: arg object which is used to get arg value.
56        :param build_module [maybe unused]: build module object which is used to get other services.
57        :phase: prebuild.
58        """
59        if target_arg.arg_value:
60            config = Config()
61            cmd = ['ccache', '-M', ccache_max_size]
62            SystemUtil.exec_command(cmd, log_path=config.log_path)
63```
64
653. 参数使用:在编译命令中添加--ccache即可通过在指定编译阶段调用resolve_ccache()实现参数使能。
66
67
68## 注意事项
691. 为gn传递专用变量,请勿注册参数。
70例如需要增加一个gn变量为enable_cxx,只需要在build/ohos_var.gni中通过declare声明:
71```
72declare_args() {
73  enable_cxx = true
74}
75```
76并在编译命令中添加下面命令即可完成使能。
77```
78--gn-args enable_cxx=false
79```
80
81
822. 为ninja传递编译命令,请勿注册参数。
83例如需要在ninja编译命令中传递-v参数,在编译命令中添加下面命令即可完成使能。
84```
85--ninja-args=-v
86```
87