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