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