src/engine/SCons/Scanner/__init__.py

   1 """SCons.Scanner
   2
   3 The Scanner package for the SCons software construction utility.
   4
   5 """
   6
   7 #
   8 # __COPYRIGHT__
   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__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__"
  31
  32 import re
  33
  34 import SCons.Node.FS
  35 import SCons.Sig
  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 class FindPathDirs:
  47     """A class to bind a specific *PATH variable name and the fs object
  48     to a function that will return all of the *path directories."""
  49     def __init__(self, variable, fs):
  50         self.variable = variable
  51         self.fs = fs
  52     def __call__(self, env, dir, argument=None):
  53         try:
  54             path = env[self.variable]
  55         except KeyError:
  56             return ()
  57
  58         return tuple(self.fs.Rsearchall(env.subst_path(path),
  59                                         must_exist = 0,
  60                                         clazz = SCons.Node.FS.Dir,
  61                                         cwd = dir))
  62
  63 class Base:
  64     """
  65     The base class for dependency scanners.  This implements
  66     straightforward, single-pass scanning of a single file.
  67     """
  68
  69     def __init__(self,
  70                  function,
  71                  name = "NONE",
  72                  argument = _null,
  73                  skeys = [],
  74                  path_function = None,
  75                  node_class = SCons.Node.FS.Entry,
  76                  node_factory = SCons.Node.FS.default_fs.File,
  77                  scan_check = None,
  78                  recursive = None):
  79         """
  80         Construct a new scanner object given a scanner function.
  81
  82         'function' - a scanner function taking two or three
  83         arguments and returning a list of strings.
  84
  85         'name' - a name for identifying this scanner object.
  86
  87         'argument' - an optional argument that, if specified, will be
  88         passed to both the scanner function and the path_function.
  89
  90         'skeys' - an optional list argument that can be used to determine
  91         which scanner should be used for a given Node. In the case of File
  92         nodes, for example, the 'skeys' would be file suffixes.
  93
  94         'path_function' - a function that takes one to three arguments
  95         (a construction environment, optional directory, and optional
  96         argument for this instance) and returns a tuple of the
  97         directories that can be searched for implicit dependency files.
  98
  99         'node_class' - the class of Nodes which this scan will return.
 100         If node_class is None, then this scanner will not enforce any
 101         Node conversion and will return the raw results from the
 102         underlying scanner function.
 103
 104         'node_factory' - the factory function to be called to translate
 105         the raw results returned by the scanner function into the
 106         expected node_class objects.
 107
 108         'scan_check' - a function to be called to first check whether
 109         this node really needs to be scanned.
 110
 111         'recursive' - specifies that this scanner should be invoked
 112         recursively on the implicit dependencies it returns (the
 113         canonical example being #include lines in C source files).
 114
 115         The scanner function's first argument will be the name of a file
 116         that should be scanned for dependencies, the second argument will
 117         be an Environment object, the third argument will be the value
 118         passed into 'argument', and the returned list should contain the
 119         Nodes for all the direct dependencies of the file.
 120
 121         Examples:
 122
 123         s = Scanner(my_scanner_function)
 124
 125         s = Scanner(function = my_scanner_function)
 126
 127         s = Scanner(function = my_scanner_function, argument = 'foo')
 128
 129         """
 130
 131         # Note: this class could easily work with scanner functions that take
 132         # something other than a filename as an argument (e.g. a database
 133         # node) and a dependencies list that aren't file names. All that
 134         # would need to be changed is the documentation.
 135
 136         self.function = function
 137         self.path_function = path_function
 138         self.name = name
 139         self.argument = argument
 140         self.skeys = skeys
 141         self.node_class = node_class
 142         self.node_factory = node_factory
 143         self.scan_check = scan_check
 144         self.recursive = recursive
 145
 146     def path(self, env, dir = None):
 147         if not self.path_function:
 148             return ()
 149         if not self.argument is _null:
 150             return self.path_function(env, dir, self.argument)
 151         else:
 152             return self.path_function(env, dir)
 153
 154     def __call__(self, node, env, path = ()):
 155         """
 156         This method scans a single object. 'node' is the node
 157         that will be passed to the scanner function, and 'env' is the
 158         environment that will be passed to the scanner function. A list of
 159         direct dependency nodes for the specified node will be returned.
 160         """
 161         if self.scan_check and not self.scan_check(node):
 162             return []
 163
 164         if not self.argument is _null:
 165             list = self.function(node, env, path, self.argument)
 166         else:
 167             list = self.function(node, env, path)
 168         kw = {}
 169         if hasattr(node, 'dir'):
 170             kw['directory'] = node.dir
 171         nodes = []
 172         for l in list:
 173             if self.node_class and not isinstance(l, self.node_class):
 174                 l = apply(self.node_factory, (l,), kw)
 175             nodes.append(l)
 176         return nodes
 177
 178     def __cmp__(self, other):
 179         return cmp(self.__dict__, other.__dict__)
 180
 181     def __hash__(self):
 182         return hash(repr(self))
 183
 184     def add_skey(self, skey):
 185         """Add a skey to the list of skeys"""
 186         self.skeys.append(skey)
 187
 188 class Current(Base):
 189     """
 190     A class for scanning files that are source files (have no builder)
 191     or are derived files and are current (which implies that they exist,
 192     either locally or in a repository).
 193     """
 194
 195     def __init__(self, *args, **kw):
 196         def current_check(node):
 197             c = not node.has_builder() or node.current(SCons.Sig.default_calc)
 198             return c
 199         kw['scan_check'] = current_check
 200         apply(Base.__init__, (self,) + args, kw)
 201
 202 class Classic(Current):
 203     """
 204     A Scanner subclass to contain the common logic for classic CPP-style
 205     include scanning, but which can be customized to use different
 206     regular expressions to find the includes.
 207
 208     Note that in order for this to work "out of the box" (without
 209     overriding the find_include() method), the regular expression passed
 210     to the constructor must return the name of the include file in group
 211     0.
 212     """
 213
 214     def __init__(self, name, suffixes, path_variable, regex,
 215                  fs=SCons.Node.FS.default_fs, *args, **kw):
 216
 217         self.cre = re.compile(regex, re.M)
 218         self.fs = fs
 219
 220         def _scan(node, env, path, self=self, fs=fs):
 221             return self.scan(node, env, path)
 222
 223         kw['function'] = _scan
 224         kw['path_function'] = FindPathDirs(path_variable, fs)
 225         kw['recursive'] = 1
 226         kw['skeys'] = suffixes
 227
 228         apply(Current.__init__, (self,) + args, kw)
 229
 230     def find_include(self, include, source_dir, path):
 231         n = SCons.Node.FS.find_file(include, (source_dir,) + path, self.fs.File)
 232         return n, include
 233
 234     def scan(self, node, env, path=()):
 235         node = node.rfile()
 236
 237         if not node.exists():
 238             return []
 239
 240         # cache the includes list in node so we only scan it once:
 241         if node.includes != None:
 242             includes = node.includes
 243         else:
 244             includes = self.cre.findall(node.get_contents())
 245             node.includes = includes
 246
 247         nodes = []
 248         source_dir = node.get_dir()
 249         for include in includes:
 250             n, i = self.find_include(include, source_dir, path)
 251
 252             if not n is None:
 253                 nodes.append(n)
 254             else:
 255                 SCons.Warnings.warn(SCons.Warnings.DependencyWarning,
 256                                     "No dependency generated for file: %s (included from: %s) -- file not found" % (i, node))
 257
 258         # Schwartzian transform from the Python FAQ Wizard
 259         def st(List, Metric):
 260             def pairing(element, M = Metric):
 261                 return (M(element), element)
 262             def stripit(pair):
 263                 return pair[1]
 264             paired = map(pairing, List)
 265             paired.sort()
 266             return map(stripit, paired)
 267
 268         def normalize(node):
 269             # We don't want the order of includes to be
 270             # modified by case changes on case insensitive OSes, so
 271             # normalize the case of the filename here:
 272             # (see test/win32pathmadness.py for a test of this)
 273             return SCons.Node.FS._my_normcase(str(node))
 274
 275         transformed = st(nodes, normalize)
 276         # print "Classic: " + str(node) + " => " + str(map(lambda x: str(x),list(transformed)))
 277         return transformed
 278
 279 class ClassicCPP(Classic):
 280     """
 281     A Classic Scanner subclass which takes into account the type of
 282     bracketing used to include the file, and uses classic CPP rules
 283     for searching for the files based on the bracketing.
 284
 285     Note that in order for this to work, the regular expression passed
 286     to the constructor must return the leading bracket in group 0, and
 287     the contained filename in group 1.
 288     """
 289     def find_include(self, include, source_dir, path):
 290         if include[0] == '"':
 291             n = SCons.Node.FS.find_file(include[1],
 292                                         (source_dir,) + path,
 293                                         self.fs.File)
 294         else:
 295             n = SCons.Node.FS.find_file(include[1],
 296                                         path + (source_dir,),
 297                                         self.fs.File)
 298         return n, include[1]