SCons.Scanner

1 """SCons.Scanner 2 3 The Scanner package for the SCons software construction utility. 4 5 """ 6 7 # 8 # Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 The SCons Foundation 9 # 10 # Permission is hereby granted, free of charge, to any person obtaining 11 # a copy of this software and associated documentation files (the 12 # "Software"), to deal in the Software without restriction, including 13 # without limitation the rights to use, copy, modify, merge, publish, 14 # distribute, sublicense, and/or sell copies of the Software, and to 15 # permit persons to whom the Software is furnished to do so, subject to 16 # the following conditions: 17 # 18 # The above copyright notice and this permission notice shall be included 19 # in all copies or substantial portions of the Software. 20 # 21 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY 22 # KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE 23 # WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 24 # NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE 25 # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 26 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION 27 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 28 # 29 30 __revision__ = "src/engine/SCons/Scanner/__init__.py 3842 2008/12/20 22:59:52 scons" 31 32 import re 33 import string 34 35 import SCons.Node.FS 36 import SCons.Util 37 38

39 -class _Null:

40 pass

41 42 # This is used instead of None as a default argument value so None can be 43 # used as an actual argument value. 44 _null = _Null 45

46 -def Scanner(function, *args, **kw):

47 """ 48 Public interface factory function for creating different types 49 of Scanners based on the different types of "functions" that may 50 be supplied. 51 52 TODO: Deprecate this some day. We've moved the functionality 53 inside the Base class and really don't need this factory function 54 any more. It was, however, used by some of our Tool modules, so 55 the call probably ended up in various people's custom modules 56 patterned on SCons code. 57 """ 58 if SCons.Util.is_Dict(function): 59 return apply(Selector, (function,) + args, kw) 60 else: 61 return apply(Base, (function,) + args, kw)

62 63 64

65 -class FindPathDirs:

66 """A class to bind a specific *PATH variable name to a function that 67 will return all of the *path directories."""

68 - def __init__(self, variable):

69 self.variable = variable

70 - def __call__(self, env, dir=None, target=None, source=None, argument=None):

71 import SCons.PathList 72 try: 73 path = env[self.variable] 74 except KeyError: 75 return () 76 77 dir = dir or env.fs._cwd 78 path = SCons.PathList.PathList(path).subst_path(env, target, source) 79 return tuple(dir.Rfindalldirs(path))

80 81 82

83 -class Base:

84 """ 85 The base class for dependency scanners. This implements 86 straightforward, single-pass scanning of a single file. 87 """ 88

89 - def __init__(self, 90 function, 91 name = "NONE", 92 argument = _null, 93 skeys = _null, 94 path_function = None, 95 node_class = SCons.Node.FS.Entry, 96 node_factory = None, 97 scan_check = None, 98 recursive = None):

99 """ 100 Construct a new scanner object given a scanner function. 101 102 'function' - a scanner function taking two or three 103 arguments and returning a list of strings. 104 105 'name' - a name for identifying this scanner object. 106 107 'argument' - an optional argument that, if specified, will be 108 passed to both the scanner function and the path_function. 109 110 'skeys' - an optional list argument that can be used to determine 111 which scanner should be used for a given Node. In the case of File 112 nodes, for example, the 'skeys' would be file suffixes. 113 114 'path_function' - a function that takes four or five arguments 115 (a construction environment, Node for the directory containing 116 the SConscript file that defined the primary target, list of 117 target nodes, list of source nodes, and optional argument for 118 this instance) and returns a tuple of the directories that can 119 be searched for implicit dependency files. May also return a 120 callable() which is called with no args and returns the tuple 121 (supporting Bindable class). 122 123 'node_class' - the class of Nodes which this scan will return. 124 If node_class is None, then this scanner will not enforce any 125 Node conversion and will return the raw results from the 126 underlying scanner function. 127 128 'node_factory' - the factory function to be called to translate 129 the raw results returned by the scanner function into the 130 expected node_class objects. 131 132 'scan_check' - a function to be called to first check whether 133 this node really needs to be scanned. 134 135 'recursive' - specifies that this scanner should be invoked 136 recursively on all of the implicit dependencies it returns 137 (the canonical example being #include lines in C source files). 138 May be a callable, which will be called to filter the list 139 of nodes found to select a subset for recursive scanning 140 (the canonical example being only recursively scanning 141 subdirectories within a directory). 142 143 The scanner function's first argument will be a Node that should 144 be scanned for dependencies, the second argument will be an 145 Environment object, the third argument will be the tuple of paths 146 returned by the path_function, and the fourth argument will be 147 the value passed into 'argument', and the returned list should 148 contain the Nodes for all the direct dependencies of the file. 149 150 Examples: 151 152 s = Scanner(my_scanner_function) 153 154 s = Scanner(function = my_scanner_function) 155 156 s = Scanner(function = my_scanner_function, argument = 'foo') 157 158 """ 159 160 # Note: this class could easily work with scanner functions that take 161 # something other than a filename as an argument (e.g. a database 162 # node) and a dependencies list that aren't file names. All that 163 # would need to be changed is the documentation. 164 165 self.function = function 166 self.path_function = path_function 167 self.name = name 168 self.argument = argument 169 170 if skeys is _null: 171 if SCons.Util.is_Dict(function): 172 skeys = function.keys() 173 else: 174 skeys = [] 175 self.skeys = skeys 176 177 self.node_class = node_class 178 self.node_factory = node_factory 179 self.scan_check = scan_check 180 if callable(recursive): 181 self.recurse_nodes = recursive 182 elif recursive: 183 self.recurse_nodes = self._recurse_all_nodes 184 else: 185 self.recurse_nodes = self._recurse_no_nodes

186

187 - def path(self, env, dir=None, target=None, source=None):

188 if not self.path_function: 189 return () 190 if not self.argument is _null: 191 return self.path_function(env, dir, target, source, self.argument) 192 else: 193 return self.path_function(env, dir, target, source)

194

195 - def __call__(self, node, env, path = ()):

196 """ 197 This method scans a single object. 'node' is the node 198 that will be passed to the scanner function, and 'env' is the 199 environment that will be passed to the scanner function. A list of 200 direct dependency nodes for the specified node will be returned. 201 """ 202 if self.scan_check and not self.scan_check(node, env): 203 return [] 204 205 self = self.select(node) 206 207 if not self.argument is _null: 208 list = self.function(node, env, path, self.argument) 209 else: 210 list = self.function(node, env, path) 211 212 kw = {} 213 if hasattr(node, 'dir'): 214 kw['directory'] = node.dir 215 node_factory = env.get_factory(self.node_factory) 216 nodes = [] 217 for l in list: 218 if self.node_class and not isinstance(l, self.node_class): 219 l = apply(node_factory, (l,), kw) 220 nodes.append(l) 221 return nodes

222

223 - def __cmp__(self, other):

224 try: 225 return cmp(self.__dict__, other.__dict__) 226 except AttributeError: 227 # other probably doesn't have a __dict__ 228 return cmp(self.__dict__, other)

229

230 - def __hash__(self):

231 return id(self)

232

233 - def __str__(self):

234 return self.name

235

236 - def add_skey(self, skey):

237 """Add a skey to the list of skeys""" 238 self.skeys.append(skey)

239

240 - def get_skeys(self, env=None):

241 if env and SCons.Util.is_String(self.skeys): 242 return env.subst_list(self.skeys)[0] 243 return self.skeys

244

245 - def select(self, node):

246 if SCons.Util.is_Dict(self.function): 247 key = node.scanner_key() 248 try: 249 return self.function[key] 250 except KeyError: 251 return None 252 else: 253 return self

254

255 - def _recurse_all_nodes(self, nodes):

256 return nodes

257

258 - def _recurse_no_nodes(self, nodes):

259 return []

260 261 recurse_nodes = _recurse_no_nodes 262

263 - def add_scanner(self, skey, scanner):

264 self.function[skey] = scanner 265 self.add_skey(skey)

266 267

268 -class Selector(Base):

269 """ 270 A class for selecting a more specific scanner based on the 271 scanner_key() (suffix) for a specific Node. 272 273 TODO: This functionality has been moved into the inner workings of 274 the Base class, and this class will be deprecated at some point. 275 (It was never exposed directly as part of the public interface, 276 although it is used by the Scanner() factory function that was 277 used by various Tool modules and therefore was likely a template 278 for custom modules that may be out there.) 279 """

280 - def __init__(self, dict, *args, **kw):

281 apply(Base.__init__, (self, None,)+args, kw) 282 self.dict = dict 283 self.skeys = dict.keys()

284

285 - def __call__(self, node, env, path = ()):

286 return self.select(node)(node, env, path)

287

288 - def select(self, node):

289 try: 290 return self.dict[node.scanner_key()] 291 except KeyError: 292 return None

293

294 - def add_scanner(self, skey, scanner):

295 self.dict[skey] = scanner 296 self.add_skey(skey)

297 298

299 -class Current(Base):

300 """ 301 A class for scanning files that are source files (have no builder) 302 or are derived files and are current (which implies that they exist, 303 either locally or in a repository). 304 """ 305

306 - def __init__(self, *args, **kw):

307 def current_check(node, env): 308 return not node.has_builder() or node.is_up_to_date()

309 kw['scan_check'] = current_check 310 apply(Base.__init__, (self,) + args, kw)

311

312 -class Classic(Current):

313 """ 314 A Scanner subclass to contain the common logic for classic CPP-style 315 include scanning, but which can be customized to use different 316 regular expressions to find the includes. 317 318 Note that in order for this to work "out of the box" (without 319 overriding the find_include() and sort_key() methods), the regular 320 expression passed to the constructor must return the name of the 321 include file in group 0. 322 """ 323

324 - def __init__(self, name, suffixes, path_variable, regex, *args, **kw):

325 326 self.cre = re.compile(regex, re.M) 327 328 def _scan(node, env, path=(), self=self): 329 node = node.rfile() 330 if not node.exists(): 331 return [] 332 return self.scan(node, path)

333 334 kw['function'] = _scan 335 kw['path_function'] = FindPathDirs(path_variable) 336 kw['recursive'] = 1 337 kw['skeys'] = suffixes 338 kw['name'] = name 339 340 apply(Current.__init__, (self,) + args, kw)

341

342 - def find_include(self, include, source_dir, path):

343 n = SCons.Node.FS.find_file(include, (source_dir,) + tuple(path)) 344 return n, include

345

346 - def sort_key(self, include):

347 return SCons.Node.FS._my_normcase(include)

348

349 - def find_include_names(self, node):

350 return self.cre.findall(node.get_contents())

351

352 - def scan(self, node, path=()):

353 354 # cache the includes list in node so we only scan it once: 355 if node.includes != None: 356 includes = node.includes 357 else: 358 includes = self.find_include_names (node) 359 node.includes = includes 360 361 # This is a hand-coded DSU (decorate-sort-undecorate, or 362 # Schwartzian transform) pattern. The sort key is the raw name 363 # of the file as specifed on the #include line (including the 364 # " or <, since that may affect what file is found), which lets 365 # us keep the sort order constant regardless of whether the file 366 # is actually found in a Repository or locally. 367 nodes = [] 368 source_dir = node.get_dir() 369 if callable(path): 370 path = path() 371 for include in includes: 372 n, i = self.find_include(include, source_dir, path) 373 374 if n is None: 375 SCons.Warnings.warn(SCons.Warnings.DependencyWarning, 376 "No dependency generated for file: %s (included from: %s) -- file not found" % (i, node)) 377 else: 378 sortkey = self.sort_key(include) 379 nodes.append((sortkey, n)) 380 381 nodes.sort() 382 nodes = map(lambda pair: pair[1], nodes) 383 return nodes

384

385 -class ClassicCPP(Classic):

386 """ 387 A Classic Scanner subclass which takes into account the type of 388 bracketing used to include the file, and uses classic CPP rules 389 for searching for the files based on the bracketing. 390 391 Note that in order for this to work, the regular expression passed 392 to the constructor must return the leading bracket in group 0, and 393 the contained filename in group 1. 394 """

395 - def find_include(self, include, source_dir, path):

396 if include[0] == '"': 397 paths = (source_dir,) + tuple(path) 398 else: 399 paths = tuple(path) + (source_dir,) 400 401 n = SCons.Node.FS.find_file(include[1], paths) 402 403 return n, include[1]

404

405 - def sort_key(self, include):

406 return SCons.Node.FS._my_normcase(string.join(include))

407

Source Code for Package SCons.Scanner