【各環境(OS)でのトランスパイル方法と実行】
BASIC 2026 は、basic_to_c.py で BASIC ソースを C に変換し、その生成された C を各 OS 上の C コンパイラでコンパイルして実行します。
つまり、基本的な流れはどの環境でも共通です。
Python で basic_to_c.py を実行して .c を生成する  
C コンパイラで実行ファイルを作る  
実行する
基本形は以下です。
python3 basic_to_c.py sample.bas sample.c
clang sample.c -lm -o sample
./sample
Windows ネイティブだけは少し異なり、通常は python を使い、-lm は不要です。


■事前に必要なもの
BASIC 2026 を使うには、最低限以下が必要です。
Python 3
C コンパイラ
basic_to_c.py
third_party/stb/stb_image.h
third_party/stb/stb_image_write.h
また、文字列の書記素クラスタ処理をより正確に行うために、Python モジュール grapheme の導入を推奨します。
推奨インストール
python3 -m pip install -r requirements.txt
requirements.txt の内容は現在以下です。
grapheme>=0.6.0
なお、grapheme が未導入でも、トランスパイラ本体にはフォールバック実装があります。
ただし、日本語や絵文字などのマルチバイト文字をできるだけ安定して扱うには、grapheme を入れておく方が安心です。


■Python のバージョン
basic_to_c.py は Python 3 系で動作します。
現状のコード構成から、Python 3.9 以上を推奨します。
確認方法
python3 --version
Windows ネイティブでは
python --version
で確認するのが一般的です。
少なくとも現行環境では Python 3.9 系で動作確認されています。
READEXCELDATA / READEXCELSTYLE は埋め込み Excel helper を使って動作します。
openpyxl が入っていればそれを使い、無い場合でも標準ライブラリ fallback で .xlsx を直接読み込めます。
背景色だけでなく、文字色・太字・斜体・下線・揃え・フォント情報・行高・列幅・保護情報・ALL の基本取得にも対応しています。
環境差が疑われる場合は、実行後の __DEBUG.log に出力される [RUNTIME] basic_to_c.py helper=... を確認すると、
実行時にどの helper を参照したか切り分けできます。


■grapheme のインストール
マルチバイト文字、日本語、絵文字の扱いを安定させるため、grapheme の導入を推奨します。
macOS / Linux / Raspberry Pi OS / FreeBSD
python3 -m pip install grapheme
Windows ネイティブ
python -m pip install grapheme
または requirements.txt から一括導入します。
macOS / Linux / Raspberry Pi OS / FreeBSD
python3 -m pip install -r requirements.txt
Windows ネイティブ
python -m pip install -r requirements.txt
PyInstaller で固める場合は、grapheme を hidden import に含めます。
例）
pyinstaller --hidden-import grapheme ...


■READEXCELDATA を使う場合
READEXCELDATA を使う場合は、openpyxl も必要です。
macOS / Linux / Raspberry Pi OS / FreeBSD
python3 -m pip install openpyxl
Windows ネイティブ
python -m pip install openpyxl


■共通の動作確認用サンプル
まずは以下のサンプルを sample.bas として保存して試すと分かりやすいです。
10 A$="BASIC2026 日本語テスト 🇯🇵"
20 PRINT A$
30 PRINT LEN(A$)
40 PRINT MID(A$,1,8)
50 DIM data()=1,2,3,4,5
60 PRINT data()
このサンプルで確認できること
トランスパイルできるか
C コンパイルできるか
実行できるか
日本語や絵文字が壊れないか
配列表示が正しく出るか

画像系の値域も確認したい場合は、以下のような短い確認コードも使えます。
10 SCREEN img(),32,32 MAXVALUE 1.0 FILL 1,1,1,1
20 meta{}=GETMETA(img())
30 PRINT meta{"imageValueMax"}
この結果が 1 になれば、MAXVALUE 付き SCREEN がその環境でも期待通り動作しています。






・macOS
■必要なもの
Python 3
clang
pip
grapheme
必要に応じて openpyxl
■確認
python3 --version
clang --version
■依存導入
python3 -m pip install -r requirements.txt
Excel も使う場合
python3 -m pip install openpyxl
■トランスパイル
python3 basic_to_c.py sample.bas sample.c
■コンパイル
clang -Wall -Wextra sample.c -lm -o sample
■実行
./sample
■補足
SAVEPDF を使っていない通常の BASIC2026 プログラムは、上記のように -lm だけでコンパイルできます。
CoreFoundation や CoreGraphics などの framework 指定は不要です。
古い macOS 環境では、SAVEPDF を使っていないのに -framework CoreGraphics などを付けると、かえって
ld: framework not found CoreGraphics
のようなリンクエラーになる場合があります。
そのため、通常のプログラムでは framework を付けず、
clang sample.c -lm -o sample
とするのが基本です。
また、実行ファイル名に sample.bas のような .bas 拡張子を付けると、BASIC ソースと見分けにくくなります。
実行ファイル名は sample のように、ソースとは別の名前にすることを推奨します。
■SAVEPDF を使う場合
macOS では SAVEPDF が使えます。
ただし、生成された C をコンパイルする時に framework の指定が必要です。
clang sample.c -lm \
  -framework CoreFoundation \
  -framework CoreGraphics \
  -framework CoreText \
  -o sample
ただし、古い macOS / Xcode / SDK 環境では、これらの framework 名や参照方法の違いにより、コンパイルやリンクに失敗する場合があります。
その場合は、SAVEPDF を使わないプログラムと、SAVEPDF を使うプログラムを分けて確認してください。


・Windows ネイティブ
■必要なもの
Python 3
clang
pip
grapheme
必要に応じて openpyxl
■確認
python --version
clang --version
■依存導入
python -m pip install -r requirements.txt
Excel も使う場合
python -m pip install openpyxl
■トランスパイル
python basic_to_c.py sample.bas sample.c
■コンパイル
clang sample.c -o sample.exe
Windows ネイティブでは通常 -lm は不要です。
■実行
.\sample.exe
■注意点
python3 ではなく python を使う方が自然です
日本語や絵文字ファイル名を使う場合は、PowerShell と cmd.exe の両方で確認すると安心です
コンソール表示が文字化けする場合は、生成物を最新版 basic_to_c.py で再生成して再確認してください
SAVEPDF は Windows では失敗前提です


・Linux (Ubuntu 64bit環境)
■必要なもの
Python 3
clang または gcc
pkg-config
libfreetype6-dev
日本語表示確認をするなら fonts-noto-cjk
pip
grapheme
必要に応じて openpyxl
■確認
python3 --version
clang --version
必要なら gcc でも確認
gcc --version
■依存導入
まず Ubuntu 側の前提を入れる
sudo apt update
sudo apt install -y python3 build-essential clang pkg-config libfreetype6-dev fonts-noto-cjk
その上で Python 側の依存を入れる
python3 -m pip install -r requirements.txt
Excel も使う場合
python3 -m pip install openpyxl
■トランスパイル
python3 basic_to_c.py sample.bas sample.c
■コンパイル
clang の場合
clang -Wall -Wextra $(pkg-config --cflags freetype2) sample.c -lm -o sample $(pkg-config --libs freetype2)
gcc の場合
gcc $(pkg-config --cflags freetype2) sample.c -lm -o sample $(pkg-config --libs freetype2)
■実行
./sample
■注意点
SAVEPDF は基本的に使えません
DRAW("FONT") をピクセル配列へ実フォント描画したい場合は、上の `pkg-config` と `libfreetype6-dev` が重要です。
日本語の見た目確認をしたい場合は、`fonts-noto-cjk` を入れておくと確認しやすくなります。
指定した書体名がそのまま見つからない場合でも、Linux / Ubuntu では近いファミリー名・スタイル名を優先して探し、それでも無理なときだけ内蔵 3x5 ドットフォントへフォールバックします。
Windows 11 + WSL2 Ubuntu 実機では、`TEMP=67.5` の英字描画と `日本語` の描画まで確認済みです。
画像、SVG、Word、READTEXT、READDATA などは通常通り使えます
WSL2 Ubuntu で試す場合は、/mnt/c/... 直下よりも home 配下へコピーして実行した方が安定します



・Linux (Ubuntu 32bit環境)
Ubuntu 32bit 環境でも基本手順は 64bit と同じです。
■確認
python3 --version
clang --version
■依存導入
sudo apt update
sudo apt install -y python3 build-essential clang pkg-config libfreetype6-dev fonts-noto-cjk
python3 -m pip install -r requirements.txt
Excel も使う場合
python3 -m pip install openpyxl
■トランスパイル
python3 basic_to_c.py sample.bas sample.c
■コンパイル
clang -Wall -Wextra $(pkg-config --cflags freetype2) sample.c -lm -o sample $(pkg-config --libs freetype2)
または
gcc $(pkg-config --cflags freetype2) sample.c -lm -o sample $(pkg-config --libs freetype2)
■実行
./sample
■補足
ネイティブの 32bit Ubuntu ならこれで十分です。
DRAW("FONT") を実フォント描画で使う場合は、64bit 環境と同様に FreeType 関連パッケージが重要です。
もし 64bit Ubuntu 上で 32bit 実行ファイルを作りたい場合は、-m32 や multilib 環境が必要になりますが、それは通常の BASIC2026 利用とは別の話です。



・Raspberry Pi OS
Raspberry Pi OS でも基本手順は Linux とほぼ同じです。
■前提の前提
まず、以下を満たした状態にしておくと作業が安定します。
Raspberry Pi OS は比較的新しい版（Bookworm 系など）を推奨
ネット接続があり apt update / apt install が実行できる
作業ディレクトリは FAT32 直下ではなく、home 配下などの Linux 書き込み可能領域を使う
SD カード残量に余裕がある
■確認
python3 --version
clang --version
clang がなければ gcc でも構いません。
gcc --version
■依存導入
まずパッケージ側の前提を入れる
sudo apt update
sudo apt install -y python3 build-essential clang pkg-config libfreetype6-dev fonts-noto-cjk
その上で Python 側の依存を入れる
python3 -m pip install -r requirements.txt
Excel も使う場合
python3 -m pip install openpyxl
■トランスパイル
python3 basic_to_c.py sample.bas sample.c
■コンパイル
clang の場合
clang -Wall -Wextra $(pkg-config --cflags freetype2) sample.c -lm -o sample $(pkg-config --libs freetype2)
gcc の場合
gcc $(pkg-config --cflags freetype2) sample.c -lm -o sample $(pkg-config --libs freetype2)
■実行
./sample
■補足
DRAW("FONT") をピクセル配列へ実フォント描画したい場合は、上の `pkg-config` と `libfreetype6-dev` が重要です。
これらがない状態でコンパイルすると、文字色は反映されても字形は従来の 3x5 ドットフォント fallback になります。
日本語の見た目確認をしたい場合は、`fonts-noto-cjk` を入れておくと `DRAW("FONT")` の確認がしやすくなります。
Raspberry Pi 5 / Raspberry Pi OS 実機では、`TEMP=67.5` の英字描画と `日本語` の描画まで確認済みです。
指定した書体名がそのまま見つからない場合でも、Linux / Raspberry Pi OS では近いファミリー名・スタイル名を優先して探し、それでも無理なときだけ内蔵 3x5 ドットフォントへフォールバックします。
Raspberry Pi OS は、BASIC2026 の設計思想である
ローカル処理中心
標準入力・標準出力重視
小規模ツールや画像処理
と相性が良い環境です。
ただし、SDカードの劣化や容量不足は実運用上の注意点です。
保存失敗時の各種 __...ERROR.log は確認しやすい場所に置くのが安全です。



・FreeBSD
FreeBSD でも basic_to_c.py の実行、C への変換、clang によるコンパイル、生成バイナリの実行、JPEG の読み込み・処理・保存は確認済みです。
■確認
python3 --version
clang --version
■依存導入
pkg install -y python3 llvm pkgconf freetype2 fontconfig noto-sans-jp
python3 -m pip install -r requirements.txt
Excel も使う場合
python3 -m pip install openpyxl
■トランスパイル
python3 basic_to_c.py sample.bas sample.c
■コンパイル
clang -Wall -Wextra $(pkg-config --cflags freetype2) sample.c -lm -o sample $(pkg-config --libs freetype2)
■実行
./sample
■注意点
DRAW("FONT") をピクセル配列へ実フォント描画したい場合は、`pkgconf` と `freetype2` が重要です。
日本語表示確認には `noto-sans-jp` が扱いやすく、`Noto Sans JP` を優先候補にすると分かりやすいです。
FreeBSD 実機でも、`TEMP=67.5` の英字描画と `日本語` の描画まで確認済みです。
CREATEIMAGE("QRCODE") による QRコード画像生成も FreeBSD 15 実機で確認済みです。
UTF-8 指定の日本語 QRコードも Android 端末で読み取り確認されています。
ただし、iPhone 標準カメラは長い日本語 QRコードや高バージョン QRコードで読み取り差が出ることがあるため、必要に応じて Android / iPhone の両方で確認してください。
また、CREATEIMAGE("MICROQRCODE") による Micro QR は、iPhone / Android の標準カメラでは読めない、または安定しない場合があります。
Micro QR は一般ユーザー向け配布にはあまり向かず、対応アプリや専用スキャナを前提にした用途向けと考えてください。
フォント package が見つからない場合は、`.ttc` / `.ttf` / `.otf` を `~/.local/share/fonts` に置いて `fc-cache -f -v` してください。
SAVEPDF は非 macOS 環境なので基本的に失敗します


■最適化について
　数値計算・画像処理を行う場合は以下のようなオプションを指定すると処理が高速になります。

推奨:
clang -O2 -lm

高速化重視:
clang -O3 -ffast-math -lm

注意:
-ffast-math は IEEE754 の厳密な演算順序や
NaN/INF の扱いが変化する場合があります。



■最低限の合格確認
どの OS でも、まず以下が通るか確認すると安心です。
Python が動く
basic_to_c.py が動く
C コンパイルが通る
生成実行ファイルが動く
日本語や絵文字が壊れない
画像の読み書きができる
必要なら Excel 読み込みができる
最小確認コマンド例
python3 basic_to_c.py sample.bas sample.c
clang -Wall -Wextra $(pkg-config --cflags freetype2) sample.c -lm -o sample $(pkg-config --libs freetype2)
./sample
Windows ネイティブでは
python basic_to_c.py sample.bas sample.c
clang sample.c -o sample.exe
.\sample.exe


■おすすめの追加確認項目
導入直後には、次も確認しておくと安心です。
日本語ファイル名が文字化けしない
FILES() が期待通り動く
READTEXT で UTF-8 テキストが読める
LOADIMAGE / SAVEIMAGE が通る
PRINT # / PRINT ## で日本語パスへ書ける
READEXCELDATA を使うなら .xlsx が読める
特に Windows と FreeBSD は、日本語パス・絵文字パス・ターミナル表示を別途確認した方がよいです。


■不具合報告時にあると助かる情報
環境ごとの差を追うため、問題が起きた時は以下があると役立ちます。
OS名とバージョン
python --version または python3 --version
clang --version または gcc --version
実行した .bas
生成した .c
画面に出たエラー全文
__BASIC_ERROR.log
各種 __...ERROR.log
必要なら __BASIC_NOTE.txt
■サンプル1（最小サンプル）
10 PRINT "BASIC2026"
20 PRINT "日本語テスト"
30 PRINT "🇯🇵"
トランスパイルして実行し、表示が崩れないか確認します。
■サンプル2（grapheme確認）
10 A$="日本🇯🇵"
20 PRINT LEN(A$)
30 PRINT A$(3)
LEN(A$) が 3、A$(3) が 🇯🇵 になることを確認します。
■サンプル3（画像保存確認）
10 SCREEN img(),32,32 FILL 255,255,255,255
20 PSET img(),10,10,255,0,0,255
30 SAVEIMAGE "out/test.png",img()
40 PRINT "OK"
画像保存できるか確認します。
■サンプル4（READTEXT確認）
10 READTEXT #1,Text$
20 PRINT Text$
実行例
./sample data.txt
■サンプル5（READEXCELDATA確認）
10 READEXCELDATA #1,d{},"Sheet1",W,H,__EXCEL_A1,__EXCEL_VALUE
20 PRINT W
30 PRINT H
40 PRINT d{"A1"}
実行例
./sample sample.xlsx
これを使う場合は openpyxl が必要です。
■補足
BASIC 2026 は、言語機能そのものはかなり移植性が高いですが、実際の導入では次の差があります。
macOS
SAVEPDF が使える。使う場合だけ framework 指定が必要
Windows
python を使う。通常 -lm は不要
Ubuntu / Raspberry Pi OS / FreeBSD
基本は python3 + clang -lm
全環境共通
日本語や絵文字をしっかり扱うなら grapheme を入れる
Excel を読むなら
openpyxl も入れる
実務上は、まず
grapheme を入れる  
必要なら openpyxl を入れる  
最小サンプルをトランスパイルして実行する
という順で確認するのが一番安全です。
