site_scons/site_init.py

   1 #!/usr/bin/python2.4
   2 # Copyright 2009, Google Inc.
   3 # All rights reserved.
   4 #
   5 # Redistribution and use in source and binary forms, with or without
   6 # modification, are permitted provided that the following conditions are
   7 # met:
   8 #
   9 #     * Redistributions of source code must retain the above copyright
  10 # notice, this list of conditions and the following disclaimer.
  11 #     * Redistributions in binary form must reproduce the above
  12 # copyright notice, this list of conditions and the following disclaimer
  13 # in the documentation and/or other materials provided with the
  14 # distribution.
  15 #     * Neither the name of Google Inc. nor the names of its
  16 # contributors may be used to endorse or promote products derived from
  17 # this software without specific prior written permission.
  18 #
  19 # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20 # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21 # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22 # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  23 # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24 # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25 # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26 # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27 # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29 # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30
  31 """Software construction toolkit site_scons configuration.
  32
  33 This module sets up SCons for use with this toolkit.  This should contain setup
  34 which occurs outside of environments.  If a method operates within the context
  35 of an environment, it should instead go in a tool in site_tools and be invoked
  36 for the target environment.
  37 """
  38
  39 import __builtin__
  40 import sys
  41 import SCons
  42
  43
  44 def _HostPlatform():
  45   """Returns the current host platform.
  46
  47   That is, the platform we're actually running SCons on.  You shouldn't use
  48   this inside your SConscript files; instead, include the appropriate
  49   target_platform tool for your environments.  When you call
  50   BuildEnvironments(), only environments with the current host platform will be
  51   built.  If for some reason you really need to examine the host platform,
  52   check env.Bit('host_windows') / env.Bit('host_linux') / env.Bit('host_mac').
  53
  54   Returns:
  55     The host platform name - one of ('WINDOWS', 'LINUX', 'MAC').
  56   """
  57
  58   platform_map = {
  59       'win32': 'WINDOWS',
  60       'cygwin': 'WINDOWS',
  61       'linux': 'LINUX',
  62       'linux2': 'LINUX',
  63       'darwin': 'MAC',
  64   }
  65
  66   if sys.platform not in platform_map:
  67     print ('site_init.py warning: platform "%s" is not in platfom map.' %
  68            sys.platform)
  69
  70   return platform_map.get(sys.platform, sys.platform)
  71
  72
  73 #------------------------------------------------------------------------------
  74
  75
  76 def _CheckBuildModes(build_modes, environments, host_platform):
  77   """Checks the build modes for the environments.
  78
  79   Args:
  80     build_modes: List of build mode strings.
  81     environments: List of SCons environments.
  82     host_platform: Host platform string.
  83
  84   Raises:
  85     ValueError: build groups and/or types invalid.
  86   """
  87   # Make sure the list of environments for the current host platform have
  88   # unique BUILD_TYPE.  This ensures they won't overwrite each others' build
  89   # output.  (It is ok for build types in different host platforms to overlap;
  90   # that is, WINDOWS and MAC can both have a 'dbg' build type.)
  91   all_build_types = []
  92   all_build_groups = {}
  93   build_desc = {}
  94   for e in environments:
  95     if not e.Overlap(e['HOST_PLATFORMS'], [host_platform, '*']):
  96       continue
  97     if e['BUILD_TYPE'] in all_build_types:
  98       raise ValueError('Multiple environments have the same BUILD_TYPE=%s' %
  99                        e['BUILD_TYPE'])
 100     else:
 101       all_build_types.append(e['BUILD_TYPE'])
 102       build_desc[e['BUILD_TYPE']] = e.get('BUILD_TYPE_DESCRIPTION')
 103
 104     # Keep track of build groups and the build types which belong to them
 105     for g in e['BUILD_GROUPS']:
 106       if g not in all_build_groups:
 107         all_build_groups[g] = []
 108         # Don't allow build types and groups to share names
 109         if g in all_build_types:
 110           raise ValueError('Build group %s also specified as BUILD_TYPE.' % g)
 111         else:
 112           all_build_types.append(g)
 113       all_build_groups[g].append(e['BUILD_TYPE'])
 114
 115   # Add help for build types
 116   help_text = '''
 117 Use --mode=type to specify the type of build to perform.  The following types
 118 may be specified:
 119 '''
 120
 121   for build_type in all_build_types:
 122     if build_type not in all_build_groups:
 123       help_text += '    %-16s %s\n' % (
 124           build_type, build_desc.get(build_type, ''))
 125
 126   help_text += '''
 127 The following build groups may also be specified via --mode.  Build groups
 128 build one or more of the other build types.  The available build groups are:
 129 '''
 130
 131   groups_sorted = all_build_groups.keys()
 132   groups_sorted.sort()
 133   for g in groups_sorted:
 134     help_text += '    %-16s %s\n' % (g, ','.join(all_build_groups[g]))
 135
 136   help_text += '''
 137 Multiple modes may be specified, separated by commas: --mode=mode1,mode2.  If
 138 no mode is specified, the default group will be built.  This is equivalent to
 139 specifying --mode=default.
 140   '''
 141   SCons.Script.Help(help_text)
 142
 143   # Make sure all build modes specified by the user are ones which apply to
 144   # the current environment.
 145   for mode in build_modes:
 146     if mode not in all_build_types and mode not in all_build_groups:
 147       print ('Warning: Ignoring build mode "%s", which is not defined on this '
 148              'platform.' % mode)
 149
 150
 151 #------------------------------------------------------------------------------
 152
 153
 154 def BuildEnvironmentSConscripts(env):
 155   """Evaluates SConscripts for the environment.
 156
 157   Called by BuildEnvironments().
 158   """
 159   # Read SConscript for each component
 160   # TODO: Remove BUILD_COMPONENTS once all projects have transitioned to the
 161   # BUILD_SCONSCRIPTS nomenclature.
 162   for c in env.SubstList2('$BUILD_SCONSCRIPTS', '$BUILD_COMPONENTS'):
 163     # Clone the environment so components can't interfere with each other
 164     ec = env.Clone()
 165
 166     if ec.Entry(c).isdir():
 167       # The component is a directory, so assume it contains a SConscript
 168       # file.
 169       c_dir = ec.Dir(c)
 170
 171       # Use 'build.scons' as the default filename, but if that doesn't
 172       # exist, fall back to 'SConscript'.
 173       c_script = c_dir.File('build.scons')
 174       if not c_script.exists():
 175         c_script = c_dir.File('SConscript')
 176     else:
 177       # The component is a SConscript file.
 178       c_script = ec.File(c)
 179       c_dir = c_script.dir
 180
 181     # Make c_dir a string.
 182     c_dir = str(c_dir)
 183
 184     # Use build_dir differently depending on where the SConscript is.
 185     if not ec.RelativePath('$TARGET_ROOT', c_dir).startswith('..'):
 186       # The above expression means: if c_dir is $TARGET_ROOT or anything
 187       # under it. Going from c_dir to $TARGET_ROOT and dropping the not fails
 188       # to include $TARGET_ROOT.
 189       # We want to be able to allow people to use addRepository to back things
 190       # under $TARGET_ROOT/$OBJ_ROOT with things from above the current
 191       # directory. When we are passed a SConscript that is already under
 192       # $TARGET_ROOT, we should not use build_dir.
 193       ec.SConscript(c_script, exports={'env': ec}, duplicate=0)
 194     elif not ec.RelativePath('$MAIN_DIR', c_dir).startswith('..'):
 195       # The above expression means: if c_dir is $MAIN_DIR or anything
 196       # under it. Going from c_dir to $TARGET_ROOT and dropping the not fails
 197       # to include $MAIN_DIR.
 198       # Also, if we are passed a SConscript that
 199       # is not under $MAIN_DIR, we should fail loudly, because it is unclear how
 200       # this will correspond to things under $OBJ_ROOT.
 201       ec.SConscript(c_script, build_dir='$OBJ_ROOT/' + c_dir,
 202                     exports={'env': ec}, duplicate=0)
 203     else:
 204       raise SCons.Error.UserError(
 205           'Bad location for a SConscript. "%s" is not under '
 206           '\$TARGET_ROOT or \$MAIN_DIR' % c_script)
 207
 208
 209 def BuildEnvironments(environments):
 210   """Build a collection of SConscripts under a collection of environments.
 211
 212   Only environments with HOST_PLATFORMS containing the platform specified by
 213   --host-platform (or the native host platform, if --host-platform was not
 214   specified) will be matched.
 215
 216   Each matching environment is checked against the modes passed to the --mode
 217   command line argument (or 'default', if no mode(s) were specified).  If any
 218   of the modes match the environment's BUILD_TYPE or any of the environment's
 219   BUILD_GROUPS, all the BUILD_SCONSCRIPTS (and for legacy reasons,
 220   BUILD_COMPONENTS) in that environment will be built.
 221
 222   Args:
 223     environments: List of SCons environments.
 224
 225   Returns:
 226     List of environments which were actually evaluated (built).
 227   """
 228   # Get options
 229   build_modes = SCons.Script.GetOption('build_mode')
 230   # TODO: Remove support legacy MODE= argument, once everyone has transitioned
 231   # to --mode.
 232   legacy_mode_option = SCons.Script.ARGUMENTS.get('MODE')
 233   if legacy_mode_option:
 234     build_modes = legacy_mode_option
 235   build_modes = build_modes.split(',')
 236
 237   # Check build modes
 238   _CheckBuildModes(build_modes, environments, HOST_PLATFORM)
 239
 240   environments_to_evaluate = []
 241   for e in environments:
 242     if not e.Overlap(e['HOST_PLATFORMS'], [HOST_PLATFORM, '*']):
 243       continue      # Environment requires a host platform which isn't us
 244
 245     if e.Overlap([e['BUILD_TYPE'], e['BUILD_GROUPS']], build_modes):
 246       environments_to_evaluate.append(e)
 247
 248   for e in environments_to_evaluate:
 249     # Make this the root environment for deferred functions, so they don't
 250     # execute until our call to ExecuteDefer().
 251     e.SetDeferRoot()
 252
 253     # Defer building the SConscripts, so that other tools can do
 254     # per-environment setup first.
 255     e.Defer(BuildEnvironmentSConscripts)
 256
 257     # Execute deferred functions
 258     e.ExecuteDefer()
 259
 260   # Add help on targets.
 261   AddTargetHelp()
 262
 263   # Return list of environments actually evaluated
 264   return environments_to_evaluate
 265
 266
 267 #------------------------------------------------------------------------------
 268
 269
 270 def _ToolExists():
 271   """Replacement for SCons tool module exists() function, if one isn't present.
 272
 273   Returns:
 274     True.  This enables modules which always exist not to need to include a
 275         dummy exists() function.
 276   """
 277   return True
 278
 279
 280 def _ToolModule(self):
 281   """Thunk for SCons.Tool.Tool._tool_module to patch in exists() function.
 282
 283   Returns:
 284     The module from the original SCons.Tool.Tool._tool_module call, with an
 285         exists() method added if it wasn't present.
 286   """
 287   module = self._tool_module_orig()
 288   if not hasattr(module, 'exists'):
 289     module.exists = _ToolExists
 290
 291   return module
 292
 293 #------------------------------------------------------------------------------
 294
 295
 296 def AddSiteDir(site_dir):
 297   """Adds a site directory, as if passed to the --site-dir option.
 298
 299   Args:
 300     site_dir: Site directory path to add, relative to the location of the
 301         SConstruct file.
 302
 303   This may be called from the SConscript file to add a local site scons
 304   directory for a project.  This does the following:
 305      * Adds site_dir/site_scons to sys.path.
 306      * Imports site_dir/site_init.py.
 307      * Adds site_dir/site_scons to the SCons tools path.
 308   """
 309   # Call the same function that SCons does for the --site-dir option.
 310   SCons.Script.Main._load_site_scons_dir(
 311       SCons.Node.FS.get_default_fs().SConstruct_dir, site_dir)
 312
 313
 314 #------------------------------------------------------------------------------
 315
 316
 317 _new_options_help = '''
 318 Additional options for SCons:
 319
 320   --mode=MODE                 Specify build mode (see below).
 321   --host-platform=PLATFORM    Force SCons to use PLATFORM as the host platform,
 322                               instead of the actual platform on which SCons is
 323                               run.  Useful for examining the dependency tree
 324                               which would be created, but not useful for
 325                               actually running the build because it'll attempt
 326                               to use the wrong tools for your actual platform.
 327   --site-path=DIRLIST         Comma-separated list of additional site
 328                               directory paths; each is processed as if passed
 329                               to --site-dir.
 330 '''
 331
 332 def SiteInitMain():
 333   """Main code executed in site_init."""
 334
 335   # Bail out if we've been here before. This is needed to handle the case where
 336   # this site_init.py has been dropped into a project directory.
 337   if hasattr(__builtin__, 'BuildEnvironments'):
 338     return
 339
 340   # Let people use new global methods directly.
 341   __builtin__.AddSiteDir = AddSiteDir
 342   __builtin__.BuildEnvironments = BuildEnvironments
 343   # Legacy method names
 344   # TODO: Remove these once they're no longer used anywhere.
 345   __builtin__.BuildComponents = BuildEnvironments
 346
 347   # Set list of default tools for component_setup
 348   __builtin__.component_setup_tools = [
 349       # Defer must be first so other tools can register environment
 350       # setup/cleanup functions.
 351       'defer',
 352       # Component_targets must precede component_builders so builders can
 353       # define target groups.
 354       'component_targets',
 355       'command_output',
 356       'component_bits',
 357       'component_builders',
 358       'concat_source',
 359       'environment_tools',
 360       'publish',
 361       'replicate',
 362   ]
 363
 364   # Patch Tool._tool_module method to fill in an exists() method for the
 365   # module if it isn't present.
 366   # TODO: This functionality should be patched into SCons itself by changing
 367   # Tool.__init__().
 368   SCons.Tool.Tool._tool_module_orig = SCons.Tool.Tool._tool_module
 369   SCons.Tool.Tool._tool_module = _ToolModule
 370
 371   # Add our options
 372   SCons.Script.AddOption(
 373       '--mode', '--build-mode',
 374       dest='build_mode',
 375       nargs=1, type='string',
 376       action='store',
 377       metavar='MODE',
 378       default='default',
 379       help='build mode(s)')
 380   SCons.Script.AddOption(
 381       '--host-platform',
 382       dest='host_platform',
 383       nargs=1, type='string',
 384       action='store',
 385       metavar='PLATFORM',
 386       help='build mode(s)')
 387   SCons.Script.AddOption(
 388       '--site-path',
 389       dest='site_path',
 390       nargs=1, type='string',
 391       action='store',
 392       metavar='PATH',
 393       help='comma-separated list of site directories')
 394
 395   SCons.Script.Help(_new_options_help)
 396
 397   # Set current host platform
 398   host_platform = SCons.Script.GetOption('host_platform')
 399   if not host_platform:
 400     host_platform = _HostPlatform()
 401   __builtin__.HOST_PLATFORM = host_platform
 402
 403   # Check for site path.  This is a list of site directories which each are
 404   # processed as if they were passed to --site-dir.
 405   site_path = SCons.Script.GetOption('site_path')
 406   if site_path:
 407     for site_dir in site_path.split(','):
 408       AddSiteDir(site_dir)
 409
 410   # Since our site dir was specified on the SCons command line, SCons will
 411   # normally only look at our site dir.  Add back checking for project-local
 412   # site_scons directories.
 413   if not SCons.Script.GetOption('no_site_dir'):
 414     SCons.Script.Main._load_site_scons_dir(
 415         SCons.Node.FS.get_default_fs().SConstruct_dir, None)
 416
 417 # Run main code
 418 SiteInitMain()