1"""distutils.core
2
3The only module that needs to be imported to use the Distutils; provides
4the 'setup' function (which is to be called from the setup script).  Also
5indirectly provides the Distribution and Command classes, although they are
6really defined in distutils.dist and distutils.cmd.
7"""
8
9__revision__ = "$Id$"
10
11import sys
12import os
13
14from distutils.debug import DEBUG
15from distutils.errors import (DistutilsSetupError, DistutilsArgError,
16                              DistutilsError, CCompilerError)
17from distutils.util import grok_environment_error
18
19# Mainly import these so setup scripts can "from distutils.core import" them.
20from distutils.dist import Distribution
21from distutils.cmd import Command
22from distutils.config import PyPIRCCommand
23from 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.
29USAGE = """\
30usage: %(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
36def 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
46setup_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
55extension_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
61def 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
174def 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            f = open(script_name)
220            try:
221                exec f.read() in g, l
222            finally:
223                f.close()
224        finally:
225            sys.argv = save_argv
226            _setup_stop_after = None
227    except SystemExit:
228        # Hmm, should we do something if exiting with a non-zero code
229        # (ie. error)?
230        pass
231    except:
232        raise
233
234    if _setup_distribution is None:
235        raise RuntimeError, \
236              ("'distutils.core.setup()' was never called -- "
237               "perhaps '%s' is not a Distutils setup script?") % \
238              script_name
239
240    # I wonder if the setup script's namespace -- g and l -- would be of
241    # any interest to callers?
242    return _setup_distribution
243