# mruby 業務運用マニュアル

## 目次

**【基本操作】**
1. [システム概要](#1-システム概要)
2. [インストール・セットアップ手順](#2-インストールセットアップ手順)
3. [基本画面（コマンドラインインターフェース）](#3-基本画面コマンドラインインターフェース)

**【業務フローに沿った機能】**
4. [【STEP1】Rubyスクリプトの作成・実行（mrubyコマンド）](#4-step1rubyスクリプトの作成実行mrubyコマンド)
5. [【STEP2-3】対話的な開発・検証（mirbコマンド）](#5-step2-3対話的な開発検証mirbコマンド)
6. [【STEP3-4】スクリプトのコンパイル・配布（mrbcコマンド）](#6-step3-4スクリプトのコンパイル配布mrbcコマンド)
7. [【STEP4-5】デバッグ・最適化（mrdb / mruby-strip）](#7-step4-5デバッグ最適化mrdb--mruby-strip)

**【サポート機能】**
8. [C言語組み込みAPI](#8-c言語組み込みapi)
9. [mrbgem拡張パッケージ管理](#9-mrbgem拡張パッケージ管理)
10. [ビルド設定のカスタマイズ](#10-ビルド設定のカスタマイズ)

**【運用ガイド】**
11. [日常業務の流れ](#11-日常業務の流れ)
12. [よくある質問と対処法](#12-よくある質問と対処法)
13. [トラブルシューティング](#13-トラブルシューティング)

---

## 1. システム概要

### 1.1 mrubyとは

mrubyは、組み込みシステムやIoTデバイスなどリソース制約のある環境向けに設計された、軽量なRuby言語処理系です。ISO標準（ISO/IEC 30170:2012）に準拠し、C言語アプリケーションへの埋め込みが容易で、クロスプラットフォームに対応しています。

mrubyは画面（GUI/Web UI）を持たないCLIベースの言語エンジン・ライブラリです。ユーザーはコマンドラインツールを通じてスクリプトの実行・コンパイル・デバッグを行うか、C言語アプリケーションにライブラリとして組み込んで利用します。

### 1.2 本システムで行う主要業務

本システムは、主に以下の業務を支援します：

| 業務カテゴリ | 具体的な業務内容 |
|------------|----------------|
| **スクリプト実行** | Rubyスクリプトの直接実行、ワンライナー実行、標準入力からの実行 |
| **対話的開発** | mirb（対話シェル）によるコードの検証・プロトタイピング |
| **コンパイル・配布** | Rubyスクリプトのバイトコードコンパイル（.mrb）、C言語形式への変換 |
| **デバッグ** | mrdbによるブレークポイント設定・ステップ実行・変数検査 |
| **C言語組み込み** | C言語アプリケーションへのmrubyランタイムの統合 |
| **拡張開発** | mrbgemパッケージによる機能拡張・カスタムgem開発 |
| **ビルド管理** | ビルド設定のカスタマイズ、クロスコンパイル、最適化 |

### 1.3 業務フロー概要

本システムにおける業務は、以下の流れで進行します：

```
┌─────────────────────────────────────────────────────────────────┐
│                        業務フロー                                │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  【STEP 1】Rubyスクリプトを作成し、mrubyコマンドで実行           │
│      ↓                                                          │
│  【STEP 2】mirbで対話的にコードを検証・プロトタイピング           │
│      ↓                                                          │
│  【STEP 3】mrbcでスクリプトをバイトコードにコンパイル             │
│      ↓                                                          │
│  【STEP 4】mrdbでデバッグ、mruby-stripで最適化                   │
│      ↓                                                          │
│  【STEP 5】本番環境へのデプロイ・C言語アプリへの組み込み          │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

**役割別の業務概要：**

| 役割 | 主な業務 |
|------|---------|
| **スクリプト開発者** | Rubyスクリプトの作成・実行・デバッグ、mirbでの対話的検証 |
| **組み込みエンジニア** | C言語アプリケーションへのmrubyの統合、C APIを使用したRuby拡張の開発 |
| **ビルド管理者** | ビルド設定のカスタマイズ、クロスコンパイル環境の構築、mrbgemの管理 |

### 1.4 主な機能

| 機能 | 説明 | 業務フローでの位置 |
|------|------|------------------|
| mrubyコマンド | Rubyスクリプトの実行エンジン。ファイル実行・ワンライナー実行・標準入力実行をサポート | STEP 1 |
| mirbコマンド | 対話型シェル（REPL）。コードの即時実行・結果確認が可能 | STEP 2 |
| mrbcコマンド | Rubyスクリプトをバイトコード（.mrb）またはC言語形式にコンパイル | STEP 3 |
| mrdbコマンド | デバッガ。ブレークポイント設定・ステップ実行・変数検査をサポート | STEP 4 |
| mruby-stripコマンド | コンパイル済みバイナリからデバッグ情報を削除しファイルサイズを削減 | STEP 4 |
| mruby-configコマンド | ビルド設定情報の取得。C拡張のコンパイル時に使用 | 随時利用 |
| C言語組み込みAPI | C言語アプリケーションにmrubyを組み込むためのAPI群 | STEP 5 |
| mrbgemパッケージ | 66以上の標準gemによる拡張可能なモジュールシステム | 随時利用 |

### 1.5 ユーザー種別

システムには以下のユーザー種別があります：

| ユーザー種別 | 説明 |
|-------------|------|
| スクリプト開発者 | mrubyでRubyスクリプトを開発・実行するエンドユーザー |
| 組み込みエンジニア | C言語アプリケーションにmrubyを組み込んで利用する開発者 |
| ビルド管理者 | mrubyのビルド環境を構築・管理し、カスタムビルドを作成する管理者 |
| gem開発者 | mrbgemパッケージを開発し、mrubyの機能を拡張する開発者 |

### 1.6 対応プラットフォーム

mrubyは以下のプラットフォームに対応しています：

- **Linux**（GCC / Clang）
- **macOS**（Clang / GCC）
- **Windows**（MinGW / Visual C++）
- **Android**（NDK）
- **WebAssembly**（Emscripten）
- **各種組み込みプラットフォーム**（Arduino、Nintendo Switch、Game Boy Advance 等）

---

## 2. インストール・セットアップ手順

### 2.1 必要な環境

mrubyをビルドするには、以下の環境が必要です：

| 項目 | 要件 |
|------|------|
| Cコンパイラ | GCCまたはClang |
| Ruby | バージョン2.5以上（ビルドシステム実行用） |
| ar | アーカイバ（通常OSに標準搭載） |
| Git | オプション：mrbgemの取得に使用 |

### 2.2 インストール方法

1. リポジトリを取得します

```bash
git clone https://github.com/mruby/mruby.git
cd mruby
```

2. デフォルト設定でビルドします

```bash
rake
```

3. ビルドが成功すると、`build/host/bin/` 配下に実行ファイルが生成されます

```
build/host/bin/mruby        # インタプリタ
build/host/bin/mirb          # 対話シェル
build/host/bin/mrbc          # コンパイラ
build/host/bin/mrdb          # デバッガ
build/host/bin/mruby-strip   # バイナリ最適化
build/host/bin/mruby-config  # 設定情報
```

4. システムにインストールする場合（オプション）

```bash
rake install
# または、インストール先を指定
PREFIX=/opt/mruby rake install
```

### 2.3 ビルドの確認

```bash
# テストを実行してビルドの正常性を確認
rake all test
```

> **注意**: ビルドに失敗する場合は、Cコンパイラとrubyのバージョンを確認してください。`ruby --version` でRuby 2.5以上、`gcc --version` または `clang --version` でコンパイラの存在を確認できます。

---

## 3. 基本画面（コマンドラインインターフェース）

mrubyは画面（GUI）を持たず、全ての操作はコマンドラインインターフェース（CLI）から行います。

### 3.1 スクリプト開発者向けCLI

スクリプト開発者が主に使用するコマンド：

| コマンド | 用途 | 使用頻度 |
|---------|------|---------|
| `mruby` | スクリプト実行 | 高 |
| `mirb` | 対話的コード検証 | 高 |
| `mrbc` | スクリプトのコンパイル | 中 |
| `mrdb` | デバッグ | 中 |

### 3.2 組み込みエンジニア向けCLI

組み込みエンジニアが主に使用するコマンド：

| コマンド | 用途 | 使用頻度 |
|---------|------|---------|
| `mrbc` | スクリプトのC言語形式への変換 | 高 |
| `mruby-config` | ビルド設定の取得 | 高 |
| `mruby-strip` | バイナリの最適化 | 中 |
| `rake` | ビルド実行 | 高 |

---

## 4. 【STEP1】Rubyスクリプトの作成・実行（mrubyコマンド）

> **業務フローでの位置**: 開発者がRubyスクリプトを作成し、mrubyコマンドで実行するステップです。

### 4.1 スクリプトファイルを実行する

**業務シーン**: Rubyスクリプトを作成し、動作を確認したい場合

**操作手順**:

1. テキストエディタでRubyスクリプトを作成します（例：`hello.rb`）

```ruby
puts "Hello, mruby!"
```

2. ターミナルで以下のコマンドを実行します

```bash
mruby hello.rb
```

3. 実行結果が標準出力に表示されます

```
Hello, mruby!
```

### 4.2 ワンライナーを実行する

**業務シーン**: 短いコードを素早く試したい場合

**操作手順**:

1. `-e` オプションでコードを直接指定して実行します

```bash
mruby -e 'puts "Hello, mruby!"'
```

2. 複数の `-e` オプションを組み合わせることもできます

```bash
mruby -e 'x = 10' -e 'puts x * 2'
```

### 4.3 構文チェックのみ実行する

**業務シーン**: スクリプトの構文に問題がないか事前確認したい場合

**操作手順**:

1. `-c` オプションを指定して構文チェックを実行します

```bash
mruby -c script.rb
```

2. 構文エラーがなければ「Syntax OK」と表示されます。エラーがある場合はエラー内容と行番号が表示されます。

### 4.4 コンパイル済みバイナリを実行する

**業務シーン**: mrbcでコンパイルされた.mrbファイルを実行したい場合

**操作手順**:

1. `-b` オプションを指定してバイナリファイルを実行します

```bash
mruby -b script.mrb
```

### 4.5 コマンドライン引数を渡す

**業務シーン**: スクリプトに引数を渡して実行したい場合

**操作手順**:

1. スクリプトファイル名の後に引数を記述します

```bash
mruby script.rb arg1 arg2 arg3
```

2. スクリプト内では `ARGV` 定数で引数を参照できます

```ruby
ARGV.each { |arg| puts arg }
```

### 4.6 mrubyコマンドのオプション一覧

| オプション | 説明 |
|-----------|------|
| `-b` | コンパイル済みバイナリ（.mrb）を実行 |
| `-c` | 構文チェックのみ実行（実行しない） |
| `-d` | デバッグフラグを設定（`$DEBUG` を `true` に） |
| `-e 'command'` | ワンライナーのスクリプトを実行 |
| `-r library` | スクリプト実行前にライブラリを読み込み |
| `-v` | バージョン表示後、詳細モードで実行 |
| `--verbose` | 詳細モードで実行 |
| `--version` | バージョンのみ表示 |
| `--copyright` | 著作権表示 |

> **注意点・Tips**: mrubyはCRuby（MRI）とほぼ同じ構文をサポートしますが、一部未対応の機能があります。`require` は標準では使用できません（`-r` オプションまたはmrbgemで対応）。

---

## 5. 【STEP2-3】対話的な開発・検証（mirbコマンド）

> **業務フローでの位置**: 開発者がコードの動作を対話的に確認し、プロトタイピングを行うステップです。

### 5.1 mirbを起動する

**業務シーン**: コードの動作を即座に確認しながら開発したい場合

**操作手順**:

1. ターミナルで以下のコマンドを実行します

```bash
mirb
```

2. プロンプト `mirb - Pair mruby with mirb >` が表示されたら、Rubyコードを入力します

```
mirb - Pair mruby with mirb
 > 1 + 2
 => 3
 > "hello".upcase
 => "HELLO"
```

3. 終了するには `quit` または `exit` を入力します

### 5.2 複数行コードを入力する

**業務シーン**: メソッド定義やブロック構文など、複数行のコードを試したい場合

**操作手順**:

1. 通常通りコードを入力します。構文が完了していない場合、mirbは自動的に追加入力を待ちます

```
 > def greet(name)
 *   puts "Hello, #{name}!"
 * end
 => :greet
 > greet("mruby")
Hello, mruby!
 => nil
```

### 5.3 タブ補完を使用する

**業務シーン**: メソッド名やキーワードの入力を効率化したい場合

**操作手順**:

1. 入力途中で `Tab` キーを押すと、候補が表示されます

- メソッド補完：`"hello".up` + Tab → `upcase`, `upcase!`, `upto`
- グローバル変数補完：`$` + Tab → 候補一覧
- 定数・クラス補完：大文字入力 + Tab → 候補一覧
- Rubyキーワード補完：途中入力 + Tab → 候補一覧

### 5.4 直前の実行結果を参照する

**業務シーン**: 前の計算結果を次の式で使いたい場合

**操作手順**:

1. `_` 変数に最後の実行結果が自動保存されます

```
 > 2 + 3
 => 5
 > _ * 10
 => 50
```

### 5.5 mirbのオプション一覧

| オプション | 説明 |
|-----------|------|
| `-d` | `$DEBUG` を `true` に設定 |
| `-r library` | 起動前にライブラリを読み込み（複数指定可） |
| `-v` | バージョン表示後、詳細モードで起動 |
| `--verbose` | 詳細モード |
| `--version` | バージョンのみ表示 |

> **注意点・Tips**: mirbは `Ctrl+C` で現在の入力をキャンセルできます。環境変数 `MRUBY_MIRB_READLINE` でエディタバックエンドを選択できます（`readline`, `libedit`, `linenoise`, `none`）。

---

## 6. 【STEP3-4】スクリプトのコンパイル・配布（mrbcコマンド）

> **業務フローでの位置**: 開発したスクリプトをバイトコードにコンパイルし、配布可能な形式にするステップです。

### 6.1 バイトコード形式にコンパイルする

**業務シーン**: スクリプトを事前コンパイルして実行速度を向上させたい、またはソースコードを公開せずに配布したい場合

**操作手順**:

1. 以下のコマンドでスクリプトをコンパイルします

```bash
mrbc script.rb
```

2. 同じディレクトリに `script.mrb` が生成されます

3. コンパイル済みバイナリは `mruby -b` で実行できます

```bash
mruby -b script.mrb
```

### 6.2 出力ファイル名を指定する

**業務シーン**: 出力先やファイル名をカスタマイズしたい場合

**操作手順**:

1. `-o` オプションで出力ファイルを指定します

```bash
mrbc -o output.mrb script.rb
```

### 6.3 複数ファイルをマージしてコンパイルする

**業務シーン**: 複数のスクリプトファイルを1つのバイナリにまとめたい場合

**操作手順**:

1. `-o` オプションで出力ファイルを指定し、複数の入力ファイルを指定します

```bash
mrbc -o combined.mrb file1.rb file2.rb file3.rb
```

> **注意**: 複数ファイルを指定する場合は `-o` オプションが必須です。

### 6.4 C言語形式で出力する

**業務シーン**: C言語アプリケーションにスクリプトを組み込みたい場合

**操作手順**:

1. `-B` オプションでシンボル名を指定してC言語形式で出力します

```bash
mrbc -Bscript_bytecode script.rb
```

2. `script.c` が生成されます。このファイルにはバイトコードがCの配列として格納されます

3. C言語アプリケーションから以下のように使用します

```c
#include <mruby.h>
#include <mruby/irep.h>

extern const uint8_t script_bytecode[];

int main(void) {
  mrb_state *mrb = mrb_open();
  mrb_load_irep(mrb, script_bytecode);
  mrb_close(mrb);
  return 0;
}
```

### 6.5 デバッグ情報付きでコンパイルする

**業務シーン**: mrdbでデバッグを行う予定がある場合

**操作手順**:

1. `-g` オプションでデバッグ情報を含めてコンパイルします

```bash
mrbc -g script.rb
```

> **注意**: `-g` オプションなしでコンパイルした.mrbファイルは、mrdbで行番号指定のブレークポイントが設定できません。

### 6.6 mrbcコマンドのオプション一覧

| オプション | 説明 |
|-----------|------|
| `-c` | 構文チェックのみ |
| `-o <outfile>` | 出力ファイルを指定（複数ファイル時は必須） |
| `-v` | バージョン表示後、詳細モード |
| `-g` | デバッグ情報を含める |
| `-B <symbol>` | C言語形式で出力、シンボル名を指定 |
| `-S` | C構造体形式で出力（`-B` と組み合わせ） |
| `-s` | シンボルを静的変数として定義 |
| `--remove-lv` | ローカル変数名を削除 |
| `--no-ext-ops` | 拡張オペコード使用を禁止 |
| `--no-optimize` | ピープホール最適化を無効化 |

---

## 7. 【STEP4-5】デバッグ・最適化（mrdb / mruby-strip）

> **業務フローでの位置**: 開発者がスクリプトのデバッグを行い、本番配布用にバイナリを最適化するステップです。

### 7.1 mrdbでデバッグする

**業務シーン**: スクリプトの動作を詳細に確認し、バグを特定したい場合

**前提条件**: mrdbでデバッグするには、事前にスクリプトをデバッグ情報付きでコンパイルする必要があります（.rbファイルの場合は不要）。

**操作手順**:

1. mrdbを起動します

```bash
# Rubyソースファイルの場合
mrdb script.rb

# コンパイル済みバイナリの場合（要-g付きコンパイル）
mrbc -g script.rb
mrdb -b script.mrb
```

2. ブレークポイントを設定します

```
(script.rb:1) break 10           # 10行目にブレークポイント
(script.rb:1) break MyClass:run  # メソッドにブレークポイント
```

3. プログラムを実行します

```
(script.rb:1) run
```

4. ブレークポイントに到達したら、変数を検査します

```
(script.rb:10) info locals    # ローカル変数を表示
(script.rb:10) print x        # 変数xの値を表示
(script.rb:10) eval x + y     # 式を評価
```

5. ステップ実行で1行ずつ進めます

```
(script.rb:10) step    # ステップイン（関数内に入る）
(script.rb:10) next    # ステップオーバー（関数をスキップ）
```

6. 実行を継続します

```
(script.rb:11) continue    # 次のブレークポイントまで実行
```

7. デバッガを終了します

```
(script.rb:15) quit
```

### 7.2 mrdbのコマンド一覧

| コマンド | 略称 | 説明 |
|---------|------|------|
| `break [file:]linenum` | `b` | 行番号でブレークポイント設定 |
| `break [class:]method` | `b` | メソッドでブレークポイント設定 |
| `continue [N]` | `c` | 実行継続（N番目のブレークポイントまで） |
| `delete [no]` | `d` | ブレークポイント削除 |
| `disable [no]` | `dis` | ブレークポイント無効化 |
| `enable [no]` | `en` | ブレークポイント有効化 |
| `eval <expr>` | `ev` | 式を評価して表示 |
| `help [cmd]` | `h` | ヘルプ表示 |
| `info breakpoints [no]` | `i b` | ブレークポイント情報表示 |
| `info locals` | `i l` | ローカル変数表示 |
| `list [file:]first[,last]` | `l` | ソースコード表示 |
| `print <expr>` | `p` | 式の値を表示 |
| `quit` | `q` | デバッガ終了 |
| `run` | `r` | プログラム実行 |
| `step` | `s` | ステップイン |
| `next` | `n` | ステップオーバー |

### 7.3 mruby-stripでバイナリを最適化する

**業務シーン**: 本番環境や組み込み環境向けにファイルサイズを削減したい場合

**操作手順**:

1. コンパイル済み.mrbファイルからデバッグ情報を削除します

```bash
mruby-strip script.mrb
```

2. ローカル変数名も削除してさらにサイズを削減する場合

```bash
mruby-strip -l script.mrb
```

3. 複数ファイルを一括で最適化する場合

```bash
mruby-strip file1.mrb file2.mrb file3.mrb
```

> **注意**: mruby-stripはファイルをインプレース（上書き）で修正します。ストリップ後のファイルはmrdbで行番号指定のブレークポイントが設定できなくなります。元のファイルが必要な場合は事前にバックアップしてください。

### 7.4 開発から配布までのワークフロー

```
スクリプト開発 → デバッグ → コンパイル → 最適化 → 配布

script.rb
    ↓ [mruby / mirb で動作確認]
    ↓
    ↓ [mrdb でデバッグ]
    ↓
    ↓ [mrbc -g でデバッグ情報付きコンパイル]
script.mrb (デバッグ情報付き)
    ↓ [mrdb -b でバイナリデバッグ]
    ↓
    ↓ [mruby-strip でデバッグ情報削除]
script.mrb (配布用・軽量)
    ↓ [mruby -b で本番実行]
```

---

## 8. C言語組み込みAPI

### 8.1 基本的な組み込み手順

**業務シーン**: C言語アプリケーションにRubyスクリプト実行機能を組み込みたい場合

**操作手順**:

1. mrubyをビルドしてライブラリを生成します

```bash
cd mruby
rake
```

2. 生成されたライブラリとヘッダファイルを使用してC言語プログラムを記述します

```c
#include <mruby.h>
#include <mruby/compile.h>

int main(void) {
    /* mrubyの初期化 */
    mrb_state *mrb = mrb_open();
    if (!mrb) {
        fprintf(stderr, "mruby initialization failed\n");
        return 1;
    }

    /* Rubyコードの実行 */
    mrb_load_string(mrb, "puts 'Hello from mruby!'");

    /* 例外チェック */
    if (mrb->exc) {
        mrb_print_error(mrb);
    }

    /* mrubyの終了 */
    mrb_close(mrb);
    return 0;
}
```

3. コンパイルとリンクを行います

```bash
gcc -I build/host/include -L build/host/lib \
    -o myapp myapp.c -lmruby -lm
```

### 8.2 主なC API関数

| 関数 | 説明 |
|------|------|
| `mrb_open()` | mrubyランタイムの初期化（gem読み込み含む） |
| `mrb_open_core()` | コア機能のみの初期化（軽量） |
| `mrb_close(mrb)` | ランタイムの終了とメモリ解放 |
| `mrb_load_string(mrb, code)` | 文字列のRubyコードを実行 |
| `mrb_load_file(mrb, fp)` | ファイルからRubyコードを読み込み実行 |
| `mrb_define_class(mrb, name, super)` | 新しいクラスを定義 |
| `mrb_define_method(mrb, cls, name, func, aspec)` | メソッドを定義 |
| `mrb_funcall(mrb, obj, method, argc, ...)` | Rubyメソッドを呼び出す |
| `mrb_get_args(mrb, format, ...)` | メソッドの引数を取得 |

### 8.3 GCアリーナの管理

**業務シーン**: ループ内でmrubyコードを繰り返し実行する場合

> **重要**: `mrb_load_string()` などのRubyコード実行関数は内部的にGCアリーナエントリを消費します。ループ内で使用する場合は、アリーナのsave/restoreで囲む必要があります。

```c
for (int i = 0; i < 1000; i++) {
    int ai = mrb_gc_arena_save(mrb);
    mrb_load_string(mrb, buffer);
    mrb_gc_arena_restore(mrb, ai);
}
```

---

## 9. mrbgem拡張パッケージ管理

### 9.1 gemboxで機能セットを選択する

**業務シーン**: ビルドに含めるmrbgemの組み合わせを管理したい場合

**操作手順**:

1. ビルド設定ファイル（`build_config.rb`）を編集します

```ruby
MRuby::Build.new do |conf|
  conf.toolchain :gcc

  # デフォルトの機能セットを読み込む
  conf.gembox 'default'
end
```

2. 利用可能な主なgembox:

| gembox | 内容 |
|--------|------|
| `default` | 標準的な機能セット（ほとんどのユースケースに対応） |
| `full-core` | 全ての標準gemを含む完全版 |
| `stdlib` | 標準ライブラリ拡張（Array、Hash、String等の拡張メソッド） |
| `stdlib-ext` | 追加の標準拡張 |
| `stdlib-io` | IO関連（File、Dir、Socket等） |
| `math` | 数学関数（Math、Complex、Rational等） |
| `metaprog` | メタプログラミング（eval、Method等） |

### 9.2 個別のgemを追加する

**操作手順**:

1. ビルド設定ファイルに `conf.gem` を追加します

```ruby
MRuby::Build.new do |conf|
  conf.toolchain :gcc
  conf.gembox 'default'

  # コア内蔵gem
  conf.gem :core => 'mruby-time'

  # GitHubから取得
  conf.gem :github => 'mattn/mruby-onig-regexp'

  # ローカルパスから
  conf.gem '/path/to/my-mrbgem'
end
```

2. `rake` でリビルドします

### 9.3 カスタムgemを開発する

**業務シーン**: mrubyに独自の機能を追加したい場合

**操作手順**:

1. gem用のディレクトリ構造を作成します

```
mruby-my-gem/
├── mrbgem.rake        # gem仕様定義
├── mrblib/            # Rubyソースコード
│   └── my_gem.rb
├── src/               # Cソースコード（オプション）
│   └── my_gem.c
└── test/              # テストコード
    └── my_gem_test.rb
```

2. `mrbgem.rake` にgem仕様を定義します

```ruby
MRuby::Gem::Specification.new('mruby-my-gem') do |spec|
  spec.license = 'MIT'
  spec.author = 'Your Name'
  spec.summary = 'My custom mrbgem'
  spec.version = '1.0.0'

  # 依存関係（必要に応じて）
  spec.add_dependency('mruby-time')
end
```

3. ビルド設定にgemを追加してビルドします

---

## 10. ビルド設定のカスタマイズ

### 10.1 カスタムビルド設定ファイルを使用する

**業務シーン**: プロジェクト固有のビルド設定を作成したい場合

**操作手順**:

1. 設定ファイルを作成します（例：`my_build_config.rb`）

```ruby
MRuby::Build.new do |conf|
  conf.toolchain :gcc

  # デバッグモードを有効化
  conf.enable_debug

  # gemboxの選択
  conf.gembox 'default'

  # テスト有効化
  conf.enable_test
  conf.enable_bintest
end
```

2. 設定ファイルを指定してビルドします

```bash
MRUBY_CONFIG=./my_build_config.rb rake
```

### 10.2 主なビルド設定マクロ

| マクロ | 説明 | 用途 |
|--------|------|------|
| `MRB_NO_STDIO` | 標準入出力機能を除外 | 組み込みシステム向け最小ビルド |
| `MRB_NO_FLOAT` | 浮動小数点機能を除外 | FPUのない環境向け |
| `MRB_USE_FLOAT32` | 32ビット浮動小数点を使用 | メモリ節約 |
| `MRB_INT32` | 32ビット整数を使用 | 32ビット環境 |
| `MRB_INT64` | 64ビット整数を使用 | 64ビット環境（デフォルト） |
| `MRB_UTF8_STRING` | UTF-8文字列サポートを有効化 | 多言語対応 |
| `MRB_GC_STRESS` | GCストレステスト | デバッグ用 |
| `MRB_DEBUG` | アサーション有効化 | デバッグ用 |
| `MRB_USE_DEBUG_HOOK` | デバッグフック有効化 | mrdb使用時 |

### 10.3 クロスコンパイルを設定する

**業務シーン**: 組み込みターゲット向けにmrubyをビルドしたい場合

**操作手順**:

1. ビルド設定ファイルに `MRuby::CrossBuild` を追加します

```ruby
MRuby::CrossBuild.new('my-target') do |conf|
  conf.toolchain :gcc

  # クロスコンパイラの指定
  conf.cc.command = 'arm-linux-gnueabihf-gcc'
  conf.linker.command = 'arm-linux-gnueabihf-gcc'
  conf.archiver.command = 'arm-linux-gnueabihf-ar'

  conf.gembox 'default'
end
```

2. ビルドを実行します

```bash
MRUBY_CONFIG=./my_cross_config.rb rake
```

3. 成果物は `build/my-target/` ディレクトリに生成されます

### 10.4 組み込みプラットフォーム設定例

mrubyには多数のクロスコンパイル設定がプリセットされています：

| 設定ファイル | 対象プラットフォーム |
|-------------|-------------------|
| `cross-mingw.rb` | Windows（MinGW） |
| `android_arm64_v8a.rb` | Android ARM64 |
| `emscripten.rb` | WebAssembly |
| `ArduinoDue.rb` | Arduino Due |
| `minimal.rb` | 最小構成（stdio除外） |

```bash
# 例：最小構成でビルド
MRUBY_CONFIG=minimal rake
```

---

## 11. 日常業務の流れ

本セクションでは、業務フローに沿った日常業務の流れを説明します。

```
業務フロー概要（再掲）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
【STEP 1】Rubyスクリプトを作成し、mrubyコマンドで実行 → 4章参照
    ↓
【STEP 2】mirbで対話的にコードを検証・プロトタイピング → 5章参照
    ↓
【STEP 3】mrbcでスクリプトをバイトコードにコンパイル → 6章参照
    ↓
【STEP 4】mrdbでデバッグ、mruby-stripで最適化 → 7章参照
    ↓
【STEP 5】本番環境へのデプロイ・C言語アプリへの組み込み → 8章参照
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

### 11.1 【スクリプト開発者】STEP1: スクリプトの作成と実行

業務開始時に、Rubyスクリプトを作成して動作を確認します。

1. テキストエディタでスクリプトファイルを作成します
2. `mruby script.rb` で実行して動作を確認します
3. 期待通りに動作しない場合は、mirbで部分的にコードを検証します（STEP2へ）
4. 必要に応じて `-d` オプションでデバッグモードで実行します

### 11.2 【スクリプト開発者】STEP2: 対話的な検証

コードの一部を対話的に確認し、プロトタイピングを行います。

1. `mirb` を起動します
2. 検証したいコードを入力して即座に結果を確認します
3. 問題がないことを確認したら、スクリプトファイルに反映します
4. `quit` でmirbを終了します

### 11.3 【組み込みエンジニア】STEP3: コンパイルと配布準備

確認済みのスクリプトをバイトコードにコンパイルします。

1. `mrbc script.rb` でバイトコードにコンパイルします
2. C言語組み込み用の場合は `mrbc -Bsymbol script.rb` でC形式に変換します
3. `mruby -b script.mrb` でコンパイル済みバイナリの動作を確認します

### 11.4 【スクリプト開発者】STEP4-5: デバッグと最適化

スクリプトのデバッグを行い、配布用に最適化します。

1. 問題がある場合は `mrdb script.rb` でデバッグセッションを開始します
2. ブレークポイントを設定し、変数の状態を検査します
3. デバッグが完了したら `mrbc script.rb` で再コンパイルします
4. 本番配布用に `mruby-strip script.mrb` でデバッグ情報を削除します
5. 最終確認として `mruby -b script.mrb` で動作を検証します

---

## 12. よくある質問と対処法

### 12.1 ビルドに関するQ&A

**Q: `rake` でビルドが失敗します**

A: 以下を確認してください：
- Rubyがインストールされているか：`ruby --version`（2.5以上が必要）
- Cコンパイラがインストールされているか：`gcc --version` または `clang --version`
- `rake` コマンドが利用可能か：`gem install rake` でインストール可能

**Q: 特定のgemだけをビルドに含めたい**

A: ビルド設定ファイルで `conf.gembox` の代わりに個別の `conf.gem` を使用してください。

```ruby
MRuby::Build.new do |conf|
  conf.toolchain :gcc
  conf.gem :core => 'mruby-sprintf'
  conf.gem :core => 'mruby-time'
end
```

### 12.2 実行に関するQ&A

**Q: `require` が使えません**

A: mrubyでは標準のCRubyとは異なり `require` は使用できません。以下の代替方法があります：
- `mruby -r library` オプションでライブラリを事前読み込み
- mrbgemとしてライブラリを組み込む
- 複数ファイルを `mrbc -o` でマージしてコンパイル

**Q: mrubyとCRuby（MRI）の違いは何ですか？**

A: 主な違いは以下の通りです：
- `require` / `require_relative` が標準で使えない
- 一部のコアライブラリが未実装（mrbgemで補完可能）
- メモリ使用量が大幅に少ない
- 組み込みに特化した設計
- ISO標準に準拠した言語仕様

### 12.3 デバッグに関するQ&A

**Q: mrdbでブレークポイントが設定できません**

A: `.mrb` ファイルにデバッグ情報が含まれていない可能性があります。`mrbc -g` オプションでデバッグ情報付きでコンパイルしてください。`.rb` ファイルを直接デバッグする場合はこの制限はありません。

---

## 13. トラブルシューティング

### 13.1 エラーメッセージと対処法

| エラーメッセージ | 原因 | 対処法 |
|----------------|------|--------|
| `mruby: No program input` | 実行するスクリプトが指定されていない | ファイル名を指定するか、`-e` オプションでコードを指定する |
| `mruby: Cannot open program file` | 指定されたファイルが見つからない | ファイルパスを確認する |
| `SyntaxError` | スクリプトに構文エラーがある | `mruby -c script.rb` で構文チェックを行い、エラー箇所を修正する |
| `RuntimeError` | 実行時エラーが発生した | エラーメッセージとスタックトレースを確認し、該当コードを修正する |
| `NoMethodError` | 存在しないメソッドを呼び出した | メソッド名のタイポを確認。必要なmrbgemが含まれているかビルド設定を確認する |
| `mrbc: Cannot open output file` | 出力先ディレクトリが存在しない | 出力先のディレクトリを事前に作成する |
| `NameError: uninitialized constant` | 未定義の定数を参照した | 必要なmrbgemがビルドに含まれているか確認する |

### 13.2 よくあるトラブルと解決方法

**ビルドが途中で止まる**

1. `rake clean` でビルド成果物を削除
2. `rake` で再ビルド
3. それでも解決しない場合は `rake deep_clean` で完全にクリーンアップしてから再ビルド

**mirbが即座に終了する**

1. readlineライブラリが正しくリンクされているか確認
2. 環境変数 `MRUBY_MIRB_READLINE=none` を設定してプレーンモードで試す

**メモリリークが発生する（C言語組み込み時）**

1. `mrb_close()` が確実に呼ばれていることを確認
2. ループ内でのRubyコード実行時に `mrb_gc_arena_save()` / `mrb_gc_arena_restore()` でアリーナを管理しているか確認
3. カスタムデータ型のデストラクタが正しく定義されているか確認

### 13.3 サポートへの連絡方法

mrubyに関する問題報告や質問は、以下の方法で行えます：

- **GitHubリポジトリ**: https://github.com/mruby/mruby
  - Issueの作成による問題報告・機能リクエスト
  - Pull Requestによるコード貢献
- **公式ドキュメント**: `doc/` ディレクトリ内のガイドドキュメント
- **ライセンス**: MIT License

---

## 改訂履歴

| 版数 | 改訂日 | 改訂内容 |
|-----|--------|---------|
| 1.0 | 2026-02-22 | 初版作成 |

---

*本マニュアルは、mrubyのエンドユーザー向け業務運用マニュアルです。*
*mrubyのバージョンアップにより、コマンドオプションや動作が変更される場合があります。*
