PrepareBuilding添加注释

rt-thread/tools/building.py

@@ -150,18 +150,20 @@ def GenCconfigFile(env, BuildOptions):
     pass
 
 def PrepareBuilding(env, root_directory, has_libcpu=False, remove_components = []):
-
+    # 定义全局变量
     global BuildOptions
     global Projects
     global Env
     global Rtt_Root
 
+    # 添加scons编译选项
     AddOptions()
 
+    # 从相对路径中读取绝对路径
     Env = env
     Rtt_Root = os.path.abspath(root_directory)
 
-    # make an absolute root directory
+    # 保存绝对路径，make an absolute root directory
     RTT_ROOT = Rtt_Root
     Export('RTT_ROOT')
 
@@ -170,8 +172,12 @@ def PrepareBuilding(env, root_directory, has_libcpu=False, remove_components = [
     # set BSP_ROOT in ENV
     Env['BSP_ROOT'] = Dir('#').abspath
 
+    # 添加 RT-Thread 工具路径
     sys.path = sys.path + [os.path.join(Rtt_Root, 'tools')]
 
+    #———————————————————————————————————— 构建选项的实现 ——————————————————————————————————————#
+
+    # 定义目标字典，包含目标名及其对应的编译器和平台
     # {target_name:(CROSS_TOOL, PLATFORM)}
     tgt_dict = {'mdk':('keil', 'armcc'),
                 'mdk4':('keil', 'armcc'),
@@ -191,8 +197,10 @@ def PrepareBuilding(env, root_directory, has_libcpu=False, remove_components = [
                 'xmake':('gcc', 'gcc'),
                 'codelite' : ('gcc', 'gcc'),
                 'esp-idf': ('gcc', 'gcc')}
+    # 获取目标工程名称
     tgt_name = GetOption('target')
 
+     # 根据目标名选择编译器和平台
     if tgt_name:
         # --target will change the toolchain settings which clang-analyzer is
         # depend on
@@ -200,8 +208,10 @@ def PrepareBuilding(env, root_directory, has_libcpu=False, remove_components = [
             print ('--clang-analyzer cannot be used with --target')
             sys.exit(1)
 
+        # 不生成执行代码
         SetOption('no_exec', 1)
         try:
+            # 替换rtconfig中配置的编译工具及平台
             rtconfig.CROSS_TOOL, rtconfig.PLATFORM = tgt_dict[tgt_name]
             # replace the 'RTT_CC' to 'CROSS_TOOL'
             os.environ['RTT_CC'] = rtconfig.CROSS_TOOL
@@ -209,22 +219,27 @@ def PrepareBuilding(env, root_directory, has_libcpu=False, remove_components = [
             print('Unknow target: '+ tgt_name+'. Avaible targets: ' +', '.join(tgt_dict.keys()))
             sys.exit(1)
 
+    # 设置工具程序路径前缀
     exec_prefix = GetOption('exec-prefix')
     if exec_prefix:
         os.environ['RTT_CC_PREFIX'] = exec_prefix
 
+    # 当 rtconfig.EXEC_PATH 无效时，自动更改 'RTT_EXEC_PATH'
     # auto change the 'RTT_EXEC_PATH' when 'rtconfig.EXEC_PATH' get failed
     if not os.path.exists(rtconfig.EXEC_PATH):
         if 'RTT_EXEC_PATH' in os.environ:
             # del the 'RTT_EXEC_PATH' and using the 'EXEC_PATH' setting on rtconfig.py
             del os.environ['RTT_EXEC_PATH']
-
+    
+    # 设置工具路径
     exec_path = GetOption('exec-path')
     if exec_path:
         os.environ['RTT_EXEC_PATH'] = exec_path
 
+    # 更新rtconfig中的环境变量
     utils.ReloadModule(rtconfig) # update environment variables to rtconfig.py
 
+    # 在 SConstruct 的 Environment() 中，已经加载了一些 env 变量，需要在重新加载 rtconfig.py 后同步这些变量
     # some env variables have loaded in Environment() of SConstruct before re-load rtconfig.py;
     # after update rtconfig.py's variables, those env variables need to synchronize
     if exec_prefix:
@@ -236,10 +251,12 @@ def PrepareBuilding(env, root_directory, has_libcpu=False, remove_components = [
     if exec_path:
         env.PrependENVPath('PATH', rtconfig.EXEC_PATH)
 
+    # 启用严格编译
     if GetOption('strict-compiling'):
         STRICT_FLAGS = ''
         if rtconfig.PLATFORM in ['gcc']:
             STRICT_FLAGS += ' -Werror' #-Wextra
+            #追加到编译选项cflag和cxxflag中
             env.Append(CFLAGS=STRICT_FLAGS, CXXFLAGS=STRICT_FLAGS)
 
     # add compability with Keil MDK 4.6 which changes the directory of armcc.exe
@@ -275,16 +292,21 @@ def PrepareBuilding(env, root_directory, has_libcpu=False, remove_components = [
     else:
         os.environ['PATH'] = rtconfig.EXEC_PATH + ":" + os.environ['PATH']
 
+    # 添加系统中PATH环境变量中的所有路径，包括rtconfig中的
     # add program path
     env.PrependENVPath('PATH', os.environ['PATH'])
+
+    # 将 rtconfig.h/BSP 路径添加到内核组
     # add rtconfig.h/BSP path into Kernel group
     DefineGroup("Kernel", [], [], CPPPATH=[str(Dir('#').abspath)])
 
+    # 创建一个新的 SCons Builder 对象，用于安装编译好的库
     # add library build action
     act = SCons.Action.Action(BuildLibInstallAction, 'Install compiled library... $TARGET')
     bld = Builder(action = act)
     Env.Append(BUILDERS = {'BuildLib': bld})
 
+    # 从rtconfig.h中加载宏定义
     # parse rtconfig.h to get used component
     PreProcessor = PatchedPreProcessor()
     f = open('rtconfig.h', 'r')
@@ -293,6 +315,7 @@ def PrepareBuilding(env, root_directory, has_libcpu=False, remove_components = [
     PreProcessor.process_contents(contents)
     BuildOptions = PreProcessor.cpp_namespace
 
+    # 是否启用clang-analyzer用于代码静态分析
     if GetOption('clang-analyzer'):
         # perform what scan-build does
         env.Replace(
@@ -315,10 +338,12 @@ def PrepareBuilding(env, root_directory, has_libcpu=False, remove_components = [
     # generate cconfig.h file
     GenCconfigFile(env, BuildOptions)
 
+    # nano.specs 是gcc的一个体积更小的标准库newlib
     # auto append '_REENT_SMALL' when using newlib 'nano.specs' option
     if rtconfig.PLATFORM in ['gcc'] and str(env['LINKFLAGS']).find('nano.specs') != -1:
         env.AppendUnique(CPPDEFINES = ['_REENT_SMALL'])
 
+    # 添加编译宏定义，同在rtconfig.h中添加是一样的作用
     add_rtconfig = GetOption('add_rtconfig')
     if add_rtconfig:
         add_rtconfig = add_rtconfig.split(',')
@@ -332,38 +357,45 @@ def PrepareBuilding(env, root_directory, has_libcpu=False, remove_components = [
         else:
             print('add_rtconfig arguements are illegal!')
 
+    # Generate .config from rtconfig.h
     if GetOption('genconfig'):
         from genconf import genconfig
         genconfig()
         exit(0)
 
+    # 栈空间分析
     if GetOption('stackanalysis'):
         from WCS import ThreadStackStaticAnalysis
         ThreadStackStaticAnalysis(Env)
         exit(0)
+    
+    # 打开menuconfig配置
     if platform.system() != 'Windows':
         if GetOption('menuconfig'):
             from menuconfig import menuconfig
             menuconfig(Rtt_Root)
             exit(0)
 
+    # Don`t show pyconfig window
     if GetOption('pyconfig_silent'):
         from menuconfig import guiconfig_silent
         guiconfig_silent(Rtt_Root)
         exit(0)
 
+    # Python GUI menuconfig for RT-Thread BSP
     elif GetOption('pyconfig'):
         from menuconfig import guiconfig
         guiconfig(Rtt_Root)
         exit(0)
 
+    # make rtconfig.h from config file
     configfn = GetOption('useconfig')
     if configfn:
         from menuconfig import mk_rtconfig
         mk_rtconfig(configfn)
         exit(0)
 
-
+    # 默认不使用详细输出，只输出编译结果
     if not GetOption('verbose'):
         # override the default verbose command string
         env.Replace(
@@ -380,6 +412,7 @@ def PrepareBuilding(env, root_directory, has_libcpu=False, remove_components = [
         if env['LINK'].find('gcc') != -1:
             env['LINK'] = env['LINK'].replace('gcc', 'g++')
 
+    # 设置项目构建地址
     # we need to seperate the variant_dir for BSPs and the kernels. BSPs could
     # have their own components etc. If they point to the same folder, SCons
     # would find the wrong source code to compile.
@@ -389,6 +422,8 @@ def PrepareBuilding(env, root_directory, has_libcpu=False, remove_components = [
     objs = SConscript('SConscript', variant_dir=bsp_vdir, duplicate=0)
     # include kernel
     objs.extend(SConscript(Rtt_Root + '/src/SConscript', variant_dir=kernel_vdir + '/src', duplicate=0))
+    
+    # 此处指的是，是否包含外部的libcpu移植代码。如果没有，则采用rt-thread中移植好的代码。
     # include libcpu
     if not has_libcpu:
         objs.extend(SConscript(Rtt_Root + '/libcpu/SConscript',
@@ -609,9 +644,12 @@ def _PretreatListParameters(target_list):
 
 def DefineGroup(name, src, depend, **parameters):
     global Env
+
+    # 检查依赖项是否满足，如果不满足则返回空列表
     if not GetDepend(depend):
         return []
 
+    # 查找已存在的组并获取组的路径
     # find exist group and get path of group
     group_path = ''
     for g in Projects:
@@ -620,9 +658,12 @@ def DefineGroup(name, src, depend, **parameters):
     if group_path == '':
         group_path = GetCurrentDir()
 
+    # 创建组并设置属性
     group = parameters
     group['name'] = name
     group['path'] = group_path
+
+    # 如果源文件是列表类型，则去除重复元素并转换为 File 类型
     if type(src) == type([]):
         # remove duplicate elements from list
         src = list(set(src))
@@ -630,6 +671,7 @@ def DefineGroup(name, src, depend, **parameters):
     else:
         group['src'] = src
 
+    # 添加编译选项
     if 'CFLAGS' in group:
         target = group['CFLAGS']
         if len(target) > 0:
@@ -642,6 +684,7 @@ def DefineGroup(name, src, depend, **parameters):
         target = group['CXXFLAGS']
         if len(target) > 0:
             Env.AppendUnique(CXXFLAGS = target)
+    # 添加头文件路径
     if 'CPPPATH' in group:
         target = group['CPPPATH']
         if _PretreatListParameters(target) == True:
@@ -650,18 +693,25 @@ def DefineGroup(name, src, depend, **parameters):
                 paths.append(os.path.abspath(item))
             target = paths
             Env.AppendUnique(CPPPATH = target)
+    # 添加预处理器定义
     if 'CPPDEFINES' in group:
         target = group['CPPDEFINES']
         if _PretreatListParameters(target) == True:
             Env.AppendUnique(CPPDEFINES = target)
+    
+    # 添加链接器选项
     if 'LINKFLAGS' in group:
         target = group['LINKFLAGS']
         if len(target) > 0:
             Env.AppendUnique(LINKFLAGS = target)
+
+    # 添加汇编器选项
     if 'ASFLAGS' in group:
         target = group['ASFLAGS']
         if len(target) > 0:
             Env.AppendUnique(ASFLAGS = target)
+    
+    # 添加本地头文件路径
     if 'LOCAL_CPPPATH' in group:
         paths = []
         for item in group['LOCAL_CPPPATH']:
@@ -669,6 +719,7 @@ def DefineGroup(name, src, depend, **parameters):
         group['LOCAL_CPPPATH'] = paths
 
 
+    # 针对 gcc 平台的特殊处理
     if rtconfig.PLATFORM in ['gcc']:
         if 'CFLAGS' in group:
             group['CFLAGS'] = utils.GCCC99Patch(group['CFLAGS'])
@@ -682,7 +733,8 @@ def DefineGroup(name, src, depend, **parameters):
             group['LOCAL_CXXFLAGS'] = utils.GCCC99Patch(group['LOCAL_CXXFLAGS'])
         if 'LOCAL_CFLAGS' in group:
             group['LOCAL_CFLAGS'] = utils.GCCC99Patch(group['LOCAL_CFLAGS'])
-    # check whether to clean up library
+
+    # 检查是否需要清理库文件
     if GetOption('cleanlib') and os.path.exists(os.path.join(group['path'], GroupLibFullName(name, Env))):
         if group['src'] != []:
             print('Remove library:'+ GroupLibFullName(name, Env))
@@ -690,6 +742,7 @@ def DefineGroup(name, src, depend, **parameters):
             if os.path.exists(fn):
                 os.unlink(fn)
 
+    # 添加库文件
     if 'LIBS' in group:
         target = group['LIBS']
         if _PretreatListParameters(target) == True:
@@ -699,6 +752,7 @@ def DefineGroup(name, src, depend, **parameters):
         if _PretreatListParameters(target) == True:
             Env.AppendUnique(LIBPATH = target)
 
+    # 检查是否需要构建组库
     # check whether to build group library
     if 'LIBRARY' in group:
         objs = Env.Library(name, group['src'])
@@ -706,6 +760,7 @@ def DefineGroup(name, src, depend, **parameters):
         # only add source
         objs = group['src']
 
+    # 合并组
     # merge group
     for g in Projects:
         if g['name'] == name:

vscode.code-workspace

@@ -0,0 +1,7 @@
+{
+    "folders": [
+        {
+            "path": "."
+        }
+    ]
+}