添加building注释

rt-thread/tools/building.py

@@ -823,6 +823,7 @@ def BuildLibInstallAction(target, source, env):
 
 def DoBuilding(target, objects):
 
+    # 将所有对象合并为一个列表，拆除内部嵌套
     # merge all objects into one list
     def one_list(l):
         lst = []
@@ -833,9 +834,12 @@ def DoBuilding(target, objects):
                 lst.append(item)
         return lst
 
+    # 处理本地组，传入组和对象
     # handle local group
     def local_group(group, objects):
+        # 检查组内是否有特定的编译选项
         if 'LOCAL_CFLAGS' in group or 'LOCAL_CXXFLAGS' in group or 'LOCAL_CCFLAGS' in group or 'LOCAL_CPPPATH' in group or 'LOCAL_CPPDEFINES' in group or 'LOCAL_ASFLAGS' in group:
+             # 将本地组的编译选项添加到环境变量
             CFLAGS = Env.get('CFLAGS', '') + group.get('LOCAL_CFLAGS', '')
             CCFLAGS = Env.get('CCFLAGS', '') + group.get('LOCAL_CCFLAGS', '')
             CXXFLAGS = Env.get('CXXFLAGS', '') + group.get('LOCAL_CXXFLAGS', '')
@@ -843,6 +847,10 @@ def DoBuilding(target, objects):
             CPPDEFINES = Env.get('CPPDEFINES', ['']) + group.get('LOCAL_CPPDEFINES', [''])
             ASFLAGS = Env.get('ASFLAGS', '') + group.get('LOCAL_ASFLAGS', '')
 
+            # 将源文件添加到对象列表
+            # Env.Object 是 SCons 构建环境中的一个方法，用于将源文件编译成目标（对象）文件。
+            # 该方法的主要作用是将源代码文件（如 C、C++、汇编等）编译成对应的目标文件。
+            # 在构建过程中，这些目标文件将被链接成可执行程序或库。
             for source in group['src']:
                 objects.append(Env.Object(source, CFLAGS = CFLAGS, CCFLAGS = CCFLAGS, CXXFLAGS = CXXFLAGS, ASFLAGS = ASFLAGS,
                     CPPPATH = CPPPATH, CPPDEFINES = CPPDEFINES))
@@ -851,9 +859,13 @@ def DoBuilding(target, objects):
 
         return False
 
+    # 合并所有对象为一个列表
     objects = one_list(objects)
 
     program = None
+
+    # 检查是否有特定的buildlib选项，是否有外部库的依赖
+    # 确保了具有本地标志设置的源文件能够正确处理
     # check whether special buildlib option
     lib_name = GetOption('buildlib')
     if lib_name:
@@ -872,6 +884,7 @@ def DoBuilding(target, objects):
 
                 break
     else:
+        # 移除具有本地标志设置的源文件
         # remove source files with local flags setting
         for group in Projects:
             if 'LOCAL_CFLAGS' in group or 'LOCAL_CXXFLAGS' in group or 'LOCAL_CCFLAGS' in group or 'LOCAL_CPPPATH' in group or 'LOCAL_CPPDEFINES' in group:
@@ -882,18 +895,22 @@ def DoBuilding(target, objects):
 
         # re-add the source files to the objects
 
+        # 将源文件重新添加到对象列表
         objects_in_group = []
         for group in Projects:
             local_group(group, objects_in_group)
 
+        # 分别排序，因为这两个列表的成员数据类型不同
         # sort seperately, because the data type of
         # the members of the two lists are different
         objects_in_group = sorted(objects_in_group)
         objects = sorted(objects)
         objects.append(objects_in_group)
 
+        # 将处理后的对象列表传递给程序，进行链接输出可执行程序program，target为程序名称
         program = Env.Program(target, objects)
 
+    # 调用EndBuilding函数，传入目标名称和程序
     EndBuilding(target, program)
 
 def GenTargetProject(program = None):
@@ -979,36 +996,46 @@ def EndBuilding(target, program = None):
 
     need_exit = False
 
+    # 设置环境变量
     Env['target']  = program
     Env['project'] = Projects
 
+    # 如果存在 BSP_LIBRARY_TYPE，将其设置为环境变量
     if hasattr(rtconfig, 'BSP_LIBRARY_TYPE'):
         Env['bsp_lib_type'] = rtconfig.BSP_LIBRARY_TYPE
 
+    # 如果存在 dist_handle，将其设置为环境变量
     if hasattr(rtconfig, 'dist_handle'):
         Env['dist_handle'] = rtconfig.dist_handle
 
+    # 添加后置动作
     Env.AddPostAction(target, rtconfig.POST_ACTION)
-    # Add addition clean files
+    
+    # 清除中间文件 Add addition clean files
     Clean(target, 'cconfig.h')
     Clean(target, 'rtua.py')
     Clean(target, 'rtua.pyc')
     Clean(target, '.sconsign.dblite')
 
+     # 如果指定了 target，生成 target 工程并退出
     if GetOption('target'):
         GenTargetProject(program)
         need_exit = True
 
+    # 获取 BSP_ROOT、project_name、project_path 等变量
     BSP_ROOT = Dir('#').abspath
-
     project_name = GetOption('project-name')
     project_path = GetOption('project-path')
+    
+    # 如果指定了 make-dist，生成软件分发包并退出
     if GetOption('make-dist') and program != None:
         MkDist(program, BSP_ROOT, Rtt_Root, Env, project_name, project_path)
         need_exit = True
+    # 如果指定了 make-dist-strip，生成剥离符号的软件分发包并退出
     if GetOption('make-dist-strip') and program != None:
         MkDist_Strip(program, BSP_ROOT, Rtt_Root, Env)
         need_exit = True
+    # 如果指定了 make-dist-ide，生成软件分发包和 Eclipse 工程并退出
     if GetOption('make-dist-ide') and program != None:
         import subprocess
         if not isinstance(project_path, str) or len(project_path) == 0 :
@@ -1017,15 +1044,18 @@ def EndBuilding(target, program = None):
         child = subprocess.Popen('scons --target=eclipse --project-name=' + project_name, cwd=project_path, stdout=subprocess.PIPE, stderr=subprocess.PIPE, shell=True)
         stdout, stderr = child.communicate()
         need_exit = True
+    # 如果指定了 cscope，生成 cscope 数据库
     if GetOption('cscope'):
         from cscope import CscopeDatabase
         CscopeDatabase(Projects)
 
+    # 如果不是获取帮助或目标，检查 toolchain 路径是否存在
     if not GetOption('help') and not GetOption('target'):
         if not os.path.exists(rtconfig.EXEC_PATH):
             print ("Error: the toolchain path (" + rtconfig.EXEC_PATH + ") is not exist, please check 'EXEC_PATH' in path or rtconfig.py.")
             need_exit = True
 
+    # 如果需要退出，则退出程序
     if need_exit:
         exit(0)