1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
|
**********************************
Packaging (:mod:`numpy.distutils`)
**********************************
.. module:: numpy.distutils
NumPy provides enhanced distutils functionality to make it easier to
build and install sub-packages, auto-generate code, and extension
modules that use Fortran-compiled libraries. To use features of NumPy
distutils, use the :func:`setup <core.setup>` command from
:mod:`numpy.distutils.core`. A useful :class:`Configuration
<misc_util.Configuration>` class is also provided in
:mod:`numpy.distutils.misc_util` that can make it easier to construct
keyword arguments to pass to the setup function (by passing the
dictionary obtained from the todict() method of the class). More
information is available in the :ref:`distutils-user-guide`.
.. index::
single: distutils
Modules in :mod:`numpy.distutils`
=================================
misc_util
---------
.. module:: numpy.distutils.misc_util
.. autosummary::
:toctree: generated/
get_numpy_include_dirs
dict_append
appendpath
allpath
dot_join
generate_config_py
get_cmd
terminal_has_colors
red_text
green_text
yellow_text
blue_text
cyan_text
cyg2win32
all_strings
has_f_sources
has_cxx_sources
filter_sources
get_dependencies
is_local_src_dir
get_ext_source_files
get_script_files
.. class:: Configuration(package_name=None, parent_name=None, top_path=None, package_path=None, **attrs)
Construct a configuration instance for the given package name. If
*parent_name* is not None, then construct the package as a
sub-package of the *parent_name* package. If *top_path* and
*package_path* are None then they are assumed equal to
the path of the file this instance was created in. The setup.py
files in the numpy distribution are good examples of how to use
the :class:`Configuration` instance.
.. automethod:: todict
.. automethod:: get_distribution
.. automethod:: get_subpackage
.. automethod:: add_subpackage
.. automethod:: add_data_files
.. automethod:: add_data_dir
.. automethod:: add_include_dirs
.. automethod:: add_headers
.. automethod:: add_extension
.. automethod:: add_library
.. automethod:: add_scripts
.. automethod:: add_installed_library
.. automethod:: add_npy_pkg_config
.. automethod:: paths
.. automethod:: get_config_cmd
.. automethod:: get_build_temp_dir
.. automethod:: have_f77c
.. automethod:: have_f90c
.. automethod:: get_version
.. automethod:: make_svn_version_py
.. automethod:: make_config_py
.. automethod:: get_info
Other modules
-------------
.. currentmodule:: numpy.distutils
.. autosummary::
:toctree: generated/
system_info.get_info
system_info.get_standard_file
cpuinfo.cpu
log.set_verbosity
exec_command
Building Installable C libraries
================================
Conventional C libraries (installed through `add_library`) are not installed, and
are just used during the build (they are statically linked). An installable C
library is a pure C library, which does not depend on the python C runtime, and
is installed such that it may be used by third-party packages. To build and
install the C library, you just use the method `add_installed_library` instead of
`add_library`, which takes the same arguments except for an additional
``install_dir`` argument::
>>> config.add_installed_library('foo', sources=['foo.c'], install_dir='lib')
npy-pkg-config files
--------------------
To make the necessary build options available to third parties, you could use
the `npy-pkg-config` mechanism implemented in `numpy.distutils`. This mechanism is
based on a .ini file which contains all the options. A .ini file is very
similar to .pc files as used by the pkg-config unix utility::
[meta]
Name: foo
Version: 1.0
Description: foo library
[variables]
prefix = /home/user/local
libdir = ${prefix}/lib
includedir = ${prefix}/include
[default]
cflags = -I${includedir}
libs = -L${libdir} -lfoo
Generally, the file needs to be generated during the build, since it needs some
information known at build time only (e.g. prefix). This is mostly automatic if
one uses the `Configuration` method `add_npy_pkg_config`. Assuming we have a
template file foo.ini.in as follows::
[meta]
Name: foo
Version: @version@
Description: foo library
[variables]
prefix = @prefix@
libdir = ${prefix}/lib
includedir = ${prefix}/include
[default]
cflags = -I${includedir}
libs = -L${libdir} -lfoo
and the following code in setup.py::
>>> config.add_installed_library('foo', sources=['foo.c'], install_dir='lib')
>>> subst = {'version': '1.0'}
>>> config.add_npy_pkg_config('foo.ini.in', 'lib', subst_dict=subst)
This will install the file foo.ini into the directory package_dir/lib, and the
foo.ini file will be generated from foo.ini.in, where each ``@version@`` will be
replaced by ``subst_dict['version']``. The dictionary has an additional prefix
substitution rule automatically added, which contains the install prefix (since
this is not easy to get from setup.py). npy-pkg-config files can also be
installed at the same location as used for numpy, using the path returned from
`get_npy_pkg_dir` function.
Reusing a C library from another package
----------------------------------------
Info are easily retrieved from the `get_info` function in
`numpy.distutils.misc_util`::
>>> info = get_info('npymath')
>>> config.add_extension('foo', sources=['foo.c'], extra_info=**info)
An additional list of paths to look for .ini files can be given to `get_info`.
Conversion of ``.src`` files
============================
NumPy distutils supports automatic conversion of source files named
<somefile>.src. This facility can be used to maintain very similar
code blocks requiring only simple changes between blocks. During the
build phase of setup, if a template file named <somefile>.src is
encountered, a new file named <somefile> is constructed from the
template and placed in the build directory to be used instead. Two
forms of template conversion are supported. The first form occurs for
files named <file>.ext.src where ext is a recognized Fortran
extension (f, f90, f95, f77, for, ftn, pyf). The second form is used
for all other cases. See :ref:`templating`.
|
