Update version to 4.0.0RC4.

Co-authored-by: Claude <noreply@anthropic.com>

.codespellrc

@@ -0,0 +1,3 @@
+[codespell]
+ignore-words = .github/linters/codespell.txt
+skip = ./build,./doc/api,./doc/capi

.dockerignore

@@ -0,0 +1,14 @@
+.DS_Store
+.idea
+.vscode
+.yardoc
+*.bak
+*.iml
+*.ipr
+*.swp
+*.tmp
+bin
+build
+doc/api
+doc/capi
+node_modules

.editorconfig

@@ -8,37 +8,23 @@ root = true
 [*]
 charset = utf-8
 end_of_line = lf
-indent_size = 8
-indent_style = tab
+indent_size = 2
+indent_style = space
 insert_final_newline = true
 tab_width = 8
+trim_trailing_whitespace = true
 
 [{Makefile,Makefile.*,makefile,*.mk}]
-trim_trailing_whitespace = true
+indent_style = tab
 #max_line_length = 80
 
-[*.{c,cc,C,cxx,cpp,h,hh,H,hxx,hpp,inc,y}]
-indent_size = 2
-indent_style = space
-trim_trailing_whitespace = true
+#[*.{c,cc,C,cxx,cpp,h,hh,H,hxx,hpp,inc,y}]
 #max_line_length = 120
 
-[{*.rb,Rakefile,rakefile,*.rake,*.gemspec,*.gembox}]
-indent_size = 2
-indent_style = space
-trim_trailing_whitespace = true
+#[{*.rb,Rakefile,rakefile,*.rake,*.gemspec,*.gembox}]
 #max_line_length = 120
 
 # limitation to US-ASCII
 [*.bat]
 end_of_line = crlf
-indent_style = space
 #max_line_length = 80
-
-[*.{yaml,yml}]
-indent_size = 2
-indent_style = space
-
-[*.md]
-indent_size = 2
-indent_style = space

.git-blame-ignore-revs

@@ -4,3 +4,5 @@
 61e8a540869c57ebddac53cf9d243db407d57fff
 # reindent parse.y
 650ffb9d8410e1ae2206890ef6e2a8643c600454
+# reindent build_config/playstationportable.rb
+90ab714fda6825c4e951d47d7e6ecff033dd14e3

.gitattributes

@@ -0,0 +1,4 @@
+*       text=auto eol=lf
+*.bat   text eol=crlf
+*.cmd   text eol=crlf
+*.png   binary

.github/dependabot.yml

@@ -1,10 +1,33 @@
-# Basic set up
-
+# https://docs.github.com/en/code-security/dependabot/dependabot-version-updates
 version: 2
 updates:
-
-  # Maintain dependencies for GitHub Actions
+  - package-ecosystem: "bundler"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    groups:
+      bundler-dependencies:
+        patterns:
+          - "*"
+    cooldown:
+      default-days: 7
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:
       interval: "daily"
+    groups:
+      github-actions-dependencies:
+        patterns:
+          - "*"
+    cooldown:
+      default-days: 7
+  - package-ecosystem: "pre-commit"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    groups:
+      pre-commit-hooks:
+        patterns:
+          - "*"
+    cooldown:
+      default-days: 7

.github/labeler.yml

@@ -0,0 +1,81 @@
+# https://github.com/actions/labeler
+benchmark:
+  - any:
+      - changed-files:
+          - any-glob-to-any-file:
+              - benchmark/**/*
+build:
+  - any:
+      - changed-files:
+          - any-glob-to-any-file:
+              - Dockerfile
+              - Doxyfile
+              - Makefile
+              - Rakefile
+              - appveyor.yml
+              - build_config.rb
+              - build_config/**/*
+              - docker-compose.yml
+              - lib/**/*
+              - minirake
+              - tasks/**/*
+              - .codespellrc
+              - .dockerignore
+              - .pre-commit-config.yaml
+              - .prettierignore
+              - .prettierrc
+              - .travis.yml
+              - .yardopts
+core:
+  - any:
+      - changed-files:
+          - any-glob-to-any-file:
+              - include/**/*
+              - mrblib/**/*
+              - src/**/*
+              - test/**/*
+doc:
+  - any:
+      - changed-files:
+          - any-glob-to-any-file:
+              - CONTRIBUTING.md
+              - LEGAL
+              - LICENSE
+              - NEWS
+              - README.md
+              - SECURITY.md
+              - TODO.md
+              - doc/**/*
+              - examples/**/*
+github:
+  - any:
+      - changed-files:
+          - any-glob-to-any-file:
+              - .github/**/*
+miscellaneous:
+  - any:
+      - changed-files:
+          - any-glob-to-any-file:
+              - .editorconfig
+              - .git-blame-ignore-revs
+              - .gitattributes
+              - .gitignore
+              - AUTHORS
+              - Gemfile
+              - Gemfile.lock
+              - mruby-source.gemspec
+mrbgems:
+  - any:
+      - changed-files:
+          - any-glob-to-any-file:
+              - mrbgems/**/*
+oss-fuzz:
+  - any:
+      - changed-files:
+          - any-glob-to-any-file:
+              - oss-fuzz/**/*
+tools:
+  - any:
+      - changed-files:
+          - any-glob-to-any-file:
+              - tools/**/*

.github/linters/.hadolint.yaml

@@ -0,0 +1,4 @@
+failure-threshold: info
+ignored:
+  - DL3008 # https://github.com/hadolint/hadolint/wiki/DL3008
+  - DL3013 # https://github.com/hadolint/hadolint/wiki/DL3013

.github/linters/.ls-lint.yml

@@ -0,0 +1,12 @@
+ls:
+  .c: snake_case
+  .cpp: snake_case
+  .h: snake_case
+  .json: snake_case
+  .rb: snake_case
+  .yaml: regex:\.?[a-z]+(-[a-z]+)*
+  .yml: regex:\.?[a-z]+(-[a-z]+)*
+
+ignore:
+  - build_config
+  - mrbgems/mruby-compiler/core/y.tab.c

.github/linters/.markdown-lint.yml

@@ -1,4 +1,5 @@
 # https://github.com/DavidAnson/markdownlint#rules--aliases
+# https://github.com/igorshubovych/markdownlint-cli
 # markdownlint -c .github/linters/.markdown-lint.yml .
 
 # MD001 heading-increment/header-increment - Heading levels should only increment by one level at a time
@@ -19,5 +20,14 @@ MD025: false
 # MD026 no-trailing-punctuation - Trailing punctuation in heading
 MD026: false
 
+# MD029/ol-prefix Ordered list item prefix
+MD029: false
+
+# MD033/no-inline-html - Inline HTML
+MD033: false
+
 # MD040 fenced-code-language - Fenced code blocks should have a language specified
 MD040: false
+
+# MD041 first-line-heading/first-line-h1 - First line in a file should be a top-level heading
+MD041: false

.github/linters/.rubocop.yml

@@ -0,0 +1,13 @@
+AllCops:
+  DisabledByDefault: true
+  TargetRubyVersion: 3.4
+
+Layout/AssignmentIndentation:
+  Enabled: true
+
+Layout/BlockEndNewline:
+  Enabled: true
+
+Layout/IndentationStyle:
+  Enabled: true
+  EnforcedStyle: spaces

.github/linters/.yaml-lint.yml

@@ -4,6 +4,8 @@
 extends: default
 
 rules:
+  comments:
+    min-spaces-from-content: 1
   document-start: disable
   line-length: disable
   truthy: false

.github/linters/codespell.txt

@@ -1,20 +1,16 @@
 ans
-ba
+celler
 clen
-creat
 delet
 disabl
-falsy
 filetest
 fo
 hel
-hist
 ist
-methid
 nd
 quitt
 remore
-ro
 runn
 sting
-upto
+strin
+wronly

.github/workflows/build.yml

@@ -1,3 +1,4 @@
+# https://github.com/actions/runner-images#available-images
 name: Build & Test
 
 on: [push, pull_request]
@@ -15,25 +16,56 @@ jobs:
       max-parallel: 8
       matrix:
         include:
+          - {os: ubuntu-24.04, cc: gcc, cxx: g++}
+          - {os: ubuntu-24.04, cc: clang, cxx: clang++}
           - {os: ubuntu-22.04, cc: gcc, cxx: g++}
           - {os: ubuntu-22.04, cc: clang, cxx: clang++}
-          - {os: ubuntu-20.04, cc: gcc, cxx: g++}
-          - {os: ubuntu-20.04, cc: clang, cxx: clang++}
-          - {os: macos-latest, cc: clang, cxx: clang++}
-          - {os: windows-latest, cc: gcc, cxx: g++, altname: "mingw-gcc"}
+          - {os: macos-15, cc: clang, cxx: clang++}
+          - {os: macos-14, cc: clang, cxx: clang++}
+          - {os: windows-2025, cc: gcc, cxx: g++, altname: "mingw-gcc"}
+          - {os: windows-2022, cc: gcc, cxx: g++, altname: "mingw-gcc"}
     env:
       MRUBY_CONFIG: ci/gcc-clang
       CC: ${{ matrix.cc }}
       CXX: ${{ matrix.cxx }}
       LD: ${{ matrix.cc }}
     steps:
-      - uses: actions/checkout@v3
+      - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
       - name: Ruby version
         run: ruby -v
       - name: Compiler version
         run: ${{ env.CC }} --version
       - name: Build and test
-        run: rake -m test:build && rake test:run
+        run: rake -m test:run:serial
+
+  Cosmopolitan:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - name: Ruby version
+        run: ruby -v
+      - name: Cache cosmocc
+        uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
+        id: cache-cosmocc
+        with:
+          path: ~/cosmo
+          key: cosmocc-${{ runner.os }}-20260104
+      - name: Install cosmocc
+        if: steps.cache-cosmocc.outputs.cache-hit != 'true'
+        run: |
+          mkdir -p ~/cosmo && cd ~/cosmo
+          wget https://cosmo.zip/pub/cosmocc/cosmocc.zip
+          unzip cosmocc.zip
+      - name: Build and test
+        run: |
+          COSMO_ROOT=~/cosmo rake -m test:run:serial MRUBY_CONFIG=cosmopolitan
 
   Windows-VC:
     runs-on: windows-2022
@@ -41,11 +73,14 @@ jobs:
     env:
       MRUBY_CONFIG: ci/msvc
     steps:
-      - uses: actions/checkout@v3
+      - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
       - name: Ruby version
         run: ruby -v
       - name: Build and test
         shell: cmd
         run: |
           call "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Auxiliary\Build\vcvars64.bat"
-          rake -m test:build && rake test:run
+          rake -m test:run:serial

.github/workflows/codeql-analysis.yml

@@ -1,53 +1,33 @@
-name: Code scanning - action
-
+name: CodeQL Analysis
 on:
   push:
-    branches-ignore:
-      - dependabot/**
+    branches: [master]
   pull_request:
-  schedule:
-    - cron: '0 19 * * 4'
-
+    branches: [master]
 permissions:
+  actions: read
   contents: read
-
+  security-events: write
 jobs:
-  CodeQL-Build:
-    permissions:
-      actions: read  # for github/codeql-action/init to get workflow details
-      contents: read  # for actions/checkout to fetch code
-      security-events: write  # for github/codeql-action/autobuild to send a status report
+  codeql:
+    name: CodeQL
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        language: ["actions"]
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
-          # We must fetch at least the immediate parents so that if this is
-          # a pull request then we can checkout the head.
-          fetch-depth: 2
-
-      # Initializes the CodeQL tools for scanning.
+          persist-credentials: false
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@v2
-        # Override language selection by uncommenting this and choosing your languages
-        # with:
-        #   languages: go, javascript, csharp, python, cpp, java
-
-      # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
-      # If this step fails, then you should remove it and run the build manually (see below)
+        uses: github/codeql-action/init@v4
+        with:
+          languages: ${{ matrix.language }}
       - name: Autobuild
-        uses: github/codeql-action/autobuild@v2
-
-      # ℹ️ Command-line programs to run using the OS shell.
-      # 📚 https://git.io/JvXDl
-
-      # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines
-      #    and modify them (or add more) to build your code if your project
-      #    uses a compiled language
-
-      # - run: |
-      #    make bootstrap
-      #    make release
-
+        uses: github/codeql-action/autobuild@v4
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v2
+        uses: github/codeql-action/analyze@v4
+        with:
+          category: "Security"

.github/workflows/coverage.yml

@@ -0,0 +1,46 @@
+name: Coverage
+
+on: [push]
+
+permissions:
+  contents: read
+
+jobs:
+  coverage:
+    name: Coverage
+    runs-on: ubuntu-24.04
+    env:
+      MRUBY_CONFIG: ci/gcc-clang
+      CC: clang-18
+      CXX: clang++-18
+      LD: clang-18
+      CFLAGS: -O0 -g --coverage
+      CXXFLAGS: -O0 -g --coverage
+      LDFLAGS: --coverage
+    steps:
+      - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - name: Ruby version
+        run: ruby -v
+      - name: Compiler version
+        run: ${{ env.CC }} --version
+      - name: Build and test
+        run: rake test
+      - name: Install gcovr
+        run: pip install gcovr
+      - name: Generate coverage report
+        run: |
+          {
+            echo "# Coverage report"
+            echo \`\`\`
+            gcovr --gcov-executable "llvm-cov-18 gcov" -e ".*_test.c" -e ".*/test/.*" -s --html-details -o coverage/ build
+            echo \`\`\`
+          } > "$GITHUB_STEP_SUMMARY"
+      - name: Upload coverage report
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: coverage-${{ github.sha }}
+          path: coverage/
+          retention-days: 3

.github/workflows/labeler.yml

@@ -0,0 +1,15 @@
+# https://github.com/actions/labeler
+name: Pull Request Labeler
+on:
+  - pull_request_target
+jobs:
+  triage:
+    permissions:
+      contents: read
+      pull-requests: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/labeler@634933edcd8ababfe52f92936142cc22ac488b1b # v6.0.1
+        with:
+          repo-token: "${{ secrets.GITHUB_TOKEN }}"
+          sync-labels: true

.github/workflows/lint.yml

@@ -1,36 +0,0 @@
-name: Lint
-
-on: [pull_request]
-
-permissions:
-  contents: read
-
-jobs:
-  misspell:
-    name: Check spelling with misspell
-    runs-on: ubuntu-latest
-    steps:
-      - name: Check Out
-        uses: actions/checkout@v3
-      - name: Install
-        run: wget -O - -q https://git.io/misspell | sh -s -- -b .
-      - name: Run misspell
-        run: git ls-files --empty-directory | xargs ./misspell -error
-  pre-commit:
-    name: Run pre-commit
-    runs-on: ubuntu-latest
-    steps:
-      - name: Check Out
-        uses: actions/checkout@v3
-      - name: Install
-        run: |
-          python -m pip install --upgrade pip
-          pip install pre-commit
-      - name: Set PY
-        run: echo "PY=$(python -VV | sha256sum | cut -d' ' -f1)" >> $GITHUB_ENV
-      - uses: actions/cache@v3
-        with:
-          path: ~/.cache/pre-commit
-          key: pre-commit|${{ env.PY }}|${{ hashFiles('.pre-commit-config.yaml') }}
-      - name: Run pre-commit
-        run: pre-commit run --all-files

.github/workflows/ls-lint.yml

@@ -0,0 +1,19 @@
+# https://github.com/loeffel-io/ls-lint
+name: Lint
+
+on: [pull_request]
+
+permissions:
+  contents: read
+
+jobs:
+  ls-lint:
+    name: Run ls-lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - uses: ls-lint/action@02e380fe8733d499cbfc9e22276de5085508a5bd # v2.3.1
+        with:
+          config: .github/linters/.ls-lint.yml

.github/workflows/oss-fuzz.yml

@@ -1,3 +1,4 @@
+# https://github.com/google/oss-fuzz
 name: CIFuzz
 on: [pull_request]
 permissions:
@@ -10,16 +11,16 @@ jobs:
       - name: Build Fuzzers
         uses: google/oss-fuzz/infra/cifuzz/actions/build_fuzzers@master
         with:
-          oss-fuzz-project-name: 'mruby'
+          oss-fuzz-project-name: "mruby"
           dry-run: false
       - name: Run Fuzzers
         uses: google/oss-fuzz/infra/cifuzz/actions/run_fuzzers@master
         with:
-          oss-fuzz-project-name: 'mruby'
+          oss-fuzz-project-name: "mruby"
           fuzz-seconds: 600
           dry-run: false
       - name: Upload Crash
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         if: failure()
         with:
           name: artifacts

.github/workflows/pre-commit-manual.yml

@@ -0,0 +1,22 @@
+# https://github.com/j178/prek
+name: Manual hooks
+
+on: [pull_request]
+
+permissions:
+  contents: read
+
+jobs:
+  pre-commit:
+    name: Run pre-commit
+    runs-on: ubuntu-latest
+    steps:
+      - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - uses: j178/prek-action@53276d8b0d10f8b6672aa85b4588c6921d0370cc # v2.0.1
+        with:
+          install-only: true
+      - name: Run manual pre-commit hooks
+        run: prek run --color=always --all-files --hook-stage manual

.github/workflows/pre-commit.yml

@@ -0,0 +1,20 @@
+# https://github.com/j178/prek
+name: pre-commit
+
+on: [pull_request]
+
+permissions:
+  contents: read
+
+jobs:
+  pre-commit:
+    name: Run pre-commit
+    runs-on: ubuntu-latest
+    steps:
+      - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - uses: j178/prek-action@53276d8b0d10f8b6672aa85b4588c6921d0370cc # v2.0.1
+        with:
+          extra-args: --all-files

.github/workflows/release.yml

@@ -0,0 +1,48 @@
+name: Release Builds
+
+on:
+  push:
+    tags:
+      - "*.*.*"
+
+permissions: read-all
+
+jobs:
+  source:
+    name: Source Code Releasing
+    if: ${{ github.repository == 'mruby/mruby' }}
+    permissions:
+      contents: write
+    runs-on: ubuntu-22.04
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+    steps:
+      - name: "Checkout ${{ github.ref_name }} ( ${{ github.sha }} )"
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - name: Builds
+        id: builds
+        run: |
+          tagname="$GITHUB_REF_NAME"
+          packagename="mruby-$tagname"
+          destdir=packages
+
+          mkdir -p "$destdir"
+          git archive --format zip --prefix "$packagename/" -o "$destdir/$packagename.zip" "$GITHUB_REF"
+          git archive --format tar.gz --prefix "$packagename/" -o "$destdir/$packagename.tar.gz" "$GITHUB_REF"
+          gunzip -c "$destdir/$packagename.tar.gz" | xz > "$destdir/$packagename.tar.xz"
+
+          (
+            cd "$destdir" || exit
+            sha256sum -- * > .sha256
+            mv .sha256 "$packagename.sha256"
+          )
+      - name: Release
+        uses: softprops/action-gh-release@v2
+        with:
+          draft: true
+          prerelease: ${{ contains(github.ref_name, '-rc') }}
+          body_path: NEWS
+          files: packages/*

.github/workflows/super-linter.yml

@@ -1,3 +1,4 @@
+# https://github.com/super-linter/super-linter
 name: Super-Linter
 
 on: [pull_request]
@@ -8,24 +9,24 @@ permissions:
 jobs:
   build:
     permissions:
-      contents: read  # for actions/checkout to fetch code
-      statuses: write  # for github/super-linter/slim to mark status of each linter run
+      contents: read # for actions/checkout to fetch code
+      statuses: write # for super-linter/super-linter/slim to mark status of each linter run
     name: Lint Code Base
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout Code
-        uses: actions/checkout@v3
+      - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           # Full git history is needed to get a proper list of changed files within `super-linter`
           fetch-depth: 0
+          persist-credentials: false
       - name: Lint Code Base
-        uses: github/super-linter/slim@v4.10.0
+        uses: super-linter/super-linter/slim@9e863354e3ff62e0727d37183162c4a88873df41 # v8.6.0
         env:
-          ERROR_ON_MISSING_EXEC_BIT: true
-          VALIDATE_BASH: true
           # VALIDATE_BASH_EXEC: true
+          VALIDATE_DOCKERFILE_HADOLINT: true
           # VALIDATE_EDITORCONFIG: true
           # VALIDATE_SHELL_SHFMT: true
           DEFAULT_BRANCH: master
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          VALIDATE_ALL_CODEBASE: false
+          VALIDATE_ALL_CODEBASE: true

.gitignore

@@ -1,8 +1,8 @@
-*.lock
 *.bak
 *.bc
 *.d
 *.i
+*.lock
 *.o
 *.orig
 *.pdb
@@ -13,25 +13,27 @@
 *.tmp
 *~
 .DS_Store
+.cache
+.ccls*
 .ccmalloc
+.git
 .svn
 .vscode
 .yardoc
-.ccls*
-compile_flags.txt
+benchmark/**/*.dat
+benchmark/*.pdf
+benchmark/*.png
+bin
+/build
+doc/api
+doc/capi
 compile_commands.json
+compile_flags.txt
 cscope.files
 cscope.out
+gmon.out
+mruby-source-*.gem
+node_modules
+perf.data*
 tags
-
-/.git
-/bin
-/build
-/mruby-source-*.gem
-
-/benchmark/**/*.dat
-/benchmark/*.pdf
-/benchmark/*.png
-
-/doc/api
-/doc/capi
+!Gemfile.lock

.pre-commit-config.yaml

@@ -1,68 +1,130 @@
 ---
-default_stages: [commit, push]
+# https://github.com/j178/prek
+default_stages: [pre-commit, pre-push]
 default_language_version:
-  # force all unspecified Python hooks to run python3
   python: python3
-minimum_pre_commit_version: '2.18.1'
+  node: 24.14.0
+minimum_pre_commit_version: "3.2.0"
+exclude: "^tools/lrama/"
 repos:
   - repo: meta
     hooks:
       - id: identity
+        name: run identity
+        description: check your identity
       - id: check-hooks-apply
+        name: run check-hooks-apply
+        description: check hooks apply to the repository
+  - repo: local
+    hooks:
+      - id: prettier
+        name: run prettier
+        description: format files with prettier
+        entry: prettier --write '**/*.md' '**/*.yaml' '**/*.yml'
+        files: \.(md|ya?ml)$
+        language: node
+        additional_dependencies: ["prettier@3.7.4"]
+        pass_filenames: false
+        stages: [manual]
+      - id: check-zip-file-is-not-committed
+        name: disallow zip files
+        description: Zip files are not allowed in the repository
+        language: fail
+        entry: |
+          Zip files are not allowed in the repository as they are hard to
+          track and have security implications. Please remove the zip file from the repository.
+        files: \.zip$
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.1
+    hooks:
+      - id: gitleaks
+        name: run gitleaks
+        description: detect hardcoded secrets with gitleaks
+  - repo: https://github.com/oxipng/oxipng
+    rev: v10.1.0
+    hooks:
+      - id: oxipng
+        name: run oxipng
+        description: use lossless compression to optimize PNG files
+        args: ["--fix", "-o", "4", "--strip", "safe", "--alpha"]
+        stages: [manual]
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.4.0
+    rev: v6.0.0
     hooks:
       - id: check-added-large-files
       - id: check-case-conflict
       - id: check-executables-have-shebangs
         exclude: ^test/t/lang\.rb$
+      - id: check-illegal-windows-names
       - id: check-merge-conflict
       - id: check-shebang-scripts-are-executable
       - id: check-vcs-permalinks
       - id: check-yaml
+      - id: destroyed-symlinks
+      - id: detect-aws-credentials
+        args: [--allow-missing-credentials]
       - id: detect-private-key
       - id: end-of-file-fixer
       - id: file-contents-sorter
-        files: ^codespell\.txt$
+        args: [--unique]
+        files: ^\.github/linters/codespell\.txt$
       - id: fix-byte-order-marker
+      - id: forbid-submodules
       - id: mixed-line-ending
       - id: trailing-whitespace
   - repo: https://github.com/Lucas-C/pre-commit-hooks
-    rev: v1.3.1
+    rev: v1.5.6
     hooks:
       - id: forbid-tabs
-        exclude: Makefile$|Makefile\..+$|makefile$|\.mk$
+        name: run no-tabs checker
+        description: check the codebase for tabs
+        exclude: Makefile$
       - id: remove-tabs
-        args: [--whitespaces-count, '2']
-        exclude: Makefile$|Makefile\..+$|makefile$|\.mk$
+        name: run tabs remover
+        description: find and convert tabs to spaces
+        args: [--whitespaces-count, "2"]
+        exclude: Makefile$
+  - repo: https://github.com/rhysd/actionlint
+    rev: v1.7.12
+    hooks:
+      - id: actionlint
+        name: run actionlint
+        description: lint GitHub Actions workflow files
   - repo: https://github.com/codespell-project/codespell
-    rev: v2.2.2
+    rev: v2.4.2
     hooks:
       - id: codespell
-        name: Run codespell
-        description: Check spelling with codespell
-        entry: codespell --ignore-words=codespell.txt
-  - repo: https://github.com/jumanjihouse/pre-commit-hooks
-    rev: 3.0.0
-    hooks:
-      - id: script-must-not-have-extension
-        name: Local policy is to exclude extension from all shell files
-        types: [shell]
+        name: run codespell
+        description: check spelling with codespell
   - repo: https://github.com/igorshubovych/markdownlint-cli
-    rev: v0.33.0
+    rev: v0.48.0
     hooks:
       - id: markdownlint
-        name: Run markdownlint
-        description: Checks the style of Markdown files
-        entry: markdownlint -c .github/linters/.markdown-lint.yml .
+        name: run markdownlint
+        description: checks the style of Markdown files
+        args: [--config=.github/linters/.markdown-lint.yml]
         types: [markdown]
-        files: \.(md|mdown|markdown)$
+        files: \.md$
+  - repo: https://github.com/rubocop/rubocop
+    rev: v1.86.0
+    hooks:
+      - id: rubocop
+        name: run rubocop
+        description: RuboCop is a Ruby code style checker (linter) and formatter based on the community-driven Ruby Style Guide
+        exclude: ^test/t/syntax\.rb$
+        args: [--config=.github/linters/.rubocop.yml]
+  - repo: https://github.com/shellcheck-py/shellcheck-py
+    rev: v0.11.0.1
+    hooks:
+      - id: shellcheck
+        name: run shellcheck
+        description: check shell scripts with a static analysis tool
   - repo: https://github.com/adrienverge/yamllint
-    rev: v1.28.0
+    rev: v1.38.0
     hooks:
       - id: yamllint
-        name: Run yamllint
-        description: Check YAML files with yamllint
-        entry: yamllint --strict -c .github/linters/.yaml-lint.yml
+        name: run yamllint
+        description: check YAML files with yamllint
+        args: [--strict, -c=.github/linters/.yaml-lint.yml]
         types: [yaml]
-        files: \.(yaml|yml)$
+        files: \.ya?ml$

.prettierignore

@@ -0,0 +1,6 @@
+# Ignore artifacts:
+build
+coverage
+doc/internal/opcode.md
+tools/lrama
+.venv

.prettierrc

@@ -0,0 +1,3 @@
+{
+  "bracketSpacing": false
+}

.travis.yml

@@ -8,4 +8,4 @@ env:
   - MRUBY_CONFIG=ci/gcc-clang
 
 script:
-  - rake -m test:build && rake test:run
+  - rake -m test:run:serial

AUTHORS

@@ -1,91 +1,98 @@
 # Authors of mruby (mruby developers)
 
-## The List of Contributors sorted by number of commits (as of 2022-01-08 4462e3d)
+## The List of Contributors sorted by number of commits (as of 2026-03-02 02877f0)
 
-   8860 Yukihiro "Matz" Matsumoto (@matz)*
-    586 KOBAYASHI Shuji (@shuujii)
-    441 dearblue (@dearblue)*
-    378 Daniel Bovensiepen (@bovi)*
-    346 Takeshi Watanabe (@take-cheeze)*
-    334 Masaki Muranaka (@monaka)
-    328 Tomoyuki Sahara (@tsahara)*
+   7532 Yukihiro "Matz" Matsumoto (@matz)*
+    712 dearblue (@dearblue)*
+    587 KOBAYASHI Shuji (@shuujii)
+    353 Daniel Bovensiepen (@bovi)*
+    345 Takeshi Watanabe (@take-cheeze)*
+    333 Masaki Muranaka (@monaka)
+    255 John Bampton (@jbampton)
     234 Jun Hiroe (@suzukaze)
+    228 Tomoyuki Sahara (@tsahara)*
     220 Cremno (@cremno)*
     209 Yuki Kurihara (@ksss)+
-    151 Yasuhiro Matsumoto (@mattn)*
+    144 Yasuhiro Matsumoto (@mattn)*
     113 Carson McDonald (@carsonmcdonald)
-    113 John Bampton (@jbampton)
-    103 Tomasz Dąbrowski (@dabroz)*
-     84 Akira Yumiyama (@akiray03)*
-     84 skandhas (@skandhas)
+    104 Tomasz Pędraszewski (@dabroz)*
+     83 Akira Yumiyama (@akiray03)*
+     83 skandhas (@skandhas)
      80 Masamitsu MURASE (@masamitsu-murase)
-     74 Yuichiro MASUI (@masuidrive)
      73 Hiroshi Mimaki (@mimaki)*
      71 Tatsuhiko Kubo (@cubicdaiya)*
-     65 Yuichiro Kaneko (@yui-knk)+
-     64 Paolo Bosetti (@pbosetti)*
+     71 Yuichiro MASUI (@masuidrive)
+     62 Yuichiro Kaneko (@yui-knk)+
      59 Kurebayashi, Takahiro (@crimsonwoods)*
      56 h2so5 (@h2so5)
      52 Ralph Desir (@Mav7)*
+     48 Paolo Bosetti (@pbosetti)*
      45 Rory O'Connell (@RoryO)*
      42 fleuria (@flaneur2020)
      40 Christopher Aue (@christopheraue)
      40 Seba Gamboa (@sagmor)
+     39 Kouhei Sutou (@kou)*
      38 Koji Yoshioka (@kyab)*+
-     38 Kouhei Sutou (@kou)*
      32 Masayoshi Takahashi (@takahashim)+
      31 MATSUMOTO Ryosuke (@matsumotory)*
      30 Nobuyoshi Nakada (@nobu)
-     26 Julian Aron Prenner (@furunkel)*
-     24 Ryan Scott (@ryan-scott-dev)*
+     26 Hoshiumi Arata (@hoshiumiarata)*
+     25 Julian Aron Prenner (@furunkel)*
      22 Clayton Smith (@clayton-shopify)
      22 Uchio Kondo (@udzura)*
      22 Zachary Scott (@zzak)*
-     22 mirichi (@mirichi)
-     21 Jared Breeden (@jbreeden)*
      21 Ryan Lopopolo (@lopopolo)
+     20 Ryan Scott (@ryan-scott-dev)*
+     20 google-labs-jules[bot] (@google-jules)
      19 Bouke van der Bijl (@bouk)
-     19 Felix Jones (@felixjones)*
-     19 Hidetaka Takano (@TJ-Hidetaka-Takano)
+     19 Jared Breeden (@jbreeden)*
      19 go kikuta (@gkta)*
      18 Corey Powell (@IceDragon200)
+     18 Hidetaka Takano (@TJ-Hidetaka-Takano)
      18 Jon Maken (@jonforums)+
-     18 Mitchell Blank Jr (@mitchblank)*
+     18 leviongit (@leviongit)
+     18 mirichi (@mirichi)
+     17 Mitchell Blank Jr (@mitchblank)*
+     16 HASUMI Hitoshi (@hasumikin)
      16 bggd (@bggd)
      16 kano4 (@kano4)
+     15 Felix Jones (@felixjones)*
      14 Blaž Hrastnik (@archseer)*
-     14 Jose Narvaez (@goyox86)
      14 Kazuki Tsujimoto (@k-tsj)
      14 Tadashi FUKUZAWA (@FUKUZAWA-Tadashi)+
      14 fn ⌃ ⌥ (@FnControlOption)
+     13 Jose Narvaez (@goyox86)
      13 Patrick Hogan (@pbhogan)
      12 Akira Kuroda (@akuroda)
      12 Kouki Ooyatsu (kaishuu0123)*
      12 NAKAMURA Usaku (@unak)*
-     12 RIZAL Reckordp (@Reckordp)+
+     12 Ray Chason (@chasonr)*
+     12 SiZiOUS (@suzious)
      12 Takashi Sawanaka (@sdottaka)*
      12 Ukrainskiy Sergey (@ukrainskiysergey)
      12 Xuejie "Rafael" Xiao (@xxuejie)*
      11 Julien Ammous (@schmurfy)
      11 Kazuho Oku (@kazuho)
+     11 RIZAL Reckordp (@Reckordp)+
      11 Seeker (@SeekingMeaning)
-     11 YAMAMOTO Masaya (pandax381)
      11 takkaw (@takkaw)
+     10 Hendrik (@Asmod4n)
      10 Miura Hideki (@miura1729)
      10 Narihiro Nakamura (@authorNari)
-     10 Ray Chason (@chasonr)*
+     10 YAMAMOTO Masaya (pandax381)
      10 Yuichi Nishiwaki (@nyuichi)
       9 Akira Mitsui (@murasesyuka)*
       9 Frank Celler (@fceller)
       9 Tatsuya Matsumoto (@tmash06)*
       8 Takashi Sogabe (@sogabe)
+      8 Wataru Ashihara (@wataash)*
       7 Bhargava Shastry (@bshastry)*
       7 Kouichi Nakanishi (@keizo042)
       7 Rubyist (@expeditiousRubyist)
       7 Simon Génier (@simon-shopify)
       7 Terence Lee (@hone)
-      7 Wataru Ashihara (@wataash)*
       7 roco (@rystyle)*
+      7 vickash (@vickash)
       6 Akito Mochizuki (@ak-mochi)
       6 Beoran (@beoran)
       6 David Siaw (@davidsiaw)*
@@ -94,55 +101,63 @@
       6 INOUE Yasuyuki (@yasuyuki)
       6 Junji Sawada (@junjis0203)
       6 Kenji Okimoto (@okkez)+
+      6 Paweł Świątkowski (@katafrakt)
       6 Selman ULUG (@selman)
       6 Yusuke Endoh (@mame)*
+      6 buty4649 (@buty4649)
+      6 masahino (@masahino)
       5 Chris Reuter (@suetanvil)
       5 Davide D'Agostino (@DAddYE)
       5 Eric Hodel (@drbrain)
-      5 Hendrik (@Asmod4n)
       5 Ichito Nagata (@i110)
       5 Keita Obo (@ktaobo)*
       5 Max Anselm (@silverhammermba)
       5 Rodrigo Malizia (@rmalizia44)+
-      5 SiZiOUS (@sizious)
+      5 Ryan Davis (@zenspider)
       5 Syohei YOSHIDA (@syohex)
       5 TOMITA Masahiro (@tmtm)
       5 Yurie Yamane (@yurie)+
       5 dreamedge (@dreamedge)
-      5 masahino (@masahino)
       5 nkshigeru (@nkshigeru)
       5 xuejianqing (@joans321)
+      4 Chris Hasiński (@khasinski)
       4 Dante Catalfamo (@dantecatalfamo)
       4 Goro Kikuchi (@gorogit)
       4 Herwin Weststrate (@herwinw)
+      4 Horimoto Yasuhiro (@komainu8)
       4 Jon Moss (@maclover7)
       4 Ken Muramatsu (@ken-mu)+
       4 Kohei Suzuki (@eagletmt)
+      4 Lanza (@LanzaSchneider)
       4 Li Yazhou (@flaneur2020)
       4 Marcus Stollsteimer (@stomar)
+      4 Mark Delk (@jethrodaniel)
       4 NARUSE, Yui (@nurse)
       4 Ravil Bayramgalin (@brainopia)*+
       4 Satoshi Odawara (@SatoshiOdawara)
+      4 UENO, M. (@eunos-1128)
       4 Yuhei Okazaki (@Yuuhei-Okazaki)*
       4 Yuji Yamano (@yyamano)
       4 kurodash (@kurodash)*
       4 wanabe (@wanabe)*
       3 Anton Davydov (@davydovanton)
+      3 Aurora Nockert (@auroranockert)
       3 Carlo Prelz (@asfluido)*
+      3 Daniel K. Sierpiński (@513ry)+
       3 David Turnbull (@AE9RB)
       3 Franck Verrot (@franckverrot)
-      3 HASUMI Hitoshi (@hasumikin)
-      3 Horimoto Yasuhiro (@komainu8)
+      3 Hirohito Higashi (@HirohitoHigashi)
       3 J. Mutua (@katmutua)+
       3 Jan Berdajs (@mrbrdo)
       3 Jonas Minnberg (@sasq64)
       3 Joseph McCullough (@joequery)
       3 Mark McCurry (@fundamental)
+      3 Meder Kydyraliev (@meder)
       3 Nobuhiro Iwamatsu (@iwamatsu)
       3 Per Lundberg (@perlun)*
       3 Rob Fors (@robfors)*
+      3 Robert Rowe (@CaptainJet)
       3 Sebastián Katzer (@katzer)*
-      3 Shouji Kuboyama (@Shokuji)*
       3 Shuta Kimura (@kimushu)+
       3 TERAJIMA, Motoyuki (@trmmy)
       3 Taichi AOKI (@aoki1980taichi)
@@ -164,7 +179,6 @@
       2 Francois Chagnon (@EiNSTeiN-)*
       2 Gilad Zohari (@gzohari)
       2 Go Saito (@govm)
-      2 Hirohito Higashi (@HirohitoHigashi)
       2 Hiroyuki Iwatsuki (@iwadon)
       2 Huei-Horng Yo (@hiroshiyui)
       2 Jonas Kulla (@Ancurio)
@@ -173,7 +187,6 @@
       2 Kazuhiko Yamashita (@pyama86)+
       2 Kazuhiro Sera (@seratch)
       2 Kuroda Daisuke (@dycoon)+
-      2 Lanza (@LanzaSchneider)
       2 Lothar Scholz (@llothar)
       2 Lukas Joeressen (@kext)
       2 Masahiro Wakame (@vvkame)+
@@ -183,9 +196,9 @@
       2 Russel Hunter Yukawa (@rhykw)+
       2 Ryunosuke SATO (@tricknotes)
       2 Santa Zhang (@santazhang)
-      2 Satoru Naba (@snaba)+
       2 Serg Podtynnyi (@shtirlic)
       2 Shannen Saez (@shancat)
+      2 Shouji Kuboyama (@Shokuji)*
       2 SouthWolf (@southwolf)
       2 TJ Singleton (@tjsingleton)
       2 Taiyo Mizuhashi (@taiyoslime)+
@@ -194,15 +207,20 @@
       2 Zhang Xiaohui (@hifoolno)
       2 icm7216 (@icm7216)
       1 A-Sat (@asatou)+
+      1 AN Long (@aisk)
       1 Abinoam Praxedes Marques Junior (@abinoam)
       1 Alex Wang (@nanamiwang)+
+      1 AlexDenisov (@AlexDenisov)
       1 Andrew Nordman (@cadwallion)
       1 Ashish Kurmi (@boahc077)
       1 Atsushi Morimoto (@mynz)
       1 Ben A Morgan (@BenMorganIO)
       1 Benoit Daloze (@eregon)
+      1 Bradley Whited (@esotericpig)
+      1 Colin MacKenzie IV (@sinisterchipmunk)
       1 Daehyub Kim (@lateau)
       1 Daniel Varga (@vargad)
+      1 Diamond Rivero (@diamant3)
       1 Edgar Boda-Majer (@eboda)
       1 Fangrui Song (@MaskRay)
       1 Flavio Medeiros (@flaviommedeiros)
@@ -239,10 +257,11 @@
       1 Lukas Elmer (@lukaselmer)
       1 Lukas Stabe (@Ahti)
       1 M.Naruoka (@fenrir-naru)
-      1 Mark Delk (@jethrodaniel)
+      1 Marcelo Juchem (@juchem)
       1 Martin Bosslet (@emboss)+
       1 Masahiko Sawada (@MasahikoSawada)
       1 Matt Aimonetti (@mattetti)
+      1 Max Base (@MaxFork)
       1 Maxim Abramchuk (@MaximAbramchuck)
       1 Megumi Tomita (@tomykaira)+
       1 Mitchell Hashimoto (@mitchellh)
@@ -251,21 +270,25 @@
       1 Nicholas (@knf)
       1 Nozomi SATO (@nozomiS)
       1 Okumura Takahiro (@hfm)
+      1 Oliver Chang (@oliverchang)
       1 Patrick Ellis (@pje)
       1 Patrick Pokatilo (@SHyx0rmZ)
       1 Pavel Evstigneev (@Paxa)+
+      1 Pete Kinnecom (@petekinnecom)
+      1 Piotr Usewicz (@pusewicz)
       1 Prayag Verma (@pra85)
       1 Ranmocy (@ranmocy)
       1 Robert McNally (@wolfmcnally)
-      1 Robert Rowe (@CaptainJet)
       1 Ryan Scott Lewis (@RyanScottLewis)
       1 Ryo Okubo (@syucream)
       1 SAkira a.k.a. Akira Suzuki (@sakisakira)
       1 Santiago Rodriguez (@sanrodari)
       1 Satoh, Hiroh (@cho45)+
+      1 Satoru Naba (@snaba)+
       1 Sayed Abdelhaleem (@visualsayed)
       1 Sergey Ukrainskiy (@ukrainskiysergey)
       1 Shugo Maeda (@shugo)
+      1 Sinkevich Artem (@ArtSin)
       1 Sorah Fukumori (@sorah)
       1 Stephen Jothen (@sjothen)
       1 Stuart Hinson (@stuarth)
@@ -281,19 +304,23 @@
       1 Yevhen Viktorov (@yevgenko)
       1 Yoji SHIDARA (@darashi)
       1 Yoshiori SHOJI (@yoshiori)
+      1 Yuji Yokoo (@yujiyokoo)
       1 Yukang (@chenyukang)
       1 Yurii Nakonechnyi (@inobelar)
       1 Yusuke Suzuki (@Constellation)+
       1 Yusuke Tanaka (@csouls)
+      1 alpha.netzilla (@alpha-netzilla)
       1 arton (@arton)
       1 duangsuse (@duangsuse)
       1 fl0l0u (@fl0l0u)
+      1 hasse (@hasse09052)
       1 hhc0null (@hhc0null)
       1 iTitou (@titouanc)
       1 javier ramírez (@javier)
       1 liyuray (@liyuray)
       1 lucas dicioccio (@lucasdicioccio)
       1 n4o847 (@n4o847)
+      1 niyarin (@niyarin)
       1 robert (@R-obert)
       1 sbsoftware (@sbsoftware)
       1 ssmallkirby (@smallkirby)

CONTRIBUTING.md

@@ -12,59 +12,123 @@ things in mind before submitting your pull request:
 - Create a branch which is dedicated to your change
 - Test your changes before creating a pull request (`rake test`)
 - If possible write a test case which confirms your change
-- Don't mix several features or bug-fixes in one pull request
+- Don't mix several features or bugfixes in one pull request
 - Create a meaningful commit message
 - Explain your change (i.e. with a link to the issue you are fixing)
 - Use mrbgem to provide non ISO features (classes, modules and methods) unless
   you have a special reason to implement them in the core
 
-## pre-commit
+## Security Issues
 
-A framework for managing and maintaining multi-language `pre-commit` hooks.
-`pre-commit` can be [installed](https://pre-commit.com/#installation) with `pip`, `curl`, `brew` or `conda`.
+If you discover a security vulnerability:
 
-You need to first install `pre-commit` and then install the `pre-commit` hooks with `pre-commit install`.
-Now `pre-commit` will run automatically on git commit!
+- **High priority security vulnerabilities** (RCE): Report via email to <matz@ruby.or.jp>
+- **VM crashes from valid Ruby code**: Please report as regular bug reports on our issue tracker
 
-It's usually a good idea to run the hooks against all the files when adding new hooks (usually `pre-commit` will only run on the changed files during git hooks).
-Use `pre-commit run --all-files` to check all files.
+For detailed guidance on what qualifies as a security issue and what doesn't, see [SECURITY.md](SECURITY.md).
 
-To run a single hook use `pre-commit run --all-files <hook_id>`
+## prek
 
-To update use `pre-commit autoupdate`
+We use [prek](https://github.com/j178/prek), a fast Rust-based pre-commit hook manager.
+It reads the standard `.pre-commit-config.yaml` format.
+
+Install `prek` following the [installation guide](https://github.com/j178/prek#installation),
+then install the hooks with `prek install`.
+Now `prek` will run automatically on git commit!
+
+It's usually a good idea to run the hooks against all the files when adding new hooks (usually `prek`
+will only run on the changed files during git hooks). Use `prek run --all-files` to check all files.
+
+To run a single hook use `prek run --all-files <hook_id>`
+
+To update use `prek autoupdate`
 
 Sometimes you might need to skip one or more hooks which can be done with the `SKIP` environment variable.
 
 `$ SKIP=yamllint git commit -m "foo"`
 
-For convenience, we have added `pre-commit run --all-files` and `pre-commit autoupdate`
+For convenience, we have added `prek run --all-files`, `prek install` and `prek autoupdate`
 to both the Makefile and the Rakefile. Run them with:
 
 - `make check` or `rake check`
+- `make checkinstall` or `rake checkinstall`
 - `make checkupdate` or `rake checkupdate`
 
-### pre-commit quick links
+To configure hooks you can modify the config file [.pre-commit-config.yaml](.pre-commit-config.yaml).
+We use [GitHub Actions](.github/workflows/pre-commit.yml) to run `prek` on every pull request.
 
-- [Quick start](https://pre-commit.com/#quick-start)
-- [Usage](https://pre-commit.com/#usage)
-- [pre-commit autoupdate](https://pre-commit.com/#pre-commit-autoupdate)
-- [Temporarily disabling hooks](https://pre-commit.com/#temporarily-disabling-hooks)
+### prek quick links
+
+- [prek GitHub](https://github.com/j178/prek)
+- [Installation](https://github.com/j178/prek#installation)
+- [Usage](https://github.com/j178/prek#usage)
+
+## Docker
+
+We have both a `Dockerfile` and `docker-compose.yml` files in the repository root.
+You can run these with the command line or use
+[Docker Desktop](https://www.docker.com/products/docker-desktop/).
+
+The Docker image is running Debian bullseye with Ruby and Python installed.
+You can build the Docker image with:
+
+`$ docker-compose build test`
+
+So far we just have one service: `test`. Running the default `docker-compose`
+command will create the Docker image, spin up a container and then build and
+run all mruby tests.
+
+The default `docker-compose` command is:
+
+`$ docker-compose -p mruby run test`
+
+You can also use Make or Rake to run the default `docker-compose`
+command from above:
+
+- `make composetest`
+- `rake composetest`
+
+List your Docker images with:
+
+```console
+$ docker images
+REPOSITORY   TAG       IMAGE ID       CREATED          SIZE
+mruby-test   latest    ec60f9536948   29 seconds ago   1.29GB
+```
+
+You can also run any custom `docker-compose` command which will override
+the default. For example to run `prek run --all-files` type:
+
+`$ docker-compose -p mruby run test prek run --all-files`
+
+For convenience, you can also run `prek` with:
+
+- `make composecheck`
+- `rake composecheck`
+
+The bonus of running `prek` with `docker-compose` is that you won't need
+to install `prek` and the hooks on your local machine.
+
+Note limitation: currently running `prek` with `docker-compose` we
+skip the `check-executables-have-shebangs` hook.
+
+Two more examples of custom `docker-compose` commands are:
+
+- `$ docker-compose -p mruby run test ls`
+- `$ docker-compose -p mruby run test rake doc:api`
+
+If you want to test using a different `docker-compose` YAML config file you
+can use the `-f` flag:
+
+`$ docker-compose -p mruby -f docker-compose.test.yml run test`
+
+- <https://docs.docker.com/compose/>
+- <https://docs.docker.com/engine/reference/commandline/cli/>
 
 ## Spell Checking
 
-We are running [misspell](https://github.com/client9/misspell) which is mainly written in
-[Golang](https://golang.org/) to check spelling with [GitHub Actions](.github/workflows/lint.yml).
-Correct commonly misspelled English words quickly with `misspell`. You can run `misspell` locally
-against all files with:
-
-```bash
-find . -type f | xargs ./misspell -error
-```
-
-Notable `misspell` help options or flags are:
-
-- `-i` string: ignore the following corrections, comma separated
-- `-w`: Overwrite file with corrections (default is just to display)
+We are using `prek` to run [codespell](https://github.com/codespell-project/codespell)
+to check code for common misspellings. We have a small custom dictionary file [codespell.txt](.github/linters/codespell.txt).
 
 ## Coding conventions
 
@@ -112,7 +176,7 @@ language itself. Please note the following hints for your Ruby code:
 #### Comply with the Ruby standard (ISO/IEC 30170:2012)
 
 mruby is currently targeting to execute Ruby code which complies to ISO/IEC
-30170:2012 (<https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=59579>),
+30170:2012 (<https://www.iso.org/standard/59579.html>),
 unless there's a clear reason, e.g. the latest Ruby has changed behavior from ISO.
 
 ## Building documentation
@@ -120,7 +184,7 @@ unless there's a clear reason, e.g. the latest Ruby has changed behavior from IS
 ### mruby API
 
 - [YARD](https://yardoc.org/) - YARD is a documentation generation tool for the Ruby programming language
-- [yard-mruby](https://rubygems.org/gems/yard-mruby) - Document MRuby sources with YARD
+- [yard-mruby](https://rubygems.org/gems/yard-mruby) - Document mruby sources with YARD
 - [yard-coderay](https://rubygems.org/gems/yard-coderay) - Adds coderay syntax highlighting to YARD docs
 
 ### C API

Dockerfile

@@ -0,0 +1,13 @@
+FROM ruby:3.2.2-bullseye
+
+RUN apt-get update && apt-get install --no-install-recommends -y python3-pip shellcheck \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+COPY Gemfile Gemfile.lock .pre-commit-config.yaml ./
+
+RUN bundle install && pip3 install --no-cache-dir pre-commit && git init . && pre-commit install-hooks
+
+COPY . .

Gemfile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gem 'rake'
+gem 'yard'
+gem 'yard-coderay'
+gem 'yard-mruby'

Gemfile.lock

@@ -0,0 +1,25 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    coderay (1.1.3)
+    rake (13.3.1)
+    yard (0.9.38)
+    yard-coderay (0.1.0)
+      coderay
+      yard
+    yard-mruby (0.3.0)
+      yard (~> 0.9.0)
+
+PLATFORMS
+  ruby
+  x86_64-darwin-21
+  x86_64-linux
+
+DEPENDENCIES
+  rake
+  yard
+  yard-coderay
+  yard-mruby
+
+BUNDLED WITH
+   2.4.10

LEGAL

@@ -3,3 +3,60 @@ LEGAL NOTICE INFORMATION
 
 All the files in this distribution are covered under the MIT license
 (see the file LICENSE) except some files mentioned below:
+
+- src/string.c (memsearch_swar): 2 clause BSD license code by Wojciech Muła (@WojciechMula)
+- src/fmt_fp.c: public domain by Dave Hylands (@dhylands)
+- mrbgems/mruby-dir/src/Win/dirent.c: MIT-like license by Kevlin Henney
+
+[src/string.c]
+The implementation of mrb_memsearch_ss() is taken from
+https://github.com/WojciechMula/sse4-strstr.git
+
+Copyright (c) 2008-2016, Wojciech Muła
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+[src/fmt_fp.c]
+
+The code in this function was inspired from Fred Bayer's pdouble.c.
+Since pdouble.c was released as Public Domain, I'm releasing this
+code as public domain as well.
+
+Dave Hylands
+
+The original code can be found in https://github.com/dhylands/format-float
+
+[mrbgems/mruby-dir/src/Win/dirent.c] used only for Windows platform
+
+Copyright Kevlin Henney, 1997, 2003, 2012. All rights reserved.
+
+Permission to use, copy, modify, and distribute this software and its
+documentation for any purpose is hereby granted without fee, provided
+that this copyright and permissions notice appear in all copies and
+derivatives.
+
+This software is supplied "as is" without express or implied warranty.
+
+But that said, if there are any problems please get in touch.

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2010-2022 mruby developers
+Copyright (c) 2010- mruby developers
 
 Permission is hereby granted, free of charge, to any person obtaining a
 copy of this software and associated documentation files (the "Software"),

Makefile

@@ -1,23 +1,63 @@
 # mruby is using Rake (https://ruby.github.io/rake/) as a build tool.
 
 RAKE = rake
+DOCKER_COMPOSE = docker-compose
+PRE_COMMIT = prek
 
-all :
+define check_command
+	@command -v $(1) >/dev/null 2>&1 || { \
+		echo "Error: $(1) is not installed or not in PATH."; \
+		exit 1; \
+	}
+endef
+
+# For colors
+ifneq ($(shell tty -s),)
+	CYAN := $(shell tput setaf 6)
+	RESET := $(shell tput sgr0)
+else
+	CYAN :=
+	RESET :=
+endif
+
+.PHONY: all test clean check checkinstall checkupdate composecheck composetest check_rake check_docker_compose check_pre_commit help
+.DEFAULT_GOAL := all
+
+all: check_rake ## build all targets, install (locally) in-repo
 	$(RAKE)
-.PHONY : all
 
-test : all
+test: check_rake all ## build and run all mruby tests
 	$(RAKE) test
-.PHONY : test
 
-clean :
+clean: check_rake ## clean all built and in-repo installed artifacts
 	$(RAKE) clean
-.PHONY : clean
 
-check :
-	pre-commit run --all-files
-.PHONY : check
+check: check_pre_commit ## run all prek hooks against all files
+	$(PRE_COMMIT) run --all-files
 
-checkupdate :
-	pre-commit autoupdate
-.PHONY : checkupdate
+checkinstall: check_pre_commit ## install the prek hooks
+	$(PRE_COMMIT) install
+
+checkupdate: check_pre_commit ## check the prek hooks for updates
+	$(PRE_COMMIT) autoupdate
+
+composecheck: check_docker_compose check_pre_commit ## run all prek hooks against all files with docker-compose
+	$(DOCKER_COMPOSE) -p mruby run test $(PRE_COMMIT) run --all-files
+
+composetest: check_docker_compose ## build and run all mruby tests with docker-compose
+	$(DOCKER_COMPOSE) -p mruby run test
+
+check_rake: ## check if Rake is installed
+	$(call check_command, $(RAKE))
+
+check_docker_compose: ## check if docker-compose is installed
+	$(call check_command, $(DOCKER_COMPOSE))
+
+check_pre_commit: ## check if prek is installed
+	$(call check_command, $(PRE_COMMIT))
+
+help: ## display this help message
+	@echo "Usage: make <target>"
+	@echo
+	@echo "Available targets:"
+	@grep -E '^[a-z_-]+:.*##' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*## *"}; {printf "  $(CYAN)%-20s$(RESET) %s\n", $$1, $$2}'

NEWS

@@ -1,12 +0,0 @@
-NEWS
-----
-
-This document is a list of user visible feature changes made between
-releases except for bug fixes.
-
-Note that each entry is kept so brief that no reason behind or
-reference information is supplied with.  For a full list of changes
-with all sufficient information, see the ChangeLog file.
-
-
-** Information about first release v1.0.0

NEWS.md

@@ -0,0 +1,367 @@
+# User visible changes in `mruby4.0` from `mruby3.4`
+
+"**_NOTE_**:" are changes to be aware of.
+
+# The language
+
+## Pattern Matching
+
+mruby now supports pattern matching (case/in) syntax:
+
+- Basic pattern matching with `case`/`in` syntax ([dadfac6](https://github.com/mruby/mruby/commit/dadfac6))
+- Array pattern matching ([ec67fd9](https://github.com/mruby/mruby/commit/ec67fd9))
+- Hash pattern matching ([2147263](https://github.com/mruby/mruby/commit/2147263))
+- Find pattern matching (`[*pre, target, *post]`) ([6c4d98b](https://github.com/mruby/mruby/commit/6c4d98b))
+- Pin operator (`^variable`) ([1de6340](https://github.com/mruby/mruby/commit/1de6340))
+- Guard clauses (`if`/`unless` conditions) ([07ac110](https://github.com/mruby/mruby/commit/07ac110))
+- One-line pattern matching (`expr in pattern`) ([e76ce24](https://github.com/mruby/mruby/commit/e76ce24))
+- Brace-less hash pattern support ([e8096bf](https://github.com/mruby/mruby/commit/e8096bf))
+
+## Other Language Changes
+
+- `&nil` in formal parameters to explicitly opt out of block arguments ([b07518e](https://github.com/mruby/mruby/commit/b07518e))
+- Trailing comma in method definition parameters: `def foo(a, b,)` ([f78334b](https://github.com/mruby/mruby/commit/f78334b))
+- Array/Hash/String subclasses can now override `[]` and `[]=` methods ([#6675](https://github.com/mruby/mruby/pull/6675))
+- `OP_SETIDX` optimization for Array and Hash ([ddd8fe1](https://github.com/mruby/mruby/commit/ddd8fe1))
+- `case`/`in` without `else` now raises `NoMatchingPatternError` ([d8de35b](https://github.com/mruby/mruby/commit/d8de35b))
+- Allow compound statement in parenthesized argument context ([919cbd8](https://github.com/mruby/mruby/commit/919cbd8))
+
+# Changes in C API
+
+- **_NOTE_**: `mrb_alloca()` renamed to `mrb_temp_alloc()` ([7fe5c2e](https://github.com/mruby/mruby/commit/7fe5c2e))
+- **_NOTE_**: `mruby/ext/io.h` renamed to `mruby/io.h` ([2813f79](https://github.com/mruby/mruby/commit/2813f79))
+- `mrb_gc_add_region()` for contiguous heap region support ([072855a](https://github.com/mruby/mruby/commit/072855a))
+- `mrb_class_outer()` to get the outer class/module ([3a1b771](https://github.com/mruby/mruby/commit/3a1b771))
+- `MRB_ENSURE()` macro for exception-safe cleanup ([3ac682b](https://github.com/mruby/mruby/commit/3ac682b))
+- `mrb_time_get_tm()` for accessing struct tm ([daaaafe](https://github.com/mruby/mruby/commit/daaaafe))
+- `MRB_OPEN_FAILURE()` macro for checking mrb_open result ([40b0cb9](https://github.com/mruby/mruby/commit/40b0cb9))
+- `mrb_print_error()` now handles NULL gracefully ([8e50a45](https://github.com/mruby/mruby/commit/8e50a45))
+- `mrb_open()` returns mrb_state with exc set on init failure ([05ffe0c](https://github.com/mruby/mruby/commit/05ffe0c))
+- `mrb_utf8_to_buf()` for UTF-8 encoding consolidation ([7e28e68](https://github.com/mruby/mruby/commit/7e28e68))
+- `kh_is_end()` macro for safe khash iteration ([893cc75](https://github.com/mruby/mruby/commit/893cc75))
+- `mrb_bigint_p()` always defined regardless of bigint gem presence ([6c4a8c0](https://github.com/mruby/mruby/commit/6c4a8c0))
+- `RInteger` and `RFloat` added to `RVALUE` union ([13dbca0](https://github.com/mruby/mruby/commit/13dbca0))
+
+# ROM Method Tables
+
+All built-in classes and most extension gems now use read-only method
+tables stored in `.rodata` instead of heap-allocated hash tables. Method
+definitions no longer consume heap memory, significantly reducing memory
+footprint for embedded use.
+
+Core classes converted: BasicObject, Object, Module, Class, Kernel,
+String, Array, Hash, Numeric, Integer, Float, NilClass, TrueClass,
+FalseClass, Range, Symbol, Exception, Proc.
+
+Extension gems converted: mruby-string-ext, mruby-array-ext, mruby-set,
+mruby-struct, mruby-class-ext, mruby-numeric-ext, mruby-random,
+mruby-kernel-ext, mruby-complex, mruby-rational, mruby-io, mruby-socket,
+mruby-method, mruby-metaprog, mruby-time, mruby-hash-ext, mruby-proc-ext,
+mruby-symbol-ext, mruby-range-ext, mruby-object-ext.
+
+# GC and Memory
+
+- **_NOTE_**: `MRB_NO_PRESYM` removed; presym is now always enabled ([81689045](https://github.com/mruby/mruby/commit/81689045))
+- Replace `gcnext` gray linked list with fixed-size gray stack, reducing per-object overhead ([31fea170](https://github.com/mruby/mruby/commit/31fea170))
+- `mrb_gc_add_region()` for providing contiguous memory buffers as GC heap pages ([072855a](https://github.com/mruby/mruby/commit/072855a))
+- Chunk-based pool for symbol string allocation ([e05bd8f](https://github.com/mruby/mruby/commit/e05bd8f))
+- Reduce `IV_INITIAL_SIZE` from 4 to 2 ([6bd1f51](https://github.com/mruby/mruby/commit/6bd1f51))
+- Lossless float encoding using rotation in word boxing ([b6148c8](https://github.com/mruby/mruby/commit/b6148c8))
+- Lossless rotation encoding for 32-bit float32 word boxing ([14a5cfb](https://github.com/mruby/mruby/commit/14a5cfb))
+- Consolidated irep allocation for .mrb loading ([74fb045](https://github.com/mruby/mruby/commit/74fb045))
+- Object shapes (hidden classes) for `MRB_TT_OBJECT` IV storage, sharing key layouts across objects with the same instance variable assignment order ([8d10056](https://github.com/mruby/mruby/commit/8d10056))
+
+# Build & Configuration
+
+- **_NOTE_**: `MRB_WORDBOX_NO_FLOAT_TRUNCATE` renamed to `MRB_WORDBOX_NO_INLINE_FLOAT` (old name still works) ([59e1fe2](https://github.com/mruby/mruby/commit/59e1fe2))
+- **_NOTE_**: `MRB_INT64` on 32-bit now requires `MRB_NO_BOXING` (other boxing modes cannot guarantee alignment for heap-allocated 64-bit integers) ([eaaa66b](https://github.com/mruby/mruby/commit/eaaa66b))
+- Amalgamation support via `rake amalgam` task ([d995ca2](https://github.com/mruby/mruby/commit/d995ca2))
+- New Platform: Cosmopolitan Libc ([#6681](https://github.com/mruby/mruby/pull/6681))
+- Emscripten: use native WASM exception handling ([ca364e3](https://github.com/mruby/mruby/commit/ca364e3))
+- HAL (Hardware Abstraction Layer) for platform abstraction in mruby-io, mruby-socket, mruby-dir, mruby-task ([74ca22f](https://github.com/mruby/mruby/commit/74ca22f))
+- `MRUBY_MIRB_READLINE` environment variable to control readline library selection ([0aafb83](https://github.com/mruby/mruby/commit/0aafb83))
+- MSYS2 drive letter support in build script ([77f6ffe](https://github.com/mruby/mruby/commit/77f6ffe))
+- Inter-gem headers separated from external API headers ([#6671](https://github.com/mruby/mruby/pull/6671))
+
+# Changes in mrbgems
+
+## New Gems
+
+- **mruby-task**: Cooperative multitasking with preemptive scheduling ([ae0d7a0](https://github.com/mruby/mruby/commit/ae0d7a0))
+- **mruby-benchmark**: Benchmarking gem ([2f40f3d](https://github.com/mruby/mruby/commit/2f40f3d))
+- **mruby-strftime**: Time#strftime implementation ([b31e22f](https://github.com/mruby/mruby/commit/b31e22f))
+
+## mruby-bin-mirb Improvements
+
+- Custom multi-line editor replacing readline ([527018c](https://github.com/mruby/mruby/commit/527018c))
+- Syntax highlighting for keywords, strings, result values, hash key symbols ([624272b](https://github.com/mruby/mruby/commit/624272b), [1713d4a](https://github.com/mruby/mruby/commit/1713d4a))
+- Automatic light/dark theme detection via OSC 11 ([db4c8d9](https://github.com/mruby/mruby/commit/db4c8d9))
+- Tab completion support ([2f15282](https://github.com/mruby/mruby/commit/2f15282))
+- Colored output for prompts and errors ([b36e0b4](https://github.com/mruby/mruby/commit/b36e0b4))
+- Auto-indentation and auto-dedent ([d52f318](https://github.com/mruby/mruby/commit/d52f318), [e901b6d](https://github.com/mruby/mruby/commit/e901b6d))
+- Command history with Up/Down navigation ([5f85c1b](https://github.com/mruby/mruby/commit/5f85c1b))
+- Line numbers in multi-line prompts ([5a3f0e2](https://github.com/mruby/mruby/commit/5a3f0e2))
+- UTF-8 multibyte character support ([4a97da3](https://github.com/mruby/mruby/commit/4a97da3))
+
+## mruby-bigint Improvements
+
+- Toom-3 multiplication for large numbers ([99620804](https://github.com/mruby/mruby/commit/99620804))
+- Karatsuba multiplication for medium-sized numbers ([85e81072](https://github.com/mruby/mruby/commit/85e81072))
+- Balance multiplication for asymmetric operands ([0220ec2b](https://github.com/mruby/mruby/commit/0220ec2b))
+- Divide-and-conquer optimization for `to_s` ([990ff90f](https://github.com/mruby/mruby/commit/990ff90f))
+- Consolidated mpn layer for low-level limb operations ([9ef3362f](https://github.com/mruby/mruby/commit/9ef3362f))
+- Always use 32-bit limbs by default ([c747c77f](https://github.com/mruby/mruby/commit/c747c77f))
+
+## Other Gem Changes
+
+- **_NOTE_**: `Hash#deconstruct_keys` removed for CRuby compatibility ([34b9412](https://github.com/mruby/mruby/commit/34b9412))
+- **mruby-enum-lazy**: Fix `Lazy#flat_map` to handle non-enumerable block return values ([#6765](https://github.com/mruby/mruby/pull/6765))
+- **mruby-array-ext**: Add `Array#find` and `Array#rfind` methods
+- **mruby-io**: Add `IO#putc` and `Kernel#putc` ([baff6e6](https://github.com/mruby/mruby/commit/baff6e6))
+- **mruby-random**: Replace xoshiro with PCG for better memory efficiency ([f1bab01](https://github.com/mruby/mruby/commit/f1bab01))
+- **mruby-compiler**: Variable-sized AST nodes for reduced memory usage
+- **mruby-compiler**: `no_return_value` context flag for script optimization ([613b03a](https://github.com/mruby/mruby/commit/613b03a))
+- `initialize_copy` and `respond_to_missing?` defined as private ([#6708](https://github.com/mruby/mruby/pull/6708))
+- Struct keyword argument initialization ([#6574](https://github.com/mruby/mruby/pull/6574))
+
+# Compiler Improvements
+
+- Variable-sized AST nodes for reduced memory consumption ([821b989](https://github.com/mruby/mruby/commit/821b989))
+- Pattern matching bytecode optimizations ([21d4135](https://github.com/mruby/mruby/commit/21d4135))
+- Optimized masgn to generate literals directly into target registers ([fb5d966](https://github.com/mruby/mruby/commit/fb5d966))
+- Optimized splat of literal arrays in args/literals ([1cb8d73](https://github.com/mruby/mruby/commit/1cb8d73))
+- Early termination after too many parse errors ([510ebd7](https://github.com/mruby/mruby/commit/510ebd7))
+- Chunk array literals at 64 elements to reduce register pressure ([f98d641](https://github.com/mruby/mruby/commit/f98d641))
+- Chunk `%w()` and `%i()` literals to reduce register pressure ([62cf0dc](https://github.com/mruby/mruby/commit/62cf0dc))
+
+# VM Optimizations
+
+New super-instructions that fuse common opcode sequences to reduce bytecode size and improve performance:
+
+- `OP_SEND0`/`OP_SSEND0`: Zero-argument method call, avoiding argument count setup ([9123ef4](https://github.com/mruby/mruby/commit/9123ef4))
+- `OP_TDEF`/`OP_SDEF`: Fused method definition combining TCLASS/SCLASS+METHOD+DEF into single instruction, saving 4 bytes per method ([8d4f47e](https://github.com/mruby/mruby/commit/8d4f47e))
+- `OP_GETIDX0`: Fast path for `array[0]` and `Array#first` access ([680f7ec](https://github.com/mruby/mruby/commit/680f7ec))
+- `OP_ADDILV`/`OP_SUBILV`: Local variable increment/decrement fusion for `i += n` patterns ([43f64b9](https://github.com/mruby/mruby/commit/43f64b9))
+- `OP_RETSELF`: Single-byte instruction for `return self` pattern ([a71db8c](https://github.com/mruby/mruby/commit/a71db8c))
+- `OP_RETNIL`: Single-byte instruction for `return nil` pattern ([64e30bf](https://github.com/mruby/mruby/commit/64e30bf))
+- `OP_RETTRUE`/`OP_RETFALSE`: Single-byte instructions for `return true`/`return false` patterns ([0b15727](https://github.com/mruby/mruby/commit/0b15727))
+- `OP_MATCHERR`: Pattern matching error with conditional execution ([944168a](https://github.com/mruby/mruby/commit/944168a))
+- `OP_BLKCALL`: Direct block call for `yield`, bypassing method dispatch (13-17% faster) ([3aa2872](https://github.com/mruby/mruby/commit/3aa2872))
+
+Other optimizations:
+
+- 1.5x stack growth instead of linear growth for reduced reallocations ([f7988c93](https://github.com/mruby/mruby/commit/f7988c93))
+- Skip keyword argument hash duplication ([5970e350](https://github.com/mruby/mruby/commit/5970e350))
+
+# Fixed GitHub Issues
+
+- [#5531](https://github.com/mruby/mruby/issues/5531) Hash recursion detection
+- [#6506](https://github.com/mruby/mruby/issues/6506) Constant lookup in singleton class
+- [#6507](https://github.com/mruby/mruby/issues/6507) tally multi-values
+- [#6508](https://github.com/mruby/mruby/issues/6508) Enumerable#sum index
+- [#6509](https://github.com/mruby/mruby/issues/6509) scope_new nregs initialization
+- [#6515](https://github.com/mruby/mruby/issues/6515) y.tab.c in repository
+- [#6516](https://github.com/mruby/mruby/issues/6516) Private backquote
+- [#6554](https://github.com/mruby/mruby/issues/6554) Socket private #initialize
+- [#6570](https://github.com/mruby/mruby/issues/6570) instance_eval crash
+- [#6613](https://github.com/mruby/mruby/issues/6613) const_added hook during bootstrapping
+- [#6635](https://github.com/mruby/mruby/issues/6635), [#6636](https://github.com/mruby/mruby/issues/6636) Colon3 constant lookup
+- [#6637](https://github.com/mruby/mruby/issues/6637) arm64 mingw64 builtin setjmp/longjmp
+- [#6642](https://github.com/mruby/mruby/issues/6642) Task segfault when sleep called from C
+- [#6645](https://github.com/mruby/mruby/issues/6645) Set memory leak from double initialization
+- [#6646](https://github.com/mruby/mruby/issues/6646) IO#gets negative length
+- [#6647](https://github.com/mruby/mruby/issues/6647) IO#ungetc buffer overflow
+- [#6648](https://github.com/mruby/mruby/issues/6648) sprintf buffer overread
+- [#6649](https://github.com/mruby/mruby/issues/6649) Array#sort! use-after-realloc
+- [#6650](https://github.com/mruby/mruby/issues/6650) Array#fill validation
+- [#6652](https://github.com/mruby/mruby/issues/6652) Array comparison use-after-realloc
+- [#6657](https://github.com/mruby/mruby/issues/6657) Exception handling for ||= on class variables
+- [#6659](https://github.com/mruby/mruby/issues/6659) Super with keyword arguments
+- [#6660](https://github.com/mruby/mruby/issues/6660) Regression on struct/array/hash == override with super
+- [#6662](https://github.com/mruby/mruby/issues/6662) Array set operations use-after-free
+- [#6664](https://github.com/mruby/mruby/issues/6664) Set#flatten memory leak
+- [#6666](https://github.com/mruby/mruby/issues/6666) Regexp literal with encoding
+- [#6668](https://github.com/mruby/mruby/issues/6668) Method#== for aliased methods and comparison bug
+- [#6671](https://github.com/mruby/mruby/issues/6671) Separate inter-gem headers from external API headers
+- [#6674](https://github.com/mruby/mruby/issues/6674) Document pattern matching limitations
+- [#6675](https://github.com/mruby/mruby/issues/6675) Allow Hash#[] to be aliased again
+- [#6687](https://github.com/mruby/mruby/issues/6687) Expand MRB_SYM/MRB_GVSYM support for symbols with special characters
+- [#6698](https://github.com/mruby/mruby/issues/6698) Bigint tests fail on architectures other than x86_64 and i386
+- [#6701](https://github.com/mruby/mruby/issues/6701) Heap-use-after-free in mrb_vm_exec involving mruby-rational / mruby-bigint
+- [#6702](https://github.com/mruby/mruby/issues/6702) mruby-bigint doesn't compile in C++ project
+- [#6704](https://github.com/mruby/mruby/issues/6704) Heap-buffer-overflow in mrb_vm_exec via malformed source code
+- [#6705](https://github.com/mruby/mruby/issues/6705) Can't get outer class of an object in C
+- [#6713](https://github.com/mruby/mruby/issues/6713) mruby-polarssl not work
+- [#6720](https://github.com/mruby/mruby/issues/6720) Random float range: different behavior from CRuby
+- [#6722](https://github.com/mruby/mruby/issues/6722) RBreak size overflow on 32-bit platforms with MRB_NO_BOXING
+- [#6740](https://github.com/mruby/mruby/issues/6740) `%w()`/`%i()` register pressure with large literals
+- [#6741](https://github.com/mruby/mruby/issues/6741) `case`/`in` without `else` should raise `NoMatchingPatternError`
+- [#6760](https://github.com/mruby/mruby/issues/6760) `mrb_gc_unregister()` not removing all matching entries
+
+# Merged Pull Requests
+
+- [#6418](https://github.com/mruby/mruby/pull/6418) Add `ls-lint` with GitHub Actions
+- [#6492](https://github.com/mruby/mruby/pull/6492) fix a typo, update specs
+- [#6493](https://github.com/mruby/mruby/pull/6493) Fix TYPO in memory.md
+- [#6495](https://github.com/mruby/mruby/pull/6495) Remove `MRB_ENDIAN_LOHI()` that is no longer in use
+- [#6497](https://github.com/mruby/mruby/pull/6497) gha: update `build.yml` try `windows-2025` image
+- [#6498](https://github.com/mruby/mruby/pull/6498) Clean up and standardize the pre-commit config
+- [#6501](https://github.com/mruby/mruby/pull/6501) Update pre-commit Node.js version to `v22.14.0 LTS`
+- [#6502](https://github.com/mruby/mruby/pull/6502) pre-commit: update prettier to the latest version
+- [#6503](https://github.com/mruby/mruby/pull/6503) misc: fix typos
+- [#6505](https://github.com/mruby/mruby/pull/6505) mrbgems: fix spelling
+- [#6510](https://github.com/mruby/mruby/pull/6510) Fixed class method visibility via `module_function`
+- [#6511](https://github.com/mruby/mruby/pull/6511) Exclude the external project "lrama" from pre-commit
+- [#6513](https://github.com/mruby/mruby/pull/6513) mruby 3.4.0 released
+- [#6517](https://github.com/mruby/mruby/pull/6517) core/codegen.c: remove unneeded duplicate semicolon
+- [#6518](https://github.com/mruby/mruby/pull/6518) Change mrbc_args.flags bit width from 2 to 3
+- [#6519](https://github.com/mruby/mruby/pull/6519) Add `tools/lrama` to `.prettierignore`
+- [#6520](https://github.com/mruby/mruby/pull/6520) pre-commit: autoupdate and update node LTS version
+- [#6521](https://github.com/mruby/mruby/pull/6521) Add codespell config file `.codespellrc`
+- [#6522](https://github.com/mruby/mruby/pull/6522) gha: label more files
+- [#6523](https://github.com/mruby/mruby/pull/6523) add `rand(Range)` and unify implementations of `Random#rand` and `Kernel#rand`
+- [#6524](https://github.com/mruby/mruby/pull/6524) Fix Kernel#p when no argument
+- [#6525](https://github.com/mruby/mruby/pull/6525) Skip adding empty input to mirb history
+- [#6526](https://github.com/mruby/mruby/pull/6526) Add build config for Luckfox Pico embedded SBC
+- [#6528](https://github.com/mruby/mruby/pull/6528) misc: fix spelling
+- [#6530](https://github.com/mruby/mruby/pull/6530) Revert "class.c (find_visibility_scope): when callinfo returns, \*ep == NULL; #6512"
+- [#6531](https://github.com/mruby/mruby/pull/6531) Improve method table performance by rehashing at 75% load factor
+- [#6532](https://github.com/mruby/mruby/pull/6532) Reverted method table optimizations to prioritize memory savings
+- [#6533](https://github.com/mruby/mruby/pull/6533) Fix calling `extended` callback
+- [#6534](https://github.com/mruby/mruby/pull/6534) Add descriptive comment to mrb_read_float function
+- [#6535](https://github.com/mruby/mruby/pull/6535) Added descriptive comments for functions/macros in src/mempool.c
+- [#6536](https://github.com/mruby/mruby/pull/6536) Add descriptive comments to public functions in src/debug.c
+- [#6537](https://github.com/mruby/mruby/pull/6537) Updated comments in `cdump.c` to remove the `@brief` tag
+- [#6539](https://github.com/mruby/mruby/pull/6539) Add descriptive comments for functions in src/load.c
+- [#6540](https://github.com/mruby/mruby/pull/6540) Add descriptive comments to MRB_API functions in object.c
+- [#6541](https://github.com/mruby/mruby/pull/6541) Add descriptive comments for MRB_API functions in src/array.c
+- [#6542](https://github.com/mruby/mruby/pull/6542) Add descriptive comments to MRB_API functions in src/symbol.c
+- [#6543](https://github.com/mruby/mruby/pull/6543) Add descriptive comments to several functions in src/dump.c
+- [#6544](https://github.com/mruby/mruby/pull/6544) Fix build strings that must be mutable
+- [#6545](https://github.com/mruby/mruby/pull/6545) Add descriptive comments for MRB_API functions in src/class.c
+- [#6548](https://github.com/mruby/mruby/pull/6548) Add descriptive comments to MRB_API functions in src/etc.c
+- [#6549](https://github.com/mruby/mruby/pull/6549) Add descriptive comments to kernel functions
+- [#6550](https://github.com/mruby/mruby/pull/6550) Add descriptive comments for MRB_API functions in src/proc.c
+- [#6551](https://github.com/mruby/mruby/pull/6551) Add descriptive comments for MRB_API functions in src/state.c
+- [#6552](https://github.com/mruby/mruby/pull/6552) Fix: Correct placement of comments in src/variable.c
+- [#6553](https://github.com/mruby/mruby/pull/6553) Add descriptive comments for MRB_API functions in src/vm.c
+- [#6555](https://github.com/mruby/mruby/pull/6555) `mrb_mt_foreach()` needs to update the pointer at each loop
+- [#6556](https://github.com/mruby/mruby/pull/6556) `iv_foreach()` needs to update the pointer at each loop
+- [#6560](https://github.com/mruby/mruby/pull/6560) Refactor: Improve Set GC marking and freeing
+- [#6561](https://github.com/mruby/mruby/pull/6561) pre-commit updates and fix prettier entrypoint
+- [#6562](https://github.com/mruby/mruby/pull/6562) misc: fix spelling word case
+- [#6563](https://github.com/mruby/mruby/pull/6563) pre-commit add rubocop with one rule spaces for indentation
+- [#6564](https://github.com/mruby/mruby/pull/6564) Remove jumanjihouse pre-commit hooks no longer maintained
+- [#6565](https://github.com/mruby/mruby/pull/6565) Rubocop: fix target Ruby version; add two more cops; fix lint error
+- [#6566](https://github.com/mruby/mruby/pull/6566) Removed unreferenced variables in `CrossBuild#run_bintest`
+- [#6567](https://github.com/mruby/mruby/pull/6567) Avoid array object creation in `cmd_bin` method in bintest
+- [#6568](https://github.com/mruby/mruby/pull/6568) mruby-bin-debugger depends on mruby-bin-mrbc in bintest
+- [#6569](https://github.com/mruby/mruby/pull/6569) sed s/Mruby/MRuby/g
+- [#6571](https://github.com/mruby/mruby/pull/6571) Update limitations.md to add behavior on small hash
+- [#6572](https://github.com/mruby/mruby/pull/6572) Add Claude Code GitHub Workflow
+- [#6573](https://github.com/mruby/mruby/pull/6573) pre-commit fixes and updates
+- [#6574](https://github.com/mruby/mruby/pull/6574) Support initializing structs via keyword arguments
+- [#6575](https://github.com/mruby/mruby/pull/6575) Fix typo in file time methods
+- [#6581](https://github.com/mruby/mruby/pull/6581) Merge `mrb_obj_iv_inspect()` into `mrb_obj_inspect()`
+- [#6582](https://github.com/mruby/mruby/pull/6582) Stricter type tag in `mrb_obj_alloc()`
+- [#6583](https://github.com/mruby/mruby/pull/6583) Add fallback to local build_config.rb before using default configuration
+- [#6585](https://github.com/mruby/mruby/pull/6585) Fix typo in mruby3.2 docs
+- [#6586](https://github.com/mruby/mruby/pull/6586) Makefile: refactor add docs and add command line `help` target
+- [#6587](https://github.com/mruby/mruby/pull/6587) Add Set#hash tests
+- [#6588](https://github.com/mruby/mruby/pull/6588) Add CodeQL Analysis for GitHub Actions
+- [#6589](https://github.com/mruby/mruby/pull/6589) Add pre-commit hook `check-zip-file-is-not-committed`
+- [#6591](https://github.com/mruby/mruby/pull/6591) mruby-eval fix license link in README
+- [#6593](https://github.com/mruby/mruby/pull/6593) README: Add Contributors Avatars, Star History, Table of Contents
+- [#6598](https://github.com/mruby/mruby/pull/6598) Fix heap buffer overflow in `#method_missing`
+- [#6599](https://github.com/mruby/mruby/pull/6599) pre-commit: run `markdown-link-check`, `oxipng`, `prettier` manually
+- [#6600](https://github.com/mruby/mruby/pull/6600) `dreamcast_shelf build config`: update to use KallistiOS wrappers
+- [#6601](https://github.com/mruby/mruby/pull/6601) fix: skip local build_config.rb when working in MRUBY_ROOT
+- [#6602](https://github.com/mruby/mruby/pull/6602) Improved iseq annotations for `new` and `!=`
+- [#6604](https://github.com/mruby/mruby/pull/6604) pre-commit config updates
+- [#6607](https://github.com/mruby/mruby/pull/6607) fix bigint on raspberry pi
+- [#6610](https://github.com/mruby/mruby/pull/6610) Extract golden ratio prime into constant
+- [#6614](https://github.com/mruby/mruby/pull/6614) Fix uninitialized variable in io_gets causing segmentation fault
+- [#6617](https://github.com/mruby/mruby/pull/6617) Fix various minor problems and speed up build
+- [#6618](https://github.com/mruby/mruby/pull/6618) Stop generating unnecessary C++ files in mruby-bin-mruby
+- [#6621](https://github.com/mruby/mruby/pull/6621) Set up all GEMS before mruby core tasks definition
+- [#6624](https://github.com/mruby/mruby/pull/6624) Fixed wrong `MRuby::Build.current` at the top level of `mrbgem.rake`
+- [#6628](https://github.com/mruby/mruby/pull/6628) Revert `File.absolute_path` logic
+- [#6629](https://github.com/mruby/mruby/pull/6629) pre-commit update
+- [#6631](https://github.com/mruby/mruby/pull/6631) Revert "Rakefile: make the whole thing parallel unless SERIAL=1"
+- [#6633](https://github.com/mruby/mruby/pull/6633) Fix a heap-buffer-overflow in str strip! methods
+- [#6643](https://github.com/mruby/mruby/pull/6643) Fix crash caused by an incorrect node type check in `codegen_masgn`
+- [#6651](https://github.com/mruby/mruby/pull/6651) Address stack-use-after-return in the mruby bigint implementation
+- [#6653](https://github.com/mruby/mruby/pull/6653) Improve HAL-related components for MinGW
+- [#6655](https://github.com/mruby/mruby/pull/6655) Preventing Memory Leaks in `Array#__combination_init`
+- [#6656](https://github.com/mruby/mruby/pull/6656) Fix integer overflow in allocation size calculation
+- [#6663](https://github.com/mruby/mruby/pull/6663) Added the `kh_is_end()` macro function
+- [#6665](https://github.com/mruby/mruby/pull/6665) Fixed use-after-free with `Set#join`
+- [#6670](https://github.com/mruby/mruby/pull/6670) Arranging VM dispatch macros
+- [#6673](https://github.com/mruby/mruby/pull/6673) Adjust broken license links; clean up Markdown
+- [#6677](https://github.com/mruby/mruby/pull/6677) gha: run pre-commit with `--color=always`
+- [#6678](https://github.com/mruby/mruby/pull/6678) Put ls-lint and pre-commit in separate workflow files
+- [#6679](https://github.com/mruby/mruby/pull/6679) pre-commit autoupdate; update node and prettier
+- [#6681](https://github.com/mruby/mruby/pull/6681) Add Cosmopolitan Libc build configuration
+- [#6689](https://github.com/mruby/mruby/pull/6689) docs: fix pre-commit manual hooks; fix link
+- [#6694](https://github.com/mruby/mruby/pull/6694) Fix mirb build under Cosmopolitan
+- [#6695](https://github.com/mruby/mruby/pull/6695) Dependabot: add a cooldown period for new releases
+- [#6696](https://github.com/mruby/mruby/pull/6696) Fix parse error with required kwargs and omitted parens
+- [#6699](https://github.com/mruby/mruby/pull/6699) Fix mruby-task for PicoRuby Integration
+- [#6700](https://github.com/mruby/mruby/pull/6700) Fix float/double pack/unpack on s390x
+- [#6706](https://github.com/mruby/mruby/pull/6706) Refactor task class to use symbol IDs
+- [#6708](https://github.com/mruby/mruby/pull/6708) `initialize_copy` and `respond_to_missing?` defined as private
+- [#6709](https://github.com/mruby/mruby/pull/6709) Add the `MRB_ENSURE()` macro
+- [#6711](https://github.com/mruby/mruby/pull/6711) Fix out of bounds read and write in IO.select
+- [#6714](https://github.com/mruby/mruby/pull/6714) Fix OP_DEBUG operand type and add NULL check for debug_op_hook
+- [#6716](https://github.com/mruby/mruby/pull/6716) Fixes identity for proc object
+- [#6717](https://github.com/mruby/mruby/pull/6717) Fix mruby-task: wrapping by critical section and setting initial task receiver
+- [#6718](https://github.com/mruby/mruby/pull/6718) Add installation instructions for conda and Homebrew
+- [#6723](https://github.com/mruby/mruby/pull/6723) Add `RInteger` and `RFloat` to `RVALUE`
+- [#6727](https://github.com/mruby/mruby/pull/6727) Language documentation: update wording of "overloading" section
+- [#6729](https://github.com/mruby/mruby/pull/6729) Simplifying dependency addition for gensym task
+- [#6730](https://github.com/mruby/mruby/pull/6730) Simplifying presym file generation actions
+- [#6733](https://github.com/mruby/mruby/pull/6733) Include `mruby/presym.h` for all source files
+- [#6734](https://github.com/mruby/mruby/pull/6734) Chunk array literals at 64 elements to reduce register pressure
+- [#6735](https://github.com/mruby/mruby/pull/6735) Prevent full recompilation without changes to presym file
+- [#6739](https://github.com/mruby/mruby/pull/6739) Fix MSYS2 build error with drive letters
+- [#6743](https://github.com/mruby/mruby/pull/6743) Chunk `%w()` and `%i()` literals to reduce register pressure
+- [#6744](https://github.com/mruby/mruby/pull/6744) Raise `NoMatchingPatternError` in `case`/`in` without `else`
+- [#6747](https://github.com/mruby/mruby/pull/6747) Correctly handle empty hash as default named argument
+- [#6749](https://github.com/mruby/mruby/pull/6749) Fix microcontroller profile
+- [#6750](https://github.com/mruby/mruby/pull/6750) Fix out-of-bounds read and divide-by-zero in `Array#product`
+- [#6752](https://github.com/mruby/mruby/pull/6752) Fix `attr_reader`-generated methods accepting extra arguments
+- [#6753](https://github.com/mruby/mruby/pull/6753) Further optimize `Array#product`
+- [#6754](https://github.com/mruby/mruby/pull/6754) Mark `attr_reader` procs as noarg
+- [#6755](https://github.com/mruby/mruby/pull/6755) Reload `ci` after `mrb_hash_delete_key()` in keyword argument handling
+- [#6756](https://github.com/mruby/mruby/pull/6756) Avoid impact of object modifications caused by `mrb_vm_exec()` calls
+- [#6758](https://github.com/mruby/mruby/pull/6758) Don't assign result of `mrb_funcall()` directly to `regs`
+- [#6759](https://github.com/mruby/mruby/pull/6759) Define `mrb_bigint_p()` always
+- [#6761](https://github.com/mruby/mruby/pull/6761) Fix `mrb_gc_unregister()` to remove all matching entries
+- [#6762](https://github.com/mruby/mruby/pull/6762) Write generated test C files atomically to avoid build race condition
+- [#6765](https://github.com/mruby/mruby/pull/6765) Fix `Lazy#flat_map` to handle non-enumerable block return values
+- [#6767](https://github.com/mruby/mruby/pull/6767) Allow compound statement in parenthesized argument context
+- [#6780](https://github.com/mruby/mruby/pull/6780) Fix `String#prepend` with self-referencing arguments
+- [#6781](https://github.com/mruby/mruby/pull/6781) Protect `sprintf` format string from mutation during callbacks
+- [#6783](https://github.com/mruby/mruby/pull/6783) Pin GitHub Actions workflows to commit hashes
+
+# Security Fixes
+
+- Buffer overflow in bigint uadd ([3f2611e](https://github.com/mruby/mruby/commit/3f2611e))
+- Stack buffer overflow in Montgomery reduction ([edce0a3](https://github.com/mruby/mruby/commit/edce0a3))
+- Buffer overflow in pack_uu encoding ([2993302](https://github.com/mruby/mruby/commit/2993302))
+- Buffer overflow in IO#ungetc ([01ab2ff](https://github.com/mruby/mruby/commit/01ab2ff))
+- Heap-buffer-overflow in pattern alternation codegen ([eea9e30](https://github.com/mruby/mruby/commit/eea9e30))
+- Out of bounds read and write in IO.select ([44831711](https://github.com/mruby/mruby/commit/44831711))
+- Off-by-one in bounds check for symbol names and pool strings in load.c ([b3b8c01](https://github.com/mruby/mruby/commit/b3b8c01))
+- Use-after-free in Set operations ([a6b55e7](https://github.com/mruby/mruby/commit/a6b55e7))
+- Use-after-free in Array set operations ([729b84c](https://github.com/mruby/mruby/commit/729b84c))
+- Use-after-free in Set#join ([0e653eb](https://github.com/mruby/mruby/commit/0e653eb))
+- Use-after-realloc in Array#sort! ([eb39897](https://github.com/mruby/mruby/commit/eb39897))
+- Heap-use-after-free in insertion_sort ([099d2c47](https://github.com/mruby/mruby/commit/099d2c47))
+- Integer overflow in str_check_length ([6afff1c3](https://github.com/mruby/mruby/commit/6afff1c3))
+- Integer overflow in Integer#lcm ([070bef24](https://github.com/mruby/mruby/commit/070bef24))
+- Heap buffer overflow in `#method_missing` ([550d10a](https://github.com/mruby/mruby/commit/550d10a))
+- Out-of-bounds read and divide-by-zero in `Array#product` ([8441eaf](https://github.com/mruby/mruby/commit/8441eaf))
+- Heap buffer overflow in `String#prepend` with self-referencing arguments ([18ba026](https://github.com/mruby/mruby/commit/18ba026))
+- Use-after-free in `sprintf` via `to_s` callback mutating format string ([48fc422](https://github.com/mruby/mruby/commit/48fc422))
+- Multiple memory leak fixes in bigint, Set, Array, and Task gems

README.md

@@ -1,40 +1,70 @@
-# mruby
+<div align="center">
+  <p>
+    <a href="https://mruby.org/">
+      <img src="https://avatars.githubusercontent.com/u/1796512?s=200&v=4"
+        alt="The mruby programming language" title="mruby">
+    </a>
+  </p>
+  <h1>mruby</h1>
+  <a href="https://github.com/marketplace/actions/super-linter">
+    <img src="https://github.com/mruby/mruby/actions/workflows/super-linter.yml/badge.svg"
+      alt="GitHub Super-Linter">
+  </a>
+</div>
 
-[![GitHub Super-Linter](https://github.com/mruby/mruby/workflows/Lint%20Code%20Base/badge.svg)](https://github.com/marketplace/actions/super-linter)
+### Table of contents
+
+- [What is mruby](#what-is-mruby)
+- [How to get mruby](#how-to-get-mruby)
+- [mruby homepage](#mruby-homepage)
+- [Mailing list](#mailing-list)
+- [How to compile, test, and install (mruby and gems)](#how-to-compile-test-and-install-mruby-and-gems)
+- [Amalgamation (single-file build)](#amalgamation-single-file-build)
+- [Building documentation](#building-documentation)
+- [How to customize mruby (mrbgems)](#how-to-customize-mruby-mrbgems)
+- [Index of Document](#index-of-document)
+- [License](#license)
+- [Note for License](#note-for-license)
+- [How to Contribute](#how-to-contribute)
+- [Star History](#star-history)
+- [Contributors](#contributors)
 
 ## What is mruby
 
 mruby is the lightweight implementation of the Ruby language complying to (part
-of) the [ISO standard][ISO-standard]. Its syntax is Ruby 2.x compatible.
+of) the [ISO standard][ISO-standard] with more recent features provided by Ruby 4.x.
+Also, its syntax is Ruby 4.x compatible.
 
-mruby can be linked and embedded within your application. We provide the
-interpreter program "mruby", and the interactive mruby shell "mirb" as examples.
-You can also compile Ruby programs into compiled byte code using the mruby
-compiler "mrbc". All those tools reside in the "bin" directory. "mrbc" is
-also able to generate compiled byte code in a C source file, see the "mrbtest"
-program under the "test" directory for an example.
+You can link and embed mruby within your application. The "mruby" interpreter
+program and the interactive "mirb" shell are provided as examples. You can also
+compile Ruby programs into compiled byte code using the "mrbc" compiler. All
+these tools are located in the "bin" directory. "mrbc" can also generate
+compiled byte code in a C source file. See the "mrbtest" program under the
+"test" directory for an example.
 
 This achievement was sponsored by the Regional Innovation Creation R&D Programs
 of the Ministry of Economy, Trade and Industry of Japan.
 
 ## How to get mruby
 
-The release candidate version 3.2.0 of mruby can be downloaded via the following URL: [https://github.com/mruby/mruby/archive/3.2.0-rc.zip](https://github.com/mruby/mruby/archive/3.2.0-rc.zip)
+To get mruby, you can download the stable version 4.0.0 from the official mruby
+GitHub repository or clone the trunk of the mruby source tree with the "git
+clone" command. You can also install and compile mruby using [ruby-install](https://github.com/postmodern/ruby-install), [ruby-build](https://github.com/rbenv/ruby-build), [rvm](https://github.com/rvm/rvm), [conda](https://anaconda.org/channels/conda-forge/packages/mruby/overview) or [Homebrew](https://formulae.brew.sh/formula/mruby).
+
+The release candidate version 4.0.0 of mruby can be downloaded via the following URL: [https://github.com/mruby/mruby/archive/4.0.0-rc3.zip](https://github.com/mruby/mruby/archive/4.0.0-rc3.zip)
 
 The latest development version of mruby can be downloaded via the following URL: [https://github.com/mruby/mruby/zipball/master](https://github.com/mruby/mruby/zipball/master)
 
 The trunk of the mruby source tree can be checked out with the
 following command:
 
-```
+```console
 $ git clone https://github.com/mruby/mruby.git
 ```
 
-You can also install and compile mruby using [ruby-install](https://github.com/postmodern/ruby-install), [ruby-build](https://github.com/rbenv/ruby-build) or [rvm](https://github.com/rvm/rvm).
+## mruby homepage
 
-## mruby home-page
-
-The URL of the mruby home-page is: <https://mruby.org>.
+The URL of the mruby homepage is: <https://mruby.org>.
 
 ## Mailing list
 
@@ -44,35 +74,79 @@ We don't have a mailing list, but you can use [GitHub issues](https://github.com
 
 For the simplest case, type
 
-```
+```console
 rake all test
 ```
 
 See the [compile.md](doc/guides/compile.md) file for the detail.
 
+## Amalgamation (single-file build)
+
+mruby supports amalgamation, which combines all source files into a single
+`mruby.c` and `mruby.h` for easy embedding (similar to SQLite).
+
+```console
+rake amalgam
+```
+
+Output files are generated in `build/host/amalgam/`. To use:
+
+```console
+gcc -I./build/host/amalgam your_app.c ./build/host/amalgam/mruby.c -o your_app -lm
+```
+
 ## Building documentation
 
-There are two sets of documentation in mruby: the mruby API (generated by yard) and C API (Doxygen and Graphviz)
+There are two sets of documentation in mruby: the mruby API (generated by YARD) and C API (Doxygen and Graphviz)
 
 To build both of them, simply go
 
-```
+```console
 rake doc
 ```
 
 You can also view them in your browser
 
-```
+```console
 rake view_api
 rake view_capi
 ```
 
 ## How to customize mruby (mrbgems)
 
-mruby contains a package manager called *mrbgems*. To create extensions
-in C and/or Ruby you should create a *GEM*. For a documentation of how to
-use mrbgems consult the file [mrbgems.md](doc/guides/mrbgems.md).
-For example code of how to use mrbgems look into the folder [examples/mrbgems/](examples/mrbgems).
+mruby contains a package manager called "mrbgems" that you can use to create
+extensions in C and/or Ruby. For a guide on how to use mrbgems, consult the
+[mrbgems.md](doc/guides/mrbgems.md) file, and for example code, refer to the
+[examples/mrbgems/](examples/mrbgems) folder.
+
+## Index of Document
+
+<!--
+    This section is generated by `rake doc:update-index`.
+    All manual changes will get lost.
+-->
+
+<!-- BEGIN OF MRUBY DOCUMENT INDEX -->
+
+- [About the Limitations of mruby](doc/limitations.md)
+- [About Amalgamation (Single-File Build)](doc/guides/amalgamation.md)
+- [C API Reference](doc/guides/capi.md)
+- [About the Compile](doc/guides/compile.md)
+- [About the Debugger with the `mrdb` Command](doc/guides/debugger.md)
+- [About GC Arena](doc/guides/gc-arena-howto.md)
+- [Getting Started with mruby](doc/guides/getting-started.md)
+- [About the mruby directory structure](doc/guides/hier.md)
+- [About Linking with `libmruby`](doc/guides/link.md)
+- [About Memory Allocator Customization and Heap Regions](doc/guides/memory.md)
+- [About Build-time Configurations](doc/guides/mrbconf.md)
+- [About the Build-time Library Manager](doc/guides/mrbgems.md)
+- [ROM Method Tables for Memory-Efficient Method Registration](doc/guides/rom-method-table.md)
+- [About the Symbols](doc/guides/symbol.md)
+- [Internal Implementation / About mruby Architecture](doc/internal/architecture.md)
+- [Internal Implementation / About Value Boxing](doc/internal/boxing.md)
+- [Internal Implementation / About mruby Virtual Machine Instructions](doc/internal/opcode.md)
+
+<!-- END OF MRUBY DOCUMENT INDEX -->
 
 ## License
 
@@ -97,9 +171,16 @@ Please ask us if you want to distribute your code under another license.
 
 ## How to Contribute
 
-See the [contribution guidelines][contribution-guidelines], and then send a pull
-request to <https://github.com/mruby/mruby>. We consider you have granted
-non-exclusive right to your contributed code under MIT license.
+To contribute to mruby, please refer to the [contribution guidelines][contribution-guidelines] and send a pull request to the [mruby GitHub repository](https://github.com/mruby/mruby).
+By contributing, you grant non-exclusive rights to your code under the MIT License.
 
-[ISO-standard]: https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=59579
-[contribution-guidelines]: https://github.com/mruby/mruby/blob/master/CONTRIBUTING.md
+## Star History
+
+[![mruby Star History](https://api.star-history.com/svg?repos=mruby/mruby&type=Date)](https://www.star-history.com/#mruby/mruby&Date)
+
+## Contributors
+
+[![mruby Contributors](https://contrib.rocks/image?repo=mruby/mruby&anon=1&max=500)](https://github.com/mruby/mruby/graphs/contributors)
+
+[ISO-standard]: https://www.iso.org/standard/59579.html
+[contribution-guidelines]: CONTRIBUTING.md

Rakefile

@@ -16,6 +16,11 @@ require "mruby/build"
 MRUBY_CONFIG = MRuby::Build.mruby_config_path
 load MRUBY_CONFIG
 
+# set up all gems
+MRuby.each_target do
+  gems.setup(self) if enable_gems?
+end
+
 # load basic rules
 MRuby.each_target do |build|
   build.define_rules
@@ -31,6 +36,8 @@ load "#{MRUBY_ROOT}/tasks/presym.rake"
 load "#{MRUBY_ROOT}/tasks/test.rake"
 load "#{MRUBY_ROOT}/tasks/benchmark.rake"
 load "#{MRUBY_ROOT}/tasks/doc.rake"
+load "#{MRUBY_ROOT}/tasks/install.rake"
+load "#{MRUBY_ROOT}/tasks/amalgam.rake"
 
 ##############################
 # generic build targets, rules
@@ -56,7 +63,7 @@ task :clean do
     rm_rf build.build_dir
     rm_f build.products
   end
-  puts "Cleaned up target build folder"
+  puts "Cleaned up target build directory"
 end
 
 desc "clean everything!"
@@ -64,43 +71,32 @@ task :deep_clean => %w[clean doc:clean] do
   MRuby.each_target do |build|
     rm_rf build.gem_clone_dir
   end
-  puts "Cleaned up mrbgems build folder"
-end
-
-PREFIX = ENV['PREFIX'] || ENV['INSTALL_PREFIX'] || '/usr/local'
-
-desc "install compiled products"
-task :install => :install_bin do
-  if host = MRuby.targets['host']
-    install_D host.libmruby_static, File.join(PREFIX, "lib", File.basename(host.libmruby_static))
-    # install mruby.h and mrbconf.h
-    Dir.glob(File.join(MRUBY_ROOT, "include", "*.h")) do |src|
-      install_D src, File.join(PREFIX, "include", File.basename(src))
-    end
-    Dir.glob(File.join(MRUBY_ROOT, "include", "mruby", "*.h")) do |src|
-      install_D src, File.join(PREFIX, "include", "mruby", File.basename(src))
-    end
-    Dir.glob(File.join(File.join(MRUBY_ROOT, "build", "host", "include", "mruby", "presym", "*.h"))) do |src|
-      install_D src, File.join(PREFIX, "include", "mruby", "presym", File.basename(src))
-    end
-  end
-end
-
-desc "install compiled executable (on host)"
-task :install_bin => :all do
-  if host = MRuby.targets['host']
-    Dir.glob(File.join(MRUBY_ROOT, "bin", "*")) do |src|
-      install_D src, File.join(PREFIX, "bin", File.basename(src))
-    end
-  end
+  rm_rf "#{MRUBY_ROOT}/bin"
+  rm_rf "#{MRUBY_ROOT}/build"
+  puts "Cleaned up mrbgems build directory"
 end
 
 desc "run all pre-commit hooks against all files"
 task :check do
-  sh "pre-commit run --all-files"
+  sh "prek run --all-files"
+end
+
+desc "install the pre-commit hooks"
+task :checkinstall do
+  sh "prek install"
 end
 
 desc "check the pre-commit hooks for updates"
 task :checkupdate do
-  sh "pre-commit autoupdate"
+  sh "prek autoupdate"
+end
+
+desc "run all pre-commit hooks against all files with docker-compose"
+task :composecheck do
+  sh "docker-compose -p mruby run test prek run --all-files"
+end
+
+desc "build and run all mruby tests with docker-compose"
+task :composetest do
+  sh "docker-compose -p mruby run test"
 end

SECURITY.md

@@ -2,19 +2,53 @@
 
 ## Reporting a Vulnerability
 
-If you have any security concern, contact <matz@ruby.or.jp>.
+To report a security vulnerability, please email the mruby team at <matz@ruby.or.jp>. We appreciate your efforts to disclose your findings responsibly.
 
 ## Scope
 
-We consider the following issues as vulnerabilities:
+mruby is an embeddable Ruby implementation. Its security model is designed for integration into a host application, which is responsible for sandboxing and resource management. This policy defines what we consider a security vulnerability within the mruby interpreter itself.
 
-- Remote code execution
-- Crash caused by a valid Ruby script
+### High Priority Security Vulnerabilities
 
-We *don't* consider the following issues as vulnerabilities:
+We consider the following issues to be **high priority security vulnerabilities**:
 
-- Runtime C undefined behavior (including integer overflow)
-- Crash caused by misused API
-- Crash caused by modified compiled binary
-- ASAN/Valgrind warning for too big memory allocation
-  mruby assumes `malloc(3)` returns `NULL` for too big allocations
+- **Remote Code Execution (RCE)**: The ability to execute arbitrary machine code or shell commands from within a Ruby script, beyond the intended execution scope of the script itself.
+
+### Lower Priority: Crashes (Preferably Report as Bugs)
+
+We **accept but deprioritize** the following issues. We recommend reporting them as **bug reports** on our issue tracker rather than security reports:
+
+- **VM Crash on Valid Ruby Code**: Segmentation faults, assertion failures, or other interpreter crashes triggered by syntactically and semantically valid Ruby scripts.
+  - _Recommendation_: Please report these as bugs on our issue tracker.
+  - _Rationale_: While we will fix these issues, they typically only result in denial of service (DoS), not arbitrary code execution. They are lower priority than RCE vulnerabilities.
+  - _Note_: This does not include standard Ruby exceptions like `TypeError` or `ZeroDivisionError`, which are expected behavior.
+  - _Example_: A segmentation fault when running `[1, 2, 3].map { |x| x * 2 }` is best reported as a bug.
+
+### Out of Scope: Not Considered Security Vulnerabilities
+
+We do **not** consider the following issues to be security vulnerabilities:
+
+- **Resource Exhaustion**: Infinite loops, excessive memory allocation, or high CPU usage originating from a Ruby script.
+  - _Rationale_: The host application is responsible for implementing resource limits, sandboxing, and execution timeouts. mruby provides the execution engine; the host provides the constraints.
+  - _Example_: `loop {}` or `"a" * (2**30)` are not vulnerabilities, even if they lead to memory or CPU exhaustion.
+
+- **Crashes from Malformed Bytecode**: Crashes resulting from loading or executing corrupted or intentionally malformed `.mrb` files.
+  - _Rationale_: mruby's bytecode format is not a security boundary. Applications should only execute bytecode from trusted sources.
+  - _Example_: A crash discovered by fuzzing `.mrb` files is not considered a vulnerability.
+
+- **Crashes from C API Misuse**: Crashes caused by incorrect usage of mruby's C API from the embedding application.
+  - _Rationale_: The C API is a trusted interface for developers. The caller is responsible for adhering to the API contract (e.g., not passing `NULL` pointers, managing object lifetimes correctly).
+  - _Example_: Calling `mrb_funcall()` with an invalid `mrb_state*` pointer is not a vulnerability.
+
+- **Theoretical Undefined Behavior (UB)**: Issues reported by tools like ASAN, UBSan, or Valgrind that do not lead to a demonstrable crash or exploitable behavior in practice.
+  - _Rationale_: While we strive for clean, well-defined code, our focus is on practical security impact. We prioritize fixing UB that is exploitable over issues that are purely theoretical.
+  - _Example_: An integer overflow in an intermediate calculation that gets handled correctly before affecting program output or control flow.
+
+- **Warnings on Large Memory Allocations**: Tooling warnings related to large memory allocations that do not result in a crash.
+  - _Rationale_: mruby is designed to handle `malloc(3)` returning `NULL` on large allocation requests. This is considered graceful error handling, not a vulnerability.
+
+### Summary
+
+- **High Priority Security Reports**: Remote code execution vulnerabilities.
+- **Accepted (but preferably as bug reports)**: VM crashes from valid Ruby code.
+- **Not Accepted as Security Issues**: Resource exhaustion, malformed bytecode, C API misuse, theoretical undefined behavior, or allocation warnings.

TODO.md

@@ -1,13 +1,17 @@
 # Things to Do in the future
 
-# After mruby 3.1
+# After mruby 3.4
 
 - parser and code generator independent from `mrb_state` (picoruby?)
-- variable sized AST node
 - iv/hash entry cache
+- method inline caching improvements (cache method lookup results)
 - more peephole optimization (if possible)
+- built-in profiler (method call tracing, stack profiling, detailed memory analysis)
+- improved REPL (mirb) features (syntax highlighting)
+- configurable memory pools (per-object-type, memory-constrained devices)
+- suspend/resume VM state (serialize/deserialize for power cycling)
+- CMake build support (better IDE integration, standard C tooling)
 
 # Things to do (Things we need to consider)
 
-- `begin ... end while cond` to behave as CRuby
 - special variables ($1,$2..)

appveyor.yml

@@ -4,42 +4,44 @@ shallow_clone: true
 
 environment:
   matrix:
-    - job_name: Visual Studio 2019 64bit
+    - job_name: Visual Studio 2022 64-bit
+      visualcpp: C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvars64.bat
+      appveyor_build_worker_image: Visual Studio 2022
+
+    - job_name: Visual Studio 2019 64-bit
       visualcpp: C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvars64.bat
       appveyor_build_worker_image: Visual Studio 2019
 
-    - job_name: Visual Studio 2019 32bit
+    - job_name: Visual Studio 2019 32-bit
       visualcpp: C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvars32.bat
       appveyor_build_worker_image: Visual Studio 2019
 
-    - job_name: Visual Studio 2017 64bit
+    - job_name: Visual Studio 2017 64-bit
       visualcpp: C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvars64.bat
       appveyor_build_worker_image: Visual Studio 2017
 
-    - job_name: Visual Studio 2017 32bit
+    - job_name: Visual Studio 2017 32-bit
       visualcpp: C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvars32.bat
       appveyor_build_worker_image: Visual Studio 2017
 
-    - job_name: Visual Studio 2015 64bit
+    - job_name: Visual Studio 2015 64-bit
       visualcpp: C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat
       appveyor_build_worker_image: Visual Studio 2015
       machine: x86_amd64
 
-    - job_name: Visual Studio 2015 32bit
+    - job_name: Visual Studio 2015 32-bit
       visualcpp: C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat
       appveyor_build_worker_image: Visual Studio 2015
       machine: x86
 
 init:
   - call "%visualcpp%" %machine%
-  # For using RubyInstaller's Ruby 2.6 64bit
+  # For using RubyInstaller's Ruby 2.6 64-bit
   # 2.6 is the highest supported Ruby version across all historical
   # Visual Studio AppVeyor images. Ruby 2.7 is only on the 2019 image.
   - set PATH=C:\Ruby26-x64\bin;%PATH%
   - ruby --version
 
-
 build_script:
   - set MRUBY_CONFIG=ci/msvc
-  - rake -m test:build
-  - rake test:run
+  - rake -m test:run:serial

benchmark/bm_ao_render.rb

@@ -253,6 +253,7 @@ class Scene
 
   def render(w, h, nsubsamples)
     nsf = nsubsamples.to_f
+    nsfs = nsf * nsf
     h.times do |y|
       w.times do |x|
         rad = Vec.new(0.0, 0.0, 0.0)
@@ -288,9 +289,9 @@ class Scene
           end
         end
 
-        r = rad.x / (nsf * nsf)
-        g = rad.y / (nsf * nsf)
-        b = rad.z / (nsf * nsf)
+        r = rad.x / nsfs
+        g = rad.y / nsfs
+        b = rad.z / nsfs
         printf("%c", clamp(r))
         printf("%c", clamp(g))
         printf("%c", clamp(b))

benchmark/bm_mandel_term.rb

@@ -0,0 +1,34 @@
+def mandelbrot(c_r, c_i)
+  limit=95
+  iterations=0
+  cr = (c_r * 100).to_i
+  ci = (c_i * 100).to_i
+  zr = zi = 0
+  # Avoid sqrt by squaring the threshold: sqrt(x) < 1000 => x < 1000000
+  while iterations<limit
+    zr2 = zr*zr
+    zi2 = zi*zi
+    break if zr2+zi2 >= 1000000
+    zr, zi = (zr2-zi2)/100+cr, (zr*zi*2)/100+ci
+    iterations+=1
+  end
+  return iterations
+end
+
+def mandel_calc(min_r, min_i, max_r, max_i, res)
+  cur_i = min_i
+  while cur_i > max_i
+    putc "|"
+    cur_r = min_r
+    while cur_r < max_r
+      ch = 127 - mandelbrot(cur_r, cur_i)
+      putc ch  # Use putc with integer - no string allocation!
+      cur_r += res
+    end
+    putc "|"
+    putc "\n"
+    cur_i -= res
+  end
+end
+
+mandel_calc(-2, 1, 1, -1, 0.04)

benchmark/bm_so_mandelbrot.rb

@@ -0,0 +1,65 @@
+#  The Computer Language Benchmarks Game
+#  http://shootout.alioth.debian.org/
+#
+#  contributed by Karl von Laudermann
+#  modified by Jeremy Echols
+#  optimized: while loops instead of for..in to avoid closure overhead
+
+size = 600 # ARGV[0].to_i
+
+puts "P4\n#{size} #{size}"
+
+# Cache constants in local variables to avoid repeated constant lookup
+iter = 49
+limit_squared = 4.0
+
+byte_acc = 0
+bit_num = 0
+
+count_size = size - 1
+
+# Use while loops instead of for..in to avoid closure/upvalue overhead
+y = 0
+while y <= count_size
+  x = 0
+  while x <= count_size
+    zr = 0.0
+    zi = 0.0
+    cr = (2.0*x/size)-1.5
+    ci = (2.0*y/size)-1.0
+    escape = false
+
+    # Use while instead of for..in to avoid closure overhead
+    i = 0
+    while i <= iter
+      tr = zr*zr - zi*zi + cr
+      ti = 2*zr*zi + ci
+      zr = tr
+      zi = ti
+
+      if (zr*zr+zi*zi) > limit_squared
+        escape = true
+        break
+      end
+      i += 1
+    end
+
+    byte_acc = (byte_acc << 1) | (escape ? 0b0 : 0b1)
+    bit_num += 1
+
+    # Code is very similar for these cases, but using separate blocks
+    # ensures we skip the shifting when it's unnecessary, which is most cases.
+    if (bit_num == 8)
+      print byte_acc.chr
+      byte_acc = 0
+      bit_num = 0
+    elsif (x == count_size)
+      byte_acc <<= (8 - bit_num)
+      print byte_acc.chr
+      byte_acc = 0
+      bit_num = 0
+    end
+    x += 1
+  end
+  y += 1
+end

benchmark/vm_dispatch_bench.c

@@ -0,0 +1,197 @@
+/*
+ * VM Dispatch Micro-benchmark
+ *
+ * This benchmark measures the raw dispatch overhead of the mruby VM
+ * by executing minimal bytecode sequences.
+ *
+ * Compile:
+ *   cc -O2 -I include -I build/host/include \
+ *      benchmark/vm_dispatch_bench.c \
+ *      build/host/lib/libmruby.a -lm -o vm_dispatch_bench
+ *
+ * Run:
+ *   ./vm_dispatch_bench
+ */
+
+#include <mruby.h>
+#include <mruby/compile.h>
+#include <mruby/string.h>
+#include <mruby/proc.h>
+#include <stdio.h>
+#include <time.h>
+
+#define ITERATIONS 10
+
+static double
+get_time_ms(void)
+{
+  struct timespec ts;
+  clock_gettime(CLOCK_MONOTONIC, &ts);
+  return ts.tv_sec * 1000.0 + ts.tv_nsec / 1000000.0;
+}
+
+static void
+run_benchmark(mrb_state *mrb, const char *name, const char *code, int iterations)
+{
+  double times[ITERATIONS];
+  double total = 0.0;
+  double min_time = 1e9;
+  double max_time = 0.0;
+
+  /* Compile once */
+  mrbc_context *cxt = mrbc_context_new(mrb);
+  struct mrb_parser_state *p = mrb_parse_string(mrb, code, cxt);
+  if (!p || p->nerr > 0) {
+    fprintf(stderr, "Failed to parse: %s\n", name);
+    if (p) mrb_parser_free(p);
+    mrbc_context_free(mrb, cxt);
+    return;
+  }
+  struct RProc *proc = mrb_generate_code(mrb, p);
+  mrb_parser_free(p);
+  mrbc_context_free(mrb, cxt);
+
+  if (!proc) {
+    fprintf(stderr, "Failed to compile: %s\n", name);
+    return;
+  }
+
+  /* Warm up */
+  for (int i = 0; i < 3; i++) {
+    mrb_top_run(mrb, proc, mrb_top_self(mrb), 0);
+    mrb->exc = NULL;
+  }
+
+  /* Measure */
+  for (int i = 0; i < iterations; i++) {
+    mrb_gc_arena_save(mrb);
+    mrb_full_gc(mrb);
+
+    double t0 = get_time_ms();
+    mrb_top_run(mrb, proc, mrb_top_self(mrb), 0);
+    double t1 = get_time_ms();
+
+    times[i] = t1 - t0;
+    total += times[i];
+    if (times[i] < min_time) min_time = times[i];
+    if (times[i] > max_time) max_time = times[i];
+
+    mrb->exc = NULL;
+    mrb_gc_arena_restore(mrb, 0);
+  }
+
+  double avg = total / iterations;
+  printf("%-30s avg: %8.2f ms  min: %8.2f ms  max: %8.2f ms\n",
+         name, avg, min_time, max_time);
+}
+
+int
+main(int argc, char **argv)
+{
+  mrb_state *mrb = mrb_open();
+  if (!mrb) {
+    fprintf(stderr, "Failed to create mrb_state\n");
+    return 1;
+  }
+
+  printf("========================================\n");
+  printf("mruby VM Dispatch Micro-benchmarks\n");
+  printf("========================================\n\n");
+
+  /* 1. Pure dispatch overhead */
+  printf("--- Dispatch Overhead ---\n");
+
+  run_benchmark(mrb, "empty_loop_1M",
+    "i = 0; while i < 1000000; i += 1; end", ITERATIONS);
+
+  run_benchmark(mrb, "empty_loop_10M",
+    "i = 0; while i < 10000000; i += 1; end", ITERATIONS);
+
+  /* 2. Arithmetic operations */
+  printf("\n--- Arithmetic ---\n");
+
+  run_benchmark(mrb, "int_add_1M",
+    "x = 0; i = 0; while i < 1000000; x = x + 1; i += 1; end", ITERATIONS);
+
+  run_benchmark(mrb, "int_mul_1M",
+    "x = 1; i = 0; while i < 1000000; x = x * 1; i += 1; end", ITERATIONS);
+
+  run_benchmark(mrb, "float_add_1M",
+    "x = 0.0; i = 0; while i < 1000000; x = x + 1.0; i += 1; end", ITERATIONS);
+
+  /* 3. Method calls */
+  printf("\n--- Method Calls ---\n");
+
+  run_benchmark(mrb, "empty_method_100K",
+    "class X; def m; end; end; "
+    "o = X.new; i = 0; while i < 100000; o.m; i += 1; end", ITERATIONS);
+
+  run_benchmark(mrb, "method_1arg_100K",
+    "class Y; def m(a); a; end; end; "
+    "o = Y.new; i = 0; while i < 100000; o.m(1); i += 1; end", ITERATIONS);
+
+  run_benchmark(mrb, "method_2arg_100K",
+    "class Z; def m(a,b); a+b; end; end; "
+    "o = Z.new; i = 0; while i < 100000; o.m(1,2); i += 1; end", ITERATIONS);
+
+  /* 4. Array access */
+  printf("\n--- Array/Hash ---\n");
+
+  run_benchmark(mrb, "array_read_1M",
+    "a = [0,1,2,3,4,5,6,7,8,9]; "
+    "i = 0; s = 0; while i < 1000000; s += a[i % 10]; i += 1; end", ITERATIONS);
+
+  run_benchmark(mrb, "array_write_1M",
+    "a = [0,0,0,0,0,0,0,0,0,0]; "
+    "i = 0; while i < 1000000; a[i % 10] = i; i += 1; end", ITERATIONS);
+
+  run_benchmark(mrb, "hash_read_100K",
+    "h = {0=>0,1=>1,2=>2,3=>3,4=>4,5=>5,6=>6,7=>7,8=>8,9=>9}; "
+    "i = 0; s = 0; while i < 100000; s += h[i % 10]; i += 1; end", ITERATIONS);
+
+  /* 5. Comparison and branching */
+  printf("\n--- Comparison/Branch ---\n");
+
+  run_benchmark(mrb, "lt_compare_1M",
+    "i = 0; c = 0; while i < 1000000; c += 1 if i < 500000; i += 1; end", ITERATIONS);
+
+  run_benchmark(mrb, "eq_compare_1M",
+    "i = 0; c = 0; while i < 1000000; c += 1 if i == 500000; i += 1; end", ITERATIONS);
+
+  /* 6. Block calls */
+  printf("\n--- Blocks ---\n");
+
+  run_benchmark(mrb, "times_100K",
+    "s = 0; 100000.times { |i| s += i }", ITERATIONS);
+
+  run_benchmark(mrb, "each_100K",
+    "a = (0...1000).to_a; s = 0; 100.times { a.each { |x| s += x } }", ITERATIONS);
+
+  /* 7. Recursion */
+  printf("\n--- Recursion ---\n");
+
+  run_benchmark(mrb, "fib_25",
+    "def fib(n); n < 2 ? n : fib(n-1) + fib(n-2); end; fib(25)", ITERATIONS);
+
+  run_benchmark(mrb, "fib_30",
+    "def fib(n); n < 2 ? n : fib(n-1) + fib(n-2); end; fib(30)", ITERATIONS);
+
+  /* 8. Local variable access */
+  printf("\n--- Local Variables ---\n");
+
+  run_benchmark(mrb, "few_vars_1M",
+    "i = 0; a = 0; b = 0; "
+    "while i < 1000000; a += 1; b += 1; i += 1; end", ITERATIONS);
+
+  run_benchmark(mrb, "many_vars_1M",
+    "i = 0; a = 0; b = 0; c = 0; d = 0; e = 0; f = 0; g = 0; h = 0; "
+    "while i < 1000000; a += 1; b += 1; c += 1; d += 1; e += 1; "
+    "f += 1; g += 1; h += 1; i += 1; end", ITERATIONS);
+
+  printf("\n========================================\n");
+  printf("Benchmark complete\n");
+  printf("========================================\n");
+
+  mrb_close(mrb);
+  return 0;
+}

benchmark/vm_optimization_bench.rb

@@ -0,0 +1,513 @@
+# VM Optimization Benchmarks for mruby
+# Usage: ./bin/mruby benchmark/vm_optimization_bench.rb
+#
+# Each benchmark is designed to isolate specific VM behaviors:
+# - Dispatch overhead
+# - Arithmetic operations
+# - Method calls
+# - Array/Hash access
+# - Loop performance
+
+# Benchmark infrastructure
+def measure(name, iterations = 1)
+  # Warm up
+  3.times { yield }
+
+  # Force GC before measurement
+  GC.start
+
+  t0 = Time.now
+  iterations.times { yield }
+  elapsed = Time.now - t0
+
+  puts "#{name}: #{elapsed * 1000 / iterations} ms"
+  elapsed
+end
+
+N = 1_000_000
+M = 100_000
+
+puts "=" * 60
+puts "mruby VM Optimization Benchmarks"
+puts "=" * 60
+puts
+
+#=============================================================================
+# 1. DISPATCH OVERHEAD BENCHMARKS
+# Target: Tail-call threading, computed goto efficiency
+#=============================================================================
+puts "--- Dispatch Overhead ---"
+
+# 1a. Empty loop (pure dispatch cost)
+measure("empty_loop", 10) do
+  i = 0
+  while i < N
+    i += 1
+  end
+end
+
+# 1b. NOP-heavy (many instructions, minimal work)
+measure("nop_sequence", 10) do
+  i = 0
+  while i < M
+    a = 1; b = 2; c = 3; d = 4; e = 5
+    a = 1; b = 2; c = 3; d = 4; e = 5
+    a = 1; b = 2; c = 3; d = 4; e = 5
+    a = 1; b = 2; c = 3; d = 4; e = 5
+    i += 1
+  end
+end
+
+#=============================================================================
+# 2. ARITHMETIC BENCHMARKS
+# Target: Type specialization, register variables, ADDI fusion
+#=============================================================================
+puts
+puts "--- Arithmetic Operations ---"
+
+# 2a. Integer addition (tests OP_ADD fast path)
+measure("int_add", 10) do
+  x = 0
+  i = 0
+  while i < N
+    x = x + 1
+    i += 1
+  end
+  x
+end
+
+# 2b. Integer increment (tests potential OP_INCI fusion)
+measure("int_increment", 10) do
+  x = 0
+  i = 0
+  while i < N
+    x += 1
+    i += 1
+  end
+  x
+end
+
+# 2c. Mixed arithmetic (tests type checking overhead)
+measure("mixed_arith", 10) do
+  x = 0
+  y = 1.5
+  i = 0
+  while i < M
+    x = x + 1
+    y = y + 0.5
+    i += 1
+  end
+  x
+end
+
+# 2d. Comparison in loop (tests OP_LT + JMPNOT fusion potential)
+measure("comparison_loop", 10) do
+  x = 0
+  while x < N
+    x += 1
+  end
+  x
+end
+
+# 2e. Multiple comparisons (branch prediction)
+measure("multi_compare", 10) do
+  i = 0
+  count = 0
+  while i < M
+    count += 1 if i > 100
+    count += 1 if i < 50000
+    count += 1 if i == 25000
+    i += 1
+  end
+  count
+end
+
+#=============================================================================
+# 3. METHOD CALL BENCHMARKS
+# Target: Inline caching, method dispatch optimization
+#=============================================================================
+puts
+puts "--- Method Calls ---"
+
+class BenchClass
+  def empty_method
+  end
+
+  def simple_add(a, b)
+    a + b
+  end
+
+  def self.class_method
+  end
+end
+
+$obj = BenchClass.new
+
+# 3a. Empty method call (pure dispatch overhead)
+measure("empty_method_call", 10) do
+  obj = $obj
+  i = 0
+  while i < M
+    obj.empty_method
+    i += 1
+  end
+end
+
+# 3b. Method with arguments
+measure("method_with_args", 10) do
+  obj = $obj
+  i = 0
+  while i < M
+    obj.simple_add(1, 2)
+    i += 1
+  end
+end
+
+# 3c. Self method call (tests OP_SENDSELF potential)
+class SelfCallBench
+  def run
+    i = 0
+    while i < M
+      helper
+      i += 1
+    end
+  end
+
+  def helper
+  end
+end
+
+measure("self_method_call", 10) do
+  SelfCallBench.new.run
+end
+
+# 3d. Polymorphic call site (tests inline cache invalidation)
+class Duck1
+  def quack; 1; end
+end
+class Duck2
+  def quack; 2; end
+end
+
+$duck1 = Duck1.new
+$duck2 = Duck2.new
+
+measure("polymorphic_call", 10) do
+  d1, d2 = $duck1, $duck2
+  i = 0
+  sum = 0
+  while i < M
+    sum += d1.quack
+    sum += d2.quack
+    i += 1
+  end
+  sum
+end
+
+#=============================================================================
+# 4. ARRAY/HASH BENCHMARKS
+# Target: GETIDX/SETIDX fast path, bounds checking
+#=============================================================================
+puts
+puts "--- Array/Hash Access ---"
+
+$ary = Array.new(1000) { |i| i }
+$hash = {}
+1000.times { |i| $hash[i] = i }
+
+# 4a. Array read (sequential)
+measure("array_read_seq", 10) do
+  ary = $ary
+  i = 0
+  sum = 0
+  while i < M
+    sum += ary[i % 1000]
+    i += 1
+  end
+  sum
+end
+
+# 4b. Array read (constant index - tests constant propagation)
+measure("array_read_const", 10) do
+  ary = $ary
+  i = 0
+  sum = 0
+  while i < M
+    sum += ary[500]
+    i += 1
+  end
+  sum
+end
+
+# 4c. Array write
+measure("array_write", 10) do
+  ary = Array.new(1000, 0)
+  i = 0
+  while i < M
+    ary[i % 1000] = i
+    i += 1
+  end
+end
+
+# 4d. Hash read
+measure("hash_read", 10) do
+  h = $hash
+  i = 0
+  sum = 0
+  while i < M
+    sum += h[i % 1000]
+    i += 1
+  end
+  sum
+end
+
+#=============================================================================
+# 5. LOOP PATTERN BENCHMARKS
+# Target: Loop optimization, branch prediction
+#=============================================================================
+puts
+puts "--- Loop Patterns ---"
+
+# 5a. Simple while loop
+measure("while_loop", 10) do
+  i = 0
+  while i < N
+    i += 1
+  end
+end
+
+# 5b. times iterator (block overhead)
+measure("times_iterator", 10) do
+  sum = 0
+  M.times do |i|
+    sum += i
+  end
+  sum
+end
+
+# 5c. each iterator on array
+$small_ary = (0...1000).to_a
+measure("each_iterator", 10) do
+  ary = $small_ary
+  total = 0
+  1000.times do
+    ary.each { |x| total += x }
+  end
+  total
+end
+
+# 5d. Nested loops
+measure("nested_loop", 10) do
+  sum = 0
+  i = 0
+  while i < 1000
+    j = 0
+    while j < 1000
+      sum += 1
+      j += 1
+    end
+    i += 1
+  end
+  sum
+end
+
+#=============================================================================
+# 6. CONSTANT LOADING BENCHMARKS
+# Target: Constant pre-computation, pool access
+#=============================================================================
+puts
+puts "--- Constant Loading ---"
+
+# 6a. Integer literals (tests LOADI optimization)
+measure("int_literals", 10) do
+  i = 0
+  sum = 0
+  while i < M
+    sum += 1
+    sum += 2
+    sum += 3
+    sum += 42
+    sum += 100
+    i += 1
+  end
+  sum
+end
+
+# 6b. Large integer literals (tests LOADL from pool)
+measure("large_int_literals", 10) do
+  i = 0
+  sum = 0
+  while i < M
+    sum += 1000000
+    sum += 2000000
+    sum += 3000000
+    i += 1
+  end
+  sum
+end
+
+# 6c. Float literals
+measure("float_literals", 10) do
+  i = 0
+  sum = 0.0
+  while i < M
+    sum += 1.5
+    sum += 2.5
+    sum += 3.5
+    i += 1
+  end
+  sum
+end
+
+# 6d. String literals (allocation vs interning)
+measure("string_literals", 5) do
+  i = 0
+  while i < 100000
+    s = "hello"
+    s = "world"
+    s = "test"
+    i += 1
+  end
+end
+
+#=============================================================================
+# 7. BRANCH PREDICTION BENCHMARKS
+# Target: mrb_likely/mrb_unlikely effectiveness
+#=============================================================================
+puts
+puts "--- Branch Prediction ---"
+
+# 7a. Predictable branch (always true)
+measure("predictable_true", 10) do
+  i = 0
+  count = 0
+  while i < N
+    count += 1 if true
+    i += 1
+  end
+  count
+end
+
+# 7b. Predictable branch (always false)
+measure("predictable_false", 10) do
+  i = 0
+  count = 0
+  while i < N
+    count += 1 if false
+    i += 1
+  end
+  count
+end
+
+# 7c. Unpredictable branch (50/50)
+measure("unpredictable_50", 10) do
+  i = 0
+  count = 0
+  while i < M
+    count += 1 if i & 1 == 0
+    i += 1
+  end
+  count
+end
+
+# 7d. Rare branch (error path simulation)
+measure("rare_branch", 10) do
+  i = 0
+  count = 0
+  while i < N
+    count += 1 if i == -1  # Never true
+    i += 1
+  end
+  count
+end
+
+#=============================================================================
+# 8. REGISTER PRESSURE BENCHMARKS
+# Target: Register variable optimization
+#=============================================================================
+puts
+puts "--- Register Pressure ---"
+
+# 8a. Few local variables (should fit in registers)
+measure("few_locals", 10) do
+  i = 0
+  a = 0
+  while i < N
+    a += 1
+    i += 1
+  end
+  a
+end
+
+# 8b. Many local variables (register spilling)
+measure("many_locals", 10) do
+  i = 0
+  a = 0; b = 0; c = 0; d = 0; e = 0
+  f = 0; g = 0; h = 0; j = 0; k = 0
+  l = 0; m = 0; n = 0; o = 0; p = 0
+  while i < M
+    a += 1; b += 1; c += 1; d += 1; e += 1
+    f += 1; g += 1; h += 1; j += 1; k += 1
+    l += 1; m += 1; n += 1; o += 1; p += 1
+    i += 1
+  end
+  a + b + c + d + e + f + g + h + j + k + l + m + n + o + p
+end
+
+#=============================================================================
+# 9. COMPOSITE BENCHMARKS (Real-world-ish)
+#=============================================================================
+puts
+puts "--- Composite Benchmarks ---"
+
+# 9a. Fibonacci (recursion + arithmetic)
+def fib(n)
+  return n if n < 2
+  fib(n - 1) + fib(n - 2)
+end
+
+measure("fibonacci_30", 3) do
+  fib(30)
+end
+
+# 9b. Tak function (heavy recursion)
+def tak(x, y, z)
+  if y < x
+    tak(tak(x - 1, y, z), tak(y - 1, z, x), tak(z - 1, x, y))
+  else
+    z
+  end
+end
+
+measure("tak_18_12_6", 3) do
+  tak(18, 12, 6)
+end
+
+# 9c. Array manipulation
+measure("array_manipulation", 5) do
+  ary = []
+  10000.times { |i| ary << i }
+  ary.map! { |x| x * 2 }
+  ary.select { |x| x % 3 == 0 }.size
+end
+
+# 9d. String operations
+measure("string_ops", 5) do
+  s = ""
+  10000.times { |i| s = s + i.to_s }
+  s.size
+end
+
+# 9e. Hash operations
+measure("hash_ops", 5) do
+  h = {}
+  50000.times { |i| h[i.to_s] = i }
+  sum = 0
+  h.each { |k, v| sum += v }
+  sum
+end
+
+puts
+puts "=" * 60
+puts "Benchmark complete"
+puts "=" * 60

build_config/ArduinoDue.rb

@@ -30,7 +30,7 @@ MRuby::CrossBuild.new("ArduinoDue") do |conf|
 
     #configuration for low memory environment
     cc.defines << %w(MRB_HEAP_PAGE_SIZE=64)
-    cc.defines << %w(KHASH_DEFAULT_SIZE=8)
+    cc.defines << %w(KHASH_INITIAL_SIZE=8)
     cc.defines << %w(MRB_GC_STRESS)
     #cc.defines << %w(MRB_NO_STDIO) #if you don't need stdio.
     #cc.defines << %w(POOL_PAGE_SIZE=1000) #effective only for use with mruby-eval
@@ -60,7 +60,6 @@ MRuby::CrossBuild.new("ArduinoDue") do |conf|
   conf.disable_cxx_exception
 
   #gems from core
-  conf.gem :core => "mruby-print"
   conf.gem :core => "mruby-math"
   conf.gem :core => "mruby-enum-ext"
 

build_config/IntelGalileo.rb

@@ -56,7 +56,6 @@ MRuby::CrossBuild.new("Galileo") do |conf|
 
   #official mrbgems
   conf.gem :core => "mruby-sprintf"
-  conf.gem :core => "mruby-print"
   conf.gem :core => "mruby-math"
   conf.gem :core => "mruby-time"
   conf.gem :core => "mruby-struct"

build_config/RX630.rb

@@ -16,7 +16,7 @@ MRuby::CrossBuild.new("RX630") do |conf|
     #configuration for low memory environment
     cc.defines << %w(MRB_USE_FLOAT32)
     cc.defines << %w(MRB_HEAP_PAGE_SIZE=64)
-    cc.defines << %w(KHASH_DEFAULT_SIZE=8)
+    cc.defines << %w(KHASH_INITIAL_SIZE=8)
     cc.defines << %w(MRB_GC_STRESS)
     cc.defines << %w(MRB_NO_STDIO) #if you don't need stdio.
     #cc.defines << %w(POOL_PAGE_SIZE=1000) #effective only for use with mruby-eval
@@ -50,7 +50,6 @@ MRuby::CrossBuild.new("RX630") do |conf|
 
   #gems from core
   conf.gem :core => "mruby-sprintf"
-  conf.gem :core => "mruby-print"
   conf.gem :core => "mruby-math"
   conf.gem :core => "mruby-enum-ext"
   conf.gem :core => "mruby-numeric-ext"

build_config/android_arm64_v8a.rb

@@ -2,8 +2,8 @@
 MRuby::CrossBuild.new('android-arm64-v8a') do |conf|
   params = {
     :arch => 'arm64-v8a',
-    :sdk_version => 26,
-    :toolchain => :clang,
+    :sdk_version => 33,
+    :toolchain => :clang
   }
   toolchain :android, params
 

build_config/android_armeabi.rb

@@ -1,11 +0,0 @@
-# Requires Android NDK r13 or later.
-MRuby::CrossBuild.new('android-armeabi') do |conf|
-  params = {
-    :arch => 'armeabi',
-    :sdk_version => 26,
-    :toolchain => :clang,
-  }
-  toolchain :android, params
-
-  conf.gembox 'default'
-end

build_config/android_armeabi_v7a_neon_hard.rb

@@ -4,8 +4,8 @@ MRuby::CrossBuild.new('android-armeabi-v7a-neon-hard') do |conf|
     :arch => 'armeabi-v7a',
     :mfpu => 'neon',
     :mfloat_abi => 'hard',
-    :sdk_version => 26,
-    :toolchain => :clang,
+    :sdk_version => 33,
+    :toolchain => :clang
   }
   toolchain :android, params
 

build_config/chipKITMax32.rb

@@ -27,7 +27,7 @@ MRuby::CrossBuild.new("chipKITMax32") do |conf|
 
     #configuration for low memory environment
     cc.defines << %w(MRB_HEAP_PAGE_SIZE=64)
-    cc.defines << %w(KHASH_DEFAULT_SIZE=8)
+    cc.defines << %w(KHASH_INITIAL_SIZE=8)
     cc.defines << %w(MRB_GC_STRESS)
     #cc.defines << %w(MRB_NO_STDIO) #if you don't need stdio.
     #cc.defines << %w(POOL_PAGE_SIZE=1000) #effective only for use with mruby-eval
@@ -56,7 +56,6 @@ MRuby::CrossBuild.new("chipKITMax32") do |conf|
   conf.disable_cxx_exception
 
   #gems from core
-  conf.gem :core => "mruby-print"
   conf.gem :core => "mruby-math"
   conf.gem :core => "mruby-enum-ext"
 

build_config/ci/gcc-clang.rb

@@ -6,7 +6,7 @@ MRuby::Build.new('full-debug') do |conf|
 
   # include all core GEMs
   conf.gembox 'full-core'
-  conf.cc.defines += %w(MRB_GC_STRESS MRB_USE_DEBUG_HOOK MRB_UTF8_STRING)
+  conf.cc.defines += %w(MRB_GC_STRESS MRB_USE_DEBUG_HOOK)
 
   conf.enable_test
 end
@@ -18,7 +18,7 @@ MRuby::Build.new do |conf|
   conf.gembox 'full-core'
   conf.gem :core => 'mruby-bin-debugger'
   conf.compilers.each do |c|
-    c.defines += %w(MRB_GC_FIXED_ARENA MRB_UTF8_STRING)
+    c.defines += %w(MRB_GC_FIXED_ARENA)
   end
   conf.enable_bintest
   conf.enable_test
@@ -30,7 +30,7 @@ MRuby::Build.new('cxx_abi') do |conf|
   conf.gembox 'full-core'
   conf.cc.flags += %w(-fpermissive -std=gnu++03)
   conf.compilers.each do |c|
-    c.defines += %w(MRB_GC_FIXED_ARENA MRB_UTF8_STRING)
+    c.defines += %w(MRB_GC_FIXED_ARENA)
   end
   conf.enable_test
 

build_config/cosmopolitan.rb

@@ -0,0 +1,86 @@
+# Cosmopolitan Libc build configuration for mruby
+# https://github.com/jart/cosmopolitan
+#
+# Produces Actually Portable Executables (APE) - single binaries that run on:
+#   - Linux (x86_64, ARM64)
+#   - macOS (x86_64, ARM64)
+#   - Windows (x86_64)
+#   - FreeBSD (x86_64)
+#   - OpenBSD (x86_64)
+#   - NetBSD (x86_64)
+#
+# Requirements:
+#   Download cosmocc toolchain from https://cosmo.zip/pub/cosmocc/
+#
+# Usage:
+#   COSMO_ROOT=/path/to/cosmocc rake MRUBY_CONFIG=cosmopolitan
+#
+# The resulting binaries in bin/ will have .com extension and run on all
+# supported platforms without recompilation.
+
+COSMO_ROOT = ENV['COSMO_ROOT']
+
+unless COSMO_ROOT && File.directory?(COSMO_ROOT)
+  msg = <<~MSG
+    Cosmopolitan toolchain not found.
+
+    Please set COSMO_ROOT environment variable to the cosmocc directory:
+
+      mkdir -p ~/cosmo && cd ~/cosmo
+      wget https://cosmo.zip/pub/cosmocc/cosmocc.zip
+      unzip cosmocc.zip
+      export COSMO_ROOT=~/cosmo
+
+    Then run:
+      COSMO_ROOT=~/cosmo rake MRUBY_CONFIG=cosmopolitan
+  MSG
+  raise msg
+end
+
+MRuby::Build.new do |conf|
+  # C compiler
+  conf.cc do |cc|
+    cc.command = "#{COSMO_ROOT}/bin/cosmocc"
+    cc.flags = %w[-Os -fno-omit-frame-pointer]
+  end
+
+  # C++ compiler
+  conf.cxx do |cxx|
+    cxx.command = "#{COSMO_ROOT}/bin/cosmoc++"
+    cxx.flags = conf.cc.flags.dup
+  end
+
+  # Linker
+  conf.linker do |linker|
+    linker.command = "#{COSMO_ROOT}/bin/cosmocc"
+    linker.flags = %w[-static]
+  end
+
+  # Archiver
+  conf.archiver do |archiver|
+    archiver.command = "#{COSMO_ROOT}/bin/cosmoar"
+  end
+
+  # APE binaries use .com extension
+  conf.exts.executable = '.com'
+
+  # Cosmopolitan provides POSIX compatibility, explicitly select POSIX HALs
+  conf.gem core: 'hal-posix-io'
+  conf.gem core: 'hal-posix-socket'
+  conf.gem core: 'hal-posix-dir'
+
+  # Standard library
+  conf.gembox 'stdlib'
+  conf.gembox 'stdlib-ext'
+  conf.gembox 'stdlib-io'  # Includes mruby-io, mruby-socket, mruby-dir
+  conf.gembox 'math'
+  conf.gembox 'metaprog'
+
+  # Binary tools
+  # Note: mruby-bin-config is a shell script and incompatible with .com extension
+  conf.gem core: 'mruby-bin-mrbc'
+  conf.gem core: 'mruby-bin-mruby'
+  conf.gem core: 'mruby-bin-strip'
+  conf.gem core: 'mruby-bin-mirb'
+  conf.gem core: 'mruby-bin-debugger'
+end

build_config/default.rb

@@ -60,7 +60,7 @@ MRuby::Build.new do |conf|
   # gperf settings
   # conf.gperf do |gperf|
   #   gperf.command = 'gperf'
-  #   gperf.compile_options = %q[-L ANSI-C -C -p -j1 -i 1 -g -o -t -N mrb_reserved_word -k"1,3,$" "%{infile}" > "%{outfile}"]
+  #   gperf.compile_options = %q[-L ANSI-C -C -j1 -i 1 -o -t -N mrb_reserved_word -k"1,3,$" "%{infile}" > "%{outfile}"]
   # end
 
   # file extensions
@@ -73,6 +73,9 @@ MRuby::Build.new do |conf|
   # file separator
   # conf.file_separator = '/'
 
+  # change library directory name from the default "lib" if necessary
+  # conf.libdir_name = 'lib64'
+
   # Turn on `enable_debug` for better debugging
   # conf.enable_debug
   conf.enable_bintest

build_config/dreamcast_shelf.rb

@@ -4,114 +4,78 @@
 # Requires KallistiOS (KOS)
 # http://gamedev.allusion.net/softprj/kos/
 #
-# Tested on GNU/Linux, macOS and Windows (through MinGW-w64/MSYS2, Cygwin and DreamSDK).
-# DreamSDK is based on MinGW/MSYS: https://dreamsdk.org/
+# This configuration has been improved to be used as KallistiOS Port (kos-ports)
+# Updated: 2025-07-31
 #
-# Input this command on the directory where mruby is installed:
-#   make MRUBY_CONFIG=dreamcast_shelf
+# Tested on GNU/Linux, macOS and Windows (MinGW-w64/MSYS2, Cygwin, DreamSDK)
+# DreamSDK is based on both MinGW/MSYS and MinGW-w64/MSYS2: https://dreamsdk.org/
+#
+# Install mruby for Sega Dreamcast using the "mruby" kos-port.
+# See: https://github.com/kallistios/kallistios
+#
+# If you want to see examples, check the /examples/dreamcast/mruby directory
+# in the KallistiOS repository.
 #
 MRuby::CrossBuild.new("dreamcast") do |conf|
   toolchain :gcc
 
-  # Support for DreamSDK (based on MinGW/MSYS)
-  # To compile mruby with DreamSDK, RubyInstaller for Windows should be installed
-  DREAMSDK_HOME = ENV["DREAMSDK_HOME"]
-  MSYS_ROOT = !(DREAMSDK_HOME.nil? || DREAMSDK_HOME.empty?) ? "#{DREAMSDK_HOME}/msys/1.0" : ""
+  # Getting critical environment variables
+  KOS_BASE = ENV["KOS_BASE"]
+  KOS_CC_BASE = ENV["KOS_CC_BASE"]
 
-  # Setting paths
-  DREAMCAST_PATH = "#{MSYS_ROOT}/opt/toolchains/dc"
-  KOS_PATH = "#{DREAMCAST_PATH}/kos"
-  BIN_PATH = "#{DREAMCAST_PATH}/sh-elf/bin"
+  # Check environment variables
+  if KOS_BASE.to_s.empty?
+    raise "Error: KallistiOS is required; KOS_BASE need to be declared; Stop."
+  end
+
+  # Root directory for KallistiOS wrappers
+  # This will handle specific DreamSDK wrappers if needed
+  KOS_WRAPPERS_BASE = if ENV["ENVIRONMENT_NAME"] == "DreamSDK" && ENV["RAKE_AVAILABLE"] == "0"
+                      "#{KOS_CC_BASE}/bin"
+                    else
+                      "#{KOS_BASE}/utils/build_wrappers"
+                    end
 
   # C compiler
-  # Flags were extracted from KallistiOS environment files
   conf.cc do |cc|
-    cc.command = "#{BIN_PATH}/sh-elf-gcc"
-    cc.include_paths << ["#{KOS_PATH}/include", "#{KOS_PATH}/kernel/arch/dreamcast/include", "#{KOS_PATH}/addons/include", "#{KOS_PATH}/../kos-ports/include"]
-    cc.flags << ["-O2", "-fomit-frame-pointer", "-ml", "-m4-single-only", "-ffunction-sections", "-fdata-sections", "-Wall", "-g", "-fno-builtin", "-ml", "-m4-single-only", "-Wl,-Ttext=0x8c010000", "-Wl,--gc-sections", "-T#{KOS_PATH}/utils/ldscripts/shlelf.xc", "-nodefaultlibs"]
-    cc.compile_options = %Q[%{flags} -o "%{outfile}" -c "%{infile}"]
-    cc.defines << %w(_arch_dreamcast)
-    cc.defines << %w(_arch_sub_pristine)
+    cc.command = "#{KOS_WRAPPERS_BASE}/kos-cc"
   end
 
   # C++ compiler
   conf.cxx do |cxx|
-    cxx.command = conf.cc.command.dup
-    cxx.include_paths = conf.cc.include_paths.dup
-    cxx.flags = conf.cc.flags.dup
-    cxx.flags << %w(-fno-rtti -fno-exceptions)
-    cxx.defines = conf.cc.defines.dup
-    cxx.compile_options = conf.cc.compile_options.dup
+    cxx.command = "#{KOS_WRAPPERS_BASE}/kos-c++"
   end
 
   # Linker
-  # There is an issue when making the mruby library with KallistiOS:
-  # 'newlib_kill.o' and 'newlib_getpid.o' aren't found so they are explicitly
-  # specified here at least for now.
   conf.linker do |linker|
-    linker.command="#{BIN_PATH}/sh-elf-gcc"
-    linker.flags << ["#{MSYS_ROOT}/opt/toolchains/dc/kos/kernel/build/newlib_kill.o", "#{MSYS_ROOT}/opt/toolchains/dc/kos/kernel/build/newlib_getpid.o", "-Wl,--start-group -lkallisti -lc -lgcc -Wl,--end-group"]
-    linker.library_paths << ["#{KOS_PATH}/lib/dreamcast", "#{KOS_PATH}/addons/lib/dreamcast", "#{KOS_PATH}/../kos-ports/lib"]
+    linker.command = "#{KOS_WRAPPERS_BASE}/kos-ld"
   end
 
   # Archiver
   conf.archiver do |archiver|
-    archiver.command = "#{BIN_PATH}/sh-elf-ar"
-    archiver.archive_options = 'rcs "%{outfile}" %{objs}'
+    archiver.command = "#{KOS_WRAPPERS_BASE}/kos-ar"
   end
 
-  # No executables
+  # No executables needed for KallistiOS
   conf.bins = []
 
-  # Do not build executable test
+  # Do not build test binaries
   conf.build_mrbtest_lib_only
 
-  # Disable C++ exception
-  conf.disable_cxx_exception
+  # Gemboxes
+  conf.gembox "default-no-stdio"
+  conf.gembox "stdlib-ext"
+  conf.gembox "metaprog"
 
-  # Gems from core
-  # Some Gems are incompatible and were disabled.
-
-  conf.gem :core => "mruby-array-ext"
+  # Additional Gems
+  # Currently unsupported on KallistiOS: "mruby-io", "mruby-dir", "mruby-socket"
   conf.gem :core => "mruby-binding"
   conf.gem :core => "mruby-catch"
-  conf.gem :core => "mruby-class-ext"
-  conf.gem :core => "mruby-cmath"
-  conf.gem :core => "mruby-compar-ext"
-  conf.gem :core => "mruby-compiler"
-  conf.gem :core => "mruby-complex"
   conf.gem :core => "mruby-enum-chain"
-  conf.gem :core => "mruby-enum-ext"
-  conf.gem :core => "mruby-enum-lazy"
-  conf.gem :core => "mruby-enumerator"
+  conf.gem :core => "mruby-errno"
   conf.gem :core => "mruby-error"
-  conf.gem :core => "mruby-eval"
   conf.gem :core => "mruby-exit"
-  conf.gem :core => "mruby-fiber"
-  conf.gem :core => "mruby-hash-ext"
-#  conf.gem :core => "mruby-io"
-  conf.gem :core => "mruby-kernel-ext"
-  conf.gem :core => "mruby-math"
-  conf.gem :core => "mruby-metaprog"
-  conf.gem :core => "mruby-method"
-  conf.gem :core => "mruby-numeric-ext"
-  conf.gem :core => "mruby-object-ext"
-  conf.gem :core => "mruby-objectspace"
   conf.gem :core => "mruby-os-memsize"
-  conf.gem :core => "mruby-pack"
-  conf.gem :core => "mruby-print"
   conf.gem :core => "mruby-proc-binding"
-  conf.gem :core => "mruby-proc-ext"
-  conf.gem :core => "mruby-random"
-  conf.gem :core => "mruby-range-ext"
-  conf.gem :core => "mruby-rational"
   conf.gem :core => "mruby-sleep"
-#  conf.gem :core => "mruby-socket"
-  conf.gem :core => "mruby-sprintf"
-  conf.gem :core => "mruby-string-ext"
-  conf.gem :core => "mruby-struct"
-  conf.gem :core => "mruby-symbol-ext"
-#  conf.gem :core => "mruby-test"
-#  conf.gem :core => "mruby-time"
-  conf.gem :core => "mruby-toplevel-ext"
 end

build_config/emscripten-cxx.rb

@@ -0,0 +1,12 @@
+# Make sure to add these compile options:
+#   build/emscripten-cxx/host-bin/mruby-config --cxxflags
+#
+# Make sure to add these link options:
+#   build/emscripten-cxx/host-bin/mruby-config --ldflags --libs
+MRuby::CrossBuild.new('emscripten-cxx') do |conf|
+  conf.toolchain :emscripten
+
+  conf.gembox 'default'
+
+  conf.enable_cxx_abi
+end

build_config/emscripten.rb

@@ -0,0 +1,10 @@
+# Make sure to add these compile options:
+#   build/emscripten/host-bin/mruby-config --cflags
+#
+# Make sure to add these link options:
+#   build/emscripten/host-bin/mruby-config --ldflags --libs
+MRuby::CrossBuild.new('emscripten') do |conf|
+  conf.toolchain :emscripten
+
+  conf.gembox 'default'
+end

build_config/gameboyadvance.rb

@@ -47,7 +47,6 @@ MRuby::CrossBuild.new("gameboyadvance") do |conf|
   conf.gem core: "mruby-metaprog"
   conf.gem core: "mruby-pack"
   conf.gem core: "mruby-sprintf"
-  conf.gem core: "mruby-print"
   conf.gem core: "mruby-math"
   conf.gem core: "mruby-time"
   conf.gem core: "mruby-struct"

build_config/host-debug.rb

@@ -8,7 +8,7 @@ MRuby::Build.new('host') do |conf|
   conf.gembox 'full-core'
 
   # C compiler settings
-  conf.cc.defines = %w(MRB_USE_DEBUG_HOOK MRB_NO_BOXING MRB_UTF8_STRING)
+  conf.cc.defines = %w(MRB_USE_DEBUG_HOOK MRB_NO_BOXING)
 
   # Generate mruby debugger command (require mruby-eval)
   conf.gem :core => "mruby-bin-debugger"

build_config/host-m32-f32.rb

@@ -0,0 +1,16 @@
+MRuby::Build.new do |conf|
+  # load specific toolchain settings
+  toolchain :gcc
+
+  # include the GEM box
+  conf.gembox 'full-core'
+
+  conf.cc.flags << '-m32'
+  conf.cc.defines << 'MRB_USE_FLOAT32'
+  conf.linker.flags << '-m32'
+
+  # Turn on `enable_debug` for better debugging
+  conf.enable_debug
+  conf.enable_test
+  conf.enable_bintest
+end

build_config/host-shared.rb

@@ -1,23 +1,20 @@
+# NOTE: Currently, this configuration file does not support VisualC++!
+#       Your help is needed!
+
 MRuby::Build.new do |conf|
   # load specific toolchain settings
-
-  # Gets set by the VS command prompts.
-  if ENV['VisualStudioVersion'] || ENV['VSINSTALLDIR']
-    toolchain :visualcpp
-  else
-    toolchain :gcc
-  end
+  conf.toolchain
 
   # include the GEM box
   conf.gembox 'default'
 
   # C compiler settings
-  conf.cc do |cc|
-    cc.flags = '-fPIC'
+  conf.compilers.each do |cc|
+    cc.flags << '-fPIC'
   end
 
   conf.archiver do |archiver|
-    archiver.command = 'gcc'
+    archiver.command = cc.command
     archiver.archive_options = '-shared -o %{outfile} %{objs}'
   end
 
@@ -29,6 +26,9 @@ MRuby::Build.new do |conf|
   # file separator
   # conf.file_separator = '/'
 
+  # enable this if better compatibility with C++ is desired
+  #conf.enable_cxx_exception
+
   # Turn on `enable_debug` for better debugging
   conf.enable_debug
   conf.enable_bintest

build_config/i586-pc-msdosdjgpp.rb

@@ -0,0 +1,76 @@
+# Cross Compiling configuration for MS-DOS
+#
+# Requires DJGPP cross-compiler, see
+# https://github.com/andrewwutw/build-djgpp/releases
+
+MRuby::CrossBuild.new("i586-pc-msdosdjgpp") do |conf|
+  toolchain :gcc
+
+  # If DJGPP is not in the PATH, set this to the bin directory
+  DJGPP_PATH = nil
+
+  GCC = 'i586-pc-msdosdjgpp-gcc'
+  GXX = 'i586-pc-msdosdjgpp-g++'
+  AR  = 'i586-pc-msdosdjgpp-ar'
+
+  conf.cc do |cc|
+    cc.command = DJGPP_PATH ? File.join(DJGPP_PATH, GCC) : GCC
+    cc.defines << 'MRB_NO_IO_PREAD_PWRITE'
+    cc.defines << 'MRB_UTF8_STRING'
+  end
+
+  conf.cxx do |cxx|
+    cxx.command = DJGPP_PATH ? File.join(DJGPP_PATH, GXX) : GXX
+    cxx.defines << 'MRB_NO_IO_PREAD_PWRITE'
+    cxx.defines << 'MRB_UTF8_STRING'
+  end
+
+  conf.linker do |linker|
+    linker.command = DJGPP_PATH ? File.join(DJGPP_PATH, GXX) : GXX
+    linker.libraries = %w(m)
+  end
+
+  conf.archiver do |archiver|
+    archiver.command = DJGPP_PATH ? File.join(DJGPP_PATH, AR) : AR
+  end
+
+  # All provided gems that can be reasonably made to compile:
+  # default.gembox, minus mruby-socket and replacing mruby-cmath with mruby-cmath-alt
+  conf.gembox "stdlib"
+  conf.gembox "stdlib-ext"
+
+  conf.gem :core => 'mruby-io'              # stdlib-io.gembox <- default.gembox
+# No socket support in DJGPP
+# conf.gem :core => 'mruby-socket'          # stdlib-io.gembox <- default.gembox
+  conf.gem :core => 'mruby-errno'           # stdlib-io.gembox <- default.gembox
+  conf.gem :core => 'mruby-dir'             # stdlib-io.gembox <- default.gembox
+
+  conf.gem :core => 'mruby-bigint'          # math.gembox <- default.gembox
+  conf.gem :core => 'mruby-complex'         # math.gembox <- default.gembox
+  conf.gem :core => 'mruby-math'            # math.gembox <- default.gembox
+  conf.gem :core => 'mruby-rational'        # math.gembox <- default.gembox
+  # Alternative implementation of cmath, not requiring <complex.h>
+# conf.gem :github => 'chasonr/mruby-cmath-alt' # math.gembox <- default.gembox
+
+  conf.gembox "metaprog"
+
+  conf.gem :core => 'mruby-bin-mrbc'        # default.gembox
+  conf.gem :core => 'mruby-bin-debugger'    # default.gembox
+  conf.gem :core => 'mruby-bin-mirb'        # default.gembox
+  conf.gem :core => 'mruby-bin-mruby'       # default.gembox
+  conf.gem :core => 'mruby-bin-strip'       # default.gembox
+  conf.gem :core => 'mruby-bin-config'      # default.gembox
+
+  # Other compilable gems
+  conf.gem :core => 'mruby-binding'
+  conf.gem :core => 'mruby-catch'
+  conf.gem :core => 'mruby-enum-chain'
+  conf.gem :core => 'mruby-error'
+  conf.gem :core => 'mruby-exit'
+  conf.gem :core => 'mruby-os-memsize'
+  conf.gem :core => 'mruby-proc-binding'
+  conf.gem :core => 'mruby-sleep'
+
+  # For Onigmo regular expression support
+  conf.gem :github => 'mattn/mruby-onig-regexp'
+end

build_config/luckfox_pico.rb

@@ -0,0 +1,106 @@
+# Cross Compiling configuration for Luckfox Pico embedded SBC.
+#
+# To build on Ubuntu x86_64: rake MRUBY_CONFIG=build_config/luckfox_pico.rb
+# Uses Buildroot SDK for this board. Binaries run on the corresponding Linux image.
+# Requires: https://github.com/LuckfoxTECH/luckfox-pico
+#
+# NOTE: default config includes all standard mrbgems, EXCEPT: mruby-cmath
+#
+MRuby::CrossBuild.new("luckfox_pico") do |conf|
+  # Clone the luckfox-pico repo above next to (same directory level) as mruby.
+  SDK_BASE = File.realpath(File.expand_path("../../../", File.expand_path(__FILE__)) + "/luckfox-pico")
+  TOOLCHAIN_BASE = "#{SDK_BASE}/tools/linux/toolchain/arm-rockchip830-linux-uclibcgnueabihf"
+  SYSROOT = "#{TOOLCHAIN_BASE}/arm-rockchip830-linux-uclibcgnueabihf/sysroot"
+
+  toolchain :gcc
+
+  # C compiler settings
+  conf.cc do |cc|
+    cc.command = "#{TOOLCHAIN_BASE}/bin/arm-rockchip830-linux-uclibcgnueabihf-gcc"
+
+    cc.include_paths << "#{TOOLCHAIN_BASE}/lib/gcc/arm-rockchip830-linux-uclibcgnueabihf/8.3.0/include"
+    cc.include_paths << "#{TOOLCHAIN_BASE}/lib/gcc/arm-rockchip830-linux-uclibcgnueabihf/8.3.0/include-fixed"
+    cc.include_paths << "#{TOOLCHAIN_BASE}/arm-rockchip830-linux-uclibcgnueabihf/include/c++/8.3.0/arm-rockchip830-linux-uclibcgnueabihf"
+    cc.include_paths << "#{SYSROOT}/usr/include"
+
+    # Flags taken from the SDK's Makefile
+    cc.flags << ["-march=armv7-a", "-mfpu=neon", "-mfloat-abi=hard"]
+    cc.flags << ["-D_LARGEFILE_SOURCE", "-D_LARGEFILE64_SOURCE", "-D_FILE_OFFSET_BITS=64", "-ffunction-sections", "-fdata-sections"]
+    cc.flags << ["-O2", "-fPIC"]
+    cc.flags << ["-Wl,--copy-dt-needed-entries", "-Wl,-lc,-lgcc_s"]
+  end
+
+  # Linker settings
+  conf.linker do |linker|
+    linker.command = cc.command
+    linker.library_paths << "#{TOOLCHAIN_BASE}/arm-rockchip830-linux-uclibcgnueabihf/lib"
+    linker.flags = cc.flags
+  end
+
+  # Archiver settings
+  conf.archiver do |archiver|
+    archiver.command = "#{TOOLCHAIN_BASE}/bin/arm-rockchip830-linux-uclibcgnueabihf-ar"
+  end
+
+  # Do not build executable test
+  conf.build_mrbtest_lib_only
+
+  # Disable C++ exception
+  conf.disable_cxx_exception
+
+  # All standard gems.
+  conf.gem 'mrbgems/mruby-array-ext/'
+  conf.gem 'mrbgems/mruby-bigint/'
+  conf.gem 'mrbgems/mruby-bin-config/'
+  conf.gem 'mrbgems/mruby-bin-debugger/'
+  conf.gem 'mrbgems/mruby-bin-mirb/'
+  conf.gem 'mrbgems/mruby-bin-mrbc/'
+  conf.gem 'mrbgems/mruby-bin-mruby/'
+  conf.gem 'mrbgems/mruby-bin-strip/'
+  conf.gem 'mrbgems/mruby-binding/'
+  conf.gem 'mrbgems/mruby-catch/'
+  conf.gem 'mrbgems/mruby-class-ext/'
+  # SDK doesn't include complex math for uClibc
+  # conf.gem 'mrbgems/mruby-cmath/'
+  conf.gem 'mrbgems/mruby-compar-ext/'
+  conf.gem 'mrbgems/mruby-compiler/'
+  conf.gem 'mrbgems/mruby-complex/'
+  conf.gem 'mrbgems/mruby-data/'
+  conf.gem 'mrbgems/mruby-dir/'
+  conf.gem 'mrbgems/mruby-enum-chain/'
+  conf.gem 'mrbgems/mruby-enum-ext/'
+  conf.gem 'mrbgems/mruby-enum-lazy/'
+  conf.gem 'mrbgems/mruby-enumerator/'
+  conf.gem 'mrbgems/mruby-errno/'
+  conf.gem 'mrbgems/mruby-error/'
+  conf.gem 'mrbgems/mruby-eval/'
+  conf.gem 'mrbgems/mruby-exit/'
+  conf.gem 'mrbgems/mruby-fiber/'
+  conf.gem 'mrbgems/mruby-hash-ext/'
+  conf.gem 'mrbgems/mruby-io/'
+  conf.gem 'mrbgems/mruby-kernel-ext/'
+  conf.gem 'mrbgems/mruby-math/'
+  conf.gem 'mrbgems/mruby-metaprog/'
+  conf.gem 'mrbgems/mruby-method/'
+  conf.gem 'mrbgems/mruby-numeric-ext/'
+  conf.gem 'mrbgems/mruby-object-ext/'
+  conf.gem 'mrbgems/mruby-objectspace/'
+  conf.gem 'mrbgems/mruby-os-memsize/'
+  conf.gem 'mrbgems/mruby-pack/'
+  conf.gem 'mrbgems/mruby-proc-binding/'
+  conf.gem 'mrbgems/mruby-proc-ext/'
+  conf.gem 'mrbgems/mruby-random/'
+  conf.gem 'mrbgems/mruby-range-ext/'
+  conf.gem 'mrbgems/mruby-rational/'
+  conf.gem 'mrbgems/mruby-set/'
+  conf.gem 'mrbgems/mruby-sleep/'
+  conf.gem 'mrbgems/mruby-socket/'
+  conf.gem 'mrbgems/mruby-sprintf/'
+  conf.gem 'mrbgems/mruby-string-ext/'
+  conf.gem 'mrbgems/mruby-struct/'
+  conf.gem 'mrbgems/mruby-symbol-ext/'
+  # conf.gem 'mrbgems/mruby-test-inline-struct/'
+  # conf.gem 'mrbgems/mruby-test/'
+  conf.gem 'mrbgems/mruby-time/'
+  conf.gem 'mrbgems/mruby-toplevel-ext/'
+end

build_config/milkv_duo.rb

@@ -0,0 +1,106 @@
+# Cross Compiling configuration for Milk-V Duo.
+# To build (on Ubuntu 24.04): rake MRUBY_CONFIG=build_config/milkv_duo.rb
+#
+# Requires: https://github.com/milkv-duo/duo-sdk
+#
+MRuby::CrossBuild.new("milkv_duo") do |conf|
+  # Set this string to match your board: milkv_duo, milkv_duo256m, milkv_duos
+  MILKV_DUO_VARIANT = "milkv_duo256m"
+
+  # Expect duo-sdk directory is same level as (next to) mruby top-level directory.
+  SDK_BASE = File.expand_path("../../../", File.expand_path(__FILE__)) + "/duo-sdk"
+  TOOLCHAIN_BASE = "#{SDK_BASE}/riscv64-linux-musl-x86_64"
+  SYSROOT = "#{SDK_BASE}/rootfs"
+
+  toolchain :gcc
+
+  # C compiler settings
+  conf.cc do |cc|
+    cc.command = "#{TOOLCHAIN_BASE}/bin/riscv64-unknown-linux-musl-gcc"
+    cc.include_paths << "#{TOOLCHAIN_BASE}/lib/gcc/riscv64-unknown-linux/musl/10.2.0/include-fixed"
+    cc.include_paths << "#{TOOLCHAIN_BASE}/lib/gcc/riscv64-unknown-linux/musl/10.2.0/include"
+    cc.include_paths << "#{TOOLCHAIN_BASE}/riscv64-unknown-linux/include"
+    cc.include_paths << "#{TOOLCHAIN_BASE}/include"
+    cc.include_paths << "#{SYSROOT}/usr/include"
+    cc.flags << ["-mcpu=c906fdv", "-march=rv64imafdcv0p7xthead", "-mcmodel=medany", "-mabi=lp64d"]
+    cc.flags << ["-D_LARGEFILE_SOURCE", "-D_LARGEFILE64_SOURCE", "-D_FILE_OFFSET_BITS=64"]
+    cc.flags << ["-Wl,--copy-dt-needed-entries", "-Wl,-lc,-lgcc_s,-lwiringx"]
+    cc.defines << "MILKV_DUO_VARIANT=_#{MILKV_DUO_VARIANT}"
+  end
+
+  # Linker settings
+  conf.linker do |linker|
+    linker.command = cc.command
+    linker.library_paths << ["#{SYSROOT}/lib", "#{SYSROOT}/usr/lib"]
+    linker.flags = cc.flags
+  end
+
+  # Archiver settings
+  conf.archiver do |archiver|
+    archiver.command = "#{TOOLCHAIN_BASE}/bin/riscv64-unknown-linux-musl-gcc-ar"
+  end
+
+  # Do not build executable test
+  conf.build_mrbtest_lib_only
+
+  # Disable C++ exception
+  conf.disable_cxx_exception
+
+  # All standard gems.
+  conf.gem 'mrbgems/mruby-array-ext/'
+  conf.gem 'mrbgems/mruby-bigint/'
+  conf.gem 'mrbgems/mruby-bin-config/'
+  conf.gem 'mrbgems/mruby-bin-debugger/'
+  conf.gem 'mrbgems/mruby-bin-mirb/'
+  conf.gem 'mrbgems/mruby-bin-mrbc/'
+  conf.gem 'mrbgems/mruby-bin-mruby/'
+  conf.gem 'mrbgems/mruby-bin-strip/'
+  conf.gem 'mrbgems/mruby-binding/'
+  conf.gem 'mrbgems/mruby-catch/'
+  conf.gem 'mrbgems/mruby-class-ext/'
+  conf.gem 'mrbgems/mruby-cmath/'
+  conf.gem 'mrbgems/mruby-compar-ext/'
+  conf.gem 'mrbgems/mruby-compiler/'
+  conf.gem 'mrbgems/mruby-complex/'
+  conf.gem 'mrbgems/mruby-data/'
+  conf.gem 'mrbgems/mruby-dir/'
+  conf.gem 'mrbgems/mruby-enum-chain/'
+  conf.gem 'mrbgems/mruby-enum-ext/'
+  conf.gem 'mrbgems/mruby-enum-lazy/'
+  conf.gem 'mrbgems/mruby-enumerator/'
+  conf.gem 'mrbgems/mruby-errno/'
+  conf.gem 'mrbgems/mruby-error/'
+  conf.gem 'mrbgems/mruby-eval/'
+  conf.gem 'mrbgems/mruby-exit/'
+  conf.gem 'mrbgems/mruby-fiber/'
+  conf.gem 'mrbgems/mruby-hash-ext/'
+  conf.gem 'mrbgems/mruby-io/'
+  conf.gem 'mrbgems/mruby-kernel-ext/'
+  conf.gem 'mrbgems/mruby-math/'
+  conf.gem 'mrbgems/mruby-metaprog/'
+  conf.gem 'mrbgems/mruby-method/'
+  conf.gem 'mrbgems/mruby-numeric-ext/'
+  conf.gem 'mrbgems/mruby-object-ext/'
+  conf.gem 'mrbgems/mruby-objectspace/'
+  conf.gem 'mrbgems/mruby-os-memsize/'
+  conf.gem 'mrbgems/mruby-pack/'
+  conf.gem 'mrbgems/mruby-proc-binding/'
+  conf.gem 'mrbgems/mruby-proc-ext/'
+  conf.gem 'mrbgems/mruby-random/'
+  conf.gem 'mrbgems/mruby-range-ext/'
+  conf.gem 'mrbgems/mruby-rational/'
+  conf.gem 'mrbgems/mruby-set/'
+  conf.gem 'mrbgems/mruby-sleep/'
+  conf.gem 'mrbgems/mruby-socket/'
+  conf.gem 'mrbgems/mruby-sprintf/'
+  conf.gem 'mrbgems/mruby-string-ext/'
+  conf.gem 'mrbgems/mruby-struct/'
+  conf.gem 'mrbgems/mruby-symbol-ext/'
+  # conf.gem 'mrbgems/mruby-test-inline-struct/'
+  # conf.gem 'mrbgems/mruby-test/'
+  conf.gem 'mrbgems/mruby-time/'
+  conf.gem 'mrbgems/mruby-toplevel-ext/'
+
+  # GPIO, ADC, PWM, I2C and SPI support for Milk-V Duo
+  # conf.gem :github => 'denko-rb/mruby-milkv-duo'
+end

build_config/mrbc.rb

@@ -7,5 +7,4 @@ MRuby::Build.new do |conf|
 
   conf.build_mrbc_exec
   conf.disable_libmruby
-  conf.disable_presym
 end

build_config/nintendo_wii.rb

@@ -0,0 +1,95 @@
+# Cross Compiling configuration for the Nintendo Wii
+# This configuration requires devkitPPC
+# https://devkitpro.org/wiki/Getting_Started
+#
+#
+MRuby::CrossBuild.new("wii") do |conf|
+  toolchain :gcc
+
+  DEVKITPRO_PATH = "/opt/devkitpro"
+  BIN_PATH = "#{DEVKITPRO_PATH}/devkitPPC/bin"
+
+  # C compiler
+  conf.cc do |cc|
+    cc.command = "#{BIN_PATH}/powerpc-eabi-gcc"
+    cc.compile_options = %(%{flags} -o "%{outfile}" -c "%{infile}")
+  end
+
+  # C++ compiler
+  conf.cxx do |cxx|
+    cxx.command = "#{BIN_PATH}/powerpc-eabi-g++"
+    cxx.include_paths = conf.cc.include_paths.dup
+    cxx.flags = conf.cc.flags.dup
+    cxx.defines = conf.cc.defines.dup
+    cxx.compile_options = conf.cc.compile_options.dup
+  end
+
+  # Linker
+  conf.linker do |linker|
+    linker.command = "#{BIN_PATH}/powerpc-eabi-gcc"
+  end
+
+  # No executables
+  conf.bins = []
+
+  # Do not build executable test
+  conf.build_mrbtest_lib_only
+
+  # Disable C++ exception
+  conf.disable_cxx_exception
+
+  # All current core gems with ones with build issues commented out
+  conf.gem 'mrbgems/mruby-array-ext/'
+  conf.gem 'mrbgems/mruby-bigint/'
+  conf.gem 'mrbgems/mruby-bin-config/'
+  conf.gem 'mrbgems/mruby-bin-debugger/'
+  conf.gem 'mrbgems/mruby-bin-mirb/'
+  conf.gem 'mrbgems/mruby-bin-mrbc/'
+  conf.gem 'mrbgems/mruby-bin-mruby/'
+  conf.gem 'mrbgems/mruby-bin-strip/'
+  conf.gem 'mrbgems/mruby-binding/'
+  conf.gem 'mrbgems/mruby-catch/'
+  conf.gem 'mrbgems/mruby-class-ext/'
+  conf.gem 'mrbgems/mruby-cmath/'
+  conf.gem 'mrbgems/mruby-compar-ext/'
+  conf.gem 'mrbgems/mruby-compiler/'
+  conf.gem 'mrbgems/mruby-complex/'
+  conf.gem 'mrbgems/mruby-data/'
+  #conf.gem 'mrbgems/mruby-dir/'
+  conf.gem 'mrbgems/mruby-enum-chain/'
+  conf.gem 'mrbgems/mruby-enum-ext/'
+  conf.gem 'mrbgems/mruby-enum-lazy/'
+  conf.gem 'mrbgems/mruby-enumerator/'
+  conf.gem 'mrbgems/mruby-errno/'
+  conf.gem 'mrbgems/mruby-error/'
+  conf.gem 'mrbgems/mruby-eval/'
+  conf.gem 'mrbgems/mruby-exit/'
+  conf.gem 'mrbgems/mruby-fiber/'
+  conf.gem 'mrbgems/mruby-hash-ext/'
+  #conf.gem 'mrbgems/mruby-io/'
+  conf.gem 'mrbgems/mruby-kernel-ext/'
+  conf.gem 'mrbgems/mruby-math/'
+  conf.gem 'mrbgems/mruby-metaprog/'
+  conf.gem 'mrbgems/mruby-method/'
+  conf.gem 'mrbgems/mruby-numeric-ext/'
+  conf.gem 'mrbgems/mruby-object-ext/'
+  conf.gem 'mrbgems/mruby-objectspace/'
+  conf.gem 'mrbgems/mruby-os-memsize/'
+  conf.gem 'mrbgems/mruby-pack/'
+  conf.gem 'mrbgems/mruby-proc-binding/'
+  conf.gem 'mrbgems/mruby-proc-ext/'
+  conf.gem 'mrbgems/mruby-random/'
+  conf.gem 'mrbgems/mruby-range-ext/'
+  conf.gem 'mrbgems/mruby-rational/'
+  conf.gem 'mrbgems/mruby-set/'
+  conf.gem 'mrbgems/mruby-sleep/'
+  #conf.gem 'mrbgems/mruby-socket/'
+  conf.gem 'mrbgems/mruby-sprintf/'
+  conf.gem 'mrbgems/mruby-string-ext/'
+  conf.gem 'mrbgems/mruby-struct/'
+  conf.gem 'mrbgems/mruby-symbol-ext/'
+  conf.gem 'mrbgems/mruby-test-inline-struct/'
+  #conf.gem 'mrbgems/mruby-test/'
+  conf.gem 'mrbgems/mruby-time/'
+  conf.gem 'mrbgems/mruby-toplevel-ext/'
+end

build_config/no-float.rb

@@ -0,0 +1,17 @@
+# Define cross build settings
+MRuby::CrossBuild.new('no-float') do |conf|
+  conf.toolchain
+
+  # Add configuration
+  conf.compilers.each do |c|
+    c.defines << "MRB_NO_FLOAT"
+  end
+
+  conf.gem :core => "mruby-bin-mruby"
+
+  conf.test_runner.command = 'env'
+
+  conf.enable_debug
+#  conf.enable_bintest
+  conf.enable_test
+end

build_config/playstationportable.rb

@@ -0,0 +1,78 @@
+# Cross Compiling configuration for the Sony PlayStation Portable.
+# This configuration requires toolchain from https://github.com/pspdev
+
+MRuby::CrossBuild.new("playstationportable") do |conf|
+  toolchain :gcc
+
+  PSPDEV_PATH = "#{ENV['PSPDEV']}"
+  BIN_PATH = "#{PSPDEV_PATH}/bin"
+
+  # C compiler
+  conf.cc do |cc|
+    cc.command = "#{BIN_PATH}/psp-gcc"
+    cc.flags << ["-O2", "-D_PSP_FW_VERSION=600"]
+    cc.include_paths << ["#{PSPDEV_PATH}/psp/include", "#{PSPDEV_PATH}/psp/sdk/include"]
+    cc.compile_options = %(%{flags} -o "%{outfile}" -c "%{infile}")
+  end
+
+  # C++ compiler
+  conf.cxx do |cxx|
+    cxx.command = "#{BIN_PATH}/psp-g++"
+    cxx.include_paths = conf.cc.include_paths.dup
+    cxx.flags = conf.cc.flags.dup
+    cxx.flags << %w[-fno-rtti -fno-exceptions]
+    cxx.defines = conf.cc.defines.dup
+    cxx.compile_options = conf.cc.compile_options.dup
+  end
+
+  # Linker
+  conf.linker do |linker|
+    linker.command = "#{BIN_PATH}/psp-gcc"
+    linker.flags << ["-Wl,-zmax-page-size=128"]
+  end
+
+  # No executables
+  conf.bins = []
+
+  # Do not build executable test
+  conf.build_mrbtest_lib_only
+
+  # Gems from core
+  conf.gem :core => "mruby-metaprog"
+  conf.gem :core => "mruby-pack"
+  conf.gem :core => "mruby-sprintf"
+  conf.gem :core => "mruby-math"
+  conf.gem :core => "mruby-time"
+  conf.gem :core => "mruby-struct"
+  conf.gem :core => "mruby-compar-ext"
+  conf.gem :core => "mruby-enum-ext"
+  conf.gem :core => "mruby-string-ext"
+  conf.gem :core => "mruby-numeric-ext"
+  conf.gem :core => "mruby-array-ext"
+  conf.gem :core => "mruby-hash-ext"
+  conf.gem :core => "mruby-range-ext"
+  conf.gem :core => "mruby-proc-ext"
+  conf.gem :core => "mruby-symbol-ext"
+  conf.gem :core => "mruby-random"
+  conf.gem :core => "mruby-object-ext"
+  conf.gem :core => "mruby-objectspace"
+  conf.gem :core => "mruby-fiber"
+  conf.gem :core => "mruby-enumerator"
+  conf.gem :core => "mruby-enum-lazy"
+  conf.gem :core => "mruby-toplevel-ext"
+  conf.gem :core => "mruby-kernel-ext"
+  conf.gem :core => "mruby-class-ext"
+  conf.gem :core => "mruby-compiler"
+  conf.gem :core => "mruby-binding"
+  conf.gem :core => "mruby-catch"
+  conf.gem :core => "mruby-enum-chain"
+  conf.gem :core => "mruby-errno"
+  conf.gem :core => "mruby-error"
+  conf.gem :core => "mruby-exit"
+  conf.gem :core => "mruby-os-memsize"
+  conf.gem :core => "mruby-proc-binding"
+  conf.gem :core => "mruby-sleep"
+  conf.gem :core => "mruby-io"
+  conf.gem :core => "mruby-dir"
+  #conf.gem :core => "mruby-socket" unsupported
+end

doc/README.md

@@ -0,0 +1,67 @@
+# mruby Documentation
+
+## Getting Started
+
+New to mruby? Start here:
+
+| Document                                     | Description                            |
+| -------------------------------------------- | -------------------------------------- |
+| [Getting Started](guides/getting-started.md) | Build mruby and run your first program |
+| [Language Features](guides/language.md)      | Ruby subset supported by mruby         |
+| [Limitations](limitations.md)                | Behavioral differences from CRuby      |
+
+## Guides (for embedders and gem authors)
+
+### Embedding mruby in C
+
+| Document                                | Description                                      |
+| --------------------------------------- | ------------------------------------------------ |
+| [C API Reference](guides/capi.md)       | Values, classes, methods, error handling, fibers |
+| [GC Arena](guides/gc-arena-howto.md)    | Managing temporary objects in C extensions       |
+| [Linking](guides/link.md)               | Linking with `libmruby`                          |
+| [Amalgamation](guides/amalgamation.md)  | Single-file build for easy integration           |
+| [Precompiled Symbols](guides/symbol.md) | Compile-time symbol allocation                   |
+
+### Building and Configuring
+
+| Document                                 | Description                                 |
+| ---------------------------------------- | ------------------------------------------- |
+| [Compilation](guides/compile.md)         | Build system, cross-compilation, toolchains |
+| [Build Configuration](guides/mrbconf.md) | Compile-time macros (`MRB_*` flags)         |
+| [mrbgems](guides/mrbgems.md)             | Creating and managing gems                  |
+| [Memory](guides/memory.md)               | Allocator customization and heap regions    |
+
+### Tools
+
+| Document                                        | Description                                     |
+| ----------------------------------------------- | ----------------------------------------------- |
+| [Debugger](guides/debugger.md)                  | Using `mrdb` for debugging                      |
+| [ROM Method Tables](guides/rom-method-table.md) | Read-only method tables for constrained devices |
+
+### Reference
+
+| Document                              | Description        |
+| ------------------------------------- | ------------------ |
+| [Directory Structure](guides/hier.md) | Source tree layout |
+
+## Internals (for mruby contributors)
+
+Start with [Architecture](internal/architecture.md) for an overview,
+then dive into the subsystem you need:
+
+| Document                                  | Description                                        |
+| ----------------------------------------- | -------------------------------------------------- |
+| [Architecture](internal/architecture.md)  | Overview of object model, VM, GC, compiler         |
+| [Virtual Machine](internal/vm.md)         | Dispatch loop, call frames, method lookup, fibers  |
+| [Garbage Collector](internal/gc.md)       | Tri-color marking, write barriers, generational GC |
+| [Compiler Pipeline](internal/compiler.md) | Parser, code generator, IRep, binary format        |
+| [Opcodes](internal/opcode.md)             | VM instruction set reference                       |
+| [Value Boxing](internal/boxing.md)        | How `mrb_value` encodes types                      |
+
+## Release Notes
+
+- [mruby 3.4](mruby3.4.md)
+- [mruby 3.3](mruby3.3.md)
+- [mruby 3.2](mruby3.2.md)
+- [mruby 3.1](mruby3.1.md)
+- [mruby 3.0](mruby3.0.md)

doc/guides/amalgamation.md

@@ -0,0 +1,153 @@
+<!-- summary: About Amalgamation (Single-File Build) -->
+
+# Amalgamation
+
+Amalgamation combines all mruby source files into a single `mruby.c` and
+`mruby.h` for easy embedding, similar to SQLite's distribution model.
+
+## Benefits
+
+- **Simple integration**: Just two files to add to your project
+- **Single compilation unit**: Enables better compiler optimization
+- **No build system required**: Compile directly with any C compiler
+- **Portable**: No external dependencies beyond standard C library
+  (but see [Platform-Dependent Gems](#platform-dependent-gems) below)
+
+## Generating Amalgamation
+
+```console
+rake amalgam
+```
+
+Output files are generated in `build/<target>/amalgam/`:
+
+- `mruby.h` - All headers concatenated in dependency order
+- `mruby.c` - All sources concatenated (core + gems + mrblib)
+
+### With Custom Configuration
+
+The amalgamation includes gems specified in your build configuration:
+
+```console
+MRUBY_CONFIG=build_config/minimal.rb rake amalgam
+```
+
+## Using the Amalgamation
+
+### Basic Usage
+
+```c
+#include "mruby.h"
+
+int main(void) {
+  mrb_state *mrb = mrb_open();
+  mrb_load_string(mrb, "puts 'Hello from mruby!'");
+  mrb_close(mrb);
+  return 0;
+}
+```
+
+### Compiling
+
+```console
+gcc -I./build/host/amalgam your_app.c ./build/host/amalgam/mruby.c -o your_app -lm
+```
+
+For optimized builds:
+
+```console
+gcc -O2 -DNDEBUG -I./build/host/amalgam your_app.c ./build/host/amalgam/mruby.c -o your_app -lm
+```
+
+## Gem Compatibility
+
+### Known Working Gems
+
+The following gems work with amalgamation:
+
+- `mruby-compiler` - Required for `mrb_load_string`
+- `mruby-eval` - `eval`, `Binding`
+- `mruby-array-ext`, `mruby-string-ext`, `mruby-hash-ext`
+- `mruby-numeric-ext`, `mruby-range-ext`, `mruby-symbol-ext`
+- `mruby-proc-ext`, `mruby-kernel-ext`, `mruby-object-ext`, `mruby-class-ext`
+- `mruby-enum-ext`, `mruby-compar-ext`
+- `mruby-error`, `mruby-math`, `mruby-struct`
+- `mruby-bigint`, `mruby-rational`, `mruby-complex`
+- `mruby-io` (with `hal-posix-io`)
+- `mruby-task` (with `hal-posix-task`)
+
+### Platform-Dependent Gems
+
+Gems that use a HAL (Hardware Abstraction Layer) include
+platform-specific code in the amalgamation. For example, if
+`mruby-io` selects `hal-posix-io` on Linux, the generated `mruby.c`
+contains POSIX-specific code and cannot be compiled on Windows.
+
+If you need amalgamated files for multiple platforms, generate them
+separately for each target platform (or cross-build configuration).
+
+### Excluded Gems
+
+Binary gems (`mruby-bin-*`) are automatically excluded as they contain
+their own `main()` function. The amalgamation produces a library, not
+an executable.
+
+## Example Configuration
+
+A minimal configuration for amalgamation:
+
+```ruby
+# build_config/amalgam.rb
+MRuby::Build.new do |conf|
+  conf.toolchain :gcc
+
+  conf.gem core: 'mruby-compiler'
+  conf.gem core: 'mruby-error'
+  conf.gem core: 'mruby-eval'
+  conf.gem core: 'mruby-array-ext'
+  conf.gem core: 'mruby-string-ext'
+  conf.gem core: 'mruby-hash-ext'
+  conf.gem core: 'mruby-io'
+end
+```
+
+Generate with:
+
+```console
+MRUBY_CONFIG=build_config/amalgam.rb rake amalgam
+```
+
+## Output Sizes
+
+Typical sizes depend on included gems:
+
+- `mruby.h`: 200-500 KB
+- `mruby.c`: 2-4 MB
+
+## Technical Details
+
+### Header Processing
+
+- Include guards are stripped to allow concatenation
+- Headers are ordered by dependency (foundation types first)
+- Internal includes are commented out (already in `mruby.h`)
+
+### Source Processing
+
+- Sources are concatenated in proper initialization order
+- X-macro headers (like `mruby/ops.h`) are inlined at each use
+- Local includes (`.cstub` files) are automatically inlined
+- Generated files (`mrblib.c`, `gem_init.c`) are included
+
+### Gem Defines
+
+Gems that add preprocessor defines affecting core structures are
+automatically detected and included at the top of `mruby.h`.
+Supported patterns: `MRB_USE_*`, `MRB_UTF8_*`, `HAVE_MRUBY_*`.
+
+### Build Order
+
+1. Core sources (`src/*.c`)
+2. Gem sources (`mrbgems/*/src/*.c` or `core/*.c`)
+3. Generated mrblib (`build/*/mrblib/mrblib.c`)
+4. Gem initialization (`build/*/mrbgems/gem_init.c`)

doc/guides/capi.md

@@ -0,0 +1,856 @@
+<!-- summary: C API Reference -->
+
+# C API Reference
+
+This document covers the mruby C API for embedding and extending mruby.
+
+**Contents:**
+[Headers](#headers) |
+[State Management](#state-management) |
+[Values](#values) |
+[Defining Classes and Modules](#defining-classes-and-modules) |
+[Defining Methods](#defining-methods) |
+[Parsing Arguments](#parsing-arguments) |
+[Calling Ruby Methods from C](#calling-ruby-methods-from-c) |
+[String Operations](#string-operations) |
+[Array Operations](#array-operations) |
+[Hash Operations](#hash-operations) |
+[Wrapping C Structures](#wrapping-c-structures) |
+[Exception Handling](#exception-handling) |
+[Method Visibility](#method-visibility) |
+[Proc and Block Handling](#proc-and-block-handling) |
+[Fiber API](#fiber-api) |
+[Compilation Contexts](#compilation-contexts) |
+[Precompiled Bytecode](#precompiled-bytecode) |
+[GC Arena](#gc-arena) |
+[Memory Allocation](#memory-allocation)
+
+## Headers
+
+```c
+#include <mruby.h>            /* core types, state, class/method definition */
+#include <mruby/compile.h>    /* mrb_load_string, mrb_load_file */
+#include <mruby/string.h>     /* string operations */
+#include <mruby/array.h>      /* array operations */
+#include <mruby/hash.h>       /* hash operations */
+#include <mruby/data.h>       /* wrapping C structs */
+#include <mruby/class.h>      /* class inspection */
+#include <mruby/value.h>      /* value type macros */
+#include <mruby/irep.h>       /* loading precompiled bytecode */
+#include <mruby/error.h>      /* error handling (mrb_protect etc.) */
+#include <mruby/variable.h>   /* instance/class/global variables */
+```
+
+## State Management
+
+```c
+mrb_state *mrb = mrb_open();       /* create state with all gems */
+mrb_state *mrb = mrb_open_core();  /* create state without gems */
+mrb_close(mrb);                    /* close and free state */
+```
+
+`mrb_open()` returns `NULL` on allocation failure. Always check the
+return value.
+
+## Values
+
+All Ruby values are represented as `mrb_value` in C.
+
+### Creating Values
+
+```c
+mrb_nil_value()                          /* nil */
+mrb_true_value()                         /* true */
+mrb_false_value()                        /* false */
+mrb_bool_value(mrb_bool b)              /* true or false */
+mrb_fixnum_value(mrb_int i)             /* Integer */
+mrb_float_value(mrb_state *mrb, mrb_float f)  /* Float */
+mrb_symbol_value(mrb_sym sym)           /* Symbol */
+mrb_obj_value(void *p)                  /* object pointer to value */
+mrb_cptr_value(mrb_state *mrb, void *p) /* C pointer */
+```
+
+### Type Checking
+
+```c
+mrb_type(v)          /* returns enum mrb_vtype */
+mrb_nil_p(v)         /* true if nil */
+mrb_integer_p(v)     /* true if Integer */
+mrb_float_p(v)       /* true if Float */
+mrb_symbol_p(v)      /* true if Symbol */
+mrb_string_p(v)      /* true if String */
+mrb_array_p(v)       /* true if Array */
+mrb_hash_p(v)        /* true if Hash */
+mrb_true_p(v)        /* true if true */
+mrb_false_p(v)       /* true if false */
+mrb_undef_p(v)       /* true if undefined */
+mrb_immediate_p(v)   /* true if not a heap object */
+```
+
+### Extracting C Values
+
+```c
+mrb_integer(v)               /* mrb_int from Integer value */
+mrb_float(v)                 /* mrb_float from Float value */
+mrb_symbol(v)                /* mrb_sym from Symbol value */
+mrb_ptr(v)                   /* void* from object value */
+mrb_str_to_cstr(mrb, v)     /* const char* from String value */
+```
+
+### Value Types
+
+| `mrb_vtype`        | Ruby Class          | Notes                    |
+| ------------------ | ------------------- | ------------------------ |
+| `MRB_TT_FALSE`     | FalseClass/NilClass | `nil` has `MRB_TT_FALSE` |
+| `MRB_TT_TRUE`      | TrueClass           |                          |
+| `MRB_TT_INTEGER`   | Integer             | Immediate value          |
+| `MRB_TT_FLOAT`     | Float               | May be immediate         |
+| `MRB_TT_SYMBOL`    | Symbol              | Immediate value          |
+| `MRB_TT_STRING`    | String              | Heap object              |
+| `MRB_TT_ARRAY`     | Array               | Heap object              |
+| `MRB_TT_HASH`      | Hash                | Heap object              |
+| `MRB_TT_OBJECT`    | Object              | User-defined classes     |
+| `MRB_TT_CLASS`     | Class               |                          |
+| `MRB_TT_MODULE`    | Module              |                          |
+| `MRB_TT_PROC`      | Proc                |                          |
+| `MRB_TT_CDATA`     | (C data)            | Wrapped C structs        |
+| `MRB_TT_EXCEPTION` | Exception           |                          |
+| `MRB_TT_FIBER`     | Fiber               |                          |
+
+## Defining Classes and Modules
+
+```c
+/* Define a class under Object */
+struct RClass *my_class = mrb_define_class(mrb, "MyClass", mrb->object_class);
+
+/* Define a class under another class/module */
+struct RClass *inner = mrb_define_class_under(mrb, outer, "Inner", mrb->object_class);
+
+/* Define a module */
+struct RClass *my_mod = mrb_define_module(mrb, "MyModule");
+struct RClass *inner_mod = mrb_define_module_under(mrb, outer, "InnerMod");
+
+/* Include/prepend a module */
+mrb_include_module(mrb, my_class, my_mod);
+mrb_prepend_module(mrb, my_class, my_mod);
+
+/* Look up existing class/module */
+struct RClass *c = mrb_class_get(mrb, "String");
+struct RClass *m = mrb_module_get(mrb, "Kernel");
+
+/* Define a constant */
+mrb_define_const(mrb, my_class, "VERSION", mrb_str_new_lit(mrb, "1.0"));
+```
+
+## Defining Methods
+
+All C methods have the same signature:
+
+```c
+static mrb_value
+my_method(mrb_state *mrb, mrb_value self)
+{
+  /* self is the receiver */
+  return mrb_nil_value();
+}
+```
+
+Register with:
+
+```c
+mrb_define_method(mrb, klass, "name", my_method, MRB_ARGS_NONE());
+mrb_define_class_method(mrb, klass, "name", my_method, MRB_ARGS_REQ(1));
+mrb_define_module_function(mrb, mod, "name", my_method, MRB_ARGS_ANY());
+```
+
+### Argument Specifiers
+
+| Macro                  | Meaning                               |
+| ---------------------- | ------------------------------------- |
+| `MRB_ARGS_NONE()`      | No arguments                          |
+| `MRB_ARGS_REQ(n)`      | `n` required arguments                |
+| `MRB_ARGS_OPT(n)`      | `n` optional arguments                |
+| `MRB_ARGS_ARG(r,o)`    | `r` required + `o` optional           |
+| `MRB_ARGS_REST()`      | Splat (`*args`)                       |
+| `MRB_ARGS_BLOCK()`     | Block (`&block`)                      |
+| `MRB_ARGS_ANY()`       | Any number (same as REST)             |
+| `MRB_ARGS_KEY(n,rest)` | `n` keyword args, `rest`=1 for `**kw` |
+
+These can be combined with `|`:
+
+```c
+MRB_ARGS_REQ(1) | MRB_ARGS_OPT(2) | MRB_ARGS_BLOCK()
+```
+
+## Parsing Arguments
+
+`mrb_get_args()` extracts arguments from the Ruby call stack:
+
+```c
+mrb_int mrb_get_args(mrb_state *mrb, const char *format, ...);
+```
+
+### Format Specifiers
+
+| Spec | Ruby Type     | C Type(s)                   | Notes                            |
+| ---- | ------------- | --------------------------- | -------------------------------- |
+| `o`  | any           | `mrb_value`                 | No type check                    |
+| `i`  | Numeric       | `mrb_int`                   | Coerces to integer               |
+| `f`  | Numeric       | `mrb_float`                 | Coerces to float                 |
+| `b`  | any           | `mrb_bool`                  | Truthiness                       |
+| `n`  | String/Symbol | `mrb_sym`                   | Converts to symbol               |
+| `s`  | String        | `const char*, mrb_int`      | Pointer + length                 |
+| `z`  | String        | `const char*`               | Null-terminated                  |
+| `S`  | String        | `mrb_value`                 | String value                     |
+| `A`  | Array         | `mrb_value`                 | Array value                      |
+| `H`  | Hash          | `mrb_value`                 | Hash value                       |
+| `C`  | Class         | `mrb_value`                 | Class/Module value               |
+| `c`  | Class         | `struct RClass*`            | Class pointer                    |
+| `a`  | Array         | `const mrb_value*, mrb_int` | Array pointer + length           |
+| `d`  | C Data        | `void*`                     | Requires `mrb_data_type*`        |
+| `&`  | Block         | `mrb_value`                 | Block argument                   |
+| `*`  | rest          | `const mrb_value*, mrb_int` | Rest arguments                   |
+| `\|` | —             | —                           | Following args are optional      |
+| `?`  | —             | `mrb_bool`                  | Was previous optional arg given? |
+| `:`  | keywords      | `mrb_kwargs`                | Keyword arguments                |
+
+Adding `!` to `S`, `A`, `H`, `C`, `c`, `s`, `z`, `a`, `d` allows `nil`
+(returns NULL/zero for nil).
+
+### Examples
+
+```c
+/* def method(name, count) */
+const char *name; mrb_int len, count;
+mrb_get_args(mrb, "si", &name, &len, &count);
+
+/* def method(required, optional=nil) */
+mrb_value req, opt = mrb_nil_value();
+mrb_get_args(mrb, "o|o", &req, &opt);
+
+/* def method(*args) */
+const mrb_value *args; mrb_int argc;
+mrb_get_args(mrb, "*", &args, &argc);
+
+/* def method(&block) */
+mrb_value block;
+mrb_get_args(mrb, "&", &block);
+
+/* def method(name:, age: 0) */
+mrb_sym kw_names[] = { mrb_intern_lit(mrb, "name"), mrb_intern_lit(mrb, "age") };
+mrb_value kw_values[2];
+mrb_kwargs kw = { 2, 1, kw_names, kw_values, NULL };
+mrb_get_args(mrb, ":", &kw);
+/* kw_values[0] = name (required), kw_values[1] = age (optional, undef if not given) */
+```
+
+## Calling Ruby Methods from C
+
+```c
+/* Call obj.method(arg1, arg2) */
+mrb_funcall(mrb, obj, "method", 2, arg1, arg2);
+
+/* Call with symbol (faster, no string lookup) */
+mrb_funcall_id(mrb, obj, mrb_intern_lit(mrb, "method"), 2, arg1, arg2);
+
+/* Call with argv array */
+mrb_value argv[] = { arg1, arg2 };
+mrb_funcall_argv(mrb, obj, mrb_intern_lit(mrb, "method"), 2, argv);
+
+/* Call with block */
+mrb_funcall_with_block(mrb, obj, mid, argc, argv, block);
+
+/* Yield to block */
+mrb_yield(mrb, block, arg);
+mrb_yield_argv(mrb, block, argc, argv);
+```
+
+## String Operations
+
+```c
+/* Creation */
+mrb_str_new_lit(mrb, "hello")              /* from string literal */
+mrb_str_new(mrb, ptr, len)                 /* from pointer + length */
+mrb_str_new_cstr(mrb, cstr)               /* from null-terminated C string */
+mrb_str_new_static(mrb, ptr, len)          /* from static data (no copy) */
+
+/* Access */
+RSTRING_PTR(str)                           /* char* pointer */
+RSTRING_LEN(str)                           /* length */
+mrb_str_to_cstr(mrb, str)                 /* null-terminated (may copy) */
+
+/* Modification */
+mrb_str_cat(mrb, str, ptr, len)            /* append bytes */
+mrb_str_cat_cstr(mrb, str, cstr)           /* append C string */
+mrb_str_cat_str(mrb, str, str2)            /* append String */
+
+/* Comparison */
+mrb_str_equal(mrb, str1, str2)             /* equality */
+mrb_str_cmp(mrb, str1, str2)              /* comparison (-1, 0, 1) */
+```
+
+## Array Operations
+
+```c
+/* Creation */
+mrb_ary_new(mrb)                           /* empty array */
+mrb_ary_new_capa(mrb, capa)               /* preallocated */
+mrb_ary_new_from_values(mrb, n, vals)     /* from C array */
+
+/* Access */
+RARRAY_PTR(ary)                            /* mrb_value* pointer */
+RARRAY_LEN(ary)                            /* length */
+mrb_ary_entry(ary, idx)                    /* get element (no mrb needed) */
+
+/* Modification */
+mrb_ary_push(mrb, ary, val)               /* append */
+mrb_ary_pop(mrb, ary)                     /* remove last */
+mrb_ary_shift(mrb, ary)                   /* remove first */
+mrb_ary_unshift(mrb, ary, val)            /* prepend */
+mrb_ary_set(mrb, ary, idx, val)           /* set element */
+mrb_ary_splice(mrb, ary, pos, len, rpl)   /* splice */
+mrb_ary_concat(mrb, ary, other)           /* extend */
+```
+
+## Hash Operations
+
+```c
+/* Creation */
+mrb_hash_new(mrb)                          /* empty hash */
+
+/* Access */
+mrb_hash_get(mrb, hash, key)              /* get value */
+mrb_hash_fetch(mrb, hash, key, def)       /* get with default */
+mrb_hash_key_p(mrb, hash, key)            /* key exists? */
+mrb_hash_empty_p(mrb, hash)               /* empty? */
+mrb_hash_size(mrb, hash)                  /* number of entries */
+
+/* Modification */
+mrb_hash_set(mrb, hash, key, val)         /* set key-value */
+mrb_hash_delete_key(mrb, hash, key)       /* delete key */
+mrb_hash_merge(mrb, hash1, hash2)         /* merge hash2 into hash1 */
+
+/* Iteration */
+mrb_hash_keys(mrb, hash)                  /* Array of keys */
+mrb_hash_values(mrb, hash)                /* Array of values */
+```
+
+## Wrapping C Structures
+
+To expose a C struct to Ruby, use `mrb_data_type` and `Data_Wrap_Struct`:
+
+```c
+/* 1. Define the data type with a name and destructor */
+static void point_free(mrb_state *mrb, void *p) {
+  mrb_free(mrb, p);
+}
+
+static const mrb_data_type point_type = {
+  "Point", point_free
+};
+
+/* 2. Allocate and initialize */
+static mrb_value
+point_init(mrb_state *mrb, mrb_value self)
+{
+  mrb_float x, y;
+  mrb_get_args(mrb, "ff", &x, &y);
+
+  double *data = (double*)mrb_malloc(mrb, sizeof(double) * 2);
+  data[0] = x;
+  data[1] = y;
+
+  DATA_PTR(self) = data;
+  DATA_TYPE(self) = &point_type;
+
+  return self;
+}
+
+/* 3. Access the wrapped data */
+static mrb_value
+point_x(mrb_state *mrb, mrb_value self)
+{
+  double *data = (double*)mrb_data_get_ptr(mrb, self, &point_type);
+  return mrb_float_value(mrb, data[0]);
+}
+
+/* 4. Register the class */
+struct RClass *point = mrb_define_class(mrb, "Point", mrb->object_class);
+MRB_SET_INSTANCE_TT(point, MRB_TT_CDATA);
+mrb_define_method(mrb, point, "initialize", point_init, MRB_ARGS_REQ(2));
+mrb_define_method(mrb, point, "x", point_x, MRB_ARGS_NONE());
+```
+
+## Exception Handling
+
+### Raising Exceptions
+
+```c
+mrb_raise(mrb, E_RUNTIME_ERROR, "something went wrong");
+mrb_raisef(mrb, E_ARGUMENT_ERROR, "expected %d, got %d", expected, actual);
+mrb_raise(mrb, E_TYPE_ERROR, "wrong type");
+```
+
+Common exception classes: `E_RUNTIME_ERROR`, `E_TYPE_ERROR`,
+`E_ARGUMENT_ERROR`, `E_RANGE_ERROR`, `E_NAME_ERROR`,
+`E_NOMETHOD_ERROR`, `E_NOTIMP_ERROR`, `E_KEY_ERROR`.
+
+### Catching Exceptions
+
+```c
+/* Check after mrb_load_string or mrb_funcall */
+mrb_value result = mrb_load_string(mrb, code);
+if (mrb->exc) {
+  mrb_print_error(mrb);
+  mrb->exc = NULL;  /* clear exception */
+}
+```
+
+### Protected Execution
+
+`mrb_protect()` executes a function under protection. If an
+exception is raised, it is captured as a return value instead of
+propagating:
+
+```c
+static mrb_value
+safe_operation(mrb_state *mrb, mrb_value data)
+{
+  /* This function might raise an exception */
+  return mrb_funcall(mrb, data, "do_something", 0);
+}
+
+mrb_bool error;
+mrb_value result = mrb_protect(mrb, safe_operation, data, &error);
+if (error) {
+  /* result contains the exception object; mrb->exc is cleared */
+  mrb_value inspect = mrb_inspect(mrb, result);
+  fprintf(stderr, "Error: %s\n", mrb_str_to_cstr(mrb, inspect));
+}
+```
+
+**Note:** `mrb_protect` clears `mrb->exc` after catching the
+exception. The exception is returned as `result`. Do not use
+`mrb_print_error()` after `mrb_protect` — it reads `mrb->exc`
+which is already `NULL`.
+
+For lower-level protection with a `void*` callback:
+
+```c
+static mrb_value
+body(mrb_state *mrb, void *userdata)
+{
+  /* ... */
+}
+
+mrb_bool error;
+mrb_value result = mrb_protect_error(mrb, body, userdata, &error);
+```
+
+### Rescue
+
+`mrb_rescue()` catches `StandardError` (like Ruby's `rescue`):
+
+```c
+static mrb_value
+body_func(mrb_state *mrb, mrb_value body_data)
+{
+  return mrb_funcall(mrb, body_data, "risky_method", 0);
+}
+
+static mrb_value
+rescue_func(mrb_state *mrb, mrb_value rescue_data)
+{
+  /* handle error, rescue_data is the data passed in */
+  return mrb_nil_value();
+}
+
+mrb_value result = mrb_rescue(mrb, body_func, body_data,
+                              rescue_func, rescue_data);
+```
+
+To rescue specific exception classes:
+
+```c
+struct RClass *classes[] = {
+  E_ARGUMENT_ERROR,
+  mrb_class_get(mrb, "IOError")
+};
+mrb_value result = mrb_rescue_exceptions(mrb, body_func, body_data,
+                                         rescue_func, rescue_data,
+                                         2, classes);
+```
+
+### Ensure
+
+`mrb_ensure()` guarantees cleanup runs regardless of exceptions
+(like Ruby's `ensure`):
+
+```c
+static mrb_value
+body_func(mrb_state *mrb, mrb_value data)
+{
+  return mrb_funcall(mrb, data, "process", 0);
+}
+
+static mrb_value
+cleanup_func(mrb_state *mrb, mrb_value data)
+{
+  mrb_funcall(mrb, data, "close", 0);
+  return mrb_nil_value();
+}
+
+mrb_value result = mrb_ensure(mrb, body_func, body_data,
+                              cleanup_func, cleanup_data);
+```
+
+The ensure function always executes. If the body raises an
+exception, the ensure runs and then the exception is re-raised.
+
+### Error State Management
+
+```c
+mrb_bool mrb_check_error(mrb_state *mrb);  /* check and clear mrb->exc */
+void mrb_clear_error(mrb_state *mrb);      /* clear mrb->exc */
+```
+
+## Method Visibility
+
+```c
+/* Public (default) */
+mrb_define_method(mrb, klass, "name", func, MRB_ARGS_NONE());
+
+/* Private - only callable without explicit receiver */
+mrb_define_private_method(mrb, klass, "name", func, MRB_ARGS_NONE());
+
+/* Class method (singleton method on the class object) */
+mrb_define_class_method(mrb, klass, "name", func, MRB_ARGS_NONE());
+
+/* Module function (both module method and private instance method) */
+mrb_define_module_function(mrb, mod, "name", func, MRB_ARGS_NONE());
+
+/* Singleton method on a specific object */
+mrb_define_singleton_method(mrb, obj, "name", func, MRB_ARGS_NONE());
+
+/* Method alias: alias new_name old_name */
+mrb_define_alias(mrb, klass, "new_name", "old_name");
+
+/* Remove a method */
+mrb_undef_method(mrb, klass, "name");
+mrb_undef_class_method(mrb, klass, "name");
+```
+
+All `_method` variants have `_id` counterparts that accept
+`mrb_sym` instead of `const char*` for better performance.
+
+## Proc and Block Handling
+
+### Creating Procs from C Functions
+
+```c
+/* Simple C function proc */
+struct RProc *proc = mrb_proc_new_cfunc(mrb, my_func);
+
+/* C closure with captured local variables */
+struct RProc *proc = mrb_closure_new_cfunc(mrb, my_func, nlocals);
+```
+
+### C Functions with Environment (requires mruby-proc-ext)
+
+Store values in a proc's environment, accessible from the C
+function:
+
+```c
+mrb_value env_values[] = { mrb_fixnum_value(42) };
+struct RProc *proc = mrb_proc_new_cfunc_with_env(mrb, my_func, 1, env_values);
+
+/* Inside my_func, retrieve environment values */
+static mrb_value my_func(mrb_state *mrb, mrb_value self)
+{
+  mrb_value val = mrb_proc_cfunc_env_get(mrb, 0); /* index 0 */
+  return val;
+}
+```
+
+## Fiber API
+
+```c
+#include <mruby.h>    /* fiber types and functions */
+```
+
+### Creating and Using Fibers
+
+```c
+/* Create a fiber from a proc */
+mrb_value fiber = mrb_fiber_new(mrb, proc);
+
+/* Resume the fiber with arguments */
+mrb_value args[] = { mrb_fixnum_value(1) };
+mrb_value result = mrb_fiber_resume(mrb, fiber, 1, args);
+
+/* Check if fiber is still alive */
+mrb_bool alive = mrb_test(mrb_fiber_alive_p(mrb, fiber));
+```
+
+### Yielding from C
+
+`mrb_fiber_yield()` can only be used as the return value of a C
+function — no code may execute after it:
+
+```c
+static mrb_value
+my_yield_method(mrb_state *mrb, mrb_value self)
+{
+  mrb_value yield_args[] = { mrb_str_new_lit(mrb, "yielded") };
+  return mrb_fiber_yield(mrb, 1, yield_args);  /* must be returned directly */
+}
+```
+
+### Fiber States
+
+| State                   | Meaning                          |
+| ----------------------- | -------------------------------- |
+| `MRB_FIBER_CREATED`     | Created but not yet resumed      |
+| `MRB_FIBER_RUNNING`     | Currently executing              |
+| `MRB_FIBER_RESUMED`     | Resumed another fiber            |
+| `MRB_FIBER_SUSPENDED`   | Yielded, waiting to resume       |
+| `MRB_FIBER_TRANSFERRED` | Transferred via `Fiber#transfer` |
+| `MRB_FIBER_TERMINATED`  | Finished execution               |
+
+**Limitation:** fibers cannot yield across C function boundaries.
+You cannot call `mrb_fiber_yield` from within a C-implemented
+method, except via `mrb_fiber_yield` at function return.
+
+## Compilation Contexts
+
+For advanced compilation control, use `mrb_ccontext`:
+
+```c
+#include <mruby/compile.h>
+
+mrb_ccontext *cxt = mrb_ccontext_new(mrb);
+
+/* Set source filename for error messages and debug info */
+mrb_ccontext_filename(mrb, cxt, "my_script.rb");
+
+/* Compile and execute with context */
+mrb_value result = mrb_load_string_cxt(mrb, "1 + 2", cxt);
+
+/* Clean up */
+mrb_ccontext_free(mrb, cxt);
+```
+
+### Context Options
+
+The `mrb_ccontext` structure provides several flags:
+
+| Field            | Purpose                                 |
+| ---------------- | --------------------------------------- |
+| `capture_errors` | Collect parse errors instead of raising |
+| `no_exec`        | Compile without executing (get RProc)   |
+| `no_optimize`    | Disable peephole optimizations          |
+| `no_ext_ops`     | Disable extended operand instructions   |
+| `keep_lv`        | Preserve local variables across loads   |
+
+### Loading with Context
+
+```c
+mrb_load_string_cxt(mrb, code, cxt);         /* string + context */
+mrb_load_nstring_cxt(mrb, code, len, cxt);   /* with explicit length */
+mrb_load_file_cxt(mrb, fp, cxt);             /* file + context */
+mrb_load_detect_file_cxt(mrb, fp, cxt);      /* auto-detect .mrb or .rb */
+```
+
+## Precompiled Bytecode
+
+Load `.mrb` files compiled by `mrbc`:
+
+```c
+#include <mruby/irep.h>
+
+/* From byte array (generated by mrbc -B) */
+mrb_value result = mrb_load_irep(mrb, bytecode);
+
+/* From buffer with explicit size (safer, bounds-checked) */
+mrb_value result = mrb_load_irep_buf(mrb, buf, size);
+
+/* From file */
+FILE *fp = fopen("script.mrb", "rb");
+mrb_value result = mrb_load_irep_file(mrb, fp);
+fclose(fp);
+
+/* Load without executing (returns irep for inspection) */
+mrb_irep *irep = mrb_read_irep(mrb, bytecode);
+```
+
+All `_irep` loading functions have `_cxt` variants that accept
+a compilation context.
+
+### Deployment Pattern
+
+Ahead-of-time compilation eliminates the need for the compiler gem
+at runtime:
+
+```shell
+# Compile to C array
+mrbc -Bscript_bytecode script.rb
+
+# This generates a C header with:
+# const uint8_t script_bytecode[];
+```
+
+```c
+#include "script.mrb.h"
+
+mrb_state *mrb = mrb_open_core();  /* no compiler needed */
+mrb_load_irep(mrb, script_bytecode);
+```
+
+**Important:** wrap bytecode loading in arena save/restore when
+loading multiple scripts:
+
+```c
+int ai = mrb_gc_arena_save(mrb);
+mrb_load_irep(mrb, script1);
+mrb_gc_arena_restore(mrb, ai);
+
+ai = mrb_gc_arena_save(mrb);
+mrb_load_irep(mrb, script2);
+mrb_gc_arena_restore(mrb, ai);
+```
+
+## Symbols
+
+```c
+/* Create symbol from string */
+mrb_sym sym = mrb_intern_lit(mrb, "name");         /* from literal */
+mrb_sym sym = mrb_intern_cstr(mrb, cstr);          /* from C string */
+mrb_sym sym = mrb_intern(mrb, ptr, len);           /* from pointer + length */
+
+/* Symbol to string */
+const char *name = mrb_sym_name(mrb, sym);
+mrb_int len;
+const char *name = mrb_sym_name_len(mrb, sym, &len);
+```
+
+## Instance Variables
+
+```c
+/* Get/set instance variables on an object */
+mrb_iv_get(mrb, obj, mrb_intern_lit(mrb, "@x"));
+mrb_iv_set(mrb, obj, mrb_intern_lit(mrb, "@x"), val);
+mrb_iv_defined(mrb, obj, mrb_intern_lit(mrb, "@x"));
+mrb_iv_remove(mrb, obj, mrb_intern_lit(mrb, "@x"));
+```
+
+## Global Variables
+
+```c
+mrb_gv_get(mrb, mrb_intern_lit(mrb, "$verbose"));
+mrb_gv_set(mrb, mrb_intern_lit(mrb, "$verbose"), mrb_true_value());
+```
+
+## Class Variables
+
+```c
+mrb_cv_get(mrb, klass, mrb_intern_lit(mrb, "@@count"));
+mrb_cv_set(mrb, klass, mrb_intern_lit(mrb, "@@count"), mrb_fixnum_value(0));
+```
+
+## Loading and Executing Code
+
+```c
+/* Load and execute a string (requires mruby-compiler gem) */
+mrb_value result = mrb_load_string(mrb, "1 + 2");
+
+/* Load and execute a file */
+FILE *f = fopen("script.rb", "r");
+mrb_value result = mrb_load_file(mrb, f);
+fclose(f);
+
+/* Load precompiled bytecode (no compiler needed) */
+mrb_value result = mrb_load_irep(mrb, bytecode_array);
+```
+
+## GC Arena
+
+When creating many temporary Ruby objects in C, use the GC arena to
+prevent them from being collected prematurely:
+
+```c
+int ai = mrb_gc_arena_save(mrb);
+/* create temporary objects here */
+mrb_gc_arena_restore(mrb, ai);
+```
+
+See [gc-arena-howto.md](gc-arena-howto.md) for details.
+
+## Memory Allocation
+
+```c
+void *p = mrb_malloc(mrb, size);           /* raises on failure */
+void *p = mrb_calloc(mrb, nmemb, size);    /* zero-initialized */
+void *p = mrb_realloc(mrb, ptr, size);     /* resize */
+mrb_free(mrb, p);                          /* free */
+
+/* NULL-returning variants (for custom error handling) */
+void *p = mrb_malloc_simple(mrb, size);
+void *p = mrb_realloc_simple(mrb, ptr, size);
+```
+
+## Type Conversion
+
+```c
+mrb_obj_as_string(mrb, val)      /* to_s */
+mrb_inspect(mrb, val)            /* inspect */
+mrb_any_to_s(mrb, val)           /* default to_s */
+mrb_str_to_integer(mrb, str, base, badcheck)  /* String to Integer */
+mrb_str_to_dbl(mrb, str, badcheck)            /* String to Float */
+mrb_ensure_float_type(mrb, val)               /* ensure Float */
+```
+
+## Object Comparison
+
+```c
+mrb_equal(mrb, a, b)    /* Ruby == */
+mrb_eql(mrb, a, b)      /* Ruby eql? */
+mrb_obj_eq(mrb, a, b)   /* Ruby equal? (identity) */
+mrb_cmp(mrb, a, b)      /* Ruby <=> (returns mrb_int) */
+```
+
+## Object Inspection
+
+```c
+mrb_obj_classname(mrb, obj)          /* class name as C string */
+mrb_obj_class(mrb, obj)              /* class as RClass* */
+mrb_obj_is_kind_of(mrb, obj, klass)  /* is_a? / kind_of? */
+mrb_obj_respond_to(mrb, klass, mid)  /* respond_to? */
+mrb_obj_id(obj)                      /* object_id */
+mrb_obj_freeze(mrb, obj)             /* freeze */
+mrb_obj_dup(mrb, obj)                /* dup */
+```
+
+## Compile-Time Flags
+
+When compiling C code that uses mruby, you must use the same flags as
+the library was built with. Use `mruby-config` to get them:
+
+```console
+$ build/host/bin/mruby-config --cflags    # compiler flags
+$ build/host/bin/mruby-config --ldflags   # linker flags
+$ build/host/bin/mruby-config --libs      # libraries
+```
+
+Key macros that affect ABI:
+
+| Macro             | Effect                                   |
+| ----------------- | ---------------------------------------- |
+| `MRB_NO_BOXING`   | Struct-based values (larger, debuggable) |
+| `MRB_WORD_BOXING` | Single-word values (fast, 32-bit safe)   |
+| `MRB_NAN_BOXING`  | NaN-tagged values (default on 32-bit)    |
+| `MRB_NO_FLOAT`    | Disable Float support                    |
+| `MRB_INT64`       | 64-bit integers                          |
+| `MRB_USE_FLOAT32` | 32-bit floats                            |
+
+Mismatching these between library and application causes silent
+data corruption.

doc/guides/compile.md

@@ -1,3 +1,5 @@
+<!-- summary: About the Compile -->
+
 # Compile
 
 mruby uses Rake to compile and cross-compile all libraries and
@@ -80,7 +82,7 @@ conf.toolchain :clang
 #### Visual Studio 2010, 2012 and 2013
 
 Toolchain configuration for Visual Studio on Windows. If you use the
-[Visual Studio Command Prompt](https://msdn.microsoft.com/en-us/library/ms229859\(v=vs.110\).aspx),
+[Visual Studio Command Prompt](<https://msdn.microsoft.com/en-us/library/ms229859(v=vs.110).aspx>),
 you normally do not have to specify this manually, since it gets automatically detected by our build process.
 
 ```ruby
@@ -117,6 +119,36 @@ set the character via `conf.file_separator`.
 conf.file_separator = '/'
 ```
 
+### Name of library directory
+
+In some environments, the `libmruby.a` file requires a different directory name than `lib`.
+You can be changed to any name by the `conf.libdir_name` accessor.
+
+```ruby
+conf.libdir_name = 'lib64'
+```
+
+Alternatively, it can be changed via the environment variable `MRUBY_SYSTEM_LIBDIR_NAME` when
+the `rake` command is run.
+
+```console
+$ export MRUBY_SYSTEM_LIBDIR_NAME=lib64
+$ rake clean all
+```
+
+NOTES:
+
+- This environment variable `MRUBY_SYSTEM_LIBDIR_NAME` does not affect `MRuby::CrossBuild`.
+  In other words, if you want to change it for `MRuby::CrossBuild`, you must set it with `MRuby::CrossBuild#libdir_name=`.
+- If you want to switch this environment variable `MRUBY_SYSTEM_LIBDIR_NAME`, you must do `rake clean`.
+
+  A bad usage example is shown below.
+
+  ```console
+  $ rake clean all
+  $ rake MRUBY_SYSTEM_LIBDIR_NAME=lib64 install
+  ```
+
 ### C Compiler
 
 Configuration of the C compiler binary, flags and include paths.
@@ -144,7 +176,7 @@ If you need an include path of header file use `search_header_path`:
 fail 'iconv.h not found' unless conf.cc.search_header_path 'iconv.h'
 ```
 
-If you need a full file name of header file use `search_header`:
+If you need a full filename of header file use `search_header`:
 
 ```ruby
 # Searches `iconv.h`.
@@ -177,7 +209,7 @@ conf.linker do |linker|
   linker.flags_before_libraries = ...
   linker.libraries = ...
   linker.flags_after_libraries = ...
-  linker.library_paths = ....
+  linker.library_paths = ...
   linker.option_library = ...
   linker.option_library_path = ...
   linker.link_options = ...
@@ -229,12 +261,9 @@ end
 
 ### Preallocated Symbols
 
-By far, preallocated symbols are highly compatible with the previous versions, so
-we expect you won't see any problem with them. But just in case you face any
-issue, you can disable preallocated symbols by specifying `conf.disable_presym`.
-
-In the build process, `mrbc` under cross compiling environment will be compiled
-with this configuration.
+Preallocated symbols are always enabled. Symbol IDs used in C source code
+(via `MRB_SYM()` etc.) are resolved to compile-time constants during the
+build process.
 
 ### Mrbgems
 
@@ -265,7 +294,7 @@ There is a `RubyGem` (gem for CRuby) named `mgem` that help you to
 manage `mrbgems`. Try `gem install mgem`. `mgem` can show you the list
 of registered `mrbgems`.
 
-See doc/mrbgems/README.md for more option about mrbgems.
+See [doc/guides/mrbgems.md](mrbgems.md) for more option about mrbgems.
 
 ### Mrbtest
 
@@ -376,7 +405,7 @@ end
 
 ## Build process
 
-During the build process the directory `build` will be created in the
+During the build process the `build` directory will be created in the
 root directory. The structure of this directory will look like this:
 
 ```
@@ -460,7 +489,7 @@ compile for `i386` a directory called `i386` is created under the
 build directory.
 
 The cross compilation workflow starts in the same way as the normal
-compilation by compiling all *native* libraries and binaries, except
+compilation by compiling all _native_ libraries and binaries, except
 for we don't have `host/mrbc` directory (`host` directory itself works
 as placeholder for `mrbc`). Afterwards the cross compilation process
 proceeds like this:
@@ -527,7 +556,7 @@ After the build, you will get `libmruby.a`. You can link it to your application.
 For compiler options and library path, you can use `mruby-config` command for
 convenience. `mruby-config` command prints the configuration used for `libmruby.a`.
 
-```
+```console
 $ mruby-config --help
 Usage: mruby-config [switches]
   switches:
@@ -545,7 +574,7 @@ For example, when you have a C source file (`c.c`) and try to
 compile and link it with `libmruby.a`, you can run the following command,
 
 ```
-gcc `mruby-config --cflags` c.c `mruby-config --ldflags` `mruby-config --libs`
+`mruby-config --cc --cflags` c.c `mruby-config --ldflags --libs`
 ```
 
 When you use `make`, add following lines in `Makefile`
@@ -557,6 +586,83 @@ LDFLAGS = `$(MRB_CONFIG) --ldflags`
 LIBS = `$(MRB_CONFIG) --libs`
 ```
 
+## Install
+
+To install the files in the `bin`, `include` and `lib` directories generated by the "host" build target into a system directory, do the following:
+
+```console
+$ rake install
+```
+
+If there are multiple build targets in the build configuration file, to install the products of all build targets, do the following:
+
+```console
+$ rake install:full
+```
+
+To install only one of several build targets, e.g., the "its-mine" build target, do the following:
+
+```console
+$ rake install:full:its-mine
+```
+
+To install only the executable files, do the following:
+
+```console
+$ rake install_bin              # only "host" build target
+$ rake install:bin              # all build targets
+$ rake install:bin:its-mine     # only "its-mine" build target
+```
+
+### Installation Directory
+
+The installation directory is `/usr/local` for the "host" build target and `/usr/local/mruby/<build-name>` for the others.
+To change them, you can set the environment variable `PREFIX` or use `MRuby::Build#install_prefix = dir` in your build configuration file.
+
+The `PREFIX` environment variable affects all build targets and changes the `/usr/local` part.
+
+The `MRuby::Build#install_prefix` can be set for each individual build target.
+In this case, the environment variable `PREFIX` is ignored.
+
+Also, if the environment variable `DESTDIR` is set, it will prepend to the path obtained by `install_prefix` to determine the final write directory.
+This is intended for temporary file expansion by the user's package work.
+
+---
+
+To summarize:
+
+- The default value of the environment variable `PREFIX` is `/usr/local`.
+- For the "host" build target, the default value of `MRuby::Build#install_prefix` is `<PREFIX>`.
+- For a build target other than "host", the default value of `MRuby::Build#install_prefix` is `<PREFIX>/mruby/<build-name>`.
+- If the environment variable `DESTDIR` is set, the actual write directory is `<DESTDIR>/<MRuby::Build#install_prefix>`.
+
+### Excluded files
+
+In some cases there are files that you do not want to install.
+In such cases, add a file path filter to the array object `MRuby::Build#install_excludes` to exclude them.
+
+The following is an object that can be defined as a file path filter.
+The `path` variable that appears is a relative path based on `MRuby::Build#build_dir`.
+
+- string objects: files matched by `string.match?(path)` are excluded.
+- regexp object: files matched by `regexp.match?(path)` are excluded.
+- proc object: files which return true with `proc.call(path)` are excluded.
+
+```ruby
+# exclude bin/mrbc
+conf.install_excludes << exefile("bin/mrbc")
+
+# exclude all files under lib/ directory
+conf.install_excludes << %r(^lib/)
+
+# exclude bin/mrbtest, but in this case it is recommended to use string instead of proc
+conf.install_excludes << proc { |path|
+  path == exefile("bin/mrbtest")
+}
+```
+
+By default, it contains only a proc object to exclude `libmruby_core`.
+
 ## Tips
 
 - If you see compilation troubles, try `rake clean` first.

doc/guides/debugger.md

@@ -1,3 +1,5 @@
+<!-- summary: About the Debugger with the `mrdb` Command -->
+
 # How to Use the mruby Debugger
 
 copyright (c) 2014 Specified Non-Profit Corporation mruby Forum
@@ -38,7 +40,7 @@ To confirm mrdb was installed properly, run mrdb with the `--version` option:
 
 ```bash
 $ mrdb --version
-mruby 3.1.0 (2022-05-12)
+mruby 3.4.0 (2025-04-20)
 ```
 
 ## 2.2 Basic Operation
@@ -50,7 +52,7 @@ To invoke the mruby debugger, just type `mrdb`.
 To specify the script file:
 
 ```bash
-$ mrdb [option] file name
+$ mrdb [option] filename
 ```
 
 For example: Debugging sample.rb
@@ -61,20 +63,20 @@ $ mrdb sample.rb
 
 You can execute the shell commands listed below:
 
-|command|description|
-|:-:|:--|
-|run|execute programs|
-|step|execute stepping|
-|continue|execute continuing program|
-|break|configure the breaking point|
-|delete|deleting the breaking points|
-|disable|disabling the breaking points|
-|enable|enabling the breaking points|
-|info breakpoints|showing list of the breaking points|
-|print|evaluating and printing the values of the mruby expressions in the script|
-|list|displaying the source cords|
-|help|showing help|
-|quit|terminating the mruby debugger|
+|     command      | description                                                               |
+| :--------------: | :------------------------------------------------------------------------ |
+|       run        | execute programs                                                          |
+|       step       | execute stepping                                                          |
+|     continue     | execute continuing program                                                |
+|      break       | configure the breaking point                                              |
+|      delete      | deleting the breaking points                                              |
+|     disable      | disabling the breaking points                                             |
+|      enable      | enabling the breaking points                                              |
+| info breakpoints | showing list of the breaking points                                       |
+|      print       | evaluating and printing the values of the mruby expressions in the script |
+|       list       | displaying the source cords                                               |
+|       help       | showing help                                                              |
+|       quit       | terminating the mruby debugger                                            |
 
 ### 2.2.2 Debugging mruby Binary Files (mrb file) with mrdb
 
@@ -83,7 +85,7 @@ You can debug the mruby binary files.
 #### 2.2.2.1 Debugging the binary files
 
 - notice
-To debug mruby binary files, you need to compile mruby files with option `-g`.
+  To debug mruby binary files, you need to compile mruby files with option `-g`.
 
 ```bash
 $ mrbc -g sample.rb
@@ -119,7 +121,7 @@ Be aware that the breakpoint command will not check the validity of the class na
 
 You can get the current breakpoint information by the following options.
 
-breakpoint breakpoint number : file name. line number
+breakpoint breakpoint number : filename. line number
 
 breakpoint breakpoint number : [class name,] method name
 
@@ -265,7 +267,7 @@ Example:
 ```
 (sample.rb:1) info breakpoints
 Num     Type           Enb What
-1       breakpoint     y   at sample.rb:3                      -> file name,line number
+1       breakpoint     y   at sample.rb:3                      -> filename,line number
 2       breakpoint     n   in Sample_class:sample_class_method -> [class:]method name
 3       breakpoint     y   in sample_global_method
 ```
@@ -299,11 +301,11 @@ When you do not specify both the `first` and `last` options, you will receive th
 Example:
 
 ```
-Specifying file name and first row number
+Specifying filename and first row number
 sample.rb:1) list sample2.rb:5
 ```
 
-Specifying the file name and the first and last row number:
+Specifying the filename and the first and last row number:
 
 ```
 (sample.rb:1) list sample2.rb:6,7

doc/guides/gc-arena-howto.md

@@ -1,9 +1,12 @@
+<!-- summary: About GC Arena -->
+
 # How to use `mrb_gc_arena_save()`/`mrb_gc_arena_restore()`/`mrb_gc_protect()`
 
 _This is an English translation of [Matz's blog post][matz blog post]
 written in Japanese._
 _Some parts are updated to reflect recent changes._
-[matz blog post]: <https://www.rubyist.net/~matz/20130731.html>
+
+[matz blog post]: https://www.rubyist.net/~matz/20130731.html
 
 When you are extending mruby using C language, you may encounter
 mysterious "arena overflow error" or memory leak or very slow
@@ -62,7 +65,7 @@ memory leak.
 
 As of this writing, mruby automatically extend arena to remember
 objects (See `MRB_GC_FIXED_ARENA` and `MRB_GC_ARENA_SIZE` in
-doc/guides/mrbconf.md).
+[doc/guides/mrbconf.md](mrbconf.md)).
 
 If you create many objects in C functions, memory usage will increase, since
 GC never kicks in. This memory usage may look like memory leaks, but will also
@@ -93,54 +96,31 @@ In mruby, C function calls are surrounded by this save/restore, but we
 can further optimize memory usage by surrounding save/restore, and can
 avoid creating arena overflow bugs.
 
-Let's take a real example. Here is the source code of `Array#inspect`:
+Let's take a real example. Here is the source code of `Array#inspect`
+(from `src/array.c`):
 
 ```c
 static mrb_value
-inspect_ary(mrb_state *mrb, mrb_value ary, mrb_value list)
+mrb_ary_to_s(mrb_state *mrb, mrb_value self)
 {
-  mrb_int i;
-  mrb_value s, arystr;
-  char head[] = { '[' };
-  char sep[] = { ',', ' ' };
-  char tail[] = { ']' };
-
-  /* check recursive */
-  for(i=0; i<RARRAY_LEN(list); i++) {
-    if (mrb_obj_equal(mrb, ary, RARRAY_PTR(list)[i])) {
-      return mrb_str_new(mrb, "[...]", 5);
-    }
+  mrb->c->ci->mid = MRB_SYM(inspect);
+  mrb_value ret = mrb_str_new_lit(mrb, "[");
+  int ai = mrb_gc_arena_save(mrb);
+  if (MRB_RECURSIVE_UNARY_P(mrb, MRB_SYM(inspect), self)) {
+    mrb_str_cat_lit(mrb, ret, "...]");
+    return ret;
   }
-
-  mrb_ary_push(mrb, list, ary);
-
-  arystr = mrb_str_new_capa(mrb, 64);
-  mrb_str_cat(mrb, arystr, head, sizeof(head));
-
-  for(i=0; i<RARRAY_LEN(ary); i++) {
-    int ai = mrb_gc_arena_save(mrb);
-
-    if (i > 0) {
-      mrb_str_cat(mrb, arystr, sep, sizeof(sep));
-    }
-    if (mrb_array_p(RARRAY_PTR(ary)[i])) {
-      s = inspect_ary(mrb, RARRAY_PTR(ary)[i], list);
-    }
-    else {
-      s = mrb_inspect(mrb, RARRAY_PTR(ary)[i]);
-    }
-    mrb_str_cat(mrb, arystr, RSTRING_PTR(s), RSTRING_LEN(s));
+  for (mrb_int i=0; i<RARRAY_LEN(self); i++) {
+    if (i>0) mrb_str_cat_lit(mrb, ret, ", ");
+    mrb_str_cat_str(mrb, ret, mrb_inspect(mrb, RARRAY_PTR(self)[i]));
     mrb_gc_arena_restore(mrb, ai);
   }
+  mrb_str_cat_lit(mrb, ret, "]");
 
-  mrb_str_cat(mrb, arystr, tail, sizeof(tail));
-  mrb_ary_pop(mrb, list);
-
-  return arystr;
+  return ret;
 }
 ```
 
-This is a real example, so slightly complicated, but bear with me.
 The essence of `Array#inspect` is that after stringifying each element
 of array using `inspect` method, we join them together so that we can
 get `inspect` representation of the entire array.
@@ -149,7 +129,7 @@ After the `inspect` representation is created, we no longer require the
 individual string representation. This means that we don't have to register
 these temporal objects into GC arena.
 
-Therefore, in order to keep the arena size small; the `ary_inspect()` function
+Therefore, in order to keep the arena size small; the function
 will do the following:
 
 - save the position of the stack top using `mrb_gc_arena_save()`.
@@ -163,7 +143,7 @@ required temporal object may be deleted by GC.
 
 We may have an usecase where after creating many temporal objects, we'd
 like to keep some of them. In this case, we cannot use the same idea
-in `ary_inspect()` like appending objects to existing one.
+in `mrb_ary_to_s()` like appending objects to existing one.
 Instead, after `mrb_gc_arena_restore()`, we must re-register the objects we
 want to keep in the arena using `mrb_gc_protect(mrb, obj)`.
 Use `mrb_gc_protect()` with caution because it could also lead to an "arena

doc/guides/getting-started.md

@@ -0,0 +1,283 @@
+<!-- summary: Getting Started with mruby -->
+
+# Getting Started with mruby
+
+This guide walks you through building mruby, running your first Ruby program,
+and embedding mruby in a C application.
+
+## Prerequisites
+
+You need:
+
+- C compiler (`gcc` or `clang`)
+- Ruby 2.5 or later (for the build system)
+- `rake` (bundled with Ruby)
+- `git` (optional, for cloning the source)
+
+## Building mruby
+
+Clone the repository and build:
+
+```console
+$ git clone https://github.com/mruby/mruby.git
+$ cd mruby
+$ rake
+```
+
+This compiles the default configuration and produces:
+
+- `bin/mruby` — Ruby script interpreter
+- `bin/mirb` — interactive Ruby shell
+- `bin/mrbc` — bytecode compiler
+- `build/host/lib/libmruby.a` — library for embedding
+
+## Running Ruby Code
+
+### Interactive shell
+
+```console
+$ bin/mirb
+mirb - Pair interactive mruby
+> puts "Hello, mruby!"
+Hello, mruby!
+ => nil
+> 1 + 2
+ => 3
+```
+
+### Running a script file
+
+Create `hello.rb`:
+
+```ruby
+puts "Hello from mruby!"
+```
+
+Run it:
+
+```console
+$ bin/mruby hello.rb
+Hello from mruby!
+```
+
+### One-liner
+
+```console
+$ bin/mruby -e 'puts "Hello!"'
+Hello!
+```
+
+## Compiling to Bytecode
+
+mruby can compile Ruby scripts to bytecode (`.mrb` files) for faster
+loading and deployment without source code:
+
+```console
+$ bin/mrbc hello.rb        # produces hello.mrb
+$ bin/mruby -b hello.mrb   # run bytecode
+Hello from mruby!
+```
+
+You can also generate C source from Ruby scripts:
+
+```console
+$ bin/mrbc -Bhello_code hello.rb   # produces hello.c with byte array
+```
+
+This generates a C file with a `const uint8_t hello_code[]` array that
+can be loaded with `mrb_load_irep()` in your C application.
+
+## Embedding mruby in C
+
+The primary use case of mruby is embedding in C/C++ applications.
+
+### Minimal example
+
+Create `embed.c`:
+
+```c
+#include <mruby.h>
+#include <mruby/compile.h>
+
+int main(void)
+{
+  mrb_state *mrb = mrb_open();
+  if (!mrb) return 1;
+
+  mrb_load_string(mrb, "puts 'Hello from embedded mruby!'");
+  if (mrb->exc) {
+    mrb_print_error(mrb);
+  }
+
+  mrb_close(mrb);
+  return 0;
+}
+```
+
+### Compile and link
+
+Use `mruby-config` to get the correct compiler and linker flags:
+
+```console
+$ gcc -I include `build/host/bin/mruby-config --cflags` embed.c \
+    `build/host/bin/mruby-config --ldflags --libs` -o embed
+$ ./embed
+Hello from embedded mruby!
+```
+
+**Important**: Always use `mruby-config --cflags` when compiling code
+that uses mruby. The build configuration may define macros (such as
+`MRB_NO_BOXING` or `MRB_USE_BIGINT`) that change the internal data
+layout. Compiling without these flags causes silent data corruption.
+
+### Calling Ruby from C
+
+```c
+#include <stdio.h>
+#include <mruby.h>
+#include <mruby/compile.h>
+#include <mruby/string.h>
+
+int main(void)
+{
+  mrb_state *mrb = mrb_open();
+
+  /* Define a Ruby method */
+  mrb_load_string(mrb, "def greet(name) \"Hello, #{name}!\" end");
+
+  /* Call it from C */
+  mrb_value result = mrb_funcall(mrb, mrb_top_self(mrb),
+                                 "greet", 1, mrb_str_new_lit(mrb, "World"));
+  printf("%s\n", mrb_str_to_cstr(mrb, result));
+
+  mrb_close(mrb);
+  return 0;
+}
+```
+
+### Defining C functions callable from Ruby
+
+```c
+#include <mruby.h>
+#include <mruby/compile.h>
+
+static mrb_value
+my_add(mrb_state *mrb, mrb_value self)
+{
+  mrb_int a, b;
+  mrb_get_args(mrb, "ii", &a, &b);
+  return mrb_fixnum_value(a + b);
+}
+
+int main(void)
+{
+  mrb_state *mrb = mrb_open();
+
+  /* Define method on Kernel (available everywhere) */
+  mrb_define_method(mrb, mrb->kernel_module, "my_add",
+                    my_add, MRB_ARGS_REQ(2));
+
+  mrb_load_string(mrb, "puts my_add(3, 4)");  /* prints 7 */
+
+  mrb_close(mrb);
+  return 0;
+}
+```
+
+## Loading Precompiled Bytecode
+
+For deployment without the compiler gem, precompile your Ruby code:
+
+```console
+$ bin/mrbc -Bruby_code app.rb
+```
+
+Then load in C:
+
+```c
+#include <mruby.h>
+#include <mruby/irep.h>
+#include "app.c"  /* contains ruby_code[] */
+
+int main(void)
+{
+  mrb_state *mrb = mrb_open();
+  mrb_load_irep(mrb, ruby_code);
+  if (mrb->exc) {
+    mrb_print_error(mrb);
+  }
+  mrb_close(mrb);
+  return 0;
+}
+```
+
+This approach does not require the `mruby-compiler` gem, resulting in
+a smaller binary.
+
+## Customizing the Build
+
+mruby's functionality is controlled by the build configuration file.
+The default is `build_config/default.rb`.
+
+### Using a custom configuration
+
+```console
+$ MRUBY_CONFIG=build_config/minimal.rb rake
+```
+
+### Selecting gems
+
+Gems add features to mruby. A minimal configuration:
+
+```ruby
+MRuby::Build.new do |conf|
+  conf.toolchain :gcc
+
+  # Core language extensions
+  conf.gem core: 'mruby-array-ext'
+  conf.gem core: 'mruby-string-ext'
+  conf.gem core: 'mruby-hash-ext'
+
+  # Tools
+  conf.gem core: 'mruby-bin-mruby'   # mruby command
+  conf.gem core: 'mruby-bin-mirb'    # interactive shell
+  conf.gem core: 'mruby-bin-mrbc'    # bytecode compiler
+
+  # Compiler (needed for mrb_load_string)
+  conf.gem core: 'mruby-compiler'
+end
+```
+
+### Using a gembox
+
+Gemboxes are predefined collections of gems:
+
+```ruby
+MRuby::Build.new do |conf|
+  conf.toolchain :gcc
+  conf.gembox 'default'    # standard set of gems
+end
+```
+
+## Amalgamation (Single-File Build)
+
+For the simplest integration, use amalgamation to combine all mruby
+source into a single `mruby.c` and `mruby.h`:
+
+```console
+$ rake amalgam
+$ gcc -I build/host/amalgam your_app.c build/host/amalgam/mruby.c -o your_app -lm
+```
+
+See [amalgamation.md](amalgamation.md) for details.
+
+## What's Next
+
+- [Language Features](language.md) — Ruby subset supported by mruby
+- [C API Reference](capi.md) — values, classes, methods, error handling
+- [Compile](compile.md) — full build system reference
+- [mrbgems](mrbgems.md) — creating and using gems
+- [Linking](link.md) — linking `libmruby` to applications
+- [Build-time Configurations](mrbconf.md) — compile-time options
+- [GC Arena](gc-arena-howto.md) — managing GC arena in C extensions
+- [Limitations](../limitations.md) — differences from CRuby

doc/guides/hier.md

@@ -0,0 +1,62 @@
+<!-- summary: About the mruby directory structure -->
+
+# The mruby directory structure
+
+```text
++- 💎 mruby/                    The top directory of mruby.
+    |
+    +- 📁 .github/              GitHub configuration files for mruby project management.
+    |
+    +- 📁 benchmark/            Benchmarking files for mruby.
+    |
+    +- 📁 bin/                  Links to temporary executables after build. Auto-created.
+    |
+    +- 📁 build/                Default build output destination for mruby. Auto-created.
+    |   |
+    |   +- 📁 repos/            The git clone destination directory for GEMs that depend on the build configuration.
+    |   |
+    |   +- 📁 host/             The "host" build output directory.
+    |
+    +- 📁 build_config/         Build configuration files for various environments.
+    |
+    +- 📁 doc/                  Documentation for mruby.
+    |   |
+    |   +- 📁 guides/           Documentation for general users.
+    |   |
+    |   +- 📁 internal/         Documentation for internal implementations for developers.
+    |
+    +- 📁 examples/             Examples of mruby usages.
+    |   |
+    |   +- 📁 mrbgems/          Examples for creating custom GEM for mruby.
+    |
+    +- 📁 include/              C header files required when using mruby.
+    |
+    +- 📁 lib/                  Ruby scripts used for building mruby.
+    |
+    +- 📁 mrbgems/              A library collection of features not provided by mruby core only.
+    |   |                       See doc/guides/mrbgems.md file
+    |   |
+    |   +- 📁 mruby-*/          The directory of each GEMs.
+    |   |
+    |   +- 📃 *.gembox          A collection of GEMs grouped by features and purposes.
+    |
+    +- 📁 mrblib/               The core Ruby scripts that makes up the main body of mruby.
+    |
+    +- 📁 oss-fuzz/             Source code for The fuzzing-test.
+    |                           See https://github.com/google/oss-fuzz
+    |
+    +- 📁 src/                  The core C source code that makes up the main body of mruby.
+    |
+    +- 📁 tasks/                Rake tasks at build-time.
+    |   |
+    |   +- 📁 toolchains/       Definitions for the compiler, linker, archiver, etc. for each toolchain.
+    |
+    +- 📁 test/                 Ruby scripts needed for testing mruby.
+    |   |
+    |   +- 📁 t/                mruby test cases.
+    |
+    +- 📁 tools/                External programs used for the mruby project.
+        |
+        +- 📁 lrama/            LALR parser generator as an alternative to bison.
+                                Import from https://github.com/ruby/lrama
+```

doc/guides/language.md

@@ -0,0 +1,430 @@
+<!-- summary: mruby Language Features and Ruby Compatibility -->
+
+# mruby Language Features
+
+This guide describes the Ruby language features supported by mruby 4.0.
+mruby implements a subset of the Ruby language, optimized for embedded use.
+For a list of specific behavioral differences, see
+[limitations.md](../limitations.md).
+
+**If you are coming from CRuby**, note these major differences upfront:
+
+- No `require` or `load` — all code is linked at build time
+- No `defined?` keyword — use `respond_to?`, `const_defined?`, etc.
+- No refinements (`refine`, `using`)
+- No `Encoding` class — UTF-8 opt-in via `MRB_UTF8_STRING`
+- Fibers cannot yield across C function boundaries
+- Integer size varies by platform and boxing mode
+- Operators cannot be overridden by user code
+
+See [Key Differences from CRuby](#key-differences-from-cruby) for
+the full list.
+
+## Syntax
+
+### Keywords
+
+mruby supports the following keywords:
+
+`BEGIN`, `END`, `alias`, `and`, `begin`, `break`, `case`, `class`,
+`def`, `do`, `else`, `elsif`, `end`, `ensure`, `false`, `for`, `if`,
+`in`, `module`, `next`, `nil`, `not`, `or`, `redo`, `rescue`,
+`retry`, `return`, `self`, `super`, `then`, `true`, `undef`,
+`unless`, `until`, `when`, `while`, `yield`
+
+Magic variables: `__FILE__`, `__LINE__`, `__ENCODING__`, `__method__`
+
+**Not supported:** `defined?` (use `respond_to?`, `const_defined?`,
+etc. instead), `refinements` (`using`, `refine`).
+
+### Classes and Modules
+
+```ruby
+class Animal
+  attr_accessor :name
+
+  def initialize(name)
+    @name = name
+  end
+
+  def speak
+    "..."
+  end
+end
+
+class Dog < Animal
+  def speak
+    "Woof!"
+  end
+end
+
+module Greetable
+  def greet
+    "Hello, I'm #{name}"
+  end
+end
+
+class Dog
+  include Greetable
+end
+```
+
+All standard class and module features are supported: inheritance,
+`include`, `prepend`, `extend`, `attr_reader`/`attr_writer`/
+`attr_accessor`, `public`/`private`/`protected` visibility, class
+variables (`@@var`), class methods, and `super`.
+
+### Methods
+
+```ruby
+# Required, optional, rest, post-rest, keyword, and block arguments
+def example(a, b = 1, *rest, last, key:, opt_key: nil, **kwargs, &block)
+end
+
+# Endless method definition
+def double(x) = x * 2
+```
+
+### Blocks and Procs
+
+```ruby
+[1, 2, 3].each { |n| puts n }
+
+[1, 2, 3].each do |n|
+  puts n
+end
+
+square = Proc.new { |x| x * x }
+square = proc { |x| x * x }
+double = lambda { |x| x * 2 }
+double = ->(x) { x * 2 }
+```
+
+### Control Flow
+
+```ruby
+# if/unless (both statement and modifier forms)
+if condition
+  # ...
+elsif other
+  # ...
+else
+  # ...
+end
+
+result = value if condition
+result = value unless condition
+
+# case/when
+case obj
+when String then "string"
+when Integer then "integer"
+else "other"
+end
+
+# Loops
+while condition
+  # ...
+end
+
+until condition
+  # ...
+end
+
+for item in collection
+  # ...
+end
+
+# Loop control
+break       # exit loop
+next        # skip to next iteration
+redo        # restart current iteration
+retry       # restart begin/rescue block
+```
+
+### Exception Handling
+
+```ruby
+begin
+  risky_operation
+rescue ArgumentError => e
+  handle_arg_error(e)
+rescue StandardError => e
+  handle_error(e)
+ensure
+  cleanup
+end
+
+raise "something went wrong"
+raise ArgumentError, "bad argument"
+```
+
+**Note:** `raise` without arguments in a `rescue` clause does not
+re-raise the current exception. Capture and re-raise explicitly:
+
+```ruby
+begin
+  risky_operation
+rescue => e
+  log(e)
+  raise e  # explicit re-raise required
+end
+```
+
+### Strings
+
+```ruby
+"double-quoted with #{interpolation}"
+'single-quoted literal'
+heredoc = <<~HEREDOC
+  indented heredoc
+  with #{interpolation}
+HEREDOC
+```
+
+### Regular Expressions
+
+Regular expressions require an external gem such as `mruby-regexp-pcre`
+or `mruby-onig-regexp`. Without a regexp gem, `Regexp` literals
+(`/pattern/`) are not available.
+
+### Pattern Matching (Limited)
+
+Only rightward assignment with simple variable binding is supported:
+
+```ruby
+expr => var   # assigns expr to var
+```
+
+`case/in` syntax, array/hash patterns, guard clauses, pin operator,
+find patterns, and alternative patterns are **not** supported.
+
+## Numeric Types
+
+mruby's numeric type sizes depend on the boxing mode and platform.
+
+### Integer
+
+| Configuration                          | Range            |
+| -------------------------------------- | ---------------- |
+| 64-bit word boxing (default on 64-bit) | roughly +/- 2^62 |
+| 32-bit word boxing (default on 32-bit) | roughly +/- 2^30 |
+| NaN boxing (64-bit only)               | -2^31 to 2^31-1  |
+
+Integer overflow raises a `RangeError` unless the `mruby-bigint` gem
+is included, in which case integers automatically promote to
+arbitrary precision.
+
+### Float
+
+By default, `Float` uses 64-bit `double`. Compile-time options:
+
+- `MRB_USE_FLOAT32`: use 32-bit `float` instead
+- `MRB_NO_FLOAT`: disable floating-point entirely
+
+With word boxing on 64-bit, many float values are stored inline
+(without heap allocation) using a rotation encoding.
+
+### Additional Numeric Types (via gems)
+
+- **Rational** (`mruby-rational`): exact rational arithmetic
+- **Complex** (`mruby-complex`): complex number support
+- **Bigint** (`mruby-bigint`): arbitrary-precision integers
+
+## Core Classes
+
+These classes are always available in mruby (no gem required):
+
+| Class         | Notes                                  |
+| ------------- | -------------------------------------- |
+| Object        | Base class for all objects             |
+| Module        | Module definition and mixin            |
+| Class         | Class definition and instantiation     |
+| NilClass      | Singleton `nil`                        |
+| TrueClass     | Singleton `true`                       |
+| FalseClass    | Singleton `false`                      |
+| Integer       | Fixed-precision integer                |
+| Float         | Floating-point (unless `MRB_NO_FLOAT`) |
+| Symbol        | Interned identifier                    |
+| String        | Mutable byte string                    |
+| Array         | Ordered collection                     |
+| Hash          | Key-value mapping                      |
+| Range         | Interval representation                |
+| Proc          | Closure / callable object              |
+| Exception     | Exception hierarchy root               |
+| StandardError | Common error base                      |
+
+### Core Modules
+
+| Module     | Notes                                     |
+| ---------- | ----------------------------------------- |
+| Kernel     | Core methods (`puts`, `p`, `raise`, etc.) |
+| Comparable | Comparison operators via `<=>`            |
+| Enumerable | Collection iteration methods              |
+
+## Standard Library (via gemboxes)
+
+mruby's standard library is organized into gemboxes. The `default`
+gembox includes all of the below. Use this table to find which
+gembox provides the class or feature you need:
+
+### Classes and Modules
+
+| Class/Module          | Gembox     | Gem               |
+| --------------------- | ---------- | ----------------- |
+| Fiber                 | stdlib     | mruby-fiber       |
+| Enumerator            | stdlib     | mruby-enumerator  |
+| Enumerator::Lazy      | stdlib     | mruby-enum-lazy   |
+| Set                   | stdlib     | mruby-set         |
+| ObjectSpace           | stdlib     | mruby-objectspace |
+| Time                  | stdlib-ext | mruby-time        |
+| Struct                | stdlib-ext | mruby-struct      |
+| Data                  | stdlib-ext | mruby-data        |
+| Random                | stdlib-ext | mruby-random      |
+| IO, File              | stdlib-io  | mruby-io          |
+| Socket                | stdlib-io  | mruby-socket      |
+| Dir                   | stdlib-io  | mruby-dir         |
+| Errno                 | stdlib-io  | mruby-errno       |
+| Math                  | math       | mruby-math        |
+| Rational              | math       | mruby-rational    |
+| Complex               | math       | mruby-complex     |
+| Bigint                | math       | mruby-bigint      |
+| Method, UnboundMethod | metaprog   | mruby-method      |
+
+### Methods and Features
+
+| Feature                       | Gembox     | Gem                |
+| ----------------------------- | ---------- | ------------------ |
+| `catch`/`throw`               | stdlib     | mruby-catch        |
+| `Kernel#sprintf`, `String#%`  | stdlib-ext | mruby-sprintf      |
+| `Array#pack`, `String#unpack` | stdlib-ext | mruby-pack         |
+| `Kernel#rand`                 | stdlib-ext | mruby-random       |
+| `Kernel#eval`                 | metaprog   | mruby-eval         |
+| `Kernel#binding`              | metaprog   | mruby-binding      |
+| `Proc#binding`                | metaprog   | mruby-proc-binding |
+| Runtime compiler              | metaprog   | mruby-compiler     |
+
+### Core Class Extensions
+
+The `stdlib` gembox also extends built-in classes with additional
+methods. These are included by default:
+
+| Extension               | Examples                                       |
+| ----------------------- | ---------------------------------------------- |
+| Array extensions        | `#dig`, `#union`, `#difference`                |
+| Hash extensions         | `#dig`, `#transform_keys`, `#transform_values` |
+| String extensions       | `#encode`, `#bytes`, `#chars`                  |
+| Numeric extensions      | `Integer#digits`, `Integer#pow`                |
+| Comparable extensions   | `#clamp`                                       |
+| Enumerable extensions   | `#sort_by`, `#min_by`, `#max_by`, `#tally`     |
+| Range extensions        | `#size`, `#cover?`                             |
+| Proc extensions         | `#<<`, `#>>` (composition)                     |
+| Symbol extensions       | `#to_proc`                                     |
+| Object extensions       | `#then`, `#yield_self`                         |
+| Kernel extensions       | `#__method__`                                  |
+| Class/Module extensions | `Module#name`                                  |
+
+### Gembox Summary
+
+| Gembox       | Contents                                      | Notes                                        |
+| ------------ | --------------------------------------------- | -------------------------------------------- |
+| `stdlib`     | Core class extensions, Fiber, Enumerator, Set | Works with `MRB_NO_STDIO` and `MRB_NO_FLOAT` |
+| `stdlib-ext` | Time, Struct, Data, Random, sprintf, pack     | Works with `MRB_NO_STDIO` and `MRB_NO_FLOAT` |
+| `stdlib-io`  | IO, File, Dir, Socket, Errno                  | Requires stdio                               |
+| `math`       | Math, Rational, Complex, Bigint               | Works with `MRB_NO_STDIO`                    |
+| `metaprog`   | eval, binding, Method, compiler               | Works with `MRB_NO_STDIO` and `MRB_NO_FLOAT` |
+| `default`    | All of the above + CLI tools                  | Full installation                            |
+
+## Key Differences from CRuby
+
+### No Runtime Loading
+
+mruby has no `require` or `load`. All code (gems, libraries) is
+linked at build time. To add functionality, include the appropriate
+gem in your build configuration:
+
+```ruby
+MRuby::Build.new do |conf|
+  conf.gem :core => "mruby-time"
+end
+```
+
+### No `defined?` Keyword
+
+The `defined?` keyword raises `NameError` instead of returning a
+type string or `nil`. Use alternatives:
+
+```ruby
+# Instead of: defined?(Foo)
+Object.const_defined?(:Foo)
+
+# Instead of: defined?(@var)
+instance_variable_defined?(:@var)
+
+# Instead of: defined?(method_name)
+respond_to?(:method_name)
+```
+
+### Fiber Limitations
+
+Fibers cannot cross C function boundaries. You cannot yield from a
+fiber inside a C-implemented method. Only `mrb_fiber_yield` at
+function return is supported.
+
+### Array and String Subclasses
+
+`Array` and `String` do not support instance variables to reduce memory.
+This means subclassing `Array` or `String` and adding `@fields` will raise an error.
+
+### Operator Overriding
+
+Operators of primitive classes cannot be overridden by user code.
+Redefining `String#+` has no effect on the behavior of the `+` operator.
+
+### Module Loading Hooks
+
+`include`/`prepend`/`extend` do not call `append_features`/
+`prepend_features`/`extend_object` hooks. The module is included
+directly.
+
+### Small Hash Optimization
+
+For small hashes, `#hash` is not called on keys. Custom `#hash`
+methods may not execute for small hash tables.
+
+### No Refinements
+
+Module refinements (`refine`, `using`) are not supported.
+
+### No Encoding Class
+
+There is no `Encoding` class. String encoding is either pure bytes
+or UTF-8 (opt-in via `MRB_UTF8_STRING` compile flag).
+
+### `nil?` in Conditionals
+
+Redefining `nil?` has no effect on conditional expressions.
+The VM uses direct nil checks for performance.
+
+### Integer Precision
+
+Integer size varies by boxing mode (see [Numeric Types](#numeric-types)
+above). Code relying on 64-bit integer precision may behave
+differently on 32-bit or NaN boxing configurations.
+
+## Build-Time Configuration
+
+Key compile-time macros that affect language behavior:
+
+| Macro                | Effect                             |
+| -------------------- | ---------------------------------- |
+| `MRB_NO_FLOAT`       | Remove all float support           |
+| `MRB_USE_FLOAT32`    | Use 32-bit float instead of double |
+| `MRB_UTF8_STRING`    | Enable UTF-8 string handling       |
+| `MRB_INT32`          | Force 32-bit integer               |
+| `MRB_INT64`          | Force 64-bit integer               |
+| `MRB_STR_LENGTH_MAX` | Max string length (default 1MB)    |
+| `MRB_ARY_LENGTH_MAX` | Max array length (default 2^17)    |
+
+See [mrbconf.md](mrbconf.md) for the complete list of configuration
+macros.

doc/guides/link.md

@@ -1,3 +1,5 @@
+<!-- summary: About Linking with `libmruby` -->
+
 # Linking `libmruby` to your application
 
 You have two ways to link `libmruby` to your application.
@@ -51,10 +53,10 @@ for example:
 To retrieve compiler options used to build `mruby`, you can use `mruby-config`
 command with following options:
 
-- `--cc`                    compiler name
-- `--cflags`                options passed to compiler
+- `--cc` compiler name
+- `--cflags` options passed to compiler
 
-```
+```console
 $ mruby-config --cflags
 -std=gnu99 -g -O3 -Wall -DMRB_GC_FIXED_ARENA -I/home/matz/work/mruby/include -I/home/matz/work/mruby/build/host/include
 ```
@@ -66,12 +68,12 @@ compatible to mruby configuration.
 
 To retrieve linker options, you can use `mruby-config` with following options:
 
-- `--ld`                    linker name
-- `--ldflags`               options passed to linker
-- `--ldflags-before-libs`   options passed to linker before linked libraries
-- `--libs`                  linked libraries
+- `--ld` linker name
+- `--ldflags` options passed to linker
+- `--ldflags-before-libs` options passed to linker before linked libraries
+- `--libs` linked libraries
 
-```
+```console
 $ mruby-config --ldflags
 -L/home/matz/work/mruby/build/host/lib
 

doc/guides/memory.md

@@ -0,0 +1,211 @@
+<!-- summary: About Memory Allocator Customization and Heap Regions -->
+
+# Memory Allocation
+
+In mruby, you can customize how memory is allocated in two ways:
+
+1. **Provide your own `malloc()`/`realloc()`/`free()`**
+2. **Override `mrb_basic_alloc_func()`**
+
+---
+
+## 1. Provide your own `malloc()`/`realloc()`/`free()`
+
+On platforms without a full C standard library —such as many microcontrollers— you may need to supply your own implementations of `malloc()`, `realloc()`, and `free()`. mruby’s allocator calls directly into these functions, so replacing them lets you control **every** allocation and deallocation performed by your entire program, including any third‑party libraries you link against.
+
+Keep in mind:
+
+- Calling `realloc(NULL, size)` must behave like `malloc(size)`.
+- Calling `free(NULL)` must be a no‑op.
+
+Simply define these three functions in your code (or link against a library that provides them), and mruby — along with all other code in your process — will use your versions automatically.
+
+## 2. Override `mrb_basic_alloc_func()`
+
+Inside mruby, all of its own memory allocations go through a single function called mrb_basic_alloc_func() (formerly mrb_default_allocf()). By defining this function in your application before linking, you can intercept and handle **only** the memory operations initiated by mruby itself without affecting other libraries or parts of your program.
+
+```c
+// Example signature:
+// void* mrb_basic_alloc_func(void* ptr, size_t size);
+```
+
+Implement mrb_basic_alloc_func() in your code, and mruby will invoke it for every internal allocation, reallocation, and free request.
+
+### Expected behavior
+
+- `mrb_basic_alloc_func(NULL, size)` should allocate `size` bytes, just like `malloc(size)`.
+- `mrb_basic_alloc_func(ptr, size)` should resize the existing block at `ptr` to `size` bytes, just like `realloc(ptr, size)`.
+- `mrb_basic_alloc_func(ptr, 0)` should free the block at `ptr`, just like `free(ptr)`.
+
+---
+
+## Summary of effects:
+
+- **Custom `malloc`/`realloc`/`free`**: replaces allocation behavior globally (mruby + all other code and third‑party libraries).
+
+- **Custom `mrb_basic_alloc_func()`**: replaces allocation behavior only for mruby’s internal use, leaving other libraries’ allocations untouched.
+
+## Migration note
+
+If you are moving from the old API:
+
+1. **Removal of `mrb_open_allocf()`**
+   - \_Old:
+
+     ```c
+     mrb_state *mrb = mrb_open_allocf(my_allocf, ud);
+     ```
+
+   - \_New:
+
+     ```c
+     // No allocf parameter; set up your hook via mrb_basic_alloc_func definition.
+     mrb_state *mrb = mrb_open_core();
+     ```
+
+2. **`mrb_open_core()` takes no arguments**
+   - Simply drop any allocf or user-data arguments, and redefine `mrb_basic_alloc_func` as you need.
+
+3. **No more `mrb_allocf` type**
+   - Definitions using the `mrb_allocf` typedef can be removed; implement `mrb_basic_alloc_func()` with the signature below:
+
+     ```c
+     void* mrb_basic_alloc_func(void *ptr, size_t size);
+     ```
+
+4. **`mrb_basic_alloc_func` signature change**
+   - _Old:_
+
+     ```c
+     void* mrb_default_allocf(mrb_state *mrb, void *ptr, size_t size, void *ud);
+     ```
+
+   - _New:_
+
+     ```c
+     void* mrb_basic_alloc_func(void *ptr, size_t size);
+     ```
+
+---
+
+### Code examples
+
+- **Old style**:
+
+  ```c
+  static void*
+  my_allocf(mrb_state *mrb, void *ud, void *ptr, size_t size)
+  {
+    // ...custom logic...
+  }
+
+  mrb_state *mrb = mrb_open_allocf(my_allocf, some_ud);
+  ```
+
+- **New style**:
+
+  ```c
+  // Define your hook before creating the state:
+  void*
+  mrb_basic_alloc_func(void *ptr, size_t size)
+  {
+    // ...custom logic...
+  }
+
+  mrb_state *mrb = mrb_open_core();
+  ```
+
+---
+
+## 3. Heap Regions: Contiguous Memory for GC
+
+By default, mruby allocates GC heap pages individually via `malloc()`.
+On embedded targets with multiple memory banks (e.g., STM32 CCM+SRAM,
+ESP32 PSRAM+IRAM), you may want to place heap pages in a specific
+memory region. `mrb_gc_add_region()` lets you provide a contiguous
+buffer that mruby carves into heap pages.
+
+### API
+
+```c
+#include <mruby/gc.h>
+
+int mrb_gc_add_region(mrb_state *mrb, void *start, size_t size);
+```
+
+- **`start`**: pointer to a contiguous memory buffer.
+- **`size`**: size of the buffer in bytes.
+- **Returns**: number of heap pages carved from the buffer, or 0 if
+  the buffer is too small.
+
+The buffer is aligned internally to pointer size. Each page is
+approximately 40 KB on 64-bit systems (24 KB on 32-bit). The caller
+retains ownership of the buffer and must keep it valid for the
+lifetime of the `mrb_state`.
+
+### Example: Static buffer
+
+```c
+#include <mruby.h>
+#include <mruby/gc.h>
+
+/* 256 KB static buffer -- about 6 pages on 64-bit */
+static char heap_buf[256 * 1024];
+
+int main(void)
+{
+  mrb_state *mrb = mrb_open();
+  int pages = mrb_gc_add_region(mrb, heap_buf, sizeof(heap_buf));
+  /* pages are immediately available for object allocation */
+
+  /* ... use mrb ... */
+
+  mrb_close(mrb);  /* region pages are cleaned up; buffer is not freed */
+  return 0;
+}
+```
+
+### Example: MCU with multiple RAM banks
+
+```c
+/* STM32 with 64 KB CCM and 128 KB SRAM */
+extern char __ccm_start[], __ccm_end[];   /* linker symbols */
+extern char __sram_start[], __sram_end[];
+
+mrb_state *mrb = mrb_open();
+mrb_gc_add_region(mrb, __ccm_start, __ccm_end - __ccm_start);
+mrb_gc_add_region(mrb, __sram_start, __sram_end - __sram_start);
+```
+
+### How it works
+
+When `mrb_gc_add_region()` is called, mruby:
+
+1. Aligns the buffer start to pointer size.
+2. Divides the buffer into `mrb_heap_page`-sized chunks.
+3. Initializes each page's freelist and links it into the GC heap.
+4. Records the region in a descriptor for O(1) pointer-to-page mapping.
+
+Region pages participate in the normal GC cycle (mark-and-sweep) like
+any other heap page. The only differences are:
+
+- **Never freed**: the GC will not call `free()` on region pages, even
+  if all objects on a page are dead. The page stays in the heap with an
+  empty freelist, ready for reuse.
+- **Fallback**: when all region pages are full, mruby falls back to
+  `malloc()` for new pages as usual.
+- **Cleanup**: `mrb_close()` frees the internal region descriptor but
+  does not free the buffer itself.
+
+### Sizing
+
+The page size is controlled by `MRB_HEAP_PAGE_SIZE` (default: 1024 slots).
+Each page occupies:
+
+| Platform | Slot size | Page size (approx) |
+| -------- | --------- | ------------------ |
+| 64-bit   | 40 bytes  | ~41 KB             |
+| 32-bit   | 24 bytes  | ~25 KB             |
+
+To estimate pages for a given buffer: `pages = buffer_size / sizeof(mrb_heap_page)`.
+Each page provides `MRB_HEAP_PAGE_SIZE` object slots.

doc/guides/mrbconf.md

@@ -1,3 +1,5 @@
+<!-- summary: About Build-time Configurations -->
+
 # mruby configuration macros
 
 ## The configuration file
@@ -18,14 +20,14 @@ This is the same for `MRuby::CrossBuild`.
 # build_config.rb
 
 MRuby::Build.new do |conf|
-  .....
+  ...
   conf.defines << 'MRB_GC_FIXED_ARENA'
   conf.defines << 'MRB_NO_METHOD_CACHE'
-  .....
+  ...
 end
 ```
 
-***NOTE***
+**_NOTE_**
 
 - Use common definitions (`conf.defines`) instead of per-compiler definitions (e.g., `conf.cc.defines`) unless there is a special reason not to.
 - It is now deprecated to edit the `include/mruby/mrbconf.h` file or give it directly as a compiler flag, as was the case before.
@@ -59,12 +61,12 @@ end
 `MRB_STACK_EXTEND_DOUBLING`
 
 - If defined doubles the stack size when extending it.
-- Otherwise extends stack with `MRB_STACK_GROWTH`.
+- Otherwise extends stack with 1.5x growth (minimum `MRB_STACK_GROWTH`).
 
 `MRB_STACK_GROWTH`
 
 - Default value is `128`.
-- Used in stack extending.
+- Minimum stack growth size when extending.
 - Ignored when `MRB_STACK_EXTEND_DOUBLING` is defined.
 
 `MRB_STACK_MAX`
@@ -93,6 +95,7 @@ end
 
 - When defined, or `MRB_INT32` are not defined on 64-bit CPU mode, `mrb_int` will be defined as `int64_t`.
 - Conflicts with `MRB_INT32`.
+- On 32-bit platforms, `MRB_INT64` requires `MRB_NO_BOXING` because heap-allocated `RInteger` needs 8-byte alignment that the GC heap may not guarantee with word or NaN boxing.
 
 ## Garbage collector configuration
 
@@ -105,7 +108,7 @@ end
 
 `MRB_GC_TURN_OFF_GENERATIONAL`
 
-- When defined turns generational GC by default.
+- When defined turns generational GC off by default.
 
 `MRB_GC_FIXED_ARENA`
 
@@ -121,13 +124,8 @@ end
 
 `MRB_HEAP_PAGE_SIZE`
 
-- Defines value is `1024`.
+- Default value is `1024`.
 - Specifies number of `RBasic` per each heap page.
-- To calculate the number of bytes per heap page, it is "(size of management data per heap page) + (size per object) * `MRB_HEAP_PAGE_SIZE`".
-  In mruby 3.1.0, the "size of management data per heap page" is 6 words, also "size per object" is 6 words.
-  For a 32-bit CPU, `(6 * 4) + (6 * 4) * MRB_HEAP_PAGE_SIZE` gives the bytes of size per heap page.
-  Conversely, for example, to keep the size per heap page to 4 Ki bytes,
-  calculate `(4096 - (6 * 4)) / (6 * 4)` to specify `MRB_HEAP_PAGE_SIZE=169`.
 
 ## Memory pool configuration
 
@@ -135,7 +133,7 @@ end
 
 - Default value is `4`.
 - If you're allocating data types that requires alignment more than default value define the
-largest value of required alignment.
+  largest value of required alignment.
 
 `POOL_PAGE_SIZE`
 
@@ -149,7 +147,7 @@ largest value of required alignment.
 
 - If defined enables fixed size `mrb_state` atexit stack.
 - Raises `RuntimeError` when `mrb_state_atexit` call count to same `mrb_state` exceeds
-`MRB_FIXED_STATE_ATEXIT_STACK_SIZE`'s value.
+  `MRB_FIXED_STATE_ATEXIT_STACK_SIZE`'s value.
 
 `MRB_FIXED_STATE_ATEXIT_STACK_SIZE`
 
@@ -171,8 +169,24 @@ largest value of required alignment.
 
 `MRB_WORD_BOXING`
 
-- If defined represent `mrb_value` as a word.
-- If defined `Float` will be a mruby object with `RBasic`.
+- If defined represent `mrb_value` as a word (natural unit of data for the processor).
+- Default boxing mode when none is specified.
+- On 64-bit platforms, floats are inlined using rotation encoding.
+- On 32-bit platforms, floats are heap-allocated as `RFloat` objects.
+
+`MRB_NO_BOXING`
+
+- If defined represent `mrb_value` as a C struct (occupies 2 words).
+- Most portable but least memory-efficient representation.
+- Required for `MRB_INT64` on 32-bit platforms.
+- Default for `host-debug` configuration.
+
+`MRB_WORDBOX_NO_INLINE_FLOAT`
+
+- If defined disables inline float values in word boxing.
+- All floats are heap-allocated as `RFloat` objects.
+- Automatically defined on 32-bit platforms (64-bit `double` cannot fit in a 32-bit word).
+- Only meaningful with `MRB_WORD_BOXING`.
 
 ## Reduce heap memory configuration
 
@@ -180,7 +194,7 @@ largest value of required alignment.
 
 - Use `etext` and `edata` section addresses defined by the linker to detect read-only data.
 - Those addresses are widely available, but not portable, nor standardized.
-- This macro is defined by default on User-mode Linux.
+- Defined by default on User-mode Linux.
 
 `MRB_NO_DEFAULT_RO_DATA_P`
 
@@ -188,16 +202,15 @@ largest value of required alignment.
 
 `MRB_USE_CUSTOM_RO_DATA_P`
 
-- Please try if `MRB_USE_LINK_TIME_RO_DATA_P` is not available.
-- The `mrb_ro_data_p()` function is implemented by the user in an arbitrary file.
+- Define to provide your own `mrb_ro_data_p()` implementation.
 - The prototype declaration is `mrb_bool mrb_ro_data_p(const char *ptr)`.
 - Return `TRUE` if `ptr` is in the read-only section, otherwise return `FALSE`.
 
 ## Other configuration
 
-`MRB_MALLOC_TRIM`
+`MRB_USE_MALLOC_TRIM`
 
-- call malloc_trim(0) for each mrb_full_gc() call
+- Call `malloc_trim(0)` for each `mrb_full_gc()` call.
 
 `MRB_UTF8_STRING`
 
@@ -206,13 +219,13 @@ largest value of required alignment.
 
 `MRB_STR_LENGTH_MAX`
 
-- The maximum length of strings (default 1MB)
-- set this value to zero to skip the check
+- The maximum length of strings (default 1048576).
+- Set this value to zero to skip the check.
 
 `MRB_ARY_LENGTH_MAX`
 
-- The maximum length of strings (default 1MB)
-- set this value to zero to skip the check
+- The maximum length of arrays (default 131072).
+- Set this value to zero to skip the check.
 
 `MRB_FUNCALL_ARGC_MAX`
 
@@ -220,10 +233,10 @@ largest value of required alignment.
 - Specifies 4th argument(`argc`) max value of `mrb_funcall`.
 - Raises `ArgumentError` when the `argc` argument is bigger then this value `mrb_funcall`.
 
-`KHASH_DEFAULT_SIZE`
+`KHASH_INITIAL_SIZE`
 
 - Default value is `32`.
-- Specifies default size of khash table bucket.
+- Specifies initial size of khash table bucket.
 - Used in `kh_init_ ## name` function.
 
 `MRB_NO_METHOD_CACHE`
@@ -236,17 +249,44 @@ largest value of required alignment.
 - Ignored if `MRB_NO_METHOD_CACHE` is defined.
 - Need to be the power of 2.
 
-`MRB_USE_METHOD_T_STRUCT`
-
-- Use C struct to represent `mrb_method_t`
-- No `MRB_USE_METHOD_T_STRUCT` requires highest 2 bits of function pointers to be zero
-- Define this macro on machines that use higher bits of pointers
-
 `MRB_USE_ALL_SYMBOLS`
 
 - Make it available `Symbol.all_symbols` in `mrbgems/mruby-symbol-ext`
 - Increase heap memory usage.
 
-`MRB_NO_DIRECT_THREADING`
+`MRB_USE_VM_SWITCH_DISPATCH`
 
-- Turn off direct threading optimization in VM loop
+- Turn on switch dispatch in VM loop.
+- Otherwise, computed goto (direct threading) is used when supported by the compiler.
+
+`MRB_SYMBOL_LINEAR_THRESHOLD`
+
+- Default value is `256`.
+- Threshold for switching symbol table from linear search to hash table.
+
+## Tuning profiles
+
+Predefined profiles adjust several macros together for specific
+deployment targets. Define one of the following:
+
+`MRB_CONSTRAINED_BASELINE_PROFILE`
+
+- For micro controllers.
+- Enables `MRB_NO_METHOD_CACHE`, reduces `KHASH_INITIAL_SIZE` to `16`,
+  and `MRB_HEAP_PAGE_SIZE` to `256`.
+
+`MRB_BASELINE_PROFILE`
+
+- Default mruby profile. No additional changes.
+
+`MRB_MAIN_PROFILE`
+
+- For desktop computers or workstations.
+- Increases `MRB_METHOD_CACHE_SIZE` to `1024` and `MRB_HEAP_PAGE_SIZE`
+  to `4096`.
+
+`MRB_HIGH_PROFILE`
+
+- For long-lived server processes.
+- Increases `MRB_METHOD_CACHE_SIZE` to `4096` and `MRB_HEAP_PAGE_SIZE`
+  to `4096`.

doc/guides/mrbgems.md

@@ -1,6 +1,8 @@
+<!-- summary: About the Build-time Library Manager -->
+
 # mrbgems
 
-mrbgems is a library manager to integrate C and Ruby extension in an easy and
+mrbgems is a library manager to integrate C and Ruby extensions in an easy and
 standardised way into mruby. Conventionally, each mrbgem name is prefixed by
 `mruby-`, e.g. `mruby-time` for a gem that provides `Time` class functionality.
 
@@ -92,6 +94,21 @@ end
 However, it should be used with caution, as it may deviate from the intent
 of the gem's author.
 
+### Gem Testing
+
+If you enable unit tests in your build with `enable_test`, tests will be
+generated for all gems and their dependencies by default. If necessary, it is
+possible to suppress tests for a specific gem like so:
+
+```ruby
+conf.gem 'mruby-noisygem' do |g|
+  g.skip_test = true
+end
+```
+
+However, it is considered best practice to leave all tests enabled whenever
+possible. A warning message will be generated for each gem with disabled tests.
+
 ## GemBox
 
 There are instances when you wish to add a collection of mrbgems into mruby at
@@ -160,9 +177,9 @@ The maximal GEM structure looks like this:
     +- test/            <- Test code (Ruby)
 ```
 
-The folder `mrblib` contains pure Ruby files to extend mruby. The folder `src`
-contains C/C++ files to extend mruby. The folder `include` contains C/C++ header
-files. The folder `test` contains C/C++ and pure Ruby files for testing purposes
+The `mrblib` directory contains pure Ruby files to extend mruby. The `src` directory
+contains C/C++ files to extend mruby. The `include` directory contains C/C++ header
+files. The `test` directory contains C/C++ and pure Ruby files for testing purposes
 which will be used by `mrbtest`. `mrbgem.rake` contains the specification
 to compile C and Ruby files. `README.md` is a short description of your GEM.
 
@@ -233,13 +250,13 @@ Version requirement supports following operators:
 - '<=': is equal or lesser
 - '~>': is equal or greater and is lesser than the next major version
   - example 1: '~> 2.2.2' means '>= 2.2.2' and '< 2.3.0'
-  - example 2: '~> 2.2'   means '>= 2.2.0' and '< 3.0.0'
+  - example 2: '~> 2.2' means '>= 2.2.0' and '< 3.0.0'
 
 When more than one version requirements is passed, the dependency must satisfy all of it.
 
 You can have default gem to use as dependency when it's not defined in your build configuration.
 When the last argument of `add_dependency` call is `Hash`, it will be treated as default gem information.
-Its format is same as argument of method `MRuby::Build#gem`, expect that it can't be treated as path gem location.
+Its format is same as argument of method `MRuby::Build#gem`, except that it can't be treated as path gem location.
 
 When a special version of dependency is required,
 use `MRuby::Build#gem` in the build configuration to override default gem.
@@ -287,12 +304,34 @@ Your GEM can export include paths to another GEMs that depends on your GEM.
 By default, `/...absolute path.../{GEM_NAME}/include` will be exported.
 So it is recommended not to put GEM's local header files on include/.
 
-These exports are retroactive.
+These exports are transitive.
 For example: when B depends on C and A depends on B, A will get include paths exported by C.
 
-Exported include_paths are automatically appended to GEM local include_paths by rake.
+Exported `include_paths` are automatically appended to GEM local `include_paths` by rake.
 You can use `spec.export_include_paths` accessor if you want more complex build.
 
+### Settings for GEM build commands/tasks
+
+When the block argument passed to `MRuby::Gem::Specification.new` is executed,
+the GEM build commands/tasks for the `MRuby::Build` instance may not yet be finalized.
+In most cases, modifying the GEM build commands/tasks within the block passed to
+`MRuby::Gem::Specification.new` is not a problem.
+
+However, you may need to perform GEM build commands/tasks after the GEM build
+commands/tasks for the `MRuby::Build` instance have been finalized.
+In such cases, you can achieve this by passing a block argument to
+`MRuby::Gem::Specification#build_settings` within the block passed to
+`MRuby::Gem::Specification.new`.
+
+```ruby
+spec.build_settings do
+  spec.cc.flags << "-any_flags"
+end
+```
+
+**NOTE**: Using the `build_settings` method will cause GEM's all build command settings
+directly written in the block passed to `MRuby::Gem::Specification.new` to be ignored.
+
 ## C Extension
 
 mruby can be extended with C. This is possible by using the C API to
@@ -349,9 +388,9 @@ mrb_c_extension_example_gem_final(mrb_state* mrb) {
 
 mruby can be extended with pure Ruby. It is possible to override existing
 classes or add new ones in this way. Put all Ruby files into the `mrblib`
-folder.
+directory.
 
-### Pre-Conditions
+### Preconditions
 
 none
 
@@ -377,13 +416,13 @@ none
 
 mruby can be extended with C and Ruby at the same time. It is possible to
 override existing classes or add new ones in this way. Put all Ruby files
-into the `mrblib` folder and all C files into the `src` folder.
+into the `mrblib` directory and all C files into the `src` directory.
 
 mruby codes under `mrblib` directory would be executed after gem init C
-function is called. Make sure *mruby script* depends on *C code* and
-*C code* doesn't depend on *mruby script*.
+function is called. Make sure _mruby script_ depends on _C code_ and
+_C code_ doesn't depend on _mruby script_.
 
-### Pre-Conditions
+### Preconditions
 
 See C and Ruby example.
 

doc/guides/rom-method-table.md

@@ -0,0 +1,413 @@
+<!-- summary: ROM Method Tables for Memory-Efficient Method Registration -->
+
+# ROM Method Tables
+
+ROM method tables allow C methods to be registered using static data
+stored in ROM (read-only memory) rather than heap-allocated RAM. This
+saves significant memory on embedded systems where RAM is scarce.
+
+## Motivation
+
+In a default mruby build, `mrb_open()` builds ~40 classes with ~700+
+method entries at startup. Each method entry is heap-allocated via
+individual `mrb_define_method_id()` calls. On a constrained MCU, this
+consumes ~14KB of RAM for method table metadata alone.
+
+ROM method tables eliminate this cost by placing method metadata in
+static `const` data at compile time. Only runtime mutations (e.g.,
+reopening a class to add methods) trigger heap allocation.
+
+## Architecture
+
+### Chained Layers
+
+Each class has a method table (`mt`) pointer to a linked list of
+`mrb_mt_tbl` layers:
+
+```
+String.mt -> [mutable layer] -> [string_ext ROM] -> [string_core ROM] -> NULL
+```
+
+**Lookup** walks the chain front-to-back, returning the first match.
+The method cache makes repeated lookups O(1), so the chain walk
+only occurs on cache misses.
+
+**Mutation** uses copy-on-write (COW): if the top layer is read-only,
+a new mutable layer is created in front of it. The ROM data is never
+modified.
+
+```
+Before: String.mt -> [string_ext ROM] -> [string_core ROM] -> NULL
+
+After String.define_method(:foo):
+         String.mt -> [mutable: foo] -> [string_ext ROM] -> [string_core ROM] -> NULL
+```
+
+### Memory Layout
+
+Each `mrb_mt_tbl` stores method entries as an array of `mrb_mt_entry`
+structs, each combining a function pointer, a symbol key, and flags:
+
+```
+ptr -> [ entry[0] | entry[1] | ... | entry[N-1] ]
+       |<-- mrb_mt_entry: { val, key, flags } -->|
+```
+
+Values are `union mrb_mt_ptr` (function pointer or proc pointer). Keys
+are pure `mrb_sym` (no flag encoding). Flags are a separate `uint32_t`
+field that stores visibility, func/proc type, and argument spec.
+
+Entries are searched linearly, so source code order does not matter.
+The method cache makes repeated lookups O(1), so the linear scan
+only occurs on cache misses.
+
+### Per-State Wrappers
+
+The `const mrb_mt_entry[]` arrays are truly static and shared across
+the process. However, the `mrb_mt_tbl` wrapper (which carries the
+`next` pointer for chaining) is heap-allocated per `mrb_state` by
+`MRB_MT_INIT_ROM()`. This allows multiple `mrb_state` instances in
+the same process to each have independent method table chains, even
+when linking to the same const entries.
+
+## How to Define a ROM Method Table
+
+### Step 1: Define the Static Data
+
+Include `<mruby/class.h>` (which provides `mrb_mt_entry`,
+`MRB_MT_ENTRY()`, and flag constants) and define the ROM entries:
+
+```c
+#include <mruby/class.h>
+
+static const mrb_mt_entry my_rom_entries[] = {
+  MRB_MT_ENTRY(my_method_a,  MRB_SYM(method_a), MRB_ARGS_REQ(1)),
+  MRB_MT_ENTRY(my_method_b,  MRB_SYM(method_b), MRB_ARGS_NONE()),
+  MRB_MT_ENTRY(my_method_eq, MRB_OPSYM(eq),     MRB_ARGS_REQ(1)),
+};
+```
+
+### Step 2: Register in the Init Function
+
+Replace `mrb_define_method_id()` calls with a single
+`MRB_MT_INIT_ROM()` call:
+
+```c
+void
+mrb_mruby_mygem_gem_init(mrb_state *mrb)
+{
+  struct RClass *c = mrb_define_class_id(mrb, MRB_SYM(MyClass), mrb->object_class);
+  MRB_MT_INIT_ROM(mrb, c, my_rom_entries);
+}
+```
+
+`MRB_MT_INIT_ROM()` allocates a per-state wrapper and pushes the ROM
+layer onto the class's method table chain.
+
+### Step 3: Verify
+
+Build and run the test suite. ROM tables are semantically transparent
+to Ruby code.
+
+## Reference
+
+### Data Types
+
+Defined in `include/mruby/class.h`:
+
+```c
+union mrb_mt_ptr {
+  const struct RProc *proc;
+  mrb_func_t func;
+};
+
+typedef struct mrb_mt_entry {
+  union mrb_mt_ptr val;
+  mrb_sym key;              /* pure symbol ID (no flags packed) */
+  uint32_t flags;           /* method flags + aspec */
+} mrb_mt_entry;
+
+typedef struct mrb_mt_tbl {
+  int             size;
+  int             alloc;       /* bit 30: MRB_MT_READONLY_BIT */
+  mrb_mt_entry   *ptr;
+  struct mrb_mt_tbl  *next;    /* next (lower-priority) layer, or NULL */
+} mrb_mt_tbl;
+```
+
+### Macros
+
+```c
+/* ROM table entry: 3rd param is MRB_ARGS_*() optionally OR'd with
+   MRB_MT_PRIVATE.  The macro OR's in MRB_MT_FUNC automatically. */
+#define MRB_MT_ENTRY(fn, sym, flags) \
+  { { .func = (fn) }, (sym), (flags) | MRB_MT_FUNC }
+
+/* Extract aspec from combined flags */
+#define MRB_MT_ASPEC(flags) ((mrb_aspec)((flags) & 0xffffff))
+
+/* Allocate a per-state ROM wrapper and push onto class method chain */
+#define MRB_MT_INIT_ROM(mrb, cls, entries) \
+  mrb_mt_init_rom(mrb, cls, entries, \
+                  (int)(sizeof(entries)/sizeof(entries[0])))
+```
+
+### Flags
+
+| Flag             | Value   | Description                         |
+| ---------------- | ------- | ----------------------------------- |
+| `MRB_MT_FUNC`    | (1<<24) | C function (auto-set by macro)      |
+| `MRB_MT_PUBLIC`  | 0       | Public visibility (default)         |
+| `MRB_MT_PRIVATE` | (1<<25) | Private visibility (in entry param) |
+
+The third parameter to `MRB_MT_ENTRY()` is an `MRB_ARGS_*()`
+expression optionally OR'd with `MRB_MT_PRIVATE`. The aspec value
+occupies bits 0-23 and the visibility flag occupies bit 25; these
+ranges do not overlap, so the values are simply OR'd together.
+`MRB_MT_FUNC` is set automatically. The no-arg optimization is
+derived at runtime from `aspec == 0` (`MRB_ARGS_NONE()`).
+
+**How to write entries:**
+
+- **`MRB_MT_ENTRY(fn, sym, MRB_ARGS_*(...))`**: Public method.
+- **`MRB_MT_ENTRY(fn, sym, MRB_ARGS_*(...) | MRB_MT_PRIVATE)`**:
+  Private method.
+- Use the same `MRB_ARGS_*()` macros as `mrb_define_method_id()`.
+
+### Symbol Macros
+
+Use the presym macros for keys. See `doc/guides/symbol.md` for the
+full list:
+
+```c
+MRB_SYM(size)       /* size */
+MRB_SYM_B(chomp)    /* chomp! */
+MRB_SYM_Q(frozen)   /* frozen? */
+MRB_SYM_E(name)     /* name= */
+MRB_OPSYM(add)      /* + */
+MRB_OPSYM(eq)       /* == */
+MRB_OPSYM(aref)     /* [] */
+MRB_OPSYM(aset)     /* []= */
+MRB_OPSYM(cmp)      /* <=> */
+MRB_IVSYM(name)     /* @name */
+```
+
+### API
+
+```c
+void mrb_mt_init_rom(mrb_state *mrb, struct RClass *c,
+                     const mrb_mt_entry *entries, int size);
+```
+
+Allocates a per-state `mrb_mt_tbl` wrapper for the const entries and
+pushes it onto the class's method table chain. The wrapper is tracked
+in `mrb->rom_mt` and freed at `mrb_close()`. Use the `MRB_MT_INIT_ROM`
+macro to auto-compute the size. Multiple calls push additional layers,
+which is how extension gems add methods to core classes.
+
+## Entry Correspondence
+
+Each `MRB_MT_ENTRY()` bundles a function pointer with its method name
+and flags in a single line. Their order in the source code does not
+matter, but keeping related methods
+together improves readability.
+
+**Method aliases** (two names for the same function) are expressed as
+separate entries sharing the same function pointer:
+
+```c
+static const mrb_mt_entry str_rom_entries[] = {
+  MRB_MT_ENTRY(mrb_str_size, MRB_SYM(size),   MRB_ARGS_NONE()),
+  MRB_MT_ENTRY(mrb_str_size, MRB_SYM(length), MRB_ARGS_NONE()),
+};
+```
+
+## Conditional Methods
+
+Methods that depend on build configuration (e.g., `MRB_NO_FLOAT`) can
+use `#ifdef` directly inside the ROM entries array. The `sizeof` in
+`MRB_MT_INIT_ROM()` automatically adjusts to the number of entries
+that survive preprocessing:
+
+```c
+static const mrb_mt_entry integer_rom_entries[] = {
+  MRB_MT_ENTRY(int_to_s, MRB_SYM(to_s), MRB_ARGS_OPT(1)),
+  MRB_MT_ENTRY(int_add,  MRB_OPSYM(add), MRB_ARGS_REQ(1)),
+#ifndef MRB_NO_FLOAT
+  MRB_MT_ENTRY(int_to_f, MRB_SYM(to_f), MRB_ARGS_NONE()),
+#endif
+};
+```
+
+For conditional methods on a **different class**, use a separate ROM
+table wrapped in the `#ifdef`:
+
+```c
+#ifndef MRB_NO_FLOAT
+static const mrb_mt_entry float_rom_entries[] = { ... };
+#endif
+
+void mrb_init_numeric(mrb_state *mrb) {
+  MRB_MT_INIT_ROM(mrb, integer, integer_rom_entries);
+#ifndef MRB_NO_FLOAT
+  MRB_MT_INIT_ROM(mrb, fl, float_rom_entries);
+#endif
+}
+```
+
+## Extension Gems
+
+Extension gems use exactly the same pattern. Since gems are
+initialized after core, calling `MRB_MT_INIT_ROM()` pushes the gem's
+ROM layer in front of the core ROM layer:
+
+```c
+/* mrbgems/mruby-string-ext/src/string.c */
+
+static const mrb_mt_entry string_ext_rom_entries[] = { ... };
+
+void mrb_mruby_string_ext_gem_init(mrb_state *mrb)
+{
+  struct RClass *s = mrb->string_class;
+  MRB_MT_INIT_ROM(mrb, s, string_ext_rom_entries);
+}
+```
+
+After initialization, String's method table chain looks like:
+
+```
+String.mt -> [string_ext ROM, 53 methods]
+          -> [string_core ROM, 46 methods]
+          -> NULL
+```
+
+A gem may also define ROM tables for multiple classes:
+
+```c
+void mrb_mruby_mygem_gem_init(mrb_state *mrb)
+{
+  MRB_MT_INIT_ROM(mrb, mrb->string_class, string_mygem_rom_entries);
+  MRB_MT_INIT_ROM(mrb, mrb->integer_class, integer_mygem_rom_entries);
+}
+```
+
+## Methods That Cannot Use ROM Tables
+
+Some methods must remain as `mrb_define_method_id()` calls:
+
+- **Class methods** (`mrb_define_class_method_id()`): ROM tables
+  register instance methods only.
+- **Module functions** (`mrb_define_module_function_id()`): Same
+  reason.
+- **Methods requiring `mrb_state*` at definition time**: For example,
+  methods that create frozen RProc objects during init.
+- **Methods on dynamically created classes**: Classes created at
+  init time (not stored in `mrb->xxx_class`) that require
+  `mrb_define_class()` to obtain the class pointer.
+- **Cross-class methods** (methods on a class the gem does not own):
+  Each ROM table adds a 16-byte `mrb_mt_tbl` layer to the target
+  class's chain. For 1-2 methods, this overhead exceeds the savings.
+  Use `mrb_define_method_id()` instead -- cross-class methods share
+  the target class's existing mutable layer.
+
+These methods are added after `MRB_MT_INIT_ROM()` and go into the
+mutable layer that sits in front of the ROM chain.
+
+## Runtime Behavior
+
+### Open Classes (COW)
+
+Ruby's open classes work transparently. When a Ruby program or C code
+adds a method to a class with a ROM table, the COW mechanism creates a
+mutable layer:
+
+```ruby
+class String
+  def my_custom_method
+    42
+  end
+end
+"hello".my_custom_method  #=> 42
+"hello".size              #=> 5 (still found in ROM layer)
+```
+
+### Method Removal
+
+`remove_method` works on ROM methods using a tombstone marker. When a
+method in a ROM layer is removed, a special entry (`MRB_MT_FUNC` flag with
+`func=NULL`) is inserted into the mutable layer. The `mt_get()` lookup
+treats this marker as "not found" and stops searching the chain,
+effectively hiding the ROM entry. Unlike `undef_method` (which blocks
+superclass lookup), `remove_method`'s tombstone allows the superclass
+method to be found.
+
+`undef_method` uses a different tombstone (`proc=NULL` without
+`MRB_MT_FUNC`), which is returned by `mt_get()` so the caller raises
+NoMethodError without searching the superclass.
+
+### Class Duplication
+
+`Class.dup` shares the ROM chain. The duplicated class gets an empty
+mutable layer pointing to the same ROM layers as the original. No ROM
+data is copied.
+
+### Garbage Collection
+
+ROM layers are skipped during GC mark and sweep phases. Only mutable
+layers are scanned for live RProc references and freed when the class
+is collected. ROM wrappers are freed at `mrb_close()` via the
+`mrb->rom_mt` tracking list.
+
+### Memory Measurement
+
+`mrb_class_mt_memsize()` reports only mutable layer memory. ROM
+wrappers are tracked separately and not counted per-class.
+
+## Converting Existing Code
+
+To convert existing `mrb_define_method_id()` calls to a ROM table:
+
+1. **Count** the number of method definitions that can be converted.
+
+2. **Create** the ROM entries array using `MRB_MT_ENTRY()`.
+
+3. **Move** each `mrb_define_method_id()` call into the entries:
+   - `MRB_MT_ENTRY(func, sym, aspec)` where:
+     - `func` is the function pointer
+     - `sym` is the symbol macro (e.g., `MRB_SYM(name)`)
+     - `aspec` is the original `MRB_ARGS_*()` macro
+   - For private methods, OR `MRB_MT_PRIVATE` into the aspec:
+     `MRB_MT_ENTRY(func, sym, aspec | MRB_MT_PRIVATE)`
+
+4. **Replace** the calls with `MRB_MT_INIT_ROM(mrb, c, entries)`.
+
+5. **Keep** any methods that cannot be converted (see above) as
+   individual `mrb_define_method_id()` calls after the ROM init.
+
+6. **Build and test**: `rake CONFIG=host-debug -j24 all test:run:serial`
+
+### Before
+
+```c
+void mrb_mruby_foo_gem_init(mrb_state *mrb) {
+  struct RClass *foo = mrb_define_class_id(mrb, MRB_SYM(Foo), mrb->object_class);
+  mrb_define_method_id(mrb, foo, MRB_SYM(bar), foo_bar, MRB_ARGS_REQ(1));
+  mrb_define_method_id(mrb, foo, MRB_SYM(baz), foo_baz, MRB_ARGS_NONE());
+  mrb_define_method_id(mrb, foo, MRB_OPSYM(eq), foo_eq,  MRB_ARGS_REQ(1));
+}
+```
+
+### After
+
+```c
+static const mrb_mt_entry foo_rom_entries[] = {
+  MRB_MT_ENTRY(foo_bar, MRB_SYM(bar),  MRB_ARGS_REQ(1)),
+  MRB_MT_ENTRY(foo_baz, MRB_SYM(baz),  MRB_ARGS_NONE()),
+  MRB_MT_ENTRY(foo_eq,  MRB_OPSYM(eq), MRB_ARGS_REQ(1)),
+};
+
+void mrb_mruby_foo_gem_init(mrb_state *mrb) {
+  struct RClass *foo = mrb_define_class_id(mrb, MRB_SYM(Foo), mrb->object_class);
+  MRB_MT_INIT_ROM(mrb, foo, foo_rom_entries);
+}
+```

doc/guides/symbol.md

@@ -1,3 +1,5 @@
+<!-- summary: About the Symbols -->
+
 # Symbols
 
 Symbols in `mruby` C source code is represented by `mrb_sym` which is alias of
@@ -57,27 +59,21 @@ To save RAM, `mruby` can use compile-time allocation of some symbols. You can
 use following macros to get preallocated symbols by including `mruby/presym.h`
 header.
 
-- `MRB_SYM(xor)`    //=> xor    (Word characters)
-- `MRB_SYM_B(xor)`  //=> xor!   (Method with Bang)
-- `MRB_SYM_Q(xor)`  //=> xor?   (Method with Question mark)
-- `MRB_SYM_E(xor)`  //=> xor=   (Method with Equal)
-- `MRB_CVSYM(xor)`  //=> @@xor  (Class Variable)
-- `MRB_IVSYM(xor)`  //=> @xor   (Instance Variable)
-- `MRB_OPSYM(xor)`  //=> ^      (Operator)
+- `MRB_SYM(xor)` //=> xor (Word characters)
+- `MRB_SYM_B(xor)` //=> xor! (Method with Bang)
+- `MRB_SYM_Q(xor)` //=> xor? (Method with Question mark)
+- `MRB_SYM_E(xor)` //=> xor= (Method with Equal)
+- `MRB_GVSYM(xor)` //=> $xor (Global Variable)
+- `MRB_CVSYM(xor)` //=> @@xor (Class Variable)
+- `MRB_IVSYM(xor)` //=> @xor (Instance Variable)
+- `MRB_OPSYM(xor)` //=> ^ (Operator)
 
 For `MRB_OPSYM()`, specify the names corresponding to operators (see
 `MRuby::Presym::OPERATORS` in `lib/mruby/presym.rb` for the names that
 can be specified for it). Other than that, describe only word characters
-excluding leading and ending punctuations.
+excluding leading and ending punctuation.
 
-These macros are converted to static symbol IDs at compile time, unless
-preallocate symbols are disabled by `conf.disable_presym`. In that case,
-these macros are expanded to `mrb_intern_lit` calls, therefore the mruby state
-variable is required. The above macros assume the variable name is `mrb`. If
-its name is not `mrb`, you need to use macros with `_2` suffix, such as
-`MRB_SYM_2` to specify `mrb_state*` variable.
-
-### Disabling Preallocated Symbols
-
-You can disable preallocated symbols by specifying `conf.disable_presym` in the
-configuration file.
+These macros are converted to static symbol IDs at compile time.
+The `_2` suffix variants (e.g., `MRB_SYM_2`) are kept for backward
+compatibility only; they accept an explicit `mrb_state*` parameter
+but ignore it. New code should use the standard macros above.

doc/internal/architecture.md

@@ -0,0 +1,182 @@
+<!-- summary: About mruby Architecture -->
+
+# mruby Architecture
+
+This document provides a map of mruby's internals for developers who
+want to understand, debug, or contribute to the codebase.
+
+## Overview
+
+mruby's execution pipeline:
+
+```text
+Ruby source → Parser → AST → Code Generator → Bytecode (irep)
+                                                    ↓
+                                                   VM → Result
+```
+
+The design priority is **memory > performance > readability**.
+
+## Object Model
+
+All heap-allocated Ruby objects share a common header (`MRB_OBJECT_HEADER`):
+
+```text
+struct RBasic (8 bytes on 64-bit)
+┌──────────────┬─────┬──────────┬────────┬───────┐
+│ RClass *c    │ tt  │ gc_color │ frozen │ flags │
+│ (class ptr)  │ 8b  │ 3b       │ 1b     │ 20b   │
+└──────────────┴─────┴──────────┴────────┴───────┘
+```
+
+All object structs embed this header via `MRB_OBJECT_HEADER`:
+
+| Struct       | Ruby Type        | Extra Fields                       |
+| ------------ | ---------------- | ---------------------------------- |
+| `RObject`    | Object instances | `iv` (instance variables)          |
+| `RClass`     | Class/Module     | `iv`, `mt` (method table), `super` |
+| `RString`    | String           | embedded or heap buffer, length    |
+| `RArray`     | Array            | embedded or heap buffer, length    |
+| `RHash`      | Hash             | hash table or k-v array            |
+| `RProc`      | Proc/Lambda      | `irep` or C function, environment  |
+| `RData`      | C data wrapper   | `void *data`, `mrb_data_type`      |
+| `RFiber`     | Fiber            | `mrb_context`                      |
+| `RException` | Exception        | `iv`                               |
+
+Immediate values (Integer, Symbol, `true`, `false`, `nil`) are encoded
+directly in `mrb_value` without heap allocation. The encoding depends on
+the boxing mode (see [boxing.md](boxing.md)).
+
+Objects must fit within 5 words (`mrb_static_assert_object_size`).
+
+## Virtual Machine
+
+The VM is register-based, using two stacks: a **value stack** for
+registers (locals, temporaries, arguments) and a **call info stack**
+for tracking method/block call frames. Each method call pushes a
+`mrb_callinfo` frame with the method symbol, proc, PC, and argument
+counts.
+
+The dispatch loop in `mrb_vm_run()` decodes opcodes and operates on
+registers. Method dispatch looks up the receiver's class method table
+(with a per-state method cache), then either calls a C function
+directly or pushes a new call frame for Ruby methods.
+
+Exception handling uses `setjmp`/`longjmp` (or C++ exceptions if
+configured). Rescue/ensure handler tables are stored in each irep
+and searched during stack unwinding.
+
+See [vm.md](vm.md) for detailed VM internals, [opcode.md](opcode.md)
+for the full instruction set.
+
+## Garbage Collector
+
+The GC uses **tri-color incremental mark-and-sweep** with an optional
+**generational mode**. Objects are colored white (unmarked), gray
+(marked, children pending), black (fully marked), or red (static/ROM).
+
+The three-phase cycle (root scan, incremental marking, sweep) runs
+in small steps between VM instructions to avoid long pauses. Write
+barriers (`mrb_field_write_barrier`, `mrb_write_barrier`) maintain
+correctness during incremental marking.
+
+The GC arena protects newly created objects in C code. Heap regions
+(`mrb_gc_add_region`) support embedded systems with fixed memory banks.
+
+See [gc.md](gc.md) for detailed GC internals,
+[../guides/gc-arena-howto.md](../guides/gc-arena-howto.md) for arena
+usage patterns, [../guides/memory.md](../guides/memory.md) for memory
+management.
+
+## Compiler Pipeline
+
+The compiler transforms Ruby source code through three stages:
+
+1. **Parser** (`parse.y`): Lrama/Bison grammar produces an AST of
+   `mrb_ast_node` structures, tracking lexer state and local scopes.
+2. **Code Generator** (`codegen.c`): walks the AST and emits bytecode
+   into `mrb_irep` structures (instruction sequence, literal pool,
+   symbol table, child ireps).
+3. **Execution**: the irep is wrapped in an `RProc` and executed by
+   the VM, or serialized to `.mrb` binary format.
+
+Alternative loading paths include `mrb_load_string()` (compile and
+run), `mrb_load_irep()` (load precompiled bytecode), and `mrbc`
+(ahead-of-time compilation).
+
+See [compiler.md](compiler.md) for detailed compiler internals,
+[opcode.md](opcode.md) for the instruction set.
+
+## Source File Map
+
+### Core (`src/`)
+
+| File          | Responsibility                                 |
+| ------------- | ---------------------------------------------- |
+| `vm.c`        | Bytecode dispatch loop, method invocation      |
+| `state.c`     | `mrb_state` init/close, irep management        |
+| `gc.c`        | Garbage collector (mark-sweep, incremental)    |
+| `class.c`     | Class/module definition, method tables         |
+| `object.c`    | Core object operations                         |
+| `variable.c`  | Instance/class/global variables, object shapes |
+| `proc.c`      | Proc/Lambda/closure handling                   |
+| `array.c`     | Array implementation                           |
+| `string.c`    | String implementation (embedded, shared, heap) |
+| `hash.c`      | Hash implementation (open addressing)          |
+| `numeric.c`   | Integer/Float arithmetic                       |
+| `symbol.c`    | Symbol table and interning                     |
+| `range.c`     | Range implementation                           |
+| `error.c`     | Exception creation, raise, backtrace           |
+| `kernel.c`    | Kernel module methods                          |
+| `load.c`      | `.mrb` bytecode loading                        |
+| `dump.c`      | Bytecode serialization (write `.mrb`)          |
+| `print.c`     | Print/puts/p output                            |
+| `backtrace.c` | Stack trace generation                         |
+
+### Compiler (`mrbgems/mruby-compiler/core/`)
+
+| File        | Responsibility                  |
+| ----------- | ------------------------------- |
+| `parse.y`   | Yacc grammar → AST              |
+| `y.tab.c`   | Generated parser (from parse.y) |
+| `codegen.c` | AST → bytecode (irep)           |
+| `node.h`    | AST node type definitions       |
+
+### Key Headers (`include/mruby/`)
+
+| Header       | Contents                              |
+| ------------ | ------------------------------------- |
+| `mruby.h`    | `mrb_state`, core API declarations    |
+| `value.h`    | `mrb_value`, type enums, value macros |
+| `object.h`   | `RBasic`, `RObject`, object header    |
+| `class.h`    | `RClass`, method table types          |
+| `string.h`   | `RString`, string macros              |
+| `array.h`    | `RArray`, array macros                |
+| `hash.h`     | `RHash`, hash API                     |
+| `data.h`     | `RData`, C data wrapping              |
+| `irep.h`     | `mrb_irep`, bytecode structures       |
+| `compile.h`  | Compiler context, `mrb_load_string`   |
+| `boxing_*.h` | Value boxing implementations          |
+
+## mrbgems System
+
+Gems are the module system for mruby. Each gem lives in
+`mrbgems/mruby-*/` and contains:
+
+```text
+mruby-example/
+├── mrbgem.rake       gem specification (name, deps, bins)
+├── src/              C source files
+├── mrblib/           Ruby source files (compiled to bytecode)
+├── include/          C headers
+├── test/             mrbtest test files
+└── bintest/          binary test files (CRuby)
+```
+
+At build time, gem Ruby files are compiled with `mrbc` and linked into
+`libmruby.a`. Gem initialization runs in dependency order via
+`gem_init.c` (auto-generated).
+
+GemBoxes (`mrbgems/*.gembox`) define named collections of gems
+(e.g., `default.gembox` includes `stdlib`, `stdlib-ext`, `stdlib-io`,
+`math`, `metaprog`, and binary tools).

doc/internal/boxing.md

@@ -1,3 +1,5 @@
+<!-- summary: About Value Boxing -->
+
 # Boxing
 
 The mruby objects and data are represented by C data type `mrb_value`. There are three options how to pack the data values in the `mrb_value`.
@@ -15,7 +17,7 @@ Some values (called immediate values, e.g. integers, booleans, symbols, etc.) ar
 The Word boxing packing bit patterns are like following:
 
 | Types  | Bit Pattern                           |
-|--------|---------------------------------------|
+| ------ | ------------------------------------- |
 | object | `xxxxxxxx xxxxxxxx xxxxxxxx xxxxx000` |
 | fixnum | `xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxx1` |
 | nil    | `00000000 00000000 00000000 00000000` |
@@ -24,17 +26,39 @@ The Word boxing packing bit patterns are like following:
 | undef  | `00000000 00000000 00000000 00010100` |
 | symbol | `xxxxxxxx xxxxxxxx xxxxxxxx xxxxxx10` |
 
-On 64 bit platform (unless `MRB_WORDBOX_NO_FLOAT_TRUNCATE`), float values are also packed in the `mrb_value`. In that case, we drop least significant 2 bits from mantissa.
-If you need full precision for floating-point numbers, define `MRB_WORDBOX_NO_FLOAT_TRUNCATE`.
+### Inline Float (64-bit)
+
+On 64-bit platforms, `double` values are packed into the word using
+rotation encoding. The IEEE 754 exponent field is rotated so that
+common exponent values (those not colliding with the pointer/tag
+patterns above) fit directly in a word. This encoding is lossless
+for most float values; only a small set of exotic exponents require
+heap allocation as `RFloat`.
+
+To disable inline float and heap-allocate all floats, define
+`MRB_WORDBOX_NO_INLINE_FLOAT`.
+
+### 32-bit Considerations
+
+On 32-bit platforms with 64-bit `double` (the common case),
+`MRB_WORDBOX_NO_INLINE_FLOAT` is automatically defined because a
+64-bit double cannot fit in a 32-bit word. All floats are
+heap-allocated as `RFloat` objects.
+
+The `RFloat` struct uses a `char[]` buffer instead of a `double`
+field to avoid alignment issues, since GC heap slots (RVALUE) on
+32-bit have only 4-byte alignment but `double` requires 8-byte.
+Accessor functions `mrb_rfloat_value()` and `mrb_rfloat_set()` use
+`memcpy` for safe access.
 
 ## NaN Boxing
 
-NaN boxing packs the Ruby data in a floating-point numbers, which represent NaN (Not a Number) values. Under IEEE753 definitions every value that exponent is all set are considered as NaN. That means NaN can represent `2^51` values. NaN boxing is a teaching to pack the values in those NaN representation. In theory, 64 bits pointers are too big to fit in NaN, but practically most OS uses only 48 bits at most for pointers (except for some OS e.g. Solaris).
+NaN boxing packs the Ruby data in a floating-point numbers, which represent NaN (Not a Number) values. Under IEEE753 definitions every value that exponent is all set are considered as NaN. That means NaN can represent `2^51` values. NaN boxing is a teaching to pack the values in those NaN representation. In theory, 64-bit pointers are too big to fit in NaN, but practically most OS use only 48 bits at most for pointers (except for some OS e.g. Solaris).
 
 The NaN boxing packing bit patterns are like following:
 
 | Types  | Bit Pattern                                                               |
-|--------|---------------------------------------------------------------------------|
+| ------ | ------------------------------------------------------------------------- |
 | float  | `SEEEEEEE EEEEFFFF FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF` |
 | +/-inf | `S1111111 11110000 00000000 00000000 00000000 00000000 00000000 00000000` |
 | nan    | `01111111 11111000 00000000 00000000 00000000 00000000 00000000 00000000` |
@@ -45,8 +69,28 @@ The NaN boxing packing bit patterns are like following:
 | ptr    | `01111111 11111100 PPPPPPPP PPPPPPPP PPPPPPPP PPPPPPPP PPPPPPPP PPPPPP01` |
 | nil    | `00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000` |
 
-The object values appear far more frequently than floating-point numbers, so we offset the value so that object pointers are unchanged. This technique is called "favor pointer"".
+The object values appear far more frequently than floating-point numbers, so we offset the value so that object pointers are unchanged. This technique is called "favor pointer".
 
 ## No Boxing
 
 No boxing represents `mrb_value` by the C struct with `type` and the value union. This is the most portable (but inefficient) representation. No boxing can be specified by `MRB_NO_BOXING`, and it's default for debugging configuration (e.g. `host-debug`).
+
+## Comparison
+
+| Property               | Word Boxing       | NaN Boxing       | No Boxing            |
+| ---------------------- | ----------------- | ---------------- | -------------------- |
+| `mrb_value` size       | 1 word (4/8 byte) | 8 bytes          | 2 words (8/16 bytes) |
+| Default on             | most platforms    | (manual opt-in)  | `host-debug`         |
+| Macro                  | `MRB_WORD_BOXING` | `MRB_NAN_BOXING` | `MRB_NO_BOXING`      |
+| Inline integers        | yes (31/63 bit)   | yes (32 bit)     | yes (full width)     |
+| Inline floats (64-bit) | yes (rotation)    | yes (native)     | yes (struct field)   |
+| Inline floats (32-bit) | no (heap RFloat)  | yes (native)     | yes (struct field)   |
+| Pointer size limit     | none              | 48 bits          | none                 |
+| Debugger friendly      | no                | no               | yes                  |
+
+## ABI Compatibility
+
+The boxing mode changes the layout of `mrb_value`. Code compiled with
+one boxing mode **cannot** be linked against a library built with a
+different mode. Always use `mruby-config --cflags` to get the correct
+compiler flags.

doc/internal/compiler.md

@@ -0,0 +1,323 @@
+<!-- summary: Compiler Pipeline Internals -->
+
+# Compiler Pipeline Internals
+
+This document describes mruby's compilation pipeline for developers
+working on the parser, code generator, or bytecode format.
+
+**Read this if you are:** adding new syntax or modifying the parser,
+debugging codegen issues (wrong registers, missing opcodes),
+working with the `.mrb` binary format, or understanding how Ruby
+constructs map to bytecode.
+
+## Pipeline Overview
+
+```text
+Ruby source
+    |
+    v
+ Lexer/Parser (parse.y)
+    |
+    v
+   AST (mrb_ast_node)
+    |
+    v
+ Code Generator (codegen.c)
+    |
+    v
+ Bytecode (mrb_irep)
+    |
+    v
+ VM execution  -or-  .mrb binary file
+```
+
+## Stage 1: Lexer and Parser
+
+The lexer and parser are combined in a single Lrama/Bison grammar
+file: `mrbgems/mruby-compiler/core/parse.y`.
+
+### Parser State
+
+The parser maintains extensive state in `mrb_parser_state`:
+
+- **lstate**: current lexer state (EXPR_BEG, EXPR_END, EXPR_ARG,
+  EXPR_DOT, EXPR_FNAME, etc.). Controls how tokens like `+`/`-`
+  are interpreted (sign vs operator) and whether newlines are
+  significant.
+- **locals**: stack of local variable lists (one per scope), stored
+  as cons-lists of symbols.
+- **lex_strterm**: string/heredoc parsing state for handling nested
+  interpolation.
+- **cond_stack**, **cmdarg_stack**: bit stacks tracking
+  conditional and command argument contexts.
+- **tree**: root AST node after successful parse.
+- **error_buffer**: accumulated parse errors.
+
+### AST Nodes
+
+The parser produces an AST using two node types:
+
+- **Cons-list nodes**: traditional binary tree pairs (car/cdr)
+- **Variable-sized nodes**: have a header with `node_type`, `lineno`,
+  and `filename_index`
+
+Key node types include `NODE_SCOPE` (new variable scope),
+`NODE_STMTS` (statement sequence), `NODE_IF`, `NODE_WHILE`,
+`NODE_CALL` (method call), `NODE_DEF` (method definition),
+`NODE_CLASS`, `NODE_RESCUE`, `NODE_ENSURE`, etc. See
+`mrbgems/mruby-compiler/core/node.h` for the complete list.
+
+### Local Variable Tracking
+
+Local variables are tracked per-scope during parsing:
+
+- `local_add(sym)`: register a new local variable in current scope
+- `local_var_p(sym)`: check if a symbol is a local variable (affects
+  whether an identifier is parsed as a method call or variable
+  reference)
+
+## Stage 2: Code Generator
+
+The code generator (`mrbgems/mruby-compiler/core/codegen.c`) walks
+the AST and emits bytecode into `mrb_irep` structures.
+
+### Codegen Scope
+
+Each lexical scope (method, block, class body) has its own
+`codegen_scope`:
+
+```text
+codegen_scope
++-- sp             current register index (stack pointer)
++-- pc             current instruction count
++-- nlocals        number of local variables
++-- nregs          maximum register index used
++-- lv             local variable list
++-- iseq[]         instruction sequence (grows dynamically)
++-- pool[]         literal pool (strings, numbers)
++-- syms[]         symbol table (method/variable names)
++-- reps[]         child ireps (nested methods/blocks)
++-- catch_table[]  exception handler entries
++-- loop           current loop context stack
++-- prev           parent scope
++-- mscope         true if method/module/class scope
+```
+
+Scopes nest for blocks, method definitions, and class/module bodies.
+Each scope produces one `mrb_irep`.
+
+### Register Allocation
+
+The code generator uses a simple stack-based register allocator:
+
+- Register 0 is always `self`
+- Registers 1..nlocals-1 are local variables (in declaration order)
+- Registers nlocals..nregs-1 are temporaries
+
+`push()` increments `sp` and tracks the high-water mark in `nregs`.
+`pop()` decrements `sp`. The allocator is linear - it does not
+reuse temporaries within an expression.
+
+### Instruction Emission
+
+Instructions are emitted via helper functions:
+
+- `genop_0(opcode)`: no operands
+- `genop_1(opcode, a)`: one operand (auto-extends with OP_EXT1
+  if a > 255)
+- `genop_2(opcode, a, b)`: two operands (auto-extends with
+  OP_EXT1/2/3 as needed)
+- `genop_3(opcode, a, b, c)`: three operands
+- `genop_W(opcode, a)`: 24-bit operand
+- `genop_2S(opcode, a, b)`: one 8-bit + one 16-bit operand
+
+### Peephole Optimization
+
+The code generator performs limited peephole optimizations, such as
+removing redundant `OP_MOVE` instructions and combining consecutive
+literal loads. Optimization is disabled at jump targets and when
+`no_optimize` is set in the compilation context.
+
+### Loop Context
+
+Loop constructs (`while`, `until`, `for`, blocks) push a
+`loopinfo` structure that tracks jump destinations:
+
+- `pc0`: destination for `next`
+- `pc1`: destination for `redo`
+- `pc2`: destination for `break`
+
+Loop types (`LOOP_NORMAL`, `LOOP_BLOCK`, `LOOP_FOR`, `LOOP_BEGIN`,
+`LOOP_RESCUE`) determine how `break`/`next`/`redo` behave.
+
+## IRep Structure
+
+The compiled bytecode is stored in `mrb_irep` (Instruction
+REPresentation):
+
+```text
+mrb_irep
++-- iseq[]      instruction sequence (mrb_code array)
++-- pool[]      literal pool (mrb_irep_pool entries)
++-- syms[]      symbol table (mrb_sym array)
++-- reps[]      child ireps (nested scopes)
++-- lv[]        local variable names (for debugging)
++-- nlocals     local variable count
++-- nregs       register count (locals + temporaries)
++-- ilen        instruction count
++-- plen        pool entry count
++-- slen        symbol count
++-- rlen        child irep count
++-- clen        catch handler count
++-- debug_info  source file/line mapping
+```
+
+### Literal Pool
+
+Pool entries store constants referenced by instructions:
+
+| Type             | Tag | Description                     |
+| ---------------- | --- | ------------------------------- |
+| `IREP_TT_STR`    | 0   | Dynamic string (heap allocated) |
+| `IREP_TT_SSTR`   | 2   | Static string (read-only)       |
+| `IREP_TT_INT32`  | 1   | 32-bit integer                  |
+| `IREP_TT_INT64`  | 3   | 64-bit integer                  |
+| `IREP_TT_FLOAT`  | 5   | Floating-point number           |
+| `IREP_TT_BIGINT` | 7   | Arbitrary-precision integer     |
+
+The code generator deduplicates pool entries: identical strings
+and equal numeric values share the same pool index.
+
+### Catch Handler Table
+
+Exception handler entries are appended after the instruction
+sequence in memory:
+
+```text
+mrb_irep_catch_handler
++-- type       MRB_CATCH_RESCUE (0) or MRB_CATCH_ENSURE (1)
++-- begin[4]   start PC of protected range
++-- end[4]     end PC of protected range
++-- target[4]  jump target when handler fires
+```
+
+During exception unwinding, handlers are searched in reverse order
+(last to first) for the current PC.
+
+## Operand Encoding
+
+Standard instructions use 8-bit operands. When a value exceeds
+255, extension prefixes widen operands to 16 bits:
+
+| Prefix    | Effect                            |
+| --------- | --------------------------------- |
+| `OP_EXT1` | First operand (a) becomes 16-bit  |
+| `OP_EXT2` | Second operand (b) becomes 16-bit |
+| `OP_EXT3` | Both a and b become 16-bit        |
+
+Instruction formats:
+
+| Format | Layout                        | Size    |
+| ------ | ----------------------------- | ------- |
+| Z      | opcode only                   | 1 byte  |
+| B      | opcode + a(8)                 | 2 bytes |
+| BB     | opcode + a(8) + b(8)          | 3 bytes |
+| BBB    | opcode + a(8) + b(8) + c(8)   | 4 bytes |
+| BS     | opcode + a(8) + b(16)         | 4 bytes |
+| BSS    | opcode + a(8) + b(16) + c(16) | 6 bytes |
+| S      | opcode + a(16)                | 3 bytes |
+| W      | opcode + a(24)                | 4 bytes |
+
+See [opcode.md](opcode.md) for the full instruction table.
+
+## OP_ENTER: Argument Specification
+
+`OP_ENTER` encodes a method's argument layout in a 24-bit value
+(W format). The bit fields are defined by the `MRB_ARGS_*` macros:
+
+```text
+Bits 23       no-block flag
+Bits 18-22    required argument count (5 bits, 0-31)
+Bits 13-17    optional argument count (5 bits, 0-31)
+Bit  12       rest argument flag (*args)
+Bits 7-11     post-rest argument count (5 bits, 0-31)
+Bits 2-6      keyword argument count (5 bits, 0-31)
+Bit  1        keyword rest flag (**kwargs)
+Bit  0        block argument flag (&block)
+```
+
+Example: `def foo(a, b=1, *rest, &block)` produces an aspec with
+1 required, 1 optional, rest flag set, and block flag set.
+
+## Presym: Compile-Time Symbols
+
+The presym system pre-allocates symbol IDs at build time for
+frequently used method names and operators. This avoids runtime
+string interning for common symbols.
+
+Generated by `lib/mruby/presym.rb`, the presym table maps symbol
+names to compile-time constants:
+
+| Macro             | Example               | Symbol        |
+| ----------------- | --------------------- | ------------- |
+| `MRB_SYM(name)`   | `MRB_SYM(initialize)` | `:initialize` |
+| `MRB_SYM_B(name)` | `MRB_SYM_B(map)`      | `:map!`       |
+| `MRB_SYM_Q(name)` | `MRB_SYM_Q(nil)`      | `:nil?`       |
+| `MRB_SYM_E(name)` | `MRB_SYM_E(name)`     | `:name=`      |
+| `MRB_OPSYM(op)`   | `MRB_OPSYM(add)`      | `:+`          |
+| `MRB_IVSYM(name)` | `MRB_IVSYM(name)`     | `:@name`      |
+| `MRB_CVSYM(name)` | `MRB_CVSYM(count)`    | `:@@count`    |
+| `MRB_GVSYM(name)` | `MRB_GVSYM(stdout)`   | `:$stdout`    |
+
+## Binary Format (.mrb)
+
+Precompiled bytecode is stored in the RITE binary format:
+
+```text
+Header: "RITE" magic + version ("0400") + CRC + size
+Section IREP: instruction sequences, pools, symbols
+Section DBG:  debug info (optional, filename/line mapping)
+Section LVAR: local variable names (optional)
+Footer: "END\0"
+```
+
+Loading functions:
+
+- `mrb_load_irep(mrb, bin)`: load and execute from byte array
+- `mrb_load_irep_buf(mrb, buf, len)`: load with explicit size
+  (safer)
+- `mrb_read_irep(mrb, bin)`: load without executing (returns
+  `mrb_irep*`)
+- `mrb_load_irep_file(mrb, fp)`: load from file
+
+The `mrbc` command-line tool performs ahead-of-time compilation:
+
+```shell
+mrbc -o output.mrb source.rb      # binary format
+mrbc -Boutput source.rb           # C array format
+```
+
+## Compilation Limits
+
+| Limit                  | Value                         |
+| ---------------------- | ----------------------------- |
+| Max nesting depth      | 256 (`MRB_CODEGEN_LEVEL_MAX`) |
+| Max local variables    | 255 (uint16 `nlocals`)        |
+| Max symbols per irep   | 65535                         |
+| Max operand (standard) | 255 (8-bit)                   |
+| Max operand (extended) | 65535 (16-bit)                |
+
+## Source Files
+
+| File                                    | Contents                  |
+| --------------------------------------- | ------------------------- |
+| `mrbgems/mruby-compiler/core/parse.y`   | Lrama/Bison grammar       |
+| `mrbgems/mruby-compiler/core/y.tab.c`   | Generated parser          |
+| `mrbgems/mruby-compiler/core/codegen.c` | Code generator            |
+| `mrbgems/mruby-compiler/core/node.h`    | AST node types            |
+| `include/mruby/irep.h`                  | IRep structure definition |
+| `include/mruby/compile.h`               | Compiler context API      |
+| `include/mruby/ops.h`                   | Opcode definitions        |
+| `src/load.c`                            | Binary format loader      |
+| `src/dump.c`                            | Binary format writer      |
+| `lib/mruby/presym.rb`                   | Presym table generator    |

doc/internal/gc.md

@@ -0,0 +1,357 @@
+<!-- summary: Garbage Collector Internals -->
+
+# Garbage Collector Internals
+
+This document describes the internals of mruby's garbage collector
+for developers working on `src/gc.c` and related code.
+
+**Read this if you are:** modifying core data structures that hold
+object references (and need to add write barriers), debugging
+memory leaks or GC-related crashes, tuning GC performance for an
+embedded target, or working on the GC code itself.
+
+**For user-facing GC docs**, see
+[gc-arena-howto.md](../guides/gc-arena-howto.md) (arena usage in C
+extensions) and [memory.md](../guides/memory.md) (heap regions).
+
+## Overview
+
+mruby uses a **tri-color incremental mark-and-sweep** garbage collector
+with an optional **generational mode**. The collector runs in small
+incremental steps between VM instruction execution, avoiding long
+pauses.
+
+## Tri-Color Model
+
+Every heap-allocated object has a color stored in
+`RBasic::gc_color` (3 bits):
+
+| Color          | Value  | Meaning                              |
+| -------------- | ------ | ------------------------------------ |
+| White (A or B) | 1 or 2 | Unmarked, candidate for collection   |
+| Gray           | 0      | Marked, but children not yet scanned |
+| Black          | 4      | Fully marked and scanned             |
+| Red            | 7      | Static/ROM object, never collected   |
+
+The GC uses two white types (A and B) in a flip-flop scheme. At the
+start of each GC cycle, the meaning of "current white" is flipped by
+XORing the white bits. This avoids recoloring all live objects at
+cycle boundaries, which is an O(1) operation instead of O(n).
+
+```c
+#define is_dead(s, o) \
+  (((o)->gc_color & other_white_part(s) & GC_WHITES) || \
+   (o)->tt == MRB_TT_FREE)
+```
+
+An object is dead if it still carries the previous cycle's white color.
+
+## Heap Structure
+
+### Heap Pages
+
+Objects are allocated from fixed-size heap pages:
+
+```text
+mrb_heap_page
++-- freelist        linked list of free slots
++-- next            next page in heap list
++-- free_next       next page with free slots
++-- old             old generation flag (generational mode)
++-- region          true if carved from a contiguous region
++-- objects[MRB_HEAP_PAGE_SIZE]   RVALUE array (default 1024)
+```
+
+Each page holds `MRB_HEAP_PAGE_SIZE` objects (default 1024). On
+64-bit systems, a page is approximately 40 KB (40 bytes per slot).
+
+### RVALUE Union
+
+All mruby object types share the same slot size via a C union:
+
+```text
+RVALUE = union of {
+  RBasic, RObject, RClass, RString, RArray, RHash,
+  RRange, RData, RProc, REnv, RFiber, RException, ...
+  struct { RBasic header; RVALUE *next; }  (free slot)
+}
+```
+
+Free slots use the union space for a freelist pointer.
+
+### Freelist
+
+Each page maintains a singly-linked freelist of available slots.
+Allocation pops from the freelist; deallocation during sweep
+prepends to the freelist. The GC tracks pages with free slots in
+`gc->free_heaps` for fast allocation.
+
+### Heap Regions
+
+For embedded systems with fixed memory banks, `mrb_gc_add_region()`
+carves heap pages from a user-provided contiguous buffer:
+
+```c
+static uint8_t heap_buf[64 * 1024];
+mrb_gc_add_region(mrb, heap_buf, sizeof(heap_buf));
+```
+
+Region pages are never freed by the GC (even if all objects die).
+When region pages are exhausted, allocation falls back to `malloc()`.
+
+## GC Phases
+
+The GC operates as a three-state machine:
+
+```text
+GC_STATE_ROOT --> GC_STATE_MARK --> GC_STATE_SWEEP --> GC_STATE_ROOT
+```
+
+### Root Scan (GC_STATE_ROOT)
+
+Marks objects directly reachable from the VM:
+
+1. Global variables (`mrb_gc_mark_gv`)
+2. GC arena (`gc->arena[0..arena_idx-1]`)
+3. All built-in classes (Object, Class, Module, etc.)
+4. Top-level self (`mrb->top_self`)
+5. Current exception (`mrb->exc`)
+6. Execution contexts (VM stacks, call info stacks, active fibers)
+7. Task queues (if `MRB_USE_TASK_SCHEDULER` is defined)
+
+After root scanning, the white color is flipped.
+
+### Incremental Marking (GC_STATE_MARK)
+
+Gray objects are popped from the gray stack and their children
+marked. Each step processes a limited number of objects:
+
+```text
+limit = (GC_STEP_SIZE / 100) * step_ratio
+```
+
+With default `step_ratio = 200` and `GC_STEP_SIZE = 1024`, the
+limit is 2048 objects per step.
+
+When the gray stack is exhausted, the final marking phase re-marks
+the arena and global variables to catch objects created during
+marking, then transitions to sweep.
+
+### Sweep (GC_STATE_SWEEP)
+
+Iterates through heap pages. For each object:
+
+- If dead (previous cycle's white): call `obj_free()`, return
+  slot to freelist
+- If alive: paint with current white for the next cycle
+
+Sweep is also incremental: `gc->sweeps` tracks the current page
+position between steps.
+
+## Gray Stack
+
+The gray stack is a fixed-size array of object pointers:
+
+```c
+struct RBasic *gray_stack[MRB_GRAY_STACK_SIZE];  /* default 1024 */
+size_t gray_stack_top;
+mrb_bool gray_overflow;
+```
+
+When the stack overflows, `gray_overflow` is set to `TRUE`. During
+marking, `gc_gray_rescan()` scans the entire heap to find any gray
+objects that could not be pushed. This guarantees correctness at the
+cost of a full heap scan.
+
+## Write Barriers
+
+During incremental marking, a black (fully marked) object storing
+a reference to a white (unmarked) object creates a dangerous edge
+that could lead to premature collection. Write barriers prevent this.
+
+### Field Write Barrier
+
+Used when assigning a specific field:
+
+```c
+mrb_field_write_barrier(mrb, parent, child);
+```
+
+If `parent` is black and `child` is white:
+
+- During marking or generational mode: paint `child` gray (add to
+  gray stack for scanning)
+- During sweep: paint `parent` with current white (demote it for
+  next cycle)
+
+### General Write Barrier
+
+Used when an object has been modified but the specific child is
+not known:
+
+```c
+mrb_write_barrier(mrb, obj);
+```
+
+Paints `obj` gray and pushes it onto the gray stack for re-scanning.
+
+## GC Arena
+
+The arena protects newly created objects from collection before
+they are stored in a reachable location. Every `mrb_obj_alloc()`
+automatically pushes the new object onto the arena.
+
+C extensions must save and restore the arena index when creating
+many temporary objects to prevent arena overflow:
+
+```c
+int ai = mrb_gc_arena_save(mrb);
+/* create temporary objects */
+mrb_gc_arena_restore(mrb, ai);
+```
+
+### Fixed vs Dynamic Arena
+
+- **Dynamic** (default): arena grows by 1.5x when full. Risk of
+  unbounded growth if arena is not properly managed.
+- **Fixed** (`MRB_GC_FIXED_ARENA`): raises an exception on overflow.
+  Arena size is `MRB_GC_ARENA_SIZE` (default 100).
+
+### Permanent Registration
+
+For long-lived C objects that must survive indefinitely:
+
+```c
+mrb_gc_register(mrb, obj);    /* add to permanent root */
+mrb_gc_unregister(mrb, obj);  /* remove from root */
+```
+
+These store objects in a global array that is always marked as
+part of the root set.
+
+See [gc-arena-howto.md](../guides/gc-arena-howto.md) for detailed
+usage patterns.
+
+## Generational Mode
+
+When enabled (default, unless `MRB_GC_TURN_OFF_GENERATIONAL` is
+defined), the GC classifies objects into young and old generations.
+
+### Minor GC
+
+Only processes young objects. Pages where all objects are old are
+marked with `page->old = TRUE` and skipped entirely during sweep.
+Minor GC always runs to completion in a single step.
+
+### Major GC
+
+A full mark-and-sweep cycle that processes all objects. Triggered
+when `gc->live > gc->oldgen_threshold`. Major GC runs
+incrementally, like the non-generational collector.
+
+After a major GC completes, the collector reverts to minor GC mode.
+The old-generation threshold is recalculated:
+
+```text
+oldgen_threshold = live_after_mark * MAJOR_GC_INC_RATIO / 100
+```
+
+With `MAJOR_GC_INC_RATIO = 120`, a major GC triggers when live
+objects exceed 120% of the last major GC's survivors.
+
+### Transitioning Between Modes
+
+```c
+mrb_gc_generational_mode_set(mrb, TRUE);   /* enable */
+mrb_gc_generational_mode_set(mrb, FALSE);  /* disable */
+```
+
+From Ruby: `GC.generational_mode = true/false`.
+
+## Object Allocation
+
+`mrb_obj_alloc()` is the core allocation function:
+
+1. If `MRB_GC_STRESS` is defined, run a full GC
+2. If `gc->live >= gc->threshold`, run `mrb_incremental_gc()`
+3. Ensure arena has space (`gc_arena_keep`)
+4. Pop an object from the freelist of `gc->free_heaps`
+5. If no free pages, allocate a new page (`add_heap`)
+6. Initialize the object (zero fill, set type and class)
+7. Paint with current white color
+8. Push onto arena (`gc_protect`)
+9. Increment `gc->live`
+
+## Object Freeing
+
+`obj_free()` performs type-specific cleanup:
+
+- **Objects/Exceptions**: free instance variable tables
+- **Classes**: free method tables and instance variable tables
+- **Arrays**: free heap buffer (if not embedded/shared)
+- **Hashes**: free hash table
+- **Strings**: free heap buffer (if not embedded/shared)
+- **Data objects**: call user-provided `dfree` callback
+- **Procs**: decrement irep reference count
+- **Fibers**: free context (stacks)
+
+The object's type is set to `MRB_TT_FREE` after freeing.
+
+## Triggering GC
+
+### Automatic
+
+GC runs automatically when `gc->live >= gc->threshold` during
+object allocation. After each cycle:
+
+```text
+threshold = (live_after_mark / 100) * interval_ratio
+minimum: GC_STEP_SIZE (1024)
+```
+
+With default `interval_ratio = 200`, GC triggers when live objects
+roughly double.
+
+### Manual
+
+```c
+mrb_full_gc(mrb);          /* force complete GC cycle */
+mrb_garbage_collect(mrb);  /* public API wrapper */
+```
+
+From Ruby: `GC.start`.
+
+## Configuration
+
+### Compile-Time
+
+| Macro                          | Default | Description                             |
+| ------------------------------ | ------- | --------------------------------------- |
+| `MRB_HEAP_PAGE_SIZE`           | 1024    | Objects per heap page                   |
+| `MRB_GRAY_STACK_SIZE`          | 1024    | Gray stack capacity                     |
+| `MRB_GC_ARENA_SIZE`            | 100     | Arena size (fixed mode) or initial size |
+| `MRB_GC_FIXED_ARENA`           | off     | Use fixed-size arena                    |
+| `MRB_GC_TURN_OFF_GENERATIONAL` | off     | Disable generational mode               |
+| `MRB_GC_STRESS`                | off     | Full GC on every allocation (debug)     |
+| `MRB_USE_MALLOC_TRIM`          | off     | Call `malloc_trim()` after full GC      |
+
+### Runtime
+
+From Ruby code:
+
+```ruby
+GC.interval_ratio = 200   # threshold = live * ratio / 100
+GC.step_ratio = 200       # objects per incremental step
+GC.generational_mode = true
+GC.start                   # force full GC
+GC.enable                  # re-enable GC
+GC.disable                 # disable GC
+```
+
+## Source Files
+
+| File                 | Contents                          |
+| -------------------- | --------------------------------- |
+| `src/gc.c`           | GC implementation (~1400 lines)   |
+| `include/mruby/gc.h` | `mrb_gc` structure, public GC API |
+| `include/mruby.h`    | Arena save/restore macros         |

doc/internal/opcode.md

@@ -1,136 +1,206 @@
-# The new bytecode
+<!-- summary: About mruby Virtual Machine Instructions -->
 
-We will reimplement the VM to use 8bit instruction code. By
-bytecode, we mean real byte code. The whole purpose is
-reducing the memory consumption of mruby VM.
+# mruby Bytecode
 
-# Instructions
+mruby uses 8-bit instruction opcodes. Each instruction is a single byte,
+allowing up to 256 opcodes. Instructions can take 0 to 3 operands.
 
-Instructions are bytes. There can be 256 instructions. Currently, we
-have 106 instructions. Instructions can take 0 to 3 operands.
+## Operands
 
-## operands
+The size of operands can be either 8 bits, 16 bits, or 24 bits.
+In the instruction table below, the operand type field describes
+the size of each operand.
 
-The size of operands can be either 8bits, 16bits or 24bits.
-In the table.1 below, the second field describes the size
-of operands.
+- `Z`: no operand
+- `B`: 8 bits
+- `S`: 16 bits
+- `W`: 24 bits
 
-- B: 8bit
-- S: 16bit
-- W: 24bit
-
-If the first and second operands are of type `B` (8bits), they may be
-extended to 16bits by the operand extension instruction immediately
+If the first and second operands are of type `B` (8 bits), they may be
+extended to 16 bits by the operand extension instruction immediately
 preceding them.
 See also `OP_EXT1`, `OP_EXT2` and `OP_EXT3`.
 
-## table.1 Instruction Table
+## Instruction Table
 
-| Instruction Name   | Operand type   | Semantics                                                  |
-|--------------------|----------------|------------------------------------------------------------|
-| `OP_NOP`           | `-`            | `no operation`                                             |
-| `OP_MOVE`          | `BB`           | `R(a) = R(b)`                                              |
-| `OP_LOADL`         | `BB`           | `R(a) = Pool(b)`                                           |
-| `OP_LOADI`         | `BB`           | `R(a) = mrb_int(b)`                                        |
-| `OP_LOADINEG`      | `BB`           | `R(a) = mrb_int(-b)`                                       |
-| `OP_LOADI__1`      | `B`            | `R(a) = mrb_int(-1)`                                       |
-| `OP_LOADI_0`       | `B`            | `R(a) = mrb_int(0)`                                        |
-| `OP_LOADI_1`       | `B`            | `R(a) = mrb_int(1)`                                        |
-| `OP_LOADI_2`       | `B`            | `R(a) = mrb_int(2)`                                        |
-| `OP_LOADI_3`       | `B`            | `R(a) = mrb_int(3)`                                        |
-| `OP_LOADI_4`       | `B`            | `R(a) = mrb_int(4)`                                        |
-| `OP_LOADI_5`       | `B`            | `R(a) = mrb_int(5)`                                        |
-| `OP_LOADI_6`       | `B`            | `R(a) = mrb_int(6)`                                        |
-| `OP_LOADI_7`       | `B`            | `R(a) = mrb_int(7)`                                        |
-| `OP_LOADI16`       | `BS`           | `R(a) = mrb_int(b)`                                        |
-| `OP_LOADI32`       | `BSS`          | `R(a) = mrb_int((b<<16)+c)`                                |
-| `OP_LOADSYM`       | `BB`           | `R(a) = Syms(b)`                                           |
-| `OP_LOADNIL`       | `B`            | `R(a) = nil`                                               |
-| `OP_LOADSELF`      | `B`            | `R(a) = self`                                              |
-| `OP_LOADT`         | `B`            | `R(a) = true`                                              |
-| `OP_LOADF`         | `B`            | `R(a) = false`                                             |
-| `OP_GETGV`         | `BB`           | `R(a) = getglobal(Syms(b))`                                |
-| `OP_SETGV`         | `BB`           | `setglobal(Syms(b), R(a))`                                 |
-| `OP_GETSV`         | `BB`           | `R(a) = Special[Syms(b)]`                                  |
-| `OP_SETSV`         | `BB`           | `Special[Syms(b)] = R(a)`                                  |
-| `OP_GETIV`         | `BB`           | `R(a) = ivget(Syms(b))`                                    |
-| `OP_SETIV`         | `BB`           | `ivset(Syms(b),R(a))`                                      |
-| `OP_GETCV`         | `BB`           | `R(a) = cvget(Syms(b))`                                    |
-| `OP_SETCV`         | `BB`           | `cvset(Syms(b),R(a))`                                      |
-| `OP_GETCONST`      | `BB`           | `R(a) = constget(Syms(b))`                                 |
-| `OP_SETCONST`      | `BB`           | `constset(Syms(b),R(a))`                                   |
-| `OP_GETMCNST`      | `BB`           | `R(a) = R(a)::Syms(b)`                                     |
-| `OP_SETMCNST`      | `BB`           | `R(a+1)::Syms(b) = R(a)`                                   |
-| `OP_GETUPVAR`      | `BBB`          | `R(a) = uvget(b,c)`                                        |
-| `OP_SETUPVAR`      | `BBB`          | `uvset(b,c,R(a))`                                          |
-| `OP_GETIDX`        | `B`            | `R(a) = R(a)[R(a+1)]`                                      |
-| `OP_SETIDX`        | `B`            | `R(a)[R(a+1)] = R(a+2)`                                    |
-| `OP_JMP`           | `S`            | `pc+=a`                                                    |
-| `OP_JMPIF`         | `BS`           | `if R(a) pc+=b`                                            |
-| `OP_JMPNOT`        | `BS`           | `if !R(a) pc+=b`                                           |
-| `OP_JMPNIL`        | `BS`           | `if R(a)==nil pc+=b`                                       |
-| `OP_JMPUW`         | `S`            | `unwind_and_jump_to(a)`                                    |
-| `OP_EXCEPT`        | `B`            | `R(a) = exc`                                               |
-| `OP_RESCUE`        | `BB`           | `R(b) = R(a).isa?(R(b))`                                   |
-| `OP_RAISEIF`       | `B`            | `raise(R(a)) if R(a)`                                      |
-| `OP_SSEND`         | `BBB`          | `R(a) = self.send(Syms(b),R(a+1)..,R(a+n+1):R(a+n+2)..) (c=n\|k<<4)` |
-| `OP_SSENDB`        | `BBB`          | `R(a) = self.send(Syms(b),R(a+1)..,R(a+n+1):R(a+n+2)..,&R(a+n+2k+1))` |
-| `OP_SEND`          | `BBB`          | `R(a) = R(a).send(Syms(b),R(a+1)..,R(a+n+1):R(a+n+2)..) (c=n\|k<<4)` |
-| `OP_SENDB`         | `BBB`          | `R(a) = R(a).send(Syms(b),R(a+1)..,R(a+n+1):R(a+n+2)..,&R(a+n+2k+1))` |
-| `OP_CALL`          | `-`            | `self.call(*, **, &) (But overlay the current call frame; tailcall)` |
-| `OP_SUPER`         | `BB`           | `R(a) = super(R(a+1),... ,R(a+b+1))`                       |
-| `OP_ARGARY`        | `BS`           | `R(a) = argument array (16=m5:r1:m5:d1:lv4)`               |
-| `OP_ENTER`         | `W`            | `arg setup according to flags (23=m5:o5:r1:m5:k5:d1:b1)`   |
-| `OP_KEY_P`         | `BB`           | `R(a) = kdict.key?(Syms(b))`                               |
-| `OP_KEYEND`        | `-`            | `raise unless kdict.empty?`                                |
-| `OP_KARG`          | `BB`           | `R(a) = kdict[Syms(b)]; kdict.delete(Syms(b))`             |
-| `OP_RETURN`        | `B`            | `return R(a) (normal)`                                     |
-| `OP_RETURN_BLK`    | `B`            | `return R(a) (in-block return)`                            |
-| `OP_BREAK`         | `B`            | `break R(a)`                                               |
-| `OP_BLKPUSH`       | `BS`           | `R(a) = block (16=m5:r1:m5:d1:lv4)`                        |
-| `OP_ADD`           | `B`            | `R(a) = R(a)+R(a+1)`                                       |
-| `OP_ADDI`          | `BB`           | `R(a) = R(a)+mrb_int(b)`                                   |
-| `OP_SUB`           | `B`            | `R(a) = R(a)-R(a+1)`                                       |
-| `OP_SUBI`          | `BB`           | `R(a) = R(a)-mrb_int(b)`                                   |
-| `OP_MUL`           | `B`            | `R(a) = R(a)*R(a+1)`                                       |
-| `OP_DIV`           | `B`            | `R(a) = R(a)/R(a+1)`                                       |
-| `OP_EQ`            | `B`            | `R(a) = R(a)==R(a+1)`                                      |
-| `OP_LT`            | `B`            | `R(a) = R(a)<R(a+1)`                                       |
-| `OP_LE`            | `B`            | `R(a) = R(a)<=R(a+1)`                                      |
-| `OP_GT`            | `B`            | `R(a) = R(a)>R(a+1)`                                       |
-| `OP_GE`            | `B`            | `R(a) = R(a)>=R(a+1)`                                      |
-| `OP_ARRAY`         | `BB`           | `R(a) = ary_new(R(a),R(a+1)..R(a+b))`                      |
-| `OP_ARRAY2`        | `BBB`          | `R(a) = ary_new(R(b),R(b+1)..R(b+c))`                      |
-| `OP_ARYCAT`        | `B`            | `ary_cat(R(a),R(a+1))`                                     |
-| `OP_ARYPUSH`       | `BB`           | `ary_push(R(a),R(a+1)..R(a+b))`                            |
-| `OP_ARYSPLAT`      | `B`            | `R(a) = ary_splat(R(a))`                                   |
-| `OP_AREF`          | `BBB`          | `R(a) = R(b)[c]`                                           |
-| `OP_ASET`          | `BBB`          | `R(b)[c] = R(a)`                                           |
-| `OP_APOST`         | `BBB`          | `*R(a),R(a+1)..R(a+c) = R(a)[b..]`                         |
-| `OP_INTERN`        | `B`            | `R(a) = intern(R(a))`                                      |
-| `OP_SYMBOL`        | `BB`           | `R(a) = intern(Pool(b))`                                   |
-| `OP_STRING`        | `BB`           | `R(a) = str_dup(Pool(b))`                                  |
-| `OP_STRCAT`        | `B`            | `str_cat(R(a),R(a+1))`                                     |
-| `OP_HASH`          | `BB`           | `R(a) = hash_new(R(a),R(a+1)..R(a+b*2-1))`                 |
-| `OP_HASHADD`       | `BB`           | `hash_push(R(a),R(a+1)..R(a+b*2))`                         |
-| `OP_HASHCAT`       | `B`            | `R(a) = hash_cat(R(a),R(a+1))`                             |
-| `OP_LAMBDA`        | `BB`           | `R(a) = lambda(Irep(b),OP_L_LAMBDA)`                       |
-| `OP_BLOCK`         | `BB`           | `R(a) = lambda(Irep(b),OP_L_BLOCK)`                        |
-| `OP_METHOD`        | `BB`           | `R(a) = lambda(Irep(b),OP_L_METHOD)`                       |
-| `OP_RANGE_INC`     | `B`            | `R(a) = range_new(R(a),R(a+1),FALSE)`                      |
-| `OP_RANGE_EXC`     | `B`            | `R(a) = range_new(R(a),R(a+1),TRUE)`                       |
-| `OP_OCLASS`        | `B`            | `R(a) = ::Object`                                          |
-| `OP_CLASS`         | `BB`           | `R(a) = newclass(R(a),Syms(b),R(a+1))`                     |
-| `OP_MODULE`        | `BB`           | `R(a) = newmodule(R(a),Syms(b))`                           |
-| `OP_EXEC`          | `BB`           | `R(a) = blockexec(R(a),Irep(b))`                           |
-| `OP_DEF`           | `BB`           | `R(a).newmethod(Syms(b),R(a+1)); R(a) = Syms(b)`           |
-| `OP_ALIAS`         | `BB`           | `alias_method(target_class,Syms(a),Syms(b))`               |
-| `OP_UNDEF`         | `B`            | `undef_method(target_class,Syms(a))`                       |
-| `OP_SCLASS`        | `B`            | `R(a) = R(a).singleton_class`                              |
-| `OP_TCLASS`        | `B`            | `R(a) = target_class`                                      |
-| `OP_DEBUG`         | `BBB`          | `print a,b,c`                                              |
-| `OP_ERR`           | `B`            | `raise(LocalJumpError, Pool(a))`                           |
-| `OP_EXT1`          | `-`            | `make 1st operand (a) 16bit`                               |
-| `OP_EXT2`          | `-`            | `make 2nd operand (b) 16bit`                               |
-| `OP_EXT3`          | `-`            | `make 1st and 2nd operands 16bit`                          |
-| `OP_STOP`          | `-`            | `stop VM`                                                  |
+| No. | Instruction Name | Operand type | Semantics                                                         |
+| --: | ---------------- | ------------ | ----------------------------------------------------------------- |
+|   0 | `OP_NOP`         | `Z`          | no operation                                                      |
+|   1 | `OP_MOVE`        | `BB`         | `R[a] = R[b]`                                                     |
+|   2 | `OP_LOADL`       | `BB`         | `R[a] = Pool[b]`                                                  |
+|   3 | `OP_LOADI8`      | `BB`         | `R[a] = mrb_int(b)`                                               |
+|   4 | `OP_LOADINEG`    | `BB`         | `R[a] = mrb_int(-b)`                                              |
+|   5 | `OP_LOADI__1`    | `B`          | `R[a] = mrb_int(-1)`                                              |
+|   6 | `OP_LOADI_0`     | `B`          | `R[a] = mrb_int(0)`                                               |
+|   7 | `OP_LOADI_1`     | `B`          | `R[a] = mrb_int(1)`                                               |
+|   8 | `OP_LOADI_2`     | `B`          | `R[a] = mrb_int(2)`                                               |
+|   9 | `OP_LOADI_3`     | `B`          | `R[a] = mrb_int(3)`                                               |
+|  10 | `OP_LOADI_4`     | `B`          | `R[a] = mrb_int(4)`                                               |
+|  11 | `OP_LOADI_5`     | `B`          | `R[a] = mrb_int(5)`                                               |
+|  12 | `OP_LOADI_6`     | `B`          | `R[a] = mrb_int(6)`                                               |
+|  13 | `OP_LOADI_7`     | `B`          | `R[a] = mrb_int(7)`                                               |
+|  14 | `OP_LOADI16`     | `BS`         | `R[a] = mrb_int(b)`                                               |
+|  15 | `OP_LOADI32`     | `BSS`        | `R[a] = mrb_int((b<<16)+c)`                                       |
+|  16 | `OP_LOADSYM`     | `BB`         | `R[a] = Syms[b]`                                                  |
+|  17 | `OP_LOADNIL`     | `B`          | `R[a] = nil`                                                      |
+|  18 | `OP_LOADSELF`    | `B`          | `R[a] = self`                                                     |
+|  19 | `OP_LOADTRUE`    | `B`          | `R[a] = true`                                                     |
+|  20 | `OP_LOADFALSE`   | `B`          | `R[a] = false`                                                    |
+|  21 | `OP_GETGV`       | `BB`         | `R[a] = getglobal(Syms[b])`                                       |
+|  22 | `OP_SETGV`       | `BB`         | `setglobal(Syms[b], R[a])`                                        |
+|  23 | `OP_GETSV`       | `BB`         | `R[a] = Special[Syms[b]]`                                         |
+|  24 | `OP_SETSV`       | `BB`         | `Special[Syms[b]] = R[a]`                                         |
+|  25 | `OP_GETIV`       | `BB`         | `R[a] = ivget(Syms[b])`                                           |
+|  26 | `OP_SETIV`       | `BB`         | `ivset(Syms[b],R[a])`                                             |
+|  27 | `OP_GETCV`       | `BB`         | `R[a] = cvget(Syms[b])`                                           |
+|  28 | `OP_SETCV`       | `BB`         | `cvset(Syms[b],R[a])`                                             |
+|  29 | `OP_GETCONST`    | `BB`         | `R[a] = constget(Syms[b])`                                        |
+|  30 | `OP_SETCONST`    | `BB`         | `constset(Syms[b],R[a])`                                          |
+|  31 | `OP_GETMCNST`    | `BB`         | `R[a] = R[a]::Syms[b]`                                            |
+|  32 | `OP_SETMCNST`    | `BB`         | `R[a+1]::Syms[b] = R[a]`                                          |
+|  33 | `OP_GETUPVAR`    | `BBB`        | `R[a] = uvget(b,c)`                                               |
+|  34 | `OP_SETUPVAR`    | `BBB`        | `uvset(b,c,R[a])`                                                 |
+|  35 | `OP_GETIDX`      | `B`          | `R[a] = R[a][R[a+1]]`                                             |
+|  36 | `OP_GETIDX0`     | `BB`         | `R[a] = R[b][0]`                                                  |
+|  37 | `OP_SETIDX`      | `B`          | `R[a][R[a+1]] = R[a+2]`                                           |
+|  38 | `OP_JMP`         | `S`          | `pc += a`                                                         |
+|  39 | `OP_JMPIF`       | `BS`         | `if R[a] pc += b`                                                 |
+|  40 | `OP_JMPNOT`      | `BS`         | `if !R[a] pc += b`                                                |
+|  41 | `OP_JMPNIL`      | `BS`         | `if R[a]==nil pc += b`                                            |
+|  42 | `OP_JMPUW`       | `S`          | `unwind_and_jump_to(a)`                                           |
+|  43 | `OP_EXCEPT`      | `B`          | `R[a] = exc`                                                      |
+|  44 | `OP_RESCUE`      | `BB`         | `R[b] = R[a].isa?(R[b])`                                          |
+|  45 | `OP_RAISEIF`     | `B`          | `raise(R[a]) if R[a]`                                             |
+|  46 | `OP_MATCHERR`    | `B`          | `raise NoMatchingPatternError unless R[a]`                        |
+|  47 | `OP_SSEND`       | `BBB`        | `R[a] = self.send(Syms[b],R[a+1]..,R[a+n+1]:R[a+n+2]..) (c=n\     |
+|  48 | `OP_SSEND0`      | `BB`         | `R[a] = self.send(Syms[b])` (no args)                             |
+|  49 | `OP_SSENDB`      | `BBB`        | `R[a] = self.send(Syms[b],R[a+1]..,&R[a+n+2k+1])`                 |
+|  50 | `OP_SEND`        | `BBB`        | `R[a] = R[a].send(Syms[b],R[a+1]..,R[a+n+1]:R[a+n+2]..) (c=n\     |
+|  51 | `OP_SEND0`       | `BB`         | `R[a] = R[a].send(Syms[b])` (no args)                             |
+|  52 | `OP_SENDB`       | `BBB`        | `R[a] = R[a].send(Syms[b],R[a+1]..,&R[a+n+2k+1])`                 |
+|  53 | `OP_CALL`        | `Z`          | `self.call(*, **, &)` (tailcall)                                  |
+|  54 | `OP_BLKCALL`     | `BB`         | `R[a] = R[a].call(R[a+1],...,R[a+b])` (direct block call)         |
+|  55 | `OP_SUPER`       | `BB`         | `R[a] = super(R[a+1],...,R[a+b+1])`                               |
+|  56 | `OP_ARGARY`      | `BS`         | `R[a] = argument array (16=m5:r1:m5:d1:lv4)`                      |
+|  57 | `OP_ENTER`       | `W`          | `arg setup according to flags (24=n1:m5:o5:r1:m5:k5:d1:b1)`       |
+|  58 | `OP_KEY_P`       | `BB`         | `R[a] = kdict.key?(Syms[b])`                                      |
+|  59 | `OP_KEYEND`      | `Z`          | `raise unless kdict.empty?`                                       |
+|  60 | `OP_KARG`        | `BB`         | `R[a] = kdict[Syms[b]]; kdict.delete(Syms[b])`                    |
+|  61 | `OP_RETURN`      | `B`          | `return R[a]` (normal)                                            |
+|  62 | `OP_RETURN_BLK`  | `B`          | `return R[a]` (in-block return)                                   |
+|  63 | `OP_RETSELF`     | `Z`          | `return self`                                                     |
+|  64 | `OP_RETNIL`      | `Z`          | `return nil`                                                      |
+|  65 | `OP_RETTRUE`     | `Z`          | `return true`                                                     |
+|  66 | `OP_RETFALSE`    | `Z`          | `return false`                                                    |
+|  67 | `OP_BREAK`       | `B`          | `break R[a]`                                                      |
+|  68 | `OP_BLKPUSH`     | `BS`         | `R[a] = block (16=m5:r1:m5:d1:lv4)`                               |
+|  69 | `OP_ADD`         | `B`          | `R[a] = R[a] + R[a+1]`                                            |
+|  70 | `OP_ADDI`        | `BB`         | `R[a] = R[a] + mrb_int(b)`                                        |
+|  71 | `OP_SUB`         | `B`          | `R[a] = R[a] - R[a+1]`                                            |
+|  72 | `OP_SUBI`        | `BB`         | `R[a] = R[a] - mrb_int(b)`                                        |
+|  73 | `OP_ADDILV`      | `BBB`        | `R[a] = R[a] + mrb_int(c)` (with local variable fallback)         |
+|  74 | `OP_SUBILV`      | `BBB`        | `R[a] = R[a] - mrb_int(c)` (with local variable fallback)         |
+|  75 | `OP_MUL`         | `B`          | `R[a] = R[a] * R[a+1]`                                            |
+|  76 | `OP_DIV`         | `B`          | `R[a] = R[a] / R[a+1]`                                            |
+|  77 | `OP_EQ`          | `B`          | `R[a] = R[a] == R[a+1]`                                           |
+|  78 | `OP_LT`          | `B`          | `R[a] = R[a] < R[a+1]`                                            |
+|  79 | `OP_LE`          | `B`          | `R[a] = R[a] <= R[a+1]`                                           |
+|  80 | `OP_GT`          | `B`          | `R[a] = R[a] > R[a+1]`                                            |
+|  81 | `OP_GE`          | `B`          | `R[a] = R[a] >= R[a+1]`                                           |
+|  82 | `OP_ARRAY`       | `BB`         | `R[a] = ary_new(R[a],R[a+1]..R[a+b])`                             |
+|  83 | `OP_ARRAY2`      | `BBB`        | `R[a] = ary_new(R[b],R[b+1]..R[b+c])`                             |
+|  84 | `OP_ARYCAT`      | `B`          | `ary_cat(R[a],R[a+1])`                                            |
+|  85 | `OP_ARYPUSH`     | `BB`         | `ary_push(R[a],R[a+1]..R[a+b])`                                   |
+|  86 | `OP_ARYSPLAT`    | `B`          | `R[a] = ary_splat(R[a])`                                          |
+|  87 | `OP_AREF`        | `BBB`        | `R[a] = R[b][c]`                                                  |
+|  88 | `OP_ASET`        | `BBB`        | `R[b][c] = R[a]`                                                  |
+|  89 | `OP_APOST`       | `BBB`        | `*R[a],R[a+1]..R[a+c] = R[a][b..]`                                |
+|  90 | `OP_INTERN`      | `B`          | `R[a] = intern(R[a])`                                             |
+|  91 | `OP_SYMBOL`      | `BB`         | `R[a] = intern(Pool[b])`                                          |
+|  92 | `OP_STRING`      | `BB`         | `R[a] = str_dup(Pool[b])`                                         |
+|  93 | `OP_STRCAT`      | `B`          | `str_cat(R[a],R[a+1])`                                            |
+|  94 | `OP_HASH`        | `BB`         | `R[a] = hash_new(R[a],R[a+1]..R[a+b*2-1])`                        |
+|  95 | `OP_HASHADD`     | `BB`         | `hash_push(R[a],R[a+1]..R[a+b*2])`                                |
+|  96 | `OP_HASHCAT`     | `B`          | `R[a] = hash_cat(R[a],R[a+1])`                                    |
+|  97 | `OP_LAMBDA`      | `BB`         | `R[a] = lambda(Irep[b],L_LAMBDA)`                                 |
+|  98 | `OP_BLOCK`       | `BB`         | `R[a] = lambda(Irep[b],L_BLOCK)`                                  |
+|  99 | `OP_METHOD`      | `BB`         | `R[a] = lambda(Irep[b],L_METHOD)`                                 |
+| 100 | `OP_RANGE_INC`   | `B`          | `R[a] = range_new(R[a],R[a+1],FALSE)`                             |
+| 101 | `OP_RANGE_EXC`   | `B`          | `R[a] = range_new(R[a],R[a+1],TRUE)`                              |
+| 102 | `OP_OCLASS`      | `B`          | `R[a] = ::Object`                                                 |
+| 103 | `OP_CLASS`       | `BB`         | `R[a] = newclass(R[a],Syms[b],R[a+1])`                            |
+| 104 | `OP_MODULE`      | `BB`         | `R[a] = newmodule(R[a],Syms[b])`                                  |
+| 105 | `OP_EXEC`        | `BB`         | `R[a] = blockexec(R[a],Irep[b])`                                  |
+| 106 | `OP_DEF`         | `BB`         | `R[a].newmethod(Syms[b],R[a+1]); R[a] = Syms[b]`                  |
+| 107 | `OP_TDEF`        | `BBB`        | `target_class.newmethod(Syms[b],Irep[c]); R[a] = Syms[b]`         |
+| 108 | `OP_SDEF`        | `BBB`        | `R[a].singleton_class.newmethod(Syms[b],Irep[c]); R[a] = Syms[b]` |
+| 109 | `OP_ALIAS`       | `BB`         | `alias_method(target_class,Syms[a],Syms[b])`                      |
+| 110 | `OP_UNDEF`       | `B`          | `undef_method(target_class,Syms[a])`                              |
+| 111 | `OP_SCLASS`      | `B`          | `R[a] = R[a].singleton_class`                                     |
+| 112 | `OP_TCLASS`      | `B`          | `R[a] = target_class`                                             |
+| 113 | `OP_DEBUG`       | `BBB`        | `print a,b,c`                                                     |
+| 114 | `OP_ERR`         | `B`          | `raise(LocalJumpError, Pool[a])`                                  |
+| 115 | `OP_EXT1`        | `Z`          | make 1st operand (a) 16 bit                                       |
+| 116 | `OP_EXT2`        | `Z`          | make 2nd operand (b) 16 bit                                       |
+| 117 | `OP_EXT3`        | `Z`          | make 1st and 2nd operands 16 bit                                  |
+| 118 | `OP_STOP`        | `Z`          | stop VM                                                           |
+
+## Notes
+
+### OP_SEND0 / OP_SSEND0
+
+These are optimized versions of `OP_SEND` / `OP_SSEND` for zero-argument
+method calls (no operand `c` needed).
+
+### OP_RETSELF / OP_RETNIL / OP_RETTRUE / OP_RETFALSE
+
+These are optimized return instructions that avoid loading a value into
+a register before returning. Common patterns like `attr_reader` methods
+(`return self.@x`) and predicate methods (`return true`/`return false`)
+benefit from these specialized opcodes.
+
+### OP_BLKCALL
+
+Direct block invocation that bypasses method dispatch. Used when calling
+a block argument directly (e.g., `yield` or `block.call`).
+
+### OP_ADDILV / OP_SUBILV
+
+Optimized integer increment/decrement that keeps operands for method
+call fallback when the receiver is not a Fixnum.
+
+### OP_TDEF / OP_SDEF
+
+Optimized method definition. `OP_TDEF` defines a method on the
+`target_class` directly from an irep without creating an intermediate
+`RProc`. `OP_SDEF` does the same for singleton methods.
+
+### OP_MATCHERR
+
+Raises `NoMatchingPatternError` when a pattern match fails. Used by
+the `case`/`in` pattern matching syntax.
+
+### OP_GETIDX / OP_GETIDX0 / OP_SETIDX Optimization
+
+These instructions optimize `[]` and `[]=` access for Array, Hash, and String.
+
+**OP_GETIDX** uses direct function calls:
+
+- `Array`: `mrb_ary_entry()` (integer index only)
+- `Hash`: `mrb_hash_get()`
+- `String`: `mrb_str_aref()` (integer/string/range index)
+
+**OP_GETIDX0** is a specialized variant for index 0 (e.g., `ary[0]`).
+
+**OP_SETIDX** uses direct function calls:
+
+- `Array`: `mrb_ary_set()` (integer index only)
+- `Hash`: `mrb_hash_set()`
+
+**Fallback to method dispatch** occurs when:
+
+- Object is a subclass (e.g., `MyArray < Array`)
+- Object has a singleton class (singleton methods defined)
+- Index type is not supported (e.g., non-integer for Array)
+
+This allows subclasses to override `[]`/`[]=` while base classes remain optimized.

doc/internal/vm.md

@@ -0,0 +1,325 @@
+<!-- summary: Virtual Machine Internals -->
+
+# Virtual Machine Internals
+
+This document describes mruby's virtual machine for developers
+working on `src/vm.c` and related code.
+
+**Read this if you are:** debugging method dispatch or call frame
+issues, working on exception handling, implementing new opcodes,
+modifying fiber/coroutine behavior, or optimizing the dispatch loop.
+
+For the instruction set, see [opcode.md](opcode.md). For the
+compiler that generates bytecode, see [compiler.md](compiler.md).
+
+## Execution Model
+
+mruby uses a **register-based VM**. Local variables and temporaries
+occupy fixed register slots determined at compile time. Each method
+call gets its own register window on a shared value stack.
+
+## Execution Context
+
+The VM state is stored in `mrb_context`:
+
+```text
+mrb_context
++-- stbase..stend    value stack (mrb_value[])
++-- cibase..ciend    call info stack (mrb_callinfo[])
++-- ci               current call frame pointer
++-- status           fiber state
++-- prev             previous context (fiber chain)
++-- vmexec           VM execution state flag
+```
+
+The value stack and call info stack grow independently. Each fiber
+has its own `mrb_context`.
+
+### Stack Sizing
+
+- Initial value stack: 128 entries (`STACK_INIT_SIZE`)
+- Initial call info stack: 32 entries (`CALLINFO_INIT_SIZE`)
+- Growth factor: 1.5x (or 2x with `MRB_STACK_EXTEND_DOUBLING`)
+- Minimum growth: 128 entries (`MRB_STACK_GROWTH`)
+- Max stack depth: `MRB_STACK_MAX` (0x40000 - 128)
+- Max call depth: `MRB_CALL_LEVEL_MAX` (512, or 128 with ASAN)
+
+Exceeding either limit raises `SystemStackError`.
+
+When the value stack is reallocated, all `REnv` objects and
+`mrb_callinfo` stack pointers are adjusted by the delta
+(`envadjust` function).
+
+## Call Frames
+
+Each method or block call pushes a `mrb_callinfo` frame:
+
+```text
+mrb_callinfo
++-- n:4          positional argument count (0-14, 15 = varargs)
++-- nk:4         keyword argument count (0-14, 15 = varargs)
++-- cci          call context info (NONE, DIRECT, SKIP, RESUMED)
++-- vis          visibility flags (public/private/protected)
++-- mid          method symbol
++-- proc         current RProc
++-- blk          block argument (RProc*)
++-- stack        pointer into value stack
++-- pc           program counter (bytecode position)
++-- u.env        closure environment (REnv*)
++-- u.target_class  receiver's class
+```
+
+### Stack Layout Per Frame
+
+```text
+ci->stack:
+  [0]      self (receiver)
+  [1..n]   positional arguments
+  [n+1..]  keyword argument pairs (key, value, key, value, ...)
+  [bidx]   block argument
+  [bidx+1..] local variables and temporaries
+```
+
+### Argument Count Encoding
+
+The `n` and `nk` fields are 4 bits each (0-15). When `n == 15`,
+positional arguments are packed into a single Array in register 1.
+When `nk == 15`, keyword arguments are packed into a single Hash.
+
+The block index is calculated by `mrb_bidx(n, nk)`:
+
+```text
+if n == 15: n = 1 (array)
+if nk == 15: n += 1 (hash)
+else: n += nk * 2 (key-value pairs)
+return n + 1 (skip self)
+```
+
+### Call Context Info (cci)
+
+| Value | Name            | Meaning                               |
+| ----- | --------------- | ------------------------------------- |
+| 0     | `CINFO_NONE`    | Normal VM-to-VM call                  |
+| 1     | `CINFO_DIRECT`  | Explicit VM call (block, lambda.call) |
+| 2     | `CINFO_SKIP`    | Skip frame in stack traces            |
+| 3     | `CINFO_RESUMED` | Fiber resumed (stop execution)        |
+
+## Dispatch Loop
+
+The main loop in `mrb_vm_run()` decodes and dispatches opcodes.
+Two dispatch strategies are available:
+
+- **Computed goto** (default on GCC/Clang): a jump table of label
+  addresses (`optable[]`) for direct dispatch. Faster due to
+  better branch prediction.
+- **Switch-based** (`MRB_USE_VM_SWITCH_DISPATCH`): a standard
+  `switch(insn)` statement. Default on MSVC and other compilers.
+
+The dispatch loop is wrapped in `MRB_TRY`/`MRB_CATCH` for exception
+handling (see [Exception Handling](#exception-handling)).
+
+## Method Dispatch
+
+When `OP_SEND` (or `OP_SSEND`, `OP_SUPER`) executes:
+
+### 1. Prepare Arguments
+
+Determine argument layout. If argument count < 15, the fast path
+uses inline registers. Otherwise, arguments are packed into an
+Array (varargs mode).
+
+### 2. Push Call Frame
+
+```c
+ci = cipush(mrb, a, CINFO_DIRECT, NULL, NULL, blk, mid, argc);
+```
+
+The new frame's stack starts at the previous frame's stack + `a`
+(the receiver's register index).
+
+### 3. Method Lookup
+
+The lookup sequence:
+
+1. **Method cache check**: hash table lookup by `(class, mid)`.
+   Default cache size: `MRB_METHOD_CACHE_SIZE` (256 entries).
+2. **Method table walk**: if cache misses, search the receiver's
+   class method table (`mt`), then walk the superclass chain.
+3. **Cache store**: on successful lookup, store in the cache.
+
+The method cache is invalidated when classes are modified
+(`mrb_mc_clear_by_class`).
+
+### 4. Invoke
+
+- **Ruby method** (irep-based): extend the stack to `irep->nregs`,
+  set `ci->pc` to `irep->iseq`, and jump to the new bytecode.
+- **C function**: call `func(mrb, recv)` directly, then pop the
+  call frame and store the return value.
+
+### 5. Visibility Check
+
+Private methods are only callable without an explicit receiver.
+Protected methods are callable from the same class hierarchy.
+Violations raise `NoMethodError`.
+
+## Exception Handling
+
+### setjmp/longjmp
+
+By default, mruby uses `setjmp`/`longjmp` for exception control
+flow:
+
+```c
+MRB_TRY(&c_jmp) {
+  mrb->jmp = &c_jmp;
+  /* dispatch loop */
+}
+MRB_CATCH(&c_jmp) {
+  /* handle exception */
+}
+MRB_END_EXC(&c_jmp);
+```
+
+With `MRB_USE_CXX_EXCEPTION`, C++ `try`/`catch` is used instead.
+
+### Handler Table
+
+Each irep contains a catch handler table (appended after iseq in
+memory) with entries for `rescue` and `ensure` blocks:
+
+```text
+mrb_irep_catch_handler
++-- type       RESCUE (0) or ENSURE (1)
++-- begin[4]   start PC of protected range
++-- end[4]     end PC of protected range
++-- target[4]  jump target when handler matches
+```
+
+### Unwinding Process
+
+When an exception occurs:
+
+1. Search the current irep's catch handler table (reverse order)
+   for a handler covering the current PC
+2. If an `ensure` handler is found: execute it (may re-raise)
+3. If a `rescue` handler is found: jump to handler code
+4. If no handler: pop the call frame (`cipop`) and repeat with
+   the parent frame
+5. `CINFO_DIRECT` frames are destroyed during propagation
+
+## Block and Closure Handling
+
+### REnv (Environment)
+
+Closures capture their enclosing scope's variables through `REnv`:
+
+```text
+REnv
++-- stack      pointer to captured variable values
++-- cxt        owning context (NULL if detached from stack)
++-- mid        method symbol
++-- flags      length, block index, visibility
+```
+
+While the defining scope is active, `REnv::stack` points directly
+into the VM value stack (shared). This avoids copying.
+
+### Environment Unsharing
+
+When a closure outlives its defining scope, `mrb_env_unshare()`
+copies the captured variables from the stack to a heap-allocated
+buffer:
+
+```c
+mrb_env_unshare(mrb, env, noraise);
+```
+
+After unsharing, `MRB_ENV_CLOSE(env)` sets `cxt = NULL` to indicate
+the environment is detached. A write barrier is issued for GC
+correctness.
+
+### Proc Types
+
+| Flag                | Meaning                        |
+| ------------------- | ------------------------------ |
+| `MRB_PROC_CFUNC_FL` | C function (not irep-based)    |
+| `MRB_PROC_STRICT`   | Lambda (strict argument check) |
+| `MRB_PROC_ORPHAN`   | No environment attachment      |
+| `MRB_PROC_ENVSET`   | Has captured environment       |
+| `MRB_PROC_SCOPE`    | Defines a new variable scope   |
+
+## Fiber Switching
+
+Fibers are lightweight coroutines. Each fiber has its own
+`mrb_context` with separate value and call info stacks.
+
+### Fiber States
+
+```text
+CREATED --> RUNNING --> SUSPENDED --> TERMINATED
+                |           ^
+                +-----------+
+                  (yield/resume)
+            TRANSFERRED (via Fiber#transfer)
+```
+
+### Context Switch
+
+On `Fiber#resume`:
+
+1. Save current context state
+2. Set `mrb->c` to the fiber's context
+3. Push arguments onto the fiber's stack
+4. Continue execution in the fiber
+
+On `Fiber.yield`:
+
+1. Save fiber context
+2. Restore the parent context (`mrb->c = c->prev`)
+3. Return yield values to the parent
+
+### Fiber Termination
+
+When a fiber completes (`fiber_terminate`):
+
+1. Unshare any environments that reference the fiber's stack
+2. Set status to `TERMINATED`
+3. Free the fiber's stacks
+4. Switch to the previous context
+
+### C Function Boundary
+
+Fibers cannot yield across C function boundaries. You cannot call
+`Fiber.yield` from within a C-implemented method (except via
+`mrb_fiber_yield` at return). This is because C call frames cannot
+be suspended and resumed.
+
+## GC Integration
+
+The VM saves the arena index at the start of the dispatch loop:
+
+```c
+int ai = mrb_gc_arena_save(mrb);
+```
+
+After each C function call, the arena is shrunk back:
+
+```c
+mrb_gc_arena_shrink(mrb, ai);
+```
+
+This prevents temporary objects created by C functions from
+accumulating in the arena.
+
+Write barriers are issued when environments are detached or closed,
+ensuring the incremental GC correctly tracks live references.
+
+## Source Files
+
+| File                    | Contents                                       |
+| ----------------------- | ---------------------------------------------- |
+| `src/vm.c`              | Dispatch loop, method invocation (~1900 lines) |
+| `include/mruby.h`       | `mrb_state`, `mrb_callinfo`, `mrb_context`     |
+| `include/mruby/proc.h`  | `RProc`, `REnv` structures                     |
+| `include/mruby/throw.h` | `MRB_TRY`/`MRB_CATCH` macros                   |

doc/limitations.md

@@ -1,3 +1,5 @@
+<!-- summary: About the Limitations of mruby -->
+
 # Limitations and Differences
 
 The philosophy of mruby is to be a lightweight implementation of
@@ -26,11 +28,11 @@ rescue
 end
 ```
 
-#### Ruby [ruby 2.0.0p645 (2015-04-13 revision 50299)]
+#### CRuby
 
 `ZeroDivisionError` is raised.
 
-#### mruby [3.1.0 (2022-05-12)]
+#### mruby
 
 `RuntimeError` is raised instead of `ZeroDivisionError`. To re-raise the exception, you have to do:
 
@@ -62,83 +64,14 @@ end
 p Liste.new "foobar"
 ```
 
-#### Ruby [ruby 2.0.0p645 (2015-04-13 revision 50299)]
+#### CRuby
 
-` [] `
+`[]`
 
-#### mruby [3.1.0 (2022-05-12)]
+#### mruby
 
 `ArgumentError` is raised.
 
-## Method visibility
-
-For simplicity reasons no method visibility (public/private/protected) is
-supported. Those methods are defined, but they are dummy methods.
-
-```ruby
-class VisibleTest
-
-  def public_method; end
-
-  private
-  def private_method; end
-
-end
-
-p VisibleTest.new.respond_to?(:private_method, false)
-p VisibleTest.new.respond_to?(:private_method, true)
-```
-
-#### Ruby [ruby 2.0.0p645 (2015-04-13 revision 50299)]
-
-```
-false
-true
-```
-
-#### mruby [3.1.0 (2022-05-12)]
-
-```
-true
-true
-```
-
-### Visibility Declaration
-
-The declaration form of following visibility methods are not implemented.
-
-- `public`
-- `private`
-- `protected`
-- `module_function`
-
-Especially, `module_function` method is not dummy, but no declaration form.
-
-```
-module TestModule
-  module_function
-  def test_func
-    p 'test_func called'
-  end
-
-  test_func
-end
-
-p 'ok'
-```
-
-#### Ruby [ruby 2.5.5p157 (2019-03-15 revision 67260)]
-
-```
-ok
-```
-
-#### mruby [3.1.0 (2022-05-12)]
-
-```
-test.rb:8: undefined method 'test_func' (NoMethodError)
-```
-
 ## `defined?`
 
 The `defined?` keyword is considered too complex to be fully
@@ -149,13 +82,13 @@ other reflection methods instead.
 defined?(Foo)
 ```
 
-#### Ruby [ruby 2.0.0p645 (2015-04-13 revision 50299)]
+#### CRuby
 
 ```
 nil
 ```
 
-#### mruby [3.1.0 (2022-05-12)]
+#### mruby
 
 `NameError` is raised.
 
@@ -168,17 +101,18 @@ of the ISO standard.
 alias $a $__a__
 ```
 
-#### Ruby [ruby 2.0.0p645 (2015-04-13 revision 50299)]
+#### CRuby
 
-` nil `
+`nil`
 
-#### mruby [3.1.0 (2022-05-12)]
+#### mruby
 
 Syntax error
 
 ## Operator modification
 
-An operator can't be overwritten by the user.
+Operators on some of the primitive classes cannot be overridden, as they are
+optimized in the VM.
 
 ```ruby
 class String
@@ -189,41 +123,21 @@ end
 'a' + 'b'
 ```
 
-#### Ruby [ruby 2.0.0p645 (2015-04-13 revision 50299)]
+#### CRuby
 
 `ArgumentError` is raised.
 The re-defined `+` operator does not accept any arguments.
 
-#### mruby [3.1.0 (2022-05-12)]
+#### mruby
 
-` 'ab' `
+`'ab'`
 Behavior of the operator wasn't changed.
 
-## `Kernel#binding` is not supported until [3.0.0 (2021-03-05)]
+## `Kernel#binding` is not supported without mruby-binding gem
 
-`Kernel#binding` method is not supported.
-
-#### Ruby [ruby 2.5.1p57 (2018-03-29 revision 63029)]
-
-```
-$ ruby -e 'puts Proc.new {}.binding'
-#<Binding:0x00000e9deabb9950>
-```
-
-#### mruby [3.0.0 (2021-03-05)]
-
-```
-$ ./bin/mruby -e 'puts Proc.new {}.binding'
-trace (most recent call last):
-        [0] -e:1
--e:1: undefined method 'binding' (NoMethodError)
-```
-
-#### mruby [3.1.0 (2022-05-12)]
-
-`binding` has been supported since 3.1.0.
-
-See also [mrbgems/mruby-binding](https://github.com/mruby/mruby/tree/master/mrbgems/mruby-binding) and [mrbgems/mruby-binding-core](https://github.com/mruby/mruby/tree/master/mrbgems/mruby-binding-core).
+`Kernel#binding` method requires the `mruby-binding` gem (included
+in the `metaprog` gembox). Without this gem, `binding` is not
+available.
 
 ## `nil?` redefinition in conditional expressions
 
@@ -259,3 +173,120 @@ f(1,[2,3])
 ```
 
 CRuby gives `[1,2,3,nil]`. mruby raises `NoMethodError` for `b`.
+
+Keyword argument expansion has similar restrictions. The following example, gives `[1, 1]` for CRuby, mruby raises `NoMethodError` for `b`.
+
+```ruby
+def g(a: 1, b: a)
+  p [a,b]
+end
+g(a:1)
+```
+
+## No Double Dispatch in Module Loading
+
+To make implementation simpler, mruby does not use double dispatching in module loading (`include`/`prepend`/`extend`).
+Those method internally called corresponding actual load methods (`append_features`/`prepend_features`/`extend_object`).
+But they are rarely overloaded, consumes more memory, and make loading little bit slower. As a Ruby implementation for the smaller device,
+we decided mruby simpler.
+
+```ruby
+module M
+  def self.append_features(mod)
+     p :append
+  end
+end
+
+class C
+  include M
+end
+```
+
+#### CRuby
+
+Prints `:append`.
+
+#### mruby
+
+Nothing printed (since `include` does not call `append_features` internally).
+
+## No `#hash` call for small hashes
+
+For performance reasons, mruby avoids calling the `#hash` method on keys when a hash table is small. This means that custom `#hash` methods on key objects may not be executed.
+
+## Pattern Matching
+
+Pattern matching is only partially supported in mruby. Currently, only the rightward assignment operator (`=>`) with simple variable binding is implemented.
+
+```ruby
+expr => var  # Supported: assigns expr to var
+```
+
+#### CRuby
+
+Full pattern matching with `case/in` syntax and various pattern types:
+
+```ruby
+case [1, 2, 3]
+in [a, b, c]
+  puts "#{a}, #{b}, #{c}"  # => "1, 2, 3"
+end
+
+case {name: "Alice", age: 30}
+in {name:, age:}
+  puts "#{name} is #{age}"  # => "Alice is 30"
+end
+```
+
+#### mruby
+
+Only rightward assignment with simple variable binding:
+
+```ruby
+[1, 2, 3] => x
+puts x  # => [1, 2, 3]
+```
+
+The following are **not supported**:
+
+- `case/in` syntax
+- Array patterns: `in [a, b, c]`
+- Hash patterns: `in {name:, age:}`
+- Guard clauses: `in pattern if condition`
+- Pin operator: `in ^variable`
+- Find patterns: `in [*, x, *]`
+- Alternative patterns: `in pattern1 | pattern2`
+- Boolean pattern check: `value in pattern`
+
+Note: mruby does provide `Array#deconstruct` and `Hash#deconstruct_keys` methods for future pattern matching compatibility.
+
+## No Refinements
+
+Module refinements (`refine`, `using`) are not supported in mruby.
+
+## No `Encoding` Class
+
+mruby does not have an `Encoding` class. Strings are treated as
+byte sequences by default. UTF-8 aware string operations can be
+enabled with the `MRB_UTF8_STRING` compile flag.
+
+## Integer Precision Varies by Boxing Mode
+
+Integer size depends on the value boxing configuration:
+
+| Configuration                 | Integer range    |
+| ----------------------------- | ---------------- |
+| Word boxing, 64-bit (default) | roughly +/- 2^62 |
+| Word boxing, 32-bit (default) | roughly +/- 2^30 |
+| NaN boxing (64-bit only)      | -2^31 to 2^31-1  |
+
+Code relying on 64-bit integer precision may behave differently
+across configurations. The `mruby-bigint` gem provides
+arbitrary-precision integers when included.
+
+## No `ObjectSpace.each_object` by Default
+
+`ObjectSpace` is only available via the `mruby-objectspace` gem
+(included in the `stdlib` gembox). Even with the gem,
+`ObjectSpace.each_object` has limited functionality compared
+to CRuby.

doc/mruby3.0.md

@@ -9,7 +9,7 @@ directory. For examples:
 
 - `default`: the default configuration
 - `host-gprof`: compiles with `gprof` for performance tuning
-- `host-m32`: compiles in gcc 32bit mode on 64bit platforms
+- `host-m32`: compiles in gcc 32-bit mode on 64-bit platforms
 - `boxing`: compiles all three boxing options
 - `clang-asan`: compiles with `clang`'s Address Sanitizer
 
@@ -42,10 +42,10 @@ We have ported some new syntax from CRuby.
 ## Renamed for consistency
 
 Some configuration macro names are changed for consistency (use `MRB_USE_XXX`
- or `MRB_NO_XXX`).
+or `MRB_NO_XXX`).
 
-|             mruby2             |          mruby3           |
-|--------------------------------|---------------------------|
+| mruby2                         | mruby3                    |
+| ------------------------------ | ------------------------- |
 | `MRB_ENABLE_ALL_SYMBOLS`       | `MRB_USE_ALL_SYMBOLS`     |
 | `MRB_ENABLE_CXX_ABI`           | `MRB_USE_CXX_ABI`         |
 | `MRB_ENABLE_CXX_EXCEPTION`     | `MRB_USE_CXX_EXCEPTION`   |
@@ -62,7 +62,7 @@ Some configuration macro names are changed for consistency (use `MRB_USE_XXX`
 - `MRB_USE_FLOAT32` is changed from `MRB_USE_FLOAT` to make sure `float` here
   means using single-precision float, and not the opposite of `MRB_NO_FLOAT`.
 - `MRB_USE_METHOD_T_STRUCT` uses `struct` version of `mrb_method_t`. More
-  portable but consumes more memory. Turned on by default on 32bit platforms.
+  portable but consumes more memory. Turned on by default on 32-bit platforms.
 - `MRB_` prefix is added to those without.
 
 ## `MRB_NO_BOXING`
@@ -149,7 +149,8 @@ No more operand extension
 
 ## Changed Instructions
 
-Jump addresses used to be specified by absolute offset from the start of `iseq`. Now they are relative offset from the address of the next instruction.
+Jump addresses used to be specified by absolute offset from the start of `iseq`. Now they are relative offset from the
+address of the next instruction.
 
 ## `Random` now use `xoshiro128++`.
 
@@ -159,4 +160,4 @@ For better and faster random number generation.
 
 Preallocated symbols are interned at compile-time. They can be accessed via symbols macros (e.g. `MRB_SYM()`).
 
-See [Symbols](https://github.com/mruby/mruby/blob/master/doc/guides/symbol.md).
+See [Symbols](guides/symbol.md).

doc/mruby3.1.md

@@ -20,7 +20,7 @@ Keyword arguments are basically separated from ordinal arguments.
 
 Some configuration macros are available:
 
-- `MRB_WORDBOX_NO_FLOAT_TRUNCATE`: by default, float values are packed in the word if possible, but define this macro to allocate float values in the heap.
+- `MRB_WORDBOX_NO_INLINE_FLOAT` (formerly `MRB_WORDBOX_NO_FLOAT_TRUNCATE`): by default, float values are packed in the word if possible, but define this macro to allocate float values in the heap.
 - `MRB_USE_RO_DATA_P_ETEXT`: define this macro if `_etext` is available on your platform.
 - `MRB_NO_DEFAULT_RO_DATA_P`: define this macro to avoid using predefined `mrb_ro_data_p()` function
 
@@ -37,7 +37,7 @@ We have added several new build configurations in the `build_config` directory.
 - `nintendo_switch.rb`
 - `serenity.rb`
 - `minimal`: minimal configuration
-- `host-f32`: compiles with `mrb_float` as 32 bit `float`
+- `host-f32`: compiles with `mrb_float` as 32-bit `float`
 - `host-nofloat`: compiles with no float configuration
 - `android_arm64_v8a.rb`: renamed from `android_arm64-v8a.rb`
 
@@ -141,8 +141,8 @@ Method calling instructions are unified. Now `OP_SEND` and `OP_SENDB` (method ca
 
 The brief description of the instructions:
 
-|`OP_SEND`   | BBB | `R[a] = R[a].call(Syms[b],R[a+1..n],R[a+n+1],R[a+n+2]..nk) c=n|nk<<4`                    |
-|`OP_SENDB`  | BBB | `R[a] = R[a].call(Syms[b],R[a+1..n],R[a+n+1..nk],R[a+n+2..nk],&R[a+n+2*nk+2]) c=n|nk<<4` |
+|`OP_SEND` | BBB | `R[a] = R[a].call(Syms[b],R[a+1..n],R[a+n+1],R[a+n+2]..nk) c=n|nk<<4` |
+|`OP_SENDB` | BBB | `R[a] = R[a].call(Syms[b],R[a+1..n],R[a+n+1..nk],R[a+n+2..nk],&R[a+n+2*nk+2]) c=n|nk<<4` |
 
 Operand C specifies the number of arguments. Lower 4 bits (`n`) represents the number of ordinal arguments, and higher 4 bits (`nk`) represents the number of keyword arguments.
 When `n == 15`, the method takes arguments packed in an array. When `nk == 15`, the method takes keyword arguments are packed in a hash.
@@ -156,7 +156,7 @@ Now takes 2 operands and pushes multiple entries to an array.
 ### Word Boxing
 
 `MRB_WORD_BOXING` now packs floating-point numbers in the word, if the size of `mrb_float` is equal or smaller than the size of `mrb_int` by default.
-If the size of `mrb_float` and `mrb_int` are same, the last 2 bits in the `mrb_float` are trimmed and used as flags. If you need full precision, you need to define `MRB_WORDBOX_NO_FLOAT_TRUNCATE` as described above.
+If the size of `mrb_float` and `mrb_int` are same, the last 2 bits in the `mrb_float` are trimmed and used as flags. If you need full precision, you need to define `MRB_WORDBOX_NO_INLINE_FLOAT` (formerly `MRB_WORDBOX_NO_FLOAT_TRUNCATE`) as described above.
 
 ### NaN Boxing
 
@@ -197,7 +197,7 @@ For better and faster hash values.
 
 ---
 
-# Major bug fixes
+# Major bugfixes
 
 - Fix infinite recursive call bugs in integer division [98799aa6](https://github.com/mruby/mruby/commit/98799aa6)
 - Fix to raise TypeError with super inside instance_eval / class_eval [#5476](https://github.com/mruby/mruby/pull/5476)
@@ -225,31 +225,31 @@ For better and faster hash values.
 
 Following CVEs are fixed in this release.
 
-- [CVE-2021-4110](https://nvd.nist.gov/vuln/detail/CVE-2021-4110)
-- [CVE-2021-4188](https://nvd.nist.gov/vuln/detail/CVE-2021-4188)
-- [CVE-2022-0080](https://nvd.nist.gov/vuln/detail/CVE-2022-0080)
-- [CVE-2022-0240](https://nvd.nist.gov/vuln/detail/CVE-2022-0240)
-- [CVE-2022-0326](https://nvd.nist.gov/vuln/detail/CVE-2022-0326)
-- [CVE-2022-0481](https://nvd.nist.gov/vuln/detail/CVE-2022-0481)
-- [CVE-2022-0631](https://nvd.nist.gov/vuln/detail/CVE-2022-0631)
-- [CVE-2022-0632](https://nvd.nist.gov/vuln/detail/CVE-2022-0632)
-- [CVE-2022-0890](https://nvd.nist.gov/vuln/detail/CVE-2022-0890)
-- [CVE-2022-1071](https://nvd.nist.gov/vuln/detail/CVE-2022-1071)
-- [CVE-2022-1106](https://nvd.nist.gov/vuln/detail/CVE-2022-1106)
-- [CVE-2022-1201](https://nvd.nist.gov/vuln/detail/CVE-2022-1201)
-- [CVE-2022-1427](https://nvd.nist.gov/vuln/detail/CVE-2022-1427)
+- [CVE-2021-4110](https://www.cve.org/CVERecord?id=CVE-2021-4110)
+- [CVE-2021-4188](https://www.cve.org/CVERecord?id=CVE-2021-4188)
+- [CVE-2022-0080](https://www.cve.org/CVERecord?id=CVE-2022-0080)
+- [CVE-2022-0240](https://www.cve.org/CVERecord?id=CVE-2022-0240)
+- [CVE-2022-0326](https://www.cve.org/CVERecord?id=CVE-2022-0326)
+- [CVE-2022-0481](https://www.cve.org/CVERecord?id=CVE-2022-0481)
+- [CVE-2022-0631](https://www.cve.org/CVERecord?id=CVE-2022-0631)
+- [CVE-2022-0632](https://www.cve.org/CVERecord?id=CVE-2022-0632)
+- [CVE-2022-0890](https://www.cve.org/CVERecord?id=CVE-2022-0890)
+- [CVE-2022-1071](https://www.cve.org/CVERecord?id=CVE-2022-1071)
+- [CVE-2022-1106](https://www.cve.org/CVERecord?id=CVE-2022-1106)
+- [CVE-2022-1201](https://www.cve.org/CVERecord?id=CVE-2022-1201)
+- [CVE-2022-1427](https://www.cve.org/CVERecord?id=CVE-2022-1427)
 
 ## Unaffected CVEs
 
 Following CVEs do not cause problems in this release. They are fixed in the later release.
 
-- [CVE-2022-0481](https://nvd.nist.gov/vuln/detail/CVE-2022-0481)
-- [CVE-2022-0525](https://nvd.nist.gov/vuln/detail/CVE-2022-0525)
-- [CVE-2022-0570](https://nvd.nist.gov/vuln/detail/CVE-2022-0570)
-- [CVE-2022-0614](https://nvd.nist.gov/vuln/detail/CVE-2022-0614)
-- [CVE-2022-0623](https://nvd.nist.gov/vuln/detail/CVE-2022-0623)
-- [CVE-2022-0630](https://nvd.nist.gov/vuln/detail/CVE-2022-0630)
-- [CVE-2022-0717](https://nvd.nist.gov/vuln/detail/CVE-2022-0817)
-- [CVE-2022-1212](https://nvd.nist.gov/vuln/detail/CVE-2022-1212)
-- [CVE-2022-1276](https://nvd.nist.gov/vuln/detail/CVE-2022-1276)
-- [CVE-2022-1286](https://nvd.nist.gov/vuln/detail/CVE-2022-1286)
+- [CVE-2022-0481](https://www.cve.org/CVERecord?id=CVE-2022-0481)
+- [CVE-2022-0525](https://www.cve.org/CVERecord?id=CVE-2022-0525)
+- [CVE-2022-0570](https://www.cve.org/CVERecord?id=CVE-2022-0570)
+- [CVE-2022-0614](https://www.cve.org/CVERecord?id=CVE-2022-0614)
+- [CVE-2022-0623](https://www.cve.org/CVERecord?id=CVE-2022-0623)
+- [CVE-2022-0630](https://www.cve.org/CVERecord?id=CVE-2022-0630)
+- [CVE-2022-0717](https://www.cve.org/CVERecord?id=CVE-2022-0817)
+- [CVE-2022-1212](https://www.cve.org/CVERecord?id=CVE-2022-1212)
+- [CVE-2022-1276](https://www.cve.org/CVERecord?id=CVE-2022-1276)
+- [CVE-2022-1286](https://www.cve.org/CVERecord?id=CVE-2022-1286)

doc/mruby3.2.md

@@ -17,7 +17,7 @@
 ## `mruby`
 
 - `-b` only specifies the script is the binary. The files loaded by `-r` are not affected by the option.
-- `mruby` now loads complied binary if the suffix is `.mrb`.
+- `mruby` now loads compiled binary if the suffix is `.mrb`.
 
 ## `mrbc`
 
@@ -32,30 +32,48 @@
 
 ## New bundled gems
 
-- mruby-errno from [https://github.com/iij/mruby-errno.git]
-- mruby-set from [https://github.com/yui-knk/mruby-set.git]
-- mruby-dir from [https://github.com/iij/mruby-dir.git]
+- mruby-errno from <https://github.com/iij/mruby-errno.git>
+- mruby-set from <https://github.com/yui-knk/mruby-set.git>
+- mruby-dir from <https://github.com/iij/mruby-dir.git>
+- mruby-data
+
+# Breaking Changes
+
+## `mrb_vm_run()` may detach top-level local variables referenced from blocks
+
+When the `mrb_vm_run()` function (including `mrb_top_run()`) is called,
+the previous top-level local variables referenced from blocks is detached under either of the following conditions.
+
+- If the `stack_keep` parameter is given as 0.
+- If the number of variables in `irep` to be executed is less than the number of previous top-level local variables.
+
+This change also affects API functions such as `mrb_load_string()` and `mrb_load_file()`.
+The conditions under which the previous top-level local variables referenced from blocks is detached in these functions are as follows:
+
+- If the function has no `mrbc_context` pointer parameter, or the `mrbc_context` pointer parameter is set to `NULL`.
+- If the number of variables held in the `mrbc_context` pointer is less than the number of previous top-level local variables.
+
+Intentional reliance on previous behavior may cause compatibility problems in your application.
 
 # CVEs
 
 Following CVEs are fixed.
 
-- [CVE-2022-0080](https://nvd.nist.gov/vuln/detail/CVE-2022-0080)
-- [CVE-2022-0240](https://nvd.nist.gov/vuln/detail/CVE-2022-0240)
-- [CVE-2022-0326](https://nvd.nist.gov/vuln/detail/CVE-2022-0326)
-- [CVE-2022-0631](https://nvd.nist.gov/vuln/detail/CVE-2022-0631)
-- [CVE-2022-0481](https://nvd.nist.gov/vuln/detail/CVE-2022-0481)
-- [CVE-2022-0525](https://nvd.nist.gov/vuln/detail/CVE-2022-0525)
-- [CVE-2022-0570](https://nvd.nist.gov/vuln/detail/CVE-2022-0570)
-- [CVE-2022-0614](https://nvd.nist.gov/vuln/detail/CVE-2022-0614)
-- [CVE-2022-0623](https://nvd.nist.gov/vuln/detail/CVE-2022-0623)
-- [CVE-2022-0630](https://nvd.nist.gov/vuln/detail/CVE-2022-0630)
-- [CVE-2022-0631](https://nvd.nist.gov/vuln/detail/CVE-2022-0631)
-- [CVE-2022-0632](https://nvd.nist.gov/vuln/detail/CVE-2022-0632)
-- [CVE-2022-0717](https://nvd.nist.gov/vuln/detail/CVE-2022-0717)
-- [CVE-2022-0890](https://nvd.nist.gov/vuln/detail/CVE-2022-0890)
-- [CVE-2022-1106](https://nvd.nist.gov/vuln/detail/CVE-2022-1106)
-- [CVE-2022-1212](https://nvd.nist.gov/vuln/detail/CVE-2022-1212)
-- [CVE-2022-1276](https://nvd.nist.gov/vuln/detail/CVE-2022-1276)
-- [CVE-2022-1286](https://nvd.nist.gov/vuln/detail/CVE-2022-1286)
-- [CVE-2022-1934](https://nvd.nist.gov/vuln/detail/CVE-2022-1934)
+- [CVE-2022-0080](https://www.cve.org/CVERecord?id=CVE-2022-0080)
+- [CVE-2022-0240](https://www.cve.org/CVERecord?id=CVE-2022-0240)
+- [CVE-2022-0326](https://www.cve.org/CVERecord?id=CVE-2022-0326)
+- [CVE-2022-0481](https://www.cve.org/CVERecord?id=CVE-2022-0481)
+- [CVE-2022-0525](https://www.cve.org/CVERecord?id=CVE-2022-0525)
+- [CVE-2022-0570](https://www.cve.org/CVERecord?id=CVE-2022-0570)
+- [CVE-2022-0614](https://www.cve.org/CVERecord?id=CVE-2022-0614)
+- [CVE-2022-0623](https://www.cve.org/CVERecord?id=CVE-2022-0623)
+- [CVE-2022-0630](https://www.cve.org/CVERecord?id=CVE-2022-0630)
+- [CVE-2022-0631](https://www.cve.org/CVERecord?id=CVE-2022-0631)
+- [CVE-2022-0632](https://www.cve.org/CVERecord?id=CVE-2022-0632)
+- [CVE-2022-0717](https://www.cve.org/CVERecord?id=CVE-2022-0717)
+- [CVE-2022-0890](https://www.cve.org/CVERecord?id=CVE-2022-0890)
+- [CVE-2022-1106](https://www.cve.org/CVERecord?id=CVE-2022-1106)
+- [CVE-2022-1212](https://www.cve.org/CVERecord?id=CVE-2022-1212)
+- [CVE-2022-1276](https://www.cve.org/CVERecord?id=CVE-2022-1276)
+- [CVE-2022-1286](https://www.cve.org/CVERecord?id=CVE-2022-1286)
+- [CVE-2022-1934](https://www.cve.org/CVERecord?id=CVE-2022-1934)