SCons/Errors.py

   1 # MIT License
   2 #
   3 # Copyright The SCons Foundation
   4 #
   5 # Permission is hereby granted, free of charge, to any person obtaining
   6 # a copy of this software and associated documentation files (the
   7 # "Software"), to deal in the Software without restriction, including
   8 # without limitation the rights to use, copy, modify, merge, publish,
   9 # distribute, sublicense, and/or sell copies of the Software, and to
  10 # permit persons to whom the Software is furnished to do so, subject to
  11 # the following conditions:
  12 #
  13 # The above copyright notice and this permission notice shall be included
  14 # in all copies or substantial portions of the Software.
  15 #
  16 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
  17 # KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  18 # WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  19 # NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  20 # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  21 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  22 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  23
  24 """SCons exception classes.
  25
  26 Used to handle internal and user errors in SCons.
  27 """
  28
  29 import shutil
  30 from typing import Optional
  31
  32 from SCons.Util.sctypes import to_String, is_String
  33 from SCons.Util.sctyping import ExecutorType
  34
  35 # Note that not all Errors are defined here, some are at the point of use
  36
  37
  38 class BuildError(Exception):
  39     """SCons Errors that can occur while building.
  40
  41     A :class:`BuildError` exception contains information both
  42     about the erorr itself, and what caused the error.
  43
  44     Attributes:
  45        node: (*cause*) the error occurred while building this target node(s)
  46        errstr: (*info*) a description of the error message
  47        status: (*info*) the return code of the action that caused the build error.
  48           Must be set to a non-zero value even if the build error is not due
  49           to an action returning a non-zero returned code.
  50        exitstatus: (*info*) SCons exit status due to this build error.
  51           Must be nonzero unless due to an explicit :meth:`Exit` call.
  52           Not always the same as ``status``, since actions return a status
  53           code that should be respected, but SCons typically exits with 2
  54           irrespective of the return value of the failed action.
  55        filename: (*info*) The name of the file or directory that caused the
  56           build error. Set to ``None`` if no files are associated with
  57           this error. This might be different from the target
  58           being built. For example, failure to create the
  59           directory in which the target file will appear. It
  60           can be ``None`` if the error is not due to a particular
  61           filename.
  62        executor: (*cause*) the executor that caused the build to fail (might
  63           be ``None`` if the build failures is not due to the executor failing)
  64        action: (*cause*) the action that caused the build to fail (might be
  65           ``None`` if the build failures is not due to the an
  66           action failure)
  67        command: (*cause*) the command line for the action that caused the
  68           build to fail (might be ``None`` if the build failures
  69           is not due to the an action failure)
  70        exc_info: (*info*) Info about exception that caused the build
  71           error. Set to ``(None, None, None)`` if this build
  72           error is not due to an exception.
  73
  74     """
  75
  76     def __init__(self,
  77                  node=None, errstr: str="Unknown error", status: int=2, exitstatus: int=2,
  78                  filename=None, executor: Optional[ExecutorType] = None, action=None, command=None,
  79                  exc_info=(None, None, None)) -> None:
  80
  81         # py3: errstr should be string and not bytes.
  82
  83         self.errstr = to_String(errstr)
  84         self.status = status
  85         self.exitstatus = exitstatus
  86         self.filename = filename
  87         self.exc_info = exc_info
  88
  89         self.node = node
  90         self.executor = executor
  91         self.action = action
  92         self.command = command
  93
  94         super().__init__(node, errstr, status, exitstatus, filename,
  95                          executor, action, command, exc_info)
  96
  97     def __str__(self) -> str:
  98         if self.filename:
  99             return self.filename + ': ' + self.errstr
 100         else:
 101             return self.errstr
 102
 103 class InternalError(Exception):
 104     pass
 105
 106 class UserError(Exception):
 107     pass
 108
 109 class StopError(Exception):
 110     pass
 111
 112 class SConsEnvironmentError(Exception):
 113     pass
 114
 115 class MSVCError(IOError):
 116     pass
 117
 118 class ExplicitExit(Exception):
 119     def __init__(self, node=None, status=None, *args) -> None:
 120         self.node = node
 121         self.status = status
 122         self.exitstatus = status
 123         super().__init__(*args)
 124
 125 def convert_to_BuildError(status, exc_info=None):
 126     """Convert a return code to a BuildError Exception.
 127
 128     The `buildError.status` we set here will normally be
 129     used as the exit status of the "scons" process.
 130
 131     Args:
 132       status: can either be a return code or an Exception.
 133       exc_info (tuple, optional): explicit exception information.
 134
 135     """
 136
 137     if not exc_info and isinstance(status, Exception):
 138         exc_info = (status.__class__, status, None)
 139
 140
 141     if isinstance(status, BuildError):
 142         buildError = status
 143         buildError.exitstatus = 2   # always exit with 2 on build errors
 144     elif isinstance(status, ExplicitExit):
 145         status = status.status
 146         errstr = 'Explicit exit, status %s' % status
 147         buildError = BuildError(
 148             errstr=errstr,
 149             status=status,      # might be 0, OK here
 150             exitstatus=status,      # might be 0, OK here
 151             exc_info=exc_info)
 152     elif isinstance(status, (StopError, UserError)):
 153         buildError = BuildError(
 154             errstr=str(status),
 155             status=2,
 156             exitstatus=2,
 157             exc_info=exc_info)
 158     elif isinstance(status, shutil.SameFileError):
 159         # PY3 has a exception for when copying file to itself
 160         # It's object provides info differently than below
 161         try:
 162             filename = status.filename
 163         except AttributeError:
 164             filename = None
 165
 166         buildError = BuildError(
 167             errstr=status.args[0],
 168             status=status.errno,
 169             exitstatus=2,
 170             filename=filename,
 171             exc_info=exc_info)
 172
 173     elif isinstance(status, (SConsEnvironmentError, OSError, IOError)):
 174         # If an IOError/OSError happens, raise a BuildError.
 175         # Report the name of the file or directory that caused the
 176         # error, which might be different from the target being built
 177         # (for example, failure to create the directory in which the
 178         # target file will appear).
 179         filename = getattr(status, 'filename', None)
 180         strerror = getattr(status, 'strerror', None)
 181         if strerror is None:
 182             strerror = str(status)
 183         errno = getattr(status, 'errno', None)
 184         if errno is None:
 185             errno = 2
 186
 187         buildError = BuildError(
 188             errstr=strerror,
 189             status=errno,
 190             exitstatus=2,
 191             filename=filename,
 192             exc_info=exc_info)
 193     elif isinstance(status, Exception):
 194         buildError = BuildError(
 195             errstr='%s : %s' % (status.__class__.__name__, status),
 196             status=2,
 197             exitstatus=2,
 198             exc_info=exc_info)
 199     elif is_String(status):
 200         buildError = BuildError(
 201             errstr=status,
 202             status=2,
 203             exitstatus=2)
 204     else:
 205         buildError = BuildError(
 206             errstr="Error %s" % status,
 207             status=status,
 208             exitstatus=2)
 209
 210     #import sys
 211     #sys.stderr.write("convert_to_BuildError: status %s => (errstr %s, status %s)\n"%(status,buildError.errstr, buildError.status))
 212     return buildError
 213
 214 # Local Variables:
 215 # tab-width:4
 216 # indent-tabs-mode:nil
 217 # End:
 218 # vim: set expandtab tabstop=4 shiftwidth=4: