Python code coverage for Lib/distutils/extension.py

#	count	content
1	n/a	"""distutils.extension
2	n/a
3	n/a	Provides the Extension class, used to describe C/C++ extension
4	n/a	modules in setup scripts."""
5	n/a
6	n/a	import os
7	n/a	import warnings
8	n/a
9	n/a	# This class is really only used by the "build_ext" command, so it might
10	n/a	# make sense to put it in distutils.command.build_ext. However, that
11	n/a	# module is already big enough, and I want to make this class a bit more
12	n/a	# complex to simplify some common cases ("foo" module in "foo.c") and do
13	n/a	# better error-checking ("foo.c" actually exists).
14	n/a	#
15	n/a	# Also, putting this in build_ext.py means every setup script would have to
16	n/a	# import that large-ish module (indirectly, through distutils.core) in
17	n/a	# order to do anything.
18	n/a
19	n/a	class Extension:
20	n/a	"""Just a collection of attributes that describes an extension
21	n/a	module and everything needed to build it (hopefully in a portable
22	n/a	way, but there are hooks that let you be as unportable as you need).
23	n/a
24	n/a	Instance attributes:
25	n/a	name : string
26	n/a	the full name of the extension, including any packages -- ie.
27	n/a	not a filename or pathname, but Python dotted name
28	n/a	sources : [string]
29	n/a	list of source filenames, relative to the distribution root
30	n/a	(where the setup script lives), in Unix form (slash-separated)
31	n/a	for portability. Source files may be C, C++, SWIG (.i),
32	n/a	platform-specific resource files, or whatever else is recognized
33	n/a	by the "build_ext" command as source for a Python extension.
34	n/a	include_dirs : [string]
35	n/a	list of directories to search for C/C++ header files (in Unix
36	n/a	form for portability)
37	n/a	define_macros : [(name : string, value : string\|None)]
38	n/a	list of macros to define; each macro is defined using a 2-tuple,
39	n/a	where 'value' is either the string to define it to or None to
40	n/a	define it without a particular value (equivalent of "#define
41	n/a	FOO" in source or -DFOO on Unix C compiler command line)
42	n/a	undef_macros : [string]
43	n/a	list of macros to undefine explicitly
44	n/a	library_dirs : [string]
45	n/a	list of directories to search for C/C++ libraries at link time
46	n/a	libraries : [string]
47	n/a	list of library names (not filenames or paths) to link against
48	n/a	runtime_library_dirs : [string]
49	n/a	list of directories to search for C/C++ libraries at run time
50	n/a	(for shared extensions, this is when the extension is loaded)
51	n/a	extra_objects : [string]
52	n/a	list of extra files to link with (eg. object files not implied
53	n/a	by 'sources', static library that must be explicitly specified,
54	n/a	binary resource files, etc.)
55	n/a	extra_compile_args : [string]
56	n/a	any extra platform- and compiler-specific information to use
57	n/a	when compiling the source files in 'sources'. For platforms and
58	n/a	compilers where "command line" makes sense, this is typically a
59	n/a	list of command-line arguments, but for other platforms it could
60	n/a	be anything.
61	n/a	extra_link_args : [string]
62	n/a	any extra platform- and compiler-specific information to use
63	n/a	when linking object files together to create the extension (or
64	n/a	to create a new static Python interpreter). Similar
65	n/a	interpretation as for 'extra_compile_args'.
66	n/a	export_symbols : [string]
67	n/a	list of symbols to be exported from a shared extension. Not
68	n/a	used on all platforms, and not generally necessary for Python
69	n/a	extensions, which typically export exactly one symbol: "init" +
70	n/a	extension_name.
71	n/a	swig_opts : [string]
72	n/a	any extra options to pass to SWIG if a source file has the .i
73	n/a	extension.
74	n/a	depends : [string]
75	n/a	list of files that the extension depends on
76	n/a	language : string
77	n/a	extension language (i.e. "c", "c++", "objc"). Will be detected
78	n/a	from the source extensions if not provided.
79	n/a	optional : boolean
80	n/a	specifies that a build failure in the extension should not abort the
81	n/a	build process, but simply not install the failing extension.
82	n/a	"""
83	n/a
84	n/a	# When adding arguments to this constructor, be sure to update
85	n/a	# setup_keywords in core.py.
86	n/a	def __init__(self, name, sources,
87	n/a	include_dirs=None,
88	n/a	define_macros=None,
89	n/a	undef_macros=None,
90	n/a	library_dirs=None,
91	n/a	libraries=None,
92	n/a	runtime_library_dirs=None,
93	n/a	extra_objects=None,
94	n/a	extra_compile_args=None,
95	n/a	extra_link_args=None,
96	n/a	export_symbols=None,
97	n/a	swig_opts = None,
98	n/a	depends=None,
99	n/a	language=None,
100	n/a	optional=None,
101	n/a	**kw # To catch unknown keywords
102	n/a	):
103	n/a	if not isinstance(name, str):
104	n/a	raise AssertionError("'name' must be a string")
105	n/a	if not (isinstance(sources, list) and
106	n/a	all(isinstance(v, str) for v in sources)):
107	n/a	raise AssertionError("'sources' must be a list of strings")
108	n/a
109	n/a	self.name = name
110	n/a	self.sources = sources
111	n/a	self.include_dirs = include_dirs or []
112	n/a	self.define_macros = define_macros or []
113	n/a	self.undef_macros = undef_macros or []
114	n/a	self.library_dirs = library_dirs or []
115	n/a	self.libraries = libraries or []
116	n/a	self.runtime_library_dirs = runtime_library_dirs or []
117	n/a	self.extra_objects = extra_objects or []
118	n/a	self.extra_compile_args = extra_compile_args or []
119	n/a	self.extra_link_args = extra_link_args or []
120	n/a	self.export_symbols = export_symbols or []
121	n/a	self.swig_opts = swig_opts or []
122	n/a	self.depends = depends or []
123	n/a	self.language = language
124	n/a	self.optional = optional
125	n/a
126	n/a	# If there are unknown keyword options, warn about them
127	n/a	if len(kw) > 0:
128	n/a	options = [repr(option) for option in kw]
129	n/a	options = ', '.join(sorted(options))
130	n/a	msg = "Unknown Extension options: %s" % options
131	n/a	warnings.warn(msg)
132	n/a
133	n/a	def __repr__(self):
134	n/a	return '<%s.%s(%r) at %#x>' % (
135	n/a	self.__class__.__module__,
136	n/a	self.__class__.__qualname__,
137	n/a	self.name,
138	n/a	id(self))
139	n/a
140	n/a
141	n/a	def read_setup_file(filename):
142	n/a	"""Reads a Setup file and returns Extension instances."""
143	n/a	from distutils.sysconfig import (parse_makefile, expand_makefile_vars,
144	n/a	_variable_rx)
145	n/a
146	n/a	from distutils.text_file import TextFile
147	n/a	from distutils.util import split_quoted
148	n/a
149	n/a	# First pass over the file to gather "VAR = VALUE" assignments.
150	n/a	vars = parse_makefile(filename)
151	n/a
152	n/a	# Second pass to gobble up the real content: lines of the form
153	n/a	# <module> ... [<sourcefile> ...] [<cpparg> ...] [<library> ...]
154	n/a	file = TextFile(filename,
155	n/a	strip_comments=1, skip_blanks=1, join_lines=1,
156	n/a	lstrip_ws=1, rstrip_ws=1)
157	n/a	try:
158	n/a	extensions = []
159	n/a
160	n/a	while True:
161	n/a	line = file.readline()
162	n/a	if line is None: # eof
163	n/a	break
164	n/a	if _variable_rx.match(line): # VAR=VALUE, handled in first pass
165	n/a	continue
166	n/a
167	n/a	if line[0] == line[-1] == "*":
168	n/a	file.warn("'%s' lines not handled yet" % line)
169	n/a	continue
170	n/a
171	n/a	line = expand_makefile_vars(line, vars)
172	n/a	words = split_quoted(line)
173	n/a
174	n/a	# NB. this parses a slightly different syntax than the old
175	n/a	# makesetup script: here, there must be exactly one extension per
176	n/a	# line, and it must be the first word of the line. I have no idea
177	n/a	# why the old syntax supported multiple extensions per line, as
178	n/a	# they all wind up being the same.
179	n/a
180	n/a	module = words[0]
181	n/a	ext = Extension(module, [])
182	n/a	append_next_word = None
183	n/a
184	n/a	for word in words[1:]:
185	n/a	if append_next_word is not None:
186	n/a	append_next_word.append(word)
187	n/a	append_next_word = None
188	n/a	continue
189	n/a
190	n/a	suffix = os.path.splitext(word)[1]
191	n/a	switch = word[0:2] ; value = word[2:]
192	n/a
193	n/a	if suffix in (".c", ".cc", ".cpp", ".cxx", ".c++", ".m", ".mm"):
194	n/a	# hmm, should we do something about C vs. C++ sources?
195	n/a	# or leave it up to the CCompiler implementation to
196	n/a	# worry about?
197	n/a	ext.sources.append(word)
198	n/a	elif switch == "-I":
199	n/a	ext.include_dirs.append(value)
200	n/a	elif switch == "-D":
201	n/a	equals = value.find("=")
202	n/a	if equals == -1: # bare "-DFOO" -- no value
203	n/a	ext.define_macros.append((value, None))
204	n/a	else: # "-DFOO=blah"
205	n/a	ext.define_macros.append((value[0:equals],
206	n/a	value[equals+2:]))
207	n/a	elif switch == "-U":
208	n/a	ext.undef_macros.append(value)
209	n/a	elif switch == "-C": # only here 'cause makesetup has it!
210	n/a	ext.extra_compile_args.append(word)
211	n/a	elif switch == "-l":
212	n/a	ext.libraries.append(value)
213	n/a	elif switch == "-L":
214	n/a	ext.library_dirs.append(value)
215	n/a	elif switch == "-R":
216	n/a	ext.runtime_library_dirs.append(value)
217	n/a	elif word == "-rpath":
218	n/a	append_next_word = ext.runtime_library_dirs
219	n/a	elif word == "-Xlinker":
220	n/a	append_next_word = ext.extra_link_args
221	n/a	elif word == "-Xcompiler":
222	n/a	append_next_word = ext.extra_compile_args
223	n/a	elif switch == "-u":
224	n/a	ext.extra_link_args.append(word)
225	n/a	if not value:
226	n/a	append_next_word = ext.extra_link_args
227	n/a	elif suffix in (".a", ".so", ".sl", ".o", ".dylib"):
228	n/a	# NB. a really faithful emulation of makesetup would
229	n/a	# append a .o file to extra_objects only if it
230	n/a	# had a slash in it; otherwise, it would s/.o/.c/
231	n/a	# and append it to sources. Hmmmm.
232	n/a	ext.extra_objects.append(word)
233	n/a	else:
234	n/a	file.warn("unrecognized argument '%s'" % word)
235	n/a
236	n/a	extensions.append(ext)
237	n/a	finally:
238	n/a	file.close()
239	n/a
240	n/a	return extensions