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