はじめに

自分は普段、Pythonのlibrary, package製作をしているのですが、その際Cythonを多く用いています。
特に.pyxファイルにcython言語で記述しているのですが、それらをbuildする際、今まではsetup.pyファイルにcythonとsetuptools(内部ではdistutils)を用いてコンパイルし、shared library (.soファイルや.pydファイル)を生成していました。
しかし、PEP517やPEP518, PEP621で記述されているとおり、pyproject.tomlにbuildやmetadataの設定をすることが推奨されており、さらに、distutilsがPython 3.10でdeprecateされ、3.12では完全に削除される予定です(PEP632)。
実際、pythonのscipyはversion1.9.0からmesonを用いたbuild systemに移行しています¹。
(要参考: https://labs.quansight.org/blog/2021/07/moving-scipy-to-meson)

しかし、mesonのドキュメントは例文が少ないためわかりにくく、未だに日本語での解説も少ないため備忘録としてPython+Cython libraryにおける設定の仕方をここにまとめておこうと思います。

Mesonとは

Meson is an open source build system meant to be both extremely fast, and, even more importantly, as user friendly as possible.
The main design point of Meson is that every moment a developer spends writing or debugging build definitions is a second wasted. So is every second spent waiting for the build system to actually start compiling code.
-- https://mesonbuild.com 引用

つまり高速でコンパイルできるbuildシステムを提供してくれるツールです。CMakeといったツールと近いみたいです。自分はC++を扱ったことがほとんどないのでそのあたりには詳しくないです...
Meson自体はPythonで記述されており、内部ではNinjaというライブラリ動いて、コンパイルを最適化してくれるみたいです。
(この方が詳しく書かれています: https://qiita.com/turenar/items/c727834fbf701beb47ef)

テストPython library構成

ソースコードについてはGitHubにて公開しております: https://github.com/munechika-koyo/test_meson

.
├── pyproject.toml
├── setup.py  <------------- setuptools developモードインストール用
├── dev.py   <-------------- 様々なbuild用CLI
├── meson.build
└── test_meson  <----------- ソースディレクトリ
    ├── __init__.py
    ├── meson.build
    ├── cmain.pyx
    ├── main.py
    ├── lib1  <------------- サブパッケージ１
    │   ├── __init__.pxd  <- module.pxyを他のcythonコードでも使用するために必要
    │   ├── __init__.py
    │   ├── meson.build
    │   ├── module.pxd  <--- TestClass1を他のクラスで継承するために必要
    │   └── module.pyx  <--- TestClass1の定義など
    └── lib2  <------------- サブパッケージ2
        ├── __init__.py
        ├── meson.build
        └── module.pyx  <--- TestClass1を継承したTestClass2の定義

テスト環境

OS: Ubuntu 22.04.2

Python環境

Python 3.12.0
Cython 3.0.6
meson 1.3.0
ninja 1.11.1
pip 23.3.1
build 0.7.0
meson-python 0.15.0

Cコンパイラ関連

gcc 11.4.0
pkg-config 1.8.0

conda環境にて上記を実現していますが、他の環境(pyenvなど)でも実現できると思います。

まず特徴として、ルート階層とソースコードのスクリプトファイル(*.py, *.pyx)がある階層にすべてにmeson.buildファイルが置かれていることです。
ここに、cythonやC言語によるコンパイル方法やincludeパス、dependency、ビルド済み配布物に含めるソースファイルなど全てを記述していきます。これが非常に冗長的で面倒な点ですが、逆にいうと非常に厳密的であると言えると思います。以下にそれぞれのmeson.buildファイルで何を記述しているか説明していきます。

meson.buildファイルの内容

`./meson.build`の内容

まずルート階層にあるmeson.buildファイルは以下の内容です:

project(
  'test-meson',  # project名 (普通はpythonのパッケージ名と同じ)
  # === 以下に使用するプログラミング言語を列挙する ===
  'c',  # cythonを使う場合はcコンパイラも用いるため、列挙しといた方がよい。
  'cython',
  # ===
  version: '0.1',  # パッケージバージョン (ファイルに記述してある場合はそれを指定することも可能)
  meson_version: '>= 1.3',
  default_options: [  # ここにコンパイルする際、必ず使用するoptionを'key=value'で指定
    'cython_args=-3',  # cythonのコンパイルオプション
    'c_std=c99',  # 使用するC言語規格 - c11にするとwindowsでcomplexに関するエラーが起こる
    'buildtype=debugoptimized',  # mesonのbuild-in オプション -Ddebug=true -Doptimization=2と等価
  ]
)

# filesystemモジュール　- ファイルをbuildディレクトリにコピーするのに用いる
fs = import('fs')

# Pythonモジュール - pythonプログラムを実行したりするのに用いる
py = import('python').find_installation(pure: false)  # pure: false でplatform依存のwheelを作成できる

# ======================================================================
# 以下にコンパイラに必要な外部ライブラリ(external dependency)について定義する
# ======================================================================
# Python dependency
py_dep = py.dependency()

# OpenMP dependency
omp_dep = dependency('openmp', required: true)

# NumPy dependency
incdir_numpy = run_command(
  py,  # Pythonでプログラムを実行
  [
    '-c',
    'import numpy; print(numpy.get_include())'
  ],
  check: true
).stdout().strip()
inc_np = include_directories(incdir_numpy)
np_dep = declare_dependency(include_directories: inc_np)  # includeディレクトリからdependencyを作成
# =======================================================================

# 次の下階層へ
subdir('test_meson')

まずproject()で基本的なビルドするソースに関する情報を載せます。
ここでdefault_optionsにcython²やc言語に関するコンパイルオプションを指定しています。c_stdやbuidtypeはmesonのbuild-inオプションで、この2つのオプションはwindowsなどのOSでコンパイルする場合は必要なようです。
さらに、コンパイルの際に必要な外部ライブラリをdpendencyオブジェクトとして定義しています。これはmesonで便利なツールの一つで、このdepオブジェクトをコンパイル時の引数に指定することで自動的にリンク付けがされます。meson側で対応していないライブラリ(NumPyなど)はinclude_directories()関数からincludeディレクトリオブジェクトを作成し、そこからdepオブジェクトを作成できます。

また、run_command()関数からPythonなどプログラムを直接実行することもできます。上ではNumPyのメソッドを用いてincludeパスの文字列を取得しています。

最後にsubdir関数を用いて下の階層に移動しています。

`./test_meson/meson.build`の内容

# local modules for .pyx file
pyx_files = [
  ['cmain', 'cmain.pyx'],  # [モジュール名, ファイル名]のリスト
]

# for文でpythonの外部モジュールをファイルごとに指定。ここで cython-> c -> .so/.pyd という流れを自動で行ってくれる。
foreach pyx_file : pyx_files
  py.extension_module(
    pyx_file[0],  # モジュール名
    pyx_file[1],  # ファイル名
    c_args: [numpy_nodepr_api],
    dependencies: [py_dep, np_dep],  # コンパイラに必要な外部ライブラリをここで指定する
    install: true,  # install_dir 先にインストールする
    install_dir: py.get_install_dir() / 'test_meson',  # .so/.pydファイルをインストールするディレクトリパスを指定
  )
endforeach

# pure pythonのソースコード
python_sources = [
    '__init__.py',
    'main.py',
]

# インストールする際のソースコードの指定 ビルド済み配布物に含める場合に必要
py.install_sources(
  python_sources,
  subdir: 'test_meson',  # インストールする際のディレクトリパス
)

# move to subdirectories
subdir('lib1')
subdir('lib2')

ここから本格的にcythonファイルのコンパイル(shared object作成等)の命令を記述していきます。
pyx_filesにモジュール名と元となるモジュールファイル名との対応を配列として静的に記述し、foreachとpy.extension_moduleを用いて記述しています。このforeach文を用いたコンパイル法は上部で要参考として載せたサイトを参考にさせていただきました。
引数のdependencyに先ほど定義したdepオブジェクトをリスト形式で指定しています。必要となるライブラリだけでよいので、ここではomp_depは指定していません。

また、py.install_sources()で.pyファイルを指定しているのは、今後wheelなどのビルド済み配布物を制作する際に含める必要があるからです。

`./test_meson/lib1/meson.build`の内容

# モジュール名と対応する.pxdファイルをbuildディレクトリにコピーし、dependecyとして宣言する
_cython_tree = declare_dependency(sources: [
  fs.copyfile('__init__.pxd'),
  fs.copyfile('module.pxd'),
])

pyx_files = [
  ['module', 'module.pyx'],
]

foreach pyx_file : pyx_files
  py.extension_module(
    pyx_file[0],
    pyx_file[1],
    c_args: [numpy_nodepr_api],
    dependencies: [py_dep, omp_dep, np_dep, _cython_tree],  # omp_depと_cython_treeを追加
    install: true,
    install_dir: py.get_install_dir() / 'test_meson/lib1',  # install先パスが異なることに注意
  )
endforeach

python_sources = [
    '__init__.py',
    '__init__.pxd',  # .pxdファイルは配布物として追加する
    'module.pxd',
]

py.install_sources(
  python_sources,
  subdir: 'test_meson/lib1',  # 同じくパスが異なることに注意
)

ここのサブパッケージにはcythonソースが記述されたmodule.pyxと、様々な宣言が記述されたmodule.pxdファイルがあります。ここで重要なのは、.pxdファイルもfs.copyfile()を用いて、buildディレクトリにコピーし、depオブジェクトとして宣言することです。コピーすることで、他のモジュールがこのlib1.moduleに依存していたとしてもcython側で適切に紐づけることができる様です。
また、py.extension_module()におけるdependency引数にomp_depと.pxdファイルから宣言された_cython_treeも加えられています。

さらに、install_dirをソースファイルがある階層と同じにします。py.install_sourcesにおけるsubdirも同様です。

cythonソースコードの注意点

cythonのコーディングにおいて気をつける点は内部モジュールをcimportする際は必ず相対インポートをすることです。
例としてtest_meson/lib2/module.pyxの一部分を表示します:

from libc.stdio cimport printf

from ..lib1.module cimport TestClass1


cdef class TestClass2(TestClass1):
            :
            :

ここではtest_meson/lib1/module.pyxで定義してあるTestClass1を相対cimportしています。

mesonビルド方法

mesonとninjaをインストールし、ルート階層でまず次のコマンドをコマンドラインで実行し、mesonをセットアップします:

$ meson setup build  # "build"ディレクトリに設定

成功すると標準出力に次のような内容が記述されます:

The Meson build system
Version: 1.3.0
Source dir: /home/koyo/Documents/test_meson
Build dir: /home/koyo/Documents/test_meson/build
Build type: native build
Project name: test-meson
Project version: 0.1
C compiler for the host machine: cc (gcc 11.4.0 "cc (Ubuntu 11.4.0-1ubuntu1~22.04) 11.4.0")
C linker for the host machine: cc ld.bfd 2.38
Cython compiler for the host machine: cython (cython 3.0.6)
Host machine cpu family: x86_64
Host machine cpu: x86_64
Program python3 found: YES (/home/koyo/.conda/envs/test-meson/bin/python3.12)
Found pkg-config: YES (/usr/bin/pkg-config) 1.8.0
Run-time dependency python found: YES 3.12
Run-time dependency OpenMP found: YES 4.5
Build targets in project: 5

Found ninja-1.11.1 at /home/koyo/.conda/envs/test-meson/bin/ninja

ここで、Cコンパイラやリンカ、depndencyが見つからないとエラーを吐きます。その場合は適切に環境変数(CCやPATHなど)を設定してください。やり直す場合は --wipeオプション付けてmeson setupを再び実行します。
適切にmesonのセットアップが完了した場合は次のようにコンパイラを実行します:

$ meson compile -C build

結果は以下の通りです:

INFO: autodetecting backend as ninja
INFO: calculating backend command to run: /home/koyo/.conda/envs/test-meson/bin/ninja -C /home/koyo/Documents/test_meson/build
ninja: Entering directory `/home/koyo/Documents/test_meson/build'
[11/11] Linking target test_meson/lib1/module.cpython-312-x86_64-linux-gnu.so

-jオプションでコア数を指定すると並列に処理してくれます。
コンパイルが成功すると./buildディレクトリ以下に.soファイルや様々な設定ファイルなどが作成されます。

これでmesonによるコンパイルは完了ですが、pythonからimport文で呼び出すには.buildにもパスを通す必要があり、少し面倒です。そこで作成された.so/.pydファイルをもとのソースツリー内にコピーしてあげましょう。その時のpythonコード例は以下の通りです:

from pathlib import Path
import sys
import shutil

BUILD_DIR = Path("build")

ext = ".pyd" if sys.platform == "win32" else ".so"
for so_path in BUILD_DIR.glob(f"**/*{ext}"):
    src = so_path.resolve()
    dst = so_path.relative_to(BUILD_DIR)
    shutil.copy(src, dst)
    print(f"copy {src} into {dst}")

カレントディレクトリがルート階層の場合のコードです。

pyproject.tomlの設定

pythonパッケージとして成立させるためにはpyproject.tomlファイルを作成し、そこに必要最小限のビルド設定を載せることがPEP518で決められています。今回のテストライブラリにおけるpyproject.tomlの設定の一部は以下のとおりです。

[build-system]
build-backend = "mesonpy"
requires = ["cython >= 3.0", "numpy", "meson-python", "ninja >= 1.8.2"]

[project]
name = "test-meson"
description = "Test for Meson with Cython"
version = "0.1"
license = { file = "LICENSE" }
readme = "README.md"
requires-python = ">=3.9"
dependencies = ["numpy"]

ここで重要なのはbuild-backendとして"mesonpy"つまりmeson-pythonを利用している点です。このバックエンドはmesonシステムをpythonパッケージで利用するためのパッケージで現在なお開発が進められています。
また、ビルドの際必要となるパッケージはrequiresとして予め登録しておく必要があります。これらのパッケージはビルド時に必要になるだけなので、ビルド時独立環境の中にのみインストールされ、ビルドが終わると削除されます。通常利用環境で依存パッケージがある場合は[project]テーブルのdependenciesに記述しましょう。

ビルド済み配布物の作成

ビルド済み配布物、いわゆるbdistやsdistを作成する際は、PyPAが提供しているbuildというビルドフロントエンドツールを使用するのが最も簡単です。使用する際は次のようにコマンドを実行します。

$ python -m build

実行が完了するとルート階層にdistというディレクトリが作成され、その下にビルド済み配布物が作成されます。

.
├── dist
│   ├── test_meson-0.1-cp312-cp312-linux_x86_64
│   └── test_meson-0.1.tar.gz

wheelファイルの中身をlessコマンドを利用して見ると、

前半省略
Archive:  dist/test_meson-0.1-cp312-cp312-linux_x86_64.whl
 Length   Method    Size  Cmpr    Date    Time   CRC-32   Name
--------  ------  ------- ---- ---------- ----- --------  ----
    3300  Defl:N     1435  57% 2023-12-03 08:52 421158e4  test_meson-0.1.dist-info/METADATA
      88  Defl:N       85   3% 2023-12-03 08:52 8d43aa0c  test_meson-0.1.dist-info/WHEEL
    1071  Defl:N      632  41% 2023-11-14 06:00 028f879f  test_meson-0.1.dist-info/LICENSE
   53528  Defl:N    17186  68% 2023-12-03 08:52 5f2369a9  test_meson/cmain.cpython-312-x86_64-linux-gnu.so
  260488  Defl:N   104417  60% 2023-12-03 08:52 393f4ffe  test_meson/lib1/module.cpython-312-x86_64-linux-gnu.so
  100792  Defl:N    37501  63% 2023-12-03 08:52 fbf1c06d  test_meson/lib2/module.cpython-312-x86_64-linux-gnu.so
      22  Defl:N       24  -9% 2023-11-14 06:00 dce6f0a3  test_meson/__init__.py
     356  Defl:N      220  38% 2023-11-14 06:00 774030ef  test_meson/main.py
      22  Defl:N       24  -9% 2023-11-14 06:00 40344f1a  test_meson/lib1/__init__.py
      22  Defl:N       24  -9% 2023-11-14 06:00 b2f6c4ff  test_meson/lib1/__init__.pxd
     280  Defl:N      172  39% 2023-11-14 06:00 2563b6d8  test_meson/lib1/module.pxd
      57  Defl:N       51  11% 2023-11-14 06:00 0d7ef4b7  test_meson/lib2/__init__.py
    1110  Defl:N      623  44% 2023-12-03 08:52 9f8e2634  test_meson-0.1.dist-info/RECORD
--------          -------  ---                            -------
  421136           162394  61%                            13 files

となっており、meson.buildで指定したファイルと.soファイルが梱包されていることがわかります。

editableインストールの活用

ライブラリ開発を行う場合はpip install -e .というeditableモードでのパッケージインストールが便利です。
これはソースコードを普通のインストール先(多くは../lib/python{version}/site-packageディレクトリ)にインストールすることなく、python実行の際にソースコードへパスを通してくれるインストール法です。詳細はPEP660に載っています。
meson-pythonではv0.13以降でeditableインストールに対応し、以下のコマンドで可能です:

$ python -m pip install --no-build-isolation --editable .

このコマンドではpythonでimportするたびに変更があればコンパイルされ、.soファイルが./build/cp12/以下に配置され、パスが通るようになります。

詳しくはmeson-pythonのドキュメントをご覧ください。

dev.py CLIの活用

毎回、meson compile、.soファイルのコピーを手打ちで実行するのは面倒なので、CLIを作成して楽にしましょう。
scipyのdev.py CLIを参考にして次のようなdev.pyを作成しました。

"""
Developer CLI: building (meson) sources in place, document, etc.
"""
import os
import shutil
import subprocess
import sys
from pathlib import Path

import rich_click as click

BASE_DIR = Path(__file__).parent.resolve()
BUILD_DIR = BASE_DIR / "build"
SRC_PATH = BASE_DIR / "test_meson"
ENVS = dict(os.environ)
N_CPUs = os.cpu_count()


@click.group()
def cli():
    """Developer CLI: building (meson) sources in place, document, etc."""
    pass


@cli.command()
@click.option("--build-dir", default=str(BUILD_DIR), help="Relative path to the build directory")
@click.option(
    "-j",
    "--parallel",
    default=N_CPUs,
    show_default=True,
    help="Number of parallel jobs for building.",
)
def build(build_dir, parallel):
    """Build & Install package using Meson build tool.
    \b
    ```python
    Examples:
    $ python dev.py build
    ```
    """
    # === setup build ===============================================
    cmd = ["meson", "setup", build_dir]
    if Path(build_dir).exists():
        cmd += ["--wipe"]
    click.echo(" ".join([str(p) for p in cmd]))
    ret = subprocess.call(cmd, env=ENVS, cwd=BASE_DIR)
    if ret == 0:
        print("Meson build setup OK")
    else:
        print("Meson build setup failed!")
        sys.exit(1)

    # === build project =============================================
    cmd = ["meson", "compile", "-C", build_dir, "-j", str(parallel)]
    click.echo(" ".join([str(p) for p in cmd]))
    ret = subprocess.call(cmd)

    if ret == 0:
        print("Build OK")
    else:
        print("Build failed!")
        sys.exit(1)

    # === install .so/.pyd files in source tree ==========================
    ext = ".pyd" if sys.platform == "win32" else ".so"
    for so_path in BUILD_DIR.glob(f"**/*{ext}"):
        src = so_path.resolve()
        dst = BASE_DIR / so_path.relative_to(BUILD_DIR)
        shutil.copy(src, dst)
        print(f"copy {src} into {dst}")
    print("Install .so files in place.")

rich_clickを用いてCLIを作成しています。ビルドを実行する際はpython dev.py buildとコマンド実行すれば良いです。

mesonビルドで注意すべき点

name-space パッケージのビルド

次のような__init__.pyファイルが最初の階層に無いパッケージのことをnamespaceパッケージと呼び、トップのライブラリ名を共通として複数のサブパッケージを用意する際に用いられます。

package/
    subpackageA/
        __init__.py
        modules.py
    subpackageB/
        __init__.py
        modules.py

この場合、cython v3.0以降では標準で対応しているのですが、mesonを用いた場合ではC言語ファイルを作成する際にトップのpackageを認識できないようです。
ですので、この場合はdev.py CLIにpackage/__init__.pyを作成した上でビルドし、その後削除するようなコードを作成する応急手当が必要となるようです。

最後に

meson + cython の pythonパッケージは、numpyやscipy、scikit-imageなどが採用していることから今後ますます利用されていくと思います。その時、この資料が少しでも皆様の参考になれば幸いです。