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.
13 from distutils
.debug
import DEBUG
14 from distutils
.errors
import *
15 from distutils
.util
import grok_environment_error
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
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.
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
34 def gen_usage (script_name
):
35 script
= os
.path
.basename(script_name
)
39 # Some mild magic to control the behaviour of 'setup()' from 'run_setup()'.
40 _setup_stop_after
= None
41 _setup_distribution
= None
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',
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')
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
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.
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
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
92 global _setup_stop_after
, _setup_distribution
94 # Determine the distribution class -- either caller-supplied or
95 # our Distribution (see below).
96 klass
= attrs
.get('distclass')
98 del attrs
['distclass']
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:]
107 # Create the Distribution instance, using the remaining arguments
108 # (ie. everything except distclass) to initialize it
110 _setup_distribution
= dist
= klass(attrs
)
111 except DistutilsSetupError
, msg
:
113 raise SystemExit, "error in %s setup command: %s" % \
116 raise SystemExit, "error in setup command: %s" % msg
118 if _setup_stop_after
== "init":
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()
126 print "options (after parsing config files):"
127 dist
.dump_option_dicts()
129 if _setup_stop_after
== "config":
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.
136 ok
= dist
.parse_command_line()
137 except DistutilsArgError
, msg
:
138 raise SystemExit, gen_usage(dist
.script_name
) + "\nerror: %s" % msg
141 print "options (after parsing command line):"
142 dist
.dump_option_dicts()
144 if _setup_stop_after
== "commandline":
147 # And finally, run all the commands found on the command line.
151 except KeyboardInterrupt:
152 raise SystemExit, "interrupted"
153 except (IOError, os
.error
), exc
:
154 error
= grok_environment_error(exc
)
157 sys
.stderr
.write(error
+ "\n")
160 raise SystemExit, error
162 except (DistutilsError
,
163 CCompilerError
), msg
:
167 raise SystemExit, "error: " + str(msg
)
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.
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
187 'stop_after' tells 'setup()' when to stop processing; possible
190 stop after the Distribution instance has been created and
191 populated with the keyword arguments to 'setup()'
193 stop after config files have been parsed (and their data
194 stored in the Distribution instance)
196 stop after the command-line ('sys.argv[1:]' or 'script_args')
197 have been parsed (and the data stored in the Distribution)
199 stop after all commands have been run (the same as if 'setup()'
200 had been called in the usual way
202 Returns the Distribution instance, which provides all information
203 used to drive the Distutils.
205 if stop_after
not in ('init', 'config', 'commandline', 'run'):
206 raise ValueError, "invalid value for 'stop_after': %r" % (stop_after
,)
208 global _setup_stop_after
, _setup_distribution
209 _setup_stop_after
= stop_after
212 g
= {'__file__': script_name
}
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
222 _setup_stop_after
= None
224 # Hmm, should we do something if exiting with a non-zero code
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?") % \
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