Lib/distutils/core.py

   1 """distutils.core
   2
   3 The only module that needs to be imported to use the Distutils; provides
   4 the 'setup' function (which is to be called from the setup script).  Also
   5 indirectly provides the Distribution and Command classes, although they are
   6 really defined in distutils.dist and distutils.cmd.
   7 """
   8
   9 __revision__ = "$Id$"
  10
  11 import sys
  12 import os
  13
  14 from distutils.debug import DEBUG
  15 from distutils.errors import (DistutilsSetupError, DistutilsArgError,
  16                               DistutilsError, CCompilerError)
  17 from distutils.util import grok_environment_error
  18
  19 # Mainly import these so setup scripts can "from distutils.core import" them.
  20 from distutils.dist import Distribution
  21 from distutils.cmd import Command
  22 from distutils.config import PyPIRCCommand
  23 from distutils.extension import Extension
  24
  25 # This is a barebones help message generated displayed when the user
  26 # runs the setup script with no arguments at all.  More useful help
  27 # is generated with various --help options: global help, list commands,
  28 # and per-command help.
  29 USAGE = """\
  30 usage: %(script)s [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...]
  31    or: %(script)s --help [cmd1 cmd2 ...]
  32    or: %(script)s --help-commands
  33    or: %(script)s cmd --help
  34 """
  35
  36 def gen_usage(script_name):
  37     script = os.path.basename(script_name)
  38     return USAGE % {'script': script}
  39
  40
  41 # Some mild magic to control the behaviour of 'setup()' from 'run_setup()'.
  42 _setup_stop_after = None
  43 _setup_distribution = None
  44
  45 # Legal keyword arguments for the setup() function
  46 setup_keywords = ('distclass', 'script_name', 'script_args', 'options',
  47                   'name', 'version', 'author', 'author_email',
  48                   'maintainer', 'maintainer_email', 'url', 'license',
  49                   'description', 'long_description', 'keywords',
  50                   'platforms', 'classifiers', 'download_url',
  51                   'requires', 'provides', 'obsoletes',
  52                   )
  53
  54 # Legal keyword arguments for the Extension constructor
  55 extension_keywords = ('name', 'sources', 'include_dirs',
  56                       'define_macros', 'undef_macros',
  57                       'library_dirs', 'libraries', 'runtime_library_dirs',
  58                       'extra_objects', 'extra_compile_args', 'extra_link_args',
  59                       'swig_opts', 'export_symbols', 'depends', 'language')
  60
  61 def setup(**attrs):
  62     """The gateway to the Distutils: do everything your setup script needs
  63     to do, in a highly flexible and user-driven way.  Briefly: create a
  64     Distribution instance; find and parse config files; parse the command
  65     line; run each Distutils command found there, customized by the options
  66     supplied to 'setup()' (as keyword arguments), in config files, and on
  67     the command line.
  68
  69     The Distribution instance might be an instance of a class supplied via
  70     the 'distclass' keyword argument to 'setup'; if no such class is
  71     supplied, then the Distribution class (in dist.py) is instantiated.
  72     All other arguments to 'setup' (except for 'cmdclass') are used to set
  73     attributes of the Distribution instance.
  74
  75     The 'cmdclass' argument, if supplied, is a dictionary mapping command
  76     names to command classes.  Each command encountered on the command line
  77     will be turned into a command class, which is in turn instantiated; any
  78     class found in 'cmdclass' is used in place of the default, which is
  79     (for command 'foo_bar') class 'foo_bar' in module
  80     'distutils.command.foo_bar'.  The command class must provide a
  81     'user_options' attribute which is a list of option specifiers for
  82     'distutils.fancy_getopt'.  Any command-line options between the current
  83     and the next command are used to set attributes of the current command
  84     object.
  85
  86     When the entire command-line has been successfully parsed, calls the
  87     'run()' method on each command object in turn.  This method will be
  88     driven entirely by the Distribution object (which each command object
  89     has a reference to, thanks to its constructor), and the
  90     command-specific options that became attributes of each command
  91     object.
  92     """
  93
  94     global _setup_stop_after, _setup_distribution
  95
  96     # Determine the distribution class -- either caller-supplied or
  97     # our Distribution (see below).
  98     klass = attrs.get('distclass')
  99     if klass:
 100         del attrs['distclass']
 101     else:
 102         klass = Distribution
 103
 104     if 'script_name' not in attrs:
 105         attrs['script_name'] = os.path.basename(sys.argv[0])
 106     if 'script_args' not in attrs:
 107         attrs['script_args'] = sys.argv[1:]
 108
 109     # Create the Distribution instance, using the remaining arguments
 110     # (ie. everything except distclass) to initialize it
 111     try:
 112         _setup_distribution = dist = klass(attrs)
 113     except DistutilsSetupError, msg:
 114         if 'name' in attrs:
 115             raise SystemExit, "error in %s setup command: %s" % \
 116                   (attrs['name'], msg)
 117         else:
 118             raise SystemExit, "error in setup command: %s" % msg
 119
 120     if _setup_stop_after == "init":
 121         return dist
 122
 123     # Find and parse the config file(s): they will override options from
 124     # the setup script, but be overridden by the command line.
 125     dist.parse_config_files()
 126
 127     if DEBUG:
 128         print "options (after parsing config files):"
 129         dist.dump_option_dicts()
 130
 131     if _setup_stop_after == "config":
 132         return dist
 133
 134     # Parse the command line and override config files; any
 135     # command-line errors are the end user's fault, so turn them into
 136     # SystemExit to suppress tracebacks.
 137     try:
 138         ok = dist.parse_command_line()
 139     except DistutilsArgError, msg:
 140         raise SystemExit, gen_usage(dist.script_name) + "\nerror: %s" % msg
 141
 142     if DEBUG:
 143         print "options (after parsing command line):"
 144         dist.dump_option_dicts()
 145
 146     if _setup_stop_after == "commandline":
 147         return dist
 148
 149     # And finally, run all the commands found on the command line.
 150     if ok:
 151         try:
 152             dist.run_commands()
 153         except KeyboardInterrupt:
 154             raise SystemExit, "interrupted"
 155         except (IOError, os.error), exc:
 156             error = grok_environment_error(exc)
 157
 158             if DEBUG:
 159                 sys.stderr.write(error + "\n")
 160                 raise
 161             else:
 162                 raise SystemExit, error
 163
 164         except (DistutilsError,
 165                 CCompilerError), msg:
 166             if DEBUG:
 167                 raise
 168             else:
 169                 raise SystemExit, "error: " + str(msg)
 170
 171     return dist
 172
 173
 174 def run_setup(script_name, script_args=None, stop_after="run"):
 175     """Run a setup script in a somewhat controlled environment, and
 176     return the Distribution instance that drives things.  This is useful
 177     if you need to find out the distribution meta-data (passed as
 178     keyword args from 'script' to 'setup()', or the contents of the
 179     config files or command-line.
 180
 181     'script_name' is a file that will be run with 'execfile()';
 182     'sys.argv[0]' will be replaced with 'script' for the duration of the
 183     call.  'script_args' is a list of strings; if supplied,
 184     'sys.argv[1:]' will be replaced by 'script_args' for the duration of
 185     the call.
 186
 187     'stop_after' tells 'setup()' when to stop processing; possible
 188     values:
 189       init
 190         stop after the Distribution instance has been created and
 191         populated with the keyword arguments to 'setup()'
 192       config
 193         stop after config files have been parsed (and their data
 194         stored in the Distribution instance)
 195       commandline
 196         stop after the command-line ('sys.argv[1:]' or 'script_args')
 197         have been parsed (and the data stored in the Distribution)
 198       run [default]
 199         stop after all commands have been run (the same as if 'setup()'
 200         had been called in the usual way
 201
 202     Returns the Distribution instance, which provides all information
 203     used to drive the Distutils.
 204     """
 205     if stop_after not in ('init', 'config', 'commandline', 'run'):
 206         raise ValueError, "invalid value for 'stop_after': %r" % (stop_after,)
 207
 208     global _setup_stop_after, _setup_distribution
 209     _setup_stop_after = stop_after
 210
 211     save_argv = sys.argv
 212     g = {'__file__': script_name}
 213     l = {}
 214     try:
 215         try:
 216             sys.argv[0] = script_name
 217             if script_args is not None:
 218                 sys.argv[1:] = script_args
 219             exec open(script_name, 'r').read() in g, l
 220         finally:
 221             sys.argv = save_argv
 222             _setup_stop_after = None
 223     except SystemExit:
 224         # Hmm, should we do something if exiting with a non-zero code
 225         # (ie. error)?
 226         pass
 227     except:
 228         raise
 229
 230     if _setup_distribution is None:
 231         raise RuntimeError, \
 232               ("'distutils.core.setup()' was never called -- "
 233                "perhaps '%s' is not a Distutils setup script?") % \
 234               script_name
 235
 236     # I wonder if the setup script's namespace -- g and l -- would be of
 237     # any interest to callers?
 238     return _setup_distribution