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
|
.. _f2py-bldsys:
=======================
F2PY and build systems
=======================
In this section we will cover the various popular build systems and their usage
with ``f2py``.
.. versionchanged:: NumPy 1.26.x
The default build system for ``f2py`` has traditionally been through the
enhanced ``numpy.distutils`` module. This module is based on ``distutils``
which was removed in ``Python 3.12.0`` in **October 2023**. Like the rest of
NumPy and SciPy, ``f2py`` uses ``meson`` now, see
:ref:`distutils-status-migration` for some more details.
All changes to ``f2py`` are tested on SciPy, so their `CI configuration`_ is
always supported.
.. note::
See :ref:`f2py-meson-distutils` for migration information.
Basic concepts
===============
Building an extension module which includes Python and Fortran consists of:
- Fortran source(s)
- One or more generated files from ``f2py``
+ A ``C`` wrapper file is always created
+ Code with modules require an additional ``.f90`` wrapper
+ Code with functions generate an additional ``.f`` wrapper
- ``fortranobject.{c,h}``
+ Distributed with ``numpy``
+ Can be queried via ``python -c "import numpy.f2py; print(numpy.f2py.get_include())"``
- NumPy headers
+ Can be queried via ``python -c "import numpy; print(numpy.get_include())"``
- Python libraries and development headers
Broadly speaking there are three cases which arise when considering the outputs of ``f2py``:
Fortran 77 programs
- Input file ``blah.f``
- Generates
+ ``blahmodule.c``
+ ``blah-f2pywrappers.f``
When no ``COMMON`` blocks are present only a ``C`` wrapper file is generated.
Wrappers are also generated to rewrite assumed shape arrays as automatic
arrays.
Fortran 90 programs
- Input file ``blah.f90``
- Generates:
+ ``blahmodule.c``
+ ``blah-f2pywrappers.f``
+ ``blah-f2pywrappers2.f90``
The ``f90`` wrapper is used to handle code which is subdivided into
modules. The ``f`` wrapper makes ``subroutines`` for ``functions``. It
rewrites assumed shape arrays as automatic arrays.
Signature files
- Input file ``blah.pyf``
- Generates:
+ ``blahmodule.c``
+ ``blah-f2pywrappers2.f90`` (occasionally)
+ ``blah-f2pywrappers.f`` (occasionally)
Signature files ``.pyf`` do not signal their language standard via the file
extension, they may generate the F90 and F77 specific wrappers depending on
their contents; which shifts the burden of checking for generated files onto
the build system.
.. versionchanged:: NumPy ``1.22.4``
``f2py`` will deterministically generate wrapper files based on the input
file Fortran standard (F77 or greater). ``--skip-empty-wrappers`` can be
passed to ``f2py`` to restore the previous behaviour of only generating
wrappers when needed by the input .
In theory keeping the above requirements in hand, any build system can be
adapted to generate ``f2py`` extension modules. Here we will cover a subset of
the more popular systems.
.. note::
``make`` has no place in a modern multi-language setup, and so is not
discussed further.
Build systems
==============
.. toctree::
:maxdepth: 2
distutils
meson
cmake
skbuild
distutils-to-meson
.. _`issue 20385`: https://github.com/numpy/numpy/issues/20385
.. _`CI configuration`: https://docs.scipy.org/doc/scipy/dev/toolchain.html#official-builds
|