Skip to content

setup.md

Latest commit

 

History

History
234 lines (173 loc) · 12.2 KB

setup.md

File metadata and controls

234 lines (173 loc) · 12.2 KB
Raw

セットアップ手順

リポジトリを clone してから、アプリケーションのビルド手順書（docs/build-howto.md） に着手できるようになるまでの準備手順。

必要なソフトウェア

ソフトウェア 最低バージョン 用途
Git 2.13 以上 サブモジュール取得
CMake 3.13 以上 LLVM・ppack のビルド設定
Ninja 任意 LLVM および picolibc のビルド実行
Meson 0.61 以上 picolibc のビルド設定（既定 libc）
C/C++ コンパイラ GCC 7 / Clang 6 以上 LLVM・ppack のホストコンパイル
Python 3 3.6 以上 gen_pceapi.py (libpceapi スタブ生成)・asm33conv.py (シンプル/スプライト ライブラリの asm 変換) ほか
zlib 開発ヘッダ 任意 ppack のリンク依存
iconv GNU libc 標準 tools/crt/ 内 UTF-8 ソースの SJIS 変換 (使う場合のみ)
autoconf 2.69 / automake 1.15.1 厳密一致 newlib の configure / Makefile.in 再生成 (滅多に使わない)

Debian/Ubuntu 系での一括インストール例：

sudo apt install git cmake ninja-build meson g++ python3 zlib1g-dev

autoconf/automake について: 既定の libc は picolibc（meson ビルド）になったため、autotools は通常のビルドでは一切呼ばれません。以下は make NEWLIB=1 でフォールバックの newlib をビルドし、かつその configure.host 等を編集して再生成する場合のみ必要です。newlib のサブモジュールには再生成済みの configure と Makefile.in が同梱されています。newlib/newlib/configure.host や acinclude.m4 を編集して再生成が必要になった場合のみ、autoconf 2.69 / automake 1.15.1 を 厳密に一致するバージョン で用意する必要があります (newer/older は互換性なし)。Debian 13 など 2.72 / 1.17 が標準の環境では ~/local/autotools/ 等にソースから入れることになります。詳細は docs/build-howto.md の「newlib ポートのメンテナンス」節を参照。

1. サブモジュールの初期化

LLVM 本体と picolibc（既定 libc）、newlib（フォールバック）はサブモジュールとして管理されている。

git submodule update --init llvm picolibc newlib

注意: llvm/ は llvm-project 全体（数 GB）をチェックアウトする。 通信帯域に制約がある場合は --depth 1 を加えてシャロークローンにできる：

git submodule update --init --depth 1 llvm picolibc newlib

ただしシャロークローンでは git log の履歴が欠落するため、 後から git fetch --unshallow で完全取得できる。

2. LLVM のビルド

build/ ディレクトリを作成して cmake を実行する。 build ディレクトリの場所は build/（リポジトリ直下）固定。 他の場所で cmake を実行すると tools/crt/Makefile が壊れる。

mkdir build
cd build

cmake -G Ninja ../llvm/llvm \
  -DCMAKE_BUILD_TYPE=Debug \
  -DLLVM_TARGETS_TO_BUILD="" \
  -DLLVM_EXPERIMENTAL_TARGETS_TO_BUILD="S1C33" \
  -DLLVM_DEFAULT_TARGET_TRIPLE="s1c33-none-piece" \
  -DLLVM_ENABLE_PROJECTS="clang;lld;lldb" \
  -DLLVM_INSTALL_UTILS=ON \
  -DLLVM_USE_LINKER=mold \
  -DCMAKE_C_COMPILER_LAUNCHER=ccache \
  -DCMAKE_CXX_COMPILER_LAUNCHER=ccache

ninja -j4

ビルド完了後、build/bin/ に以下が揃っていることを確認する：

build/bin/clang
build/bin/ld.lld
build/bin/llvm-ar
build/bin/llvm-objcopy
build/bin/llvm-objdump
build/bin/llvm-readelf

-j4 のジョブ数はメモリと CPU コア数に応じて調整してよい。 ただし LLVM のリンクは RAM を大量に消費するため、 8GB 未満の環境では -j2 程度に抑えることを推奨する。

-DCMAKE_BUILD_TYPE=Debug はデバッグビルドのため最終バイナリが大きく なるが、バックエンド開発中は -gline-tables-only や assert() が有効になる ため推奨する。リリースビルドが必要な場合は RelWithDebInfo に変更する。

ビルド高速化・省メモリオプション（任意）

開発ビルド（Debug）を速く・少ないメモリで通したい場合は、上記 cmake に以下を 追加するとよい。リンク段はコンパイルとは別に大量の RAM を消費するため、 ninja -jN の N を下げてもリンク時のメモリ不足は防げない点に注意。

  -DBUILD_SHARED_LIBS=ON \        # 共有ライブラリ化。リンク時 RAM/ディスクを大幅削減（開発ビルド向け）
  -DLLVM_OPTIMIZED_TABLEGEN=ON \  # TableGen だけ最適化ビルド → Debug 全体が速くなる
  -DLLVM_PARALLEL_LINK_JOBS=1 \   # 同時リンク数を制限。リンク段の OOM 対策
  -DLLVM_BUILD_TESTS=OFF \        # テストターゲットを構成しない
  -DLLVM_INCLUDE_TESTS=OFF        # 同上（ビルド対象削減）

-DBUILD_SHARED_LIBS=ON は開発ビルド専用。 生成物が共有ライブラリ群に 依存するため、配布用バイナリ（release-build.sh 等）には付けないこと。

3. ppack のビルド

P/ECE アプリのパッケージファイル（.pex）を生成するツール。 LLVM の cmake キャッシュとは独立して cmake を実行する。

cd tools/ppack
cmake -G Ninja -B _build -DCMAKE_BUILD_TYPE=Release .
ninja -C _build
cp _build/ppack ppack
cd ../..

完成物: tools/ppack/ppack

4. sysroot の構築

コンパイラが参照するヘッダとライブラリを sysroot/s1c33-none-piece/ に配置する。

P/ECE 純正開発環境の c:/usr/piece 以下のうち、include/ と lib/ を sdk/ ディレクトリ以下にコピーすること。標準 C ヘッダは picolibc サブモジュール（既定 libc）から自動的にインストールされる。

4-1. sysroot の一括ビルド（CRT + picolibc + ライブラリ）

スタートアップオブジェクト・picolibc (libc / libm)・picolibc リターゲット層・カーネル API スタブ・compiler-rt をすべてまとめて実行する。 手順 2 の LLVM ビルドが完了している必要がある。

make -C tools/crt

既定 libc = picolibc（2026-06〜）。標準 C / 数学は picolibc が供給する。 newlib をビルドしたい場合は make -C tools/crt NEWLIB=1（フォールバック扱い。 ただしドライバが -lpicortt を無条件リンクするため、newlib で動かすには clang/lib/Driver/ToolChains/PIECE.cpp のリンク群を戻して clang を再ビルド する必要がある）。make と make NEWLIB=1 を切り替えると、sysroot の .libc-mode マーカーが差し替えを検知して libc とヘッダを入れ替える。

以下が自動的に実行される：

  1. picolibc を meson + ninja で build/crt/picolibc（staging prefix build/crt/picolibc-stage）にビルドし、標準 C ヘッダを sysroot/s1c33-none-piece/include/ にインストール
  2. tools/crt/include/ から P/ECE 固有ヘッダ（piece.h、draw.h、s1c33cpu.h 等）をコピー (オリジナルは sdk/include/ だが、ビルドからは参照しない reference material 化済み)
  3. tools/sprite/pclsprite.h と tools/simple/{simple,thread}.h をシンボリックな canonical 元としてコピー
  4. Clang 組み込みと競合するヘッダ（stddef.h、stdarg.h、float.h）を除去
  5. crt0.o・crti.o・libpceapi.a を LLVM でビルド
  6. libclang_rt.builtins-s1c33.a（compiler-rt; fp.lib/idiv.lib の後継）を cmake でビルド
  7. picolibc の libc.a / libm.a を sysroot へインストール（手順 1 の staging からコピー）
  8. libpicortt.a（picolibc リターゲット層: stdout 破棄コンソール + sbrk）を tools/picortt/ のソースからビルド
  9. libmuslib.a（音楽ライブラリ、tools/muslib/ のソースからビルド）と libpceshim.a（libc の __assert_func / rand を小型版で上書きするシム）をビルド・インストール

初回ビルドは picolibc のフルビルドに数分かかる。以降は差分ビルドで tools/crt/ 内の変更のみ再ビルドされる。

以下が生成される：

ファイル 役割
sysroot/s1c33-none-piece/lib/crt0.o アプリヘッダ（pceAppHead @ 0x100000）、BSS ゼロクリア、コールバックラッパー
sysroot/s1c33-none-piece/lib/crti.o pceAppNotify デフォルト実装（弱シンボル・上書き可能）
sysroot/s1c33-none-piece/lib/libpceapi.a カーネル API スタブ + ユーティリティ
sysroot/s1c33-none-piece/lib/libclang_rt.builtins-s1c33.a compiler-rt（FP 演算・整数除算・i64 算術ランタイム）
sysroot/s1c33-none-piece/lib/libcxxrt.a C++ ランタイムスタブ（operator new/delete 等）
sysroot/s1c33-none-piece/lib/libpicortt.a picolibc リターゲット層（stdout 破棄コンソール + sbrk）
sysroot/s1c33-none-piece/lib/libc.a picolibc libc (printf / malloc / strtod / setjmp / 等)
sysroot/s1c33-none-piece/lib/libm.a picolibc libm（数学は libc.a に統合済み。本体は空スタブ）
sysroot/s1c33-none-piece/lib/piece.ld リンカスクリプト (P/ECE メモリマップ + ヒープ配置)

picolibc 移行完了 (2026-06): 既知の EPSON SDK バグ (sin, strtok, pow, strtod, ispunct) を持つ lib.lib / math.lib 等は、まず newlib (Phase 2 Stage A/B) で置き換えられ、2026-06 に picolibc へ移行した。picolibc の tinystdio は printf/sprintf が malloc 非依存で、malloc 未使用アプリには sbrk もリンクされない。現在のリンク行は -lclang_rt.builtins-s1c33 --start-group -lcxxrt -lpceapi -lpicortt -lpceshim -lc -lm --end-group。-mprintf=/-mscanf= で printf/scanf バリアントをリンク時選択できる。詳細は docs/build-howto.md の「リンク順序」節を参照。

注意: crt0.o は -O1 でコンパイルされる。BSS ゼロクリアループの カウンタ変数が [SP+0] に置かれると、カーネルが SP を bss_end に設定した場合に ループが自分のカウンタを上書きしてしまうため、-O0 でのビルドは禁止。 Makefile の CFLAGS_CRT は -O1 が設定されており、変更しないこと。

音楽ライブラリ libmuslib.a は tools/muslib/ のソースから LLVM でビルドされ、上記 make -C tools/crt で sysroot に自動インストールされる。

シンプル / スプライトライブラリ (libsimple.a / libsprite.a) は各々のソースディレクトリで個別に make する：

make -C tools/simple
make -C tools/sprite

どちらも tools/asm33conv/asm33conv.py を経由して .s ファイル中の as33 拡張ニーモニックを LLVM 標準命令に展開する。アプリ側で -lmuslib / -lsimple / -lsprite を明示指定してリンクする。

sysroot 完成後の確認

ls sysroot/s1c33-none-piece/lib/

以下がすべて揃っていれば準備完了：

crt0.o  crti.o  piece.ld
libclang_rt.builtins-s1c33.a
libc.a      libm.a                              ← picolibc
libcxxrt.a  libpceapi.a  libpicortt.a  libpceshim.a  ← C++ ランタイム + カーネル API + picolibc リターゲット + シム
libmuslib.a                                     ← 音楽ライブラリ (-lmuslib で明示指定)
libsimple.a libdefinst.a                        ← シンプルライブラリ (-lsimple で明示指定; make -C tools/simple で生成)
libsprite.a                                     ← スプライトライブラリ (-lsprite で明示指定; make -C tools/sprite で生成)

5. 動作確認

サンプルアプリは app/ 以下に集約されている（app/hello/、app/jien/、app/fpkplay/ など）。

cd app/hello
make

hello_l.pex が生成されれば、ツールチェーンとして一通り動作している。

次のステップ

docs/build-howto.md を参照して、自分のアプリケーションをビルドする。