Blender 4.2 からのアドオン作成方法  サードパーティライブラリを同梱

Blender 4.2 からアドオン作成方法が変更されました。
変更内容に「Use wheels to pack your external Python dependencies.」とあり
外部のモジュールを同行する場合は、wheels を使う必要がある。
ざっくりとですが同梱方法についてまとめました。

:::note info
下記のサイトを参考に書き出しています。
[Add-ons(アドオン)](https://docs.blender.org/manual/ja/4.2/advanced/extensions/addons.html#bundle-dependencies)
[Python Wheels](https://docs.blender.org/manual/ja/4.2/advanced/extensions/python_wheels.html)
:::

# 検証環境

| Tool | バージョン |
|:-:|:-:|
| Mac | Mac	Sequoia (15.1.1) |
| Blender | 4.2 |

# 必須条件
パッケージに含むことができるモジュールの条件

[Requirements](https://docs.blender.org/manual/ja/4.2/advanced/extensions/python_wheels.html#requirements)

ざっくり翻
- Wheels は Python's package index (PyPI) から変更せずにバンドルする
- Wheels は依存関係を含んいる
- Wheels のファイル名はPythonのバイナリ配布の仕様と一致している
  ※PyPI からダウンロードされた Wheels は、この規約に従っている
  参考：[パッケージ名の命名規則](https://packaging.python.org/en/latest/specifications/binary-distribution-format/#file-name-convention)
- manifest ファイル(blender_manifest\.toml)に記載する場合
  パスの区切り文字は「`/`」スラッシュを使用する

# Wheels ファイルを取得

pip を使ってWheelsファイル(\*\.whl)を取得する
取得したファイルは「`wheels`」ディクトリ内に保存する

:::note info
ディレクトリ名の「`wheels`」は通例として使用されている
:::

## ディレクトリ構成
下記の通りに Wheels ファイルを配置する
``` sh
addon
├─ wheels
│  └─ module.whl
├─ __init__.py
└─ blender_manifest.toml
```

## ファイルを取得
Wheels ファイルの取得方法を２種類ある

例：numpy を取得
**その１**
``` sh
pip wheel numpy -w ./wheels
```
pip を実行した環境に適した Wheels ファイルがダウンロードされる
上記のコマンドを下記のファイルがダウンロードされる
- numpy-2.2.1-cp311-cp311-macosx_14_0_arm64.whl
  検証環境の Mac で実行できるファイルがダウンロードされた


**その２**
``` sh
pip download numpy --dest ./wheels --only-binary=:all: --python-version=3.11 --platform=macosx_11_0_arm64
pip download numpy --dest ./wheels --only-binary=:all: --python-version=3.11 --platform=win_amd64
```
pip を実行した環境に依存せず、任意の環境向けの Wheels ファイルをダウンロードできる
上記のコマンドを実行すると下記のファイルを取得できる
- numpy-2.2.1-cp311-cp311-macosx_11_0_arm64.whl
- numpy-2.2.1-cp311-cp311-win_amd64.whl

:::note info
対象のファイルが存在しない場合、エラーメッセージが表示される
下記のコマンドを実行すると linux 環境向けがないのでエラーが表示される
``` sh
pip download numpy --dest ./wheels --only-binary=:all: --python-version=3.11 --platform=manylinux_2_28_x86_64
```
``` sh:エラー
ERROR: Could not find a version that satisfies the requirement numpy (from versions: none)
ERROR: No matching distribution found for numpy
```
事前に PyPI サイトで確認する
__[PyPI](https://pypi.org/)__
:::

# Manifest ファイルに追記
Manifest ファイル(blender_manifest\.toml)にダウンロードした Wheels ファイルを相対パスで追記する
パスの区切りは「`/`」を使用する
``` sh:blender_manifest\.toml
wheels = [
   "./wheels/numpy-2.2.1-cp311-cp311-macosx_11_0_arm64.whl",
   "./wheels/numpy-2.2.1-cp311-cp311-win_amd64.whl",
]
```

:::note info
blender_manifest\.toml のテンプレートファイルは、
Blender の「`スクリプト作成`」 > 「`テンプレート`」 > 「`Blender Manifest`」を選択すると表示される
![スクリーンショット 2024-12-26 0.04.51.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3950275/50757bb3-3b31-28eb-f336-17d735a4c60f.png)

Manifest ファイルの設定箇所(42 から 45行目)に書かれたコメントアウトを外し、パスを書換える
![スクリーンショット 2024-12-26 0.06.17.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3950275/519888f2-ddf1-6577-50b1-b1dd0bc04040.png)

書き換え終えたら保存しアドオンの Manifest ファイルとして使用する
:::

# パッケージ生成 その１
従来通り Blender build を実行しパッケージを作成する
``` sh
blender --command extension build
```

# パッケージ生成  その２ ターゲットプラットフォーム
ターゲットプラットフォーム毎にパッケージを分けたい場合は
Manifest ファイルを書換え、Blendr build にオプションを追加する

## Manifest ファイルの書換え
platforms にパラメーターを追記
``` sh:blender_manifest.toml
platforms = ["windows-x64", "macos-arm64"]
```
他に用意されているパラメーター
- windows-arm64
- macos-x64
- linux-x64

:::note info
テンプレートの Manifest ファイルの設定箇所(37行目)に書かれたコメントアウトを外し、プラットフォームを書換える
![スクリーンショット 2024-12-26 18.49.04.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3950275/bd82d4c9-6de3-a1f0-f2b0-d8d861542cfd.png)
:::

## Blendr build にオプションを追加
blender コマンドに「`--split-platforms`」を追加する

``` sh
blender --command extension build --split-platforms
```

実行後プラットフォーム毎にパッケージ(zip ファイル)が生成される


:::note info
例：
プラットフォームに windows-x64, macos-arm64 を追記した場合
下記のファイルが生成される

- addon_with_Third_lib-0.1.0-windows_x64.zip
- addon_with_Third_lib-0.1.0-macos_arm64.zip

ファイル名の最後にプラットフォーム名が追加される
:::