Merge pull request numpy#30968 from HaoZeke/doc/f2py-distribution-guide

DOC: Add f2py distribution guide for meson-python

Author: mattip

doc/source/conf.py

@@ -423,7 +423,7 @@ def setup(app):
     'matplotlib': ('https://matplotlib.org/stable', None),
     'imageio': ('https://imageio.readthedocs.io/en/stable', None),
     'skimage': ('https://scikit-image.org/docs/stable', None),
-    'pandas': ('https://pandas.pydata.org/pandas-docs/stable', None),
+    'pandas': ('https://pandas.pydata.org/docs', None),
     'scipy-lecture-notes': ('https://scipy-lectures.org', None),
     'pytest': ('https://docs.pytest.org/en/stable', None),
     'numpy-tutorials': ('https://numpy.org/numpy-tutorials', None),

doc/source/f2py/buildtools/index.rst

@@ -108,6 +108,7 @@ Build systems
    :maxdepth: 2
 
    meson
+   meson-python
    cmake
    skbuild
    distutils-to-meson

doc/source/f2py/buildtools/meson-python.rst

@@ -0,0 +1,208 @@
+.. _f2py-meson-python:
+
+=====================================================
+Distributing F2PY extensions with ``meson-python``
+=====================================================
+
+The :ref:`f2py-meson` page covers building F2PY extensions using raw ``meson``
+commands. This page shows how to package those extensions into installable
+Python distributions (sdists and wheels) using `meson-python
+<https://meson-python.readthedocs.io/>`_ as the PEP 517 build backend.
+
+This is the recommended approach for distributing F2PY-wrapped Fortran code as a
+Python package on PyPI or for local ``pip install`` workflows.
+
+.. note::
+
+   ``meson-python`` replaced ``setuptools`` / ``numpy.distutils`` as the
+   standard way to build and distribute compiled extensions in the NumPy and
+   SciPy ecosystem. See :ref:`distutils-status-migration` for background.
+
+Prerequisites
+=============
+
+You need:
+
+* A C compiler
+* A Fortran compiler (``gfortran``, ``ifort``, ``ifx``, ``flang-new``, etc.),
+  if you use any Fortran code in your package
+* Python >= 3.10
+* ``meson``, ``meson-python``, and ``numpy`` (installed automatically during the
+  build when listed in ``build-system.requires``)
+
+Minimal example
+===============
+
+The project below wraps a Fortran ``fib`` subroutine into an importable Python
+package called ``fib_wrapper``.
+
+Project layout::
+
+    fib_wrapper/           # project root
+    ├── fib.f90            # Fortran source
+    ├── fib_wrapper/       # Python package directory
+    │   └── __init__.py
+    ├── meson.build
+    └── pyproject.toml
+
+Fortran source
+--------------
+
+Save the following as ``fib.f90``:
+
+.. literalinclude:: ../code/fib_mesonpy.f90
+   :language: fortran
+
+``pyproject.toml``
+------------------
+
+.. literalinclude:: ../code/pyproj_mesonpy.toml
+   :language: toml
+
+Two entries matter here:
+
+* ``build-backend = "mesonpy"`` tells build frontends to use ``meson-python``.
+* ``requires`` lists build-time dependencies. ``numpy >= 2.0`` is required so
+  that ``f2py``, the NumPy headers, and ``dependency('numpy')`` support in Meson
+  are available during compilation.
+
+``meson.build``
+---------------
+
+.. literalinclude:: ../code/meson_mesonpy.build
+
+.. note::
+
+   The file is stored as ``meson_mesonpy.build`` in the documentation source
+   tree to avoid collisions with other examples. In your project, name it
+   ``meson.build``.
+
+The ``meson.build`` file does four things:
+
+1. Uses ``dependency('numpy')`` to locate NumPy headers, and a
+   ``declare_dependency`` to add the F2PY include directory (for
+   ``fortranobject.h``).
+2. Runs ``f2py`` via ``custom_target`` to generate the C wrapper sources.
+3. Compiles the generated C code together with the Fortran source into a Python
+   extension module using ``py.extension_module``.
+4. Installs ``__init__.py`` into the package directory so the result is a proper
+   Python package.
+
+The ``subdir: 'fib_wrapper'`` argument on the extension module is required so
+that the compiled ``fib`` shared library is installed inside the ``fib_wrapper/``
+package directory, next to ``__init__.py``. Without it the extension would
+be installed at the top level and ``import fib_wrapper`` would not find the
+``fib`` extension. The resulting installed layout is::
+
+    site-packages/
+    └── fib_wrapper/
+        ├── __init__.py        # from .fib import fib
+        └── fib.cpython-*.so   # compiled extension module
+
+``__init__.py``
+---------------
+
+A minimal ``__init__.py`` re-exports the wrapped function:
+
+.. code-block:: python
+
+   from .fib import fib
+
+Building and installing
+=======================
+
+Editable install (development)
+------------------------------
+
+.. code-block:: bash
+
+   pip install --no-build-isolation --editable .
+
+``--no-build-isolation`` reuses the current environment, which is useful when
+iterating. This requires ``meson-python``, ``meson``, ``ninja``, and ``numpy``
+to already be installed.
+
+Building a wheel
+----------------
+
+.. code-block:: bash
+
+   # If you don't yet have `pypa/build` installed: `pip install build`
+   python -m build --wheel
+
+The resulting ``.whl`` file in ``dist/`` can be uploaded to PyPI, or installed
+elsewhere with ``pip install dist/fib_wrapper-0.1.0-*.whl``.
+
+Verifying the install
+---------------------
+
+.. code-block:: python
+
+   >>> from fib_wrapper import fib
+   >>> fib(10)
+   array([ 0,  1,  1,  2,  3,  5,  8, 13, 21, 34], dtype=int32)
+
+Customizing the Fortran compiler
+================================
+
+``meson-python`` delegates compiler selection to ``meson``. By default,
+``meson`` will choose the first Fortran compiler it finds on the PATH.
+If you want more control over Fortran compiler selection, set the ``FC``
+environment variable before building:
+
+.. code-block:: bash
+
+   FC=ifx python -m build --wheel
+
+For more control, use a `Meson native file
+<https://mesonbuild.com/Native-environments.html>`_:
+
+.. code-block:: ini
+
+   ; native.ini
+   [binaries]
+   fortran = 'ifx'
+   c = 'icx'
+
+.. code-block:: bash
+
+   python -m build --wheel -Csetup-args="--native-file=native.ini"
+
+Adding dependencies (BLAS, LAPACK, etc.)
+========================================
+
+Use ``dependency()`` in ``meson.build`` to link against system libraries:
+
+.. code-block:: none
+
+   lapack_dep = dependency('lapack')
+
+   py.extension_module('mymod',
+     [sources, generated, incdir_f2py / 'fortranobject.c'],
+     dependencies : [np_dep, f2py_dep, lapack_dep],
+     install : true,
+   )
+
+``meson`` resolves dependencies through ``pkg-config``, CMake, or its own
+detection logic. See the `Meson dependency documentation
+<https://mesonbuild.com/Dependencies.html>`_ for details.
+
+Differences from the ``scikit-build-core`` workflow
+====================================================
+
+The ``scikit-build-core`` approach documented in :ref:`f2py-skbuild` uses CMake
+under the hood. ``meson-python`` provides:
+
+* Native Fortran compiler support in ``meson`` (no CMake layer).
+* Direct integration with ``pip`` / ``build`` via PEP 517.
+* The same build system used by NumPy and SciPy themselves.
+
+Further reading
+===============
+
+* `meson-python documentation <https://meson-python.readthedocs.io/>`_
+* `Meson build system <https://mesonbuild.com/>`_
+* `SciPy's meson build configuration <https://github.com/scipy/scipy/blob/main/meson.build>`_ (real-world F2PY usage)
+* :ref:`f2py-meson` (raw meson build without ``meson-python``)
+* :ref:`f2py-skbuild` (alternative using ``scikit-build-core`` / CMake)
+* :ref:`f2py-meson-distutils` (migration from ``distutils``)

doc/source/f2py/code/fib_mesonpy.f90

@@ -0,0 +1,15 @@
+subroutine fib(a, n)
+  use iso_c_binding
+  integer(c_int), intent(in) :: n
+  integer(c_int), intent(out) :: a(n)
+  integer :: i
+  do i = 1, n
+     if (i == 1) then
+        a(i) = 0
+     else if (i == 2) then
+        a(i) = 1
+     else
+        a(i) = a(i - 1) + a(i - 2)
+     end if
+  end do
+end subroutine fib

doc/source/f2py/code/meson_mesonpy.build

@@ -0,0 +1,43 @@
+project('fib_wrapper', 'c',
+  version : '0.1.0',
+  meson_version: '>=1.1.0',
+  default_options : ['warning_level=2'],
+)
+
+add_languages('fortran', native: false)
+
+py = import('python').find_installation(pure: false)
+
+# NumPy >=2.0 provides include dirs via dependency()
+np_dep = dependency('numpy')
+
+incdir_f2py = run_command(py,
+  ['-c', 'import numpy.f2py; print(numpy.f2py.get_include())'],
+  check : true
+).stdout().strip()
+
+# f2py include dir (for fortranobject.h) is not in dependency('numpy'),
+# so add it separately
+f2py_dep = declare_dependency(
+  include_directories : incdir_f2py,
+)
+
+# Generate the f2py wrappers
+fib_source = custom_target('fibmodule.c',
+  input : ['fib.f90'],
+  output : ['fibmodule.c', 'fib-f2pywrappers.f'],
+  command : [py, '-m', 'numpy.f2py', '@INPUT@', '-m', 'fib', '--lower']
+)
+
+py.extension_module('fib',
+  ['fib.f90', fib_source, incdir_f2py / 'fortranobject.c'],
+  dependencies : [np_dep, f2py_dep],
+  subdir: 'fib_wrapper',
+  install : true,
+)
+
+# Install the Python package files
+py.install_sources(
+  'fib_wrapper/__init__.py',
+  subdir: 'fib_wrapper',
+)

doc/source/f2py/code/pyproj_mesonpy.toml

@@ -0,0 +1,10 @@
+[build-system]
+# numpy>=2.0 is required for dependency('numpy') support in meson.build
+requires = ["meson-python>=0.15.0", "numpy>=2.0"]
+build-backend = "mesonpy"
+
+[project]
+name = "fib_wrapper"
+version = "0.1.0"
+requires-python = ">=3.10"
+dependencies = ["numpy"]