DOC: Add concrete Meson build example for NumPy C ufunc extension by Aniketsy · Pull Request #30008 · numpy/numpy

Aniketsy · 2025-10-17T11:28:01Z

#28614
This PR adds a new documentation page, ufunc_meson_example.rst

Please let me know if my approach or fix needs any improvements . I’m open to feedback and happy to make changes based on suggestions.
Thankyou !

Aniketsy · 2025-10-17T11:34:16Z

@mhvk please review these changes when you get chance, and let me know if this needs improvement. I have created a new file and don't know if this is best approach .

mattip

I think the added examples are missing. The other code examples are all in f2py/code, maybe put them under a ufunc subdirectory?

doc/source/f2py/ufunc_meson_example.rst

Aniketsy · 2025-10-17T14:14:29Z

@mattip I've updated with changes.

mhvk

@Aniketsy - this looks fine but it is in the wrong place! I think this should be part of https://numpy.org/doc/stable/user/c-info.ufunc-tutorial.html -- and ideally where it introduces how to compile it using setuptools, you give an alternative with meson. A big advantage is that then you can just adjust the sample for the ufunc c code that is already introduced there.

What would be brilliant is to use the same kind of switchable display as on https://numpy.org/doc/stable/building/index.html#building-from-source, where one has blocks different OS, and for different ways to create virtual environments, etc. Here, one could have one for setuptools and one for meson. Note, however, that I have not looked at the source code to see if it would be very tricky!

Aniketsy · 2025-10-19T18:24:53Z

@mhvk i have updated, the changes as per suggestion, please let me know if it needs improvement.

ngoldbaum · 2025-10-21T16:26:06Z

Awesome:

I didn't manually test that the meson example works but it looks correct at a quick glance.

My only suggestion is, IMO, we should be suggesting meson by default in the tab picker.

ngoldbaum · 2025-10-21T16:26:57Z

Also probably worth suggesting writing a pyproject.toml and picking meson-python as the build backend to make your code pip-installable.

ngoldbaum · 2025-10-21T16:27:57Z

The numpy-user-dtypes repo has a number of meson/meson-python examples that use the numpy C API you can take inspiration from: https://github.com/numpy/numpy-user-dtypes

Aniketsy · 2025-10-21T18:08:45Z

@ngoldbaum Thanks! I've updated as per suggestions, please let me know if this need improvement.

rgommers

Thanks for working on this @Aniketsy! I added some comments aiming to make the examples as idiomatic as possible.

doc/source/user/c-info.ufunc-tutorial.rst

Aniketsy · 2025-10-23T06:41:41Z

@rgommers Thanks! I've updated with changes as per suggestion, please let me know if this need improvement.

rgommers

This is getting closer. If you look at the rendered page (see here for the latest version), the page doesn't flow very well though; it contains duplicate setup.py entries now above the .. note:: blocks. Those can be deleted. The extra docstring content is mostly obsolete, except for the numpy-specific paragraphs like this one:

    setup.py file for single_type_logit.c
    Note that since this is a numpy extension
    we add an include_dirs=[get_include()] so that the
    extension is built with numpy's C/C++ header files.

Can you move those parts into the setup.py example in the tabs, and delete the rest (e.g., everything related to running python setup.py xxx is obsolete)?

There is only last issue with libraries=["npymath"]. I think we need to leave that as is but open a follow-up issue to change the example and remove those docs. We should stop encouraging anyone to use libnpymath, since we want to get rid of that. To do so, the example has to be changed to not use half-precision dtypes (it's a known issue that float16 et al routines aren't available through the regular C API).

doc/source/user/c-info.ufunc-tutorial.rst

rgommers · 2025-10-23T09:34:50Z

doc/source/user/c-info.ufunc-tutorial.rst

+
+   For modern Python packaging, it is recommended to use a `pyproject.toml` and select
+   either `meson-python` or `scikit-build-core` as your build backend. Both are well-designed,
+   well-maintained, and make your extension pip-installable and compatible with current Python packaging standards.


This note doesn't need to be repeated three times, can you just leave the first one and delete the other ones?

Aniketsy · 2025-10-23T11:16:12Z

@rgommers I've update as per suggestion, please let me know if this needs further improvements. Thanks!

rgommers · 2025-10-23T17:02:36Z

We're getting close! There's a rendering issue, see the double indent here:

rgommers

A few more small comments. Once those are resolved and the rendered version looks good, I'll do some local testing.

doc/source/user/c-info.ufunc-tutorial.rst

Aniketsy · 2025-10-24T22:11:30Z

@rgommers done with changes, please let me know if this needs further improvements. Thanks!

Aniketsy · 2025-10-26T10:41:53Z

There is only last issue with libraries=["npymath"]. I think we need to leave that as is but open a follow-up issue to change the example and remove those docs. We should stop encouraging anyone to use libnpymath, since we want to get rid of that. To do so, the example has to be changed to not use half-precision dtypes (it's a known issue that float16 et al routines aren't available through the regular C API).

@rgommers I’d love to work on this issue if you allow. Please let me know if I can go ahead with this!

rgommers · 2025-11-03T12:27:32Z

After 3 rounds of review there was still a lot of straightforward things to fix, like duplication of content and added examples that invalidated the existing text above it. So I pushed the needed changes for those directly.

The meson.build file for Example NumPy ufunc with multiple dtypes isn't correct right now, since it does lot link libnpymath. I am thinking we need the following change there:

Remove float16 support from the C example, to get the actual happy path multi-dtype support correct
Adjust the setup.py file to match
Then add a new example (or a diff) with float16, that then (a) does link libnpymath and (b) has a warning about that not being future-proof or super robust (since one sometimes needs to match the compilers used by numpy itself at wheel build time, link to ENH: Future of npymath library #20880) but currently NPY_HALF & friends are not exposed in the regular NumPy API so this is your only choice currently.
- Add to that that float16 != bfloat16 and hence not super useful, please think twice about adding this support because you very likely do not need it.

@mhvk @ngoldbaum thoughts on that approach?

mhvk

Just had a quick look. Overall, looks very nice, just a few small comments on the existing changes.

On the later question of float16, I think for these examples it is also fine to not go on to an example that includes float16, but just skip to describing what that is tricky. In the end, these examples are meant to be for people writing their first ufunc, it does not have to be too elaborate.

mhvk · 2025-11-03T22:09:19Z

doc/source/user/c-info.ufunc-tutorial.rst

+         project('spam', 'c')
+
+         py = import('python').find_installation()
+         np_dep = dependency('numpy')


This particular example actually doesn't use the numpy dependency, so this is not necessary.

mhvk · 2025-11-03T22:09:35Z

doc/source/user/c-info.ufunc-tutorial.rst

+         extension_module = py.extension_module(
+           'spam',
+           ['spammodule.c'],
+           dependencies: [np_dep],


This can go too.

mhvk · 2025-11-03T22:09:43Z

doc/source/user/c-info.ufunc-tutorial.rst

+      .. code-block:: python
+
+         from setuptools import setup, Extension
+         import numpy as np


And this one.

rgommers · 2025-11-05T12:10:17Z

On the later question of float16, I think for these examples it is also fine to not go on to an example that includes float16, but just skip to describing what that is tricky. In the end, these examples are meant to be for people writing their first ufunc, it does not have to be too elaborate.

Agreed, that sounds like a good way to go.

@Aniketsy if you're up for giving that a go, removing all float16 related content from that example and ensuring it builds, then adding a sentence at the bottom as @mhvk suggests, please go for it.

Aniketsy · 2025-11-08T13:06:50Z

I apologize for the late response, I was in the hospital.
@mhvk , @rgommers thank you for the review. I’ve updated the PR with the suggested changes. Please let me know if this needs further improvements.

…ip azp] [skip cirrus]

…skip cirrus]

mhvk · 2025-11-09T19:18:29Z

@Aniketsy - I had a look and tried everything. Some things still failed, in part because the pyproject.toml sample, as given, was not quite complete. So, I added a minimal complete one. While doing this, I saw other things to fix (including removing the last part of the file, the point of which completely escaped me), so I ended up thinking it was easier to just follow @rgommers's example and push my fixes directly to your branch. I also took the liberty to squash your commits together. Anyway, this ended up a larger refactoring than any of us thought, but I think the result is good! Thanks for starting it!!

@rgommers - I think this is now ready...

p.s. I am not sure the docs build can be viewed anywhere, but I checked it locally, and it looks good.

rgommers · 2025-11-10T14:21:59Z

I am not sure the docs build can be viewed anywhere,

The link ci/circleci: build artifact in the list of CI jobs gets you to the preview of the html docs built in CI. You then still need to navigate to the actual page,

rgommers · 2025-11-10T14:22:51Z

Thanks for another push on this @mhvk!

I was in the hospital.

I hope you are feeling better @Aniketsy!

rgommers

This is in pretty good shape now, let's declare victory and get this in. Thanks @Aniketsy and @mhvk!

mhvk · 2025-11-10T14:48:29Z

Great! And the result of a nice three-way collaboration, thanks both!

Aniketsy · 2025-11-10T15:25:20Z

I hope you are feeling better @Aniketsy!
@rgommers Thanks! I’m good for now :)

@mhvk Thank you for the guidance and corrections.

…mpy#30008) Co-authored-by: Marten Henric van Kerkwijk <mhvk@astro.utoronto.ca> Co-authored-by: Ralf Gommers <ralf.gommers@gmail.com>

github-actions bot added the 04 - Documentation label Oct 17, 2025

mattip reviewed Oct 17, 2025

View reviewed changes

doc/source/f2py/ufunc_meson_example.rst Outdated Show resolved Hide resolved

mhvk reviewed Oct 19, 2025

View reviewed changes

Aniketsy marked this pull request as draft October 21, 2025 14:00

Aniketsy marked this pull request as ready for review October 21, 2025 14:47

rgommers requested changes Oct 22, 2025

View reviewed changes

rgommers requested changes Oct 23, 2025

View reviewed changes

rgommers reviewed Oct 23, 2025

View reviewed changes

doc/source/user/c-info.ufunc-tutorial.rst Outdated Show resolved Hide resolved

doc/source/user/c-info.ufunc-tutorial.rst Outdated Show resolved Hide resolved

doc/source/user/c-info.ufunc-tutorial.rst Outdated Show resolved Hide resolved

mhvk reviewed Nov 3, 2025

View reviewed changes

Aniketsy force-pushed the doc/meson-ufunc-example branch from 781cc6e to f859953 Compare November 8, 2025 12:59

Aniketsy and others added 2 commits November 9, 2025 14:03

DOC: Update f2py usage and add Meson ufunc example [skip actions] [sk…

02a1e92

…ip azp] [skip cirrus]

DOC: ensure everything works and is clear [skip actions] [skip azp] […

d39130b

…skip cirrus]

mhvk force-pushed the doc/meson-ufunc-example branch from f859953 to d39130b Compare November 9, 2025 19:13

rgommers added this to the 2.4.0 release milestone Nov 10, 2025

rgommers approved these changes Nov 10, 2025

View reviewed changes

rgommers merged commit 933fd54 into numpy:main Nov 10, 2025
4 checks passed

rgommers mentioned this pull request Nov 10, 2025

DOC: improve documentation on f2py and/or meson #28614

Closed

Uh oh!

Conversation

Aniketsy commented Oct 17, 2025

Uh oh!

Aniketsy commented Oct 17, 2025

Uh oh!

mattip left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Aniketsy commented Oct 17, 2025

Uh oh!

mhvk left a comment

Choose a reason for hiding this comment

Uh oh!

Aniketsy commented Oct 19, 2025

Uh oh!

ngoldbaum commented Oct 21, 2025

Uh oh!

ngoldbaum commented Oct 21, 2025

Uh oh!

ngoldbaum commented Oct 21, 2025

Uh oh!

Aniketsy commented Oct 21, 2025

Uh oh!

rgommers left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Aniketsy commented Oct 23, 2025

Uh oh!

rgommers left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rgommers Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

Aniketsy commented Oct 23, 2025

Uh oh!

rgommers commented Oct 23, 2025

Uh oh!

rgommers left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Aniketsy commented Oct 24, 2025

Uh oh!

Aniketsy commented Oct 26, 2025

Uh oh!

rgommers commented Nov 3, 2025

Uh oh!

mhvk left a comment

Choose a reason for hiding this comment

Uh oh!

mhvk Nov 3, 2025

Choose a reason for hiding this comment

Uh oh!

mhvk Nov 3, 2025

Choose a reason for hiding this comment

Uh oh!

mhvk Nov 3, 2025

Choose a reason for hiding this comment

Uh oh!

rgommers commented Nov 5, 2025

Uh oh!

Aniketsy commented Nov 8, 2025

Uh oh!

mhvk commented Nov 9, 2025

Uh oh!

rgommers commented Nov 10, 2025

Uh oh!

rgommers commented Nov 10, 2025

Uh oh!