parameters: (self, additional_tool_dirs=[], additional_flags=[], required=True)
docstring: Configure the test suite to be able to invoke clang.
  
          Sets up some environment variables important to clang, locates a
          just-built or installed clang, and add a set of standard
          substitutions useful to any test suite that makes use of clang.
docstring_summary: Configure the test suite to be able to invoke clang.
docstring_tokens: Configure the test suite to be able to invoke clang .
function: def use_clang(self, additional_tool_dirs=[], additional_flags=[], required=True):
          """Configure the test suite to be able to invoke clang.
  
          Sets up some environment variables important to clang, locates a
          just-built or installed clang, and add a set of standard
          substitutions useful to any test suite that makes use of clang.
  
          """
          # Clear some environment variables that might affect Clang.
          #
          # This first set of vars are read by Clang, but shouldn't affect tests
          # that aren't specifically looking for these features, or are required
          # simply to run the tests at all.
          #
          # FIXME: Should we have a tool that enforces this?
  
          # safe_env_vars = ('TMPDIR', 'TEMP', 'TMP', 'USERPROFILE', 'PWD',
          #                  'MACOSX_DEPLOYMENT_TARGET', 'IPHONEOS_DEPLOYMENT_TARGET',
          #                  'VCINSTALLDIR', 'VC100COMNTOOLS', 'VC90COMNTOOLS',
          #                  'VC80COMNTOOLS')
          possibly_dangerous_env_vars = ['COMPILER_PATH', 'RC_DEBUG_OPTIONS',
                                         'CINDEXTEST_PREAMBLE_FILE', 'LIBRARY_PATH',
                                         'CPATH', 'C_INCLUDE_PATH', 'CPLUS_INCLUDE_PATH',
                                         'OBJC_INCLUDE_PATH', 'OBJCPLUS_INCLUDE_PATH',
                                         'LIBCLANG_TIMING', 'LIBCLANG_OBJTRACKING',
                                         'LIBCLANG_LOGGING', 'LIBCLANG_BGPRIO_INDEX',
                                         'LIBCLANG_BGPRIO_EDIT', 'LIBCLANG_NOTHREADS',
                                         'LIBCLANG_RESOURCE_USAGE',
                                         'LIBCLANG_CODE_COMPLETION_LOGGING']
          # Clang/Win32 may refer to %INCLUDE%. vsvarsall.bat sets it.
          if platform.system() != 'Windows':
              possibly_dangerous_env_vars.append('INCLUDE')
  
          self.clear_environment(possibly_dangerous_env_vars)
  
          # Tweak the PATH to include the tools dir and the scripts dir.
          # Put Clang first to avoid LLVM from overriding out-of-tree clang builds.
          exe_dir_props = [self.config.name.lower() + '_tools_dir', 'clang_tools_dir', 'llvm_tools_dir']
          paths = [getattr(self.config, pp) for pp in exe_dir_props
                   if getattr(self.config, pp, None)]
          paths = additional_tool_dirs + paths
          self.with_environment('PATH', paths, append_path=True)
  
          lib_dir_props = [self.config.name.lower() + '_libs_dir', 'clang_libs_dir', 'llvm_shlib_dir', 'llvm_libs_dir']
          paths = [getattr(self.config, pp) for pp in lib_dir_props
                   if getattr(self.config, pp, None)]
  
          self.with_environment('LD_LIBRARY_PATH', paths, append_path=True)
  
          # Discover the 'clang' and 'clangcc' to use.
  
          self.config.clang = self.use_llvm_tool(
              'clang', search_env='CLANG', required=required)
  
          shl = getattr(self.config, 'llvm_shlib_dir', None)
          pext = getattr(self.config, 'llvm_plugin_ext', None)
          if shl:
              self.config.substitutions.append(('%llvmshlibdir', shl))
          if pext:
              self.config.substitutions.append(('%pluginext', pext))
  
          builtin_include_dir = self.get_clang_builtin_include_dir(self.config.clang)
          tool_substitutions = [
              ToolSubst('%clang', command=self.config.clang, extra_args=additional_flags),
              ToolSubst('%clang_analyze_cc1', command='%clang_cc1', extra_args=['-analyze', '%analyze']+additional_flags),
              ToolSubst('%clang_cc1', command=self.config.clang, extra_args=['-cc1', '-internal-isystem', builtin_include_dir, '-nostdsysteminc']+additional_flags),
              ToolSubst('%clang_cpp', command=self.config.clang, extra_args=['--driver-mode=cpp']+additional_flags),
              ToolSubst('%clang_cl', command=self.config.clang, extra_args=['--driver-mode=cl']+additional_flags),
              ToolSubst('%clangxx', command=self.config.clang, extra_args=['--driver-mode=g++']+additional_flags),
              ]
          self.add_tool_substitutions(tool_substitutions)
  
          self.config.substitutions.append(('%itanium_abi_triple',
                                            self.make_itanium_abi_triple(self.config.target_triple)))
          self.config.substitutions.append(('%ms_abi_triple',
                                            self.make_msabi_triple(self.config.target_triple)))
          self.config.substitutions.append(
              ('%resource_dir', builtin_include_dir))
  
          # The host triple might not be set, at least if we're compiling clang from
          # an already installed llvm.
          if self.config.host_triple and self.config.host_triple != '@LLVM_HOST_TRIPLE@':
              self.config.substitutions.append(('%target_itanium_abi_host_triple',
                                                '--target=%s' % self.make_itanium_abi_triple(self.config.host_triple)))
          else:
              self.config.substitutions.append(
                  ('%target_itanium_abi_host_triple', ''))
  
          # FIXME: Find nicer way to prohibit this.
          self.config.substitutions.append(
              (' clang ', """\"*** Do not use 'clang' in tests, use '%clang'. ***\""""))
          self.config.substitutions.append(
              (' clang\+\+ ', """\"*** Do not use 'clang++' in tests, use '%clangxx'. ***\""""))
          self.config.substitutions.append(
              (' clang-cc ',
               """\"*** Do not use 'clang-cc' in tests, use '%clang_cc1'. ***\""""))
          self.config.substitutions.append(
              (' clang-cl ',
               """\"*** Do not use 'clang-cl' in tests, use '%clang_cl'. ***\""""))
          self.config.substitutions.append(
              (' clang -cc1 -analyze ',
               """\"*** Do not use 'clang -cc1 -analyze' in tests, use '%clang_analyze_cc1'. ***\""""))
          self.config.substitutions.append(
              (' clang -cc1 ',
               """\"*** Do not use 'clang -cc1' in tests, use '%clang_cc1'. ***\""""))
          self.config.substitutions.append(
              (' %clang-cc1 ',
               """\"*** invalid substitution, use '%clang_cc1'. ***\""""))
          self.config.substitutions.append(
              (' %clang-cpp ',
               """\"*** invalid substitution, use '%clang_cpp'. ***\""""))
          self.config.substitutions.append(
              (' %clang-cl ',
               """\"*** invalid substitution, use '%clang_cl'. ***\""""))
function_tokens: def use_clang ( self , additional_tool_dirs = [ ] , additional_flags = [ ] , required = True ) : # Clear some environment variables that might affect Clang. # # This first set of vars are read by Clang, but shouldn't affect tests # that aren't specifically looking for these features, or are required # simply to run the tests at all. # # FIXME: Should we have a tool that enforces this? # safe_env_vars = ('TMPDIR', 'TEMP', 'TMP', 'USERPROFILE', 'PWD', #                  'MACOSX_DEPLOYMENT_TARGET', 'IPHONEOS_DEPLOYMENT_TARGET', #                  'VCINSTALLDIR', 'VC100COMNTOOLS', 'VC90COMNTOOLS', #                  'VC80COMNTOOLS') possibly_dangerous_env_vars = [ 'COMPILER_PATH' , 'RC_DEBUG_OPTIONS' , 'CINDEXTEST_PREAMBLE_FILE' , 'LIBRARY_PATH' , 'CPATH' , 'C_INCLUDE_PATH' , 'CPLUS_INCLUDE_PATH' , 'OBJC_INCLUDE_PATH' , 'OBJCPLUS_INCLUDE_PATH' , 'LIBCLANG_TIMING' , 'LIBCLANG_OBJTRACKING' , 'LIBCLANG_LOGGING' , 'LIBCLANG_BGPRIO_INDEX' , 'LIBCLANG_BGPRIO_EDIT' , 'LIBCLANG_NOTHREADS' , 'LIBCLANG_RESOURCE_USAGE' , 'LIBCLANG_CODE_COMPLETION_LOGGING' ] # Clang/Win32 may refer to %INCLUDE%. vsvarsall.bat sets it. if platform . system ( ) != 'Windows' : possibly_dangerous_env_vars . append ( 'INCLUDE' ) self . clear_environment ( possibly_dangerous_env_vars ) # Tweak the PATH to include the tools dir and the scripts dir. # Put Clang first to avoid LLVM from overriding out-of-tree clang builds. exe_dir_props = [ self . config . name . lower ( ) + '_tools_dir' , 'clang_tools_dir' , 'llvm_tools_dir' ] paths = [ getattr ( self . config , pp ) for pp in exe_dir_props if getattr ( self . config , pp , None ) ] paths = additional_tool_dirs + paths self . with_environment ( 'PATH' , paths , append_path = True ) lib_dir_props = [ self . config . name . lower ( ) + '_libs_dir' , 'clang_libs_dir' , 'llvm_shlib_dir' , 'llvm_libs_dir' ] paths = [ getattr ( self . config , pp ) for pp in lib_dir_props if getattr ( self . config , pp , None ) ] self . with_environment ( 'LD_LIBRARY_PATH' , paths , append_path = True ) # Discover the 'clang' and 'clangcc' to use. self . config . clang = self . use_llvm_tool ( 'clang' , search_env = 'CLANG' , required = required ) shl = getattr ( self . config , 'llvm_shlib_dir' , None ) pext = getattr ( self . config , 'llvm_plugin_ext' , None ) if shl : self . config . substitutions . append ( ( '%llvmshlibdir' , shl ) ) if pext : self . config . substitutions . append ( ( '%pluginext' , pext ) ) builtin_include_dir = self . get_clang_builtin_include_dir ( self . config . clang ) tool_substitutions = [ ToolSubst ( '%clang' , command = self . config . clang , extra_args = additional_flags ) , ToolSubst ( '%clang_analyze_cc1' , command = '%clang_cc1' , extra_args = [ '-analyze' , '%analyze' ] + additional_flags ) , ToolSubst ( '%clang_cc1' , command = self . config . clang , extra_args = [ '-cc1' , '-internal-isystem' , builtin_include_dir , '-nostdsysteminc' ] + additional_flags ) , ToolSubst ( '%clang_cpp' , command = self . config . clang , extra_args = [ '--driver-mode=cpp' ] + additional_flags ) , ToolSubst ( '%clang_cl' , command = self . config . clang , extra_args = [ '--driver-mode=cl' ] + additional_flags ) , ToolSubst ( '%clangxx' , command = self . config . clang , extra_args = [ '--driver-mode=g++' ] + additional_flags ) , ] self . add_tool_substitutions ( tool_substitutions ) self . config . substitutions . append ( ( '%itanium_abi_triple' , self . make_itanium_abi_triple ( self . config . target_triple ) ) ) self . config . substitutions . append ( ( '%ms_abi_triple' , self . make_msabi_triple ( self . config . target_triple ) ) ) self . config . substitutions . append ( ( '%resource_dir' , builtin_include_dir ) ) # The host triple might not be set, at least if we're compiling clang from # an already installed llvm. if self . config . host_triple and self . config . host_triple != '@LLVM_HOST_TRIPLE@' : self . config . substitutions . append ( ( '%target_itanium_abi_host_triple' , '--target=%s' % self . make_itanium_abi_triple ( self . config . host_triple ) ) ) else : self . config . substitutions . append ( ( '%target_itanium_abi_host_triple' , '' ) ) # FIXME: Find nicer way to prohibit this. self . config . substitutions . append ( ( ' clang ' , """\"*** Do not use 'clang' in tests, use '%clang'. ***\"""" ) ) self . config . substitutions . append ( ( ' clang\+\+ ' , """\"*** Do not use 'clang++' in tests, use '%clangxx'. ***\"""" ) ) self . config . substitutions . append ( ( ' clang-cc ' , """\"*** Do not use 'clang-cc' in tests, use '%clang_cc1'. ***\"""" ) ) self . config . substitutions . append ( ( ' clang-cl ' , """\"*** Do not use 'clang-cl' in tests, use '%clang_cl'. ***\"""" ) ) self . config . substitutions . append ( ( ' clang -cc1 -analyze ' , """\"*** Do not use 'clang -cc1 -analyze' in tests, use '%clang_analyze_cc1'. ***\"""" ) ) self . config . substitutions . append ( ( ' clang -cc1 ' , """\"*** Do not use 'clang -cc1' in tests, use '%clang_cc1'. ***\"""" ) ) self . config . substitutions . append ( ( ' %clang-cc1 ' , """\"*** invalid substitution, use '%clang_cc1'. ***\"""" ) ) self . config . substitutions . append ( ( ' %clang-cpp ' , """\"*** invalid substitution, use '%clang_cpp'. ***\"""" ) ) self . config . substitutions . append ( ( ' %clang-cl ' , """\"*** invalid substitution, use '%clang_cl'. ***\"""" ) )