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
218
219
220
221
|
**********************************
Packaging (:mod:`numpy.distutils`)
**********************************
.. module:: numpy.distutils
.. warning::
``numpy.distutils`` is deprecated, and will be removed for
Python >= 3.12. For more details, see :ref:`distutils-status-migration`
.. warning::
Note that ``setuptools`` does major releases often and those may contain
changes that break ``numpy.distutils``, which will *not* be updated anymore
for new ``setuptools`` versions. It is therefore recommended to set an
upper version bound in your build configuration for the last known version
of ``setuptools`` that works with your build.
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`.
The choice and location of linked libraries such as BLAS and LAPACK as well as
include paths and other such build options can be specified in a ``site.cfg``
file located in the NumPy root repository or a ``.numpy-site.cfg`` file in your
home directory. See the ``site.cfg.example`` example file included in the NumPy
repository or sdist for documentation.
.. index::
single: distutils
Modules in :mod:`numpy.distutils`
=================================
.. toctree::
:maxdepth: 2
distutils/misc_util
.. currentmodule:: numpy.distutils
.. autosummary::
:toctree: generated/
ccompiler
ccompiler_opt
cpuinfo.cpu
core.Extension
exec_command
log.set_verbosity
system_info.get_info
system_info.get_standard_file
Configuration class
===================
.. currentmodule:: numpy.distutils.misc_util
.. 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
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::
.. hidden in a comment so as to be included in refguide but not rendered documentation
>>> import numpy.distutils.misc_util
>>> config = np.distutils.misc_util.Configuration(None, '', '.')
>>> with open('foo.c', 'w') as f: pass
>>> 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 = np.distutils.misc_util.get_info('npymath')
>>> config.add_extension('foo', sources=['foo.c'], extra_info=info)
<numpy.distutils.extension.Extension('foo') at 0x...>
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`.
|
