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 and override config files; any
 133     # command-line errors are the end user's fault, so turn them into
 134     # SystemExit to suppress tracebacks.
 135     try:
 136         ok = dist.parse_command_line()
 137     except DistutilsArgError, msg:
 138         raise SystemExit, gen_usage(dist.script_name) + "\nerror: %s" % msg
 139
 140     if DEBUG:
 141         print "options (after parsing command line):"
 142         dist.dump_option_dicts()
 143
 144     if _setup_stop_after == "commandline":
 145         return dist
 146
 147     # And finally, run all the commands found on the command line.
 148     if ok:
 149         try:
 150             dist.run_commands()
 151         except KeyboardInterrupt:
 152             raise SystemExit, "interrupted"
 153         except (IOError, os.error), exc:
 154             error = grok_environment_error(exc)
 155
 156             if DEBUG:
 157                 sys.stderr.write(error + "\n")
 158                 raise
 159             else:
 160                 raise SystemExit, error
 161
 162         except (DistutilsError,
 163                 CCompilerError), msg:
 164             if DEBUG:
 165                 raise
 166             else:
 167                 raise SystemExit, "error: " + str(msg)
 168
 169     return dist
 170
 171 # setup ()
 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     #print "_setup_distribution:", _setup_distribution
 239     return _setup_distribution
 240
 241 # run_setup ()